knotification.h

Go to the documentation of this file.

/* This file is part of the KDE libraries
   Copyright (C) 2005-2006 Olivier Goffart <ogoffart at kde.org>

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License version 2 as published by the Free Software Foundation.

   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Library General Public License for more details.

   You should have received a copy of the GNU Library General Public License
   along with this library; see the file COPYING.LIB.  If not, write to
   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
   Boston, MA 02110-1301, USA.
*/


#ifndef KNOTIFICATION_H
#define KNOTIFICATION_H

#include <kdeui_export.h>
#include <kcomponentdata.h>

#include <QtGui/QPixmap>
#include <QtCore/QObject>
#include <QtCore/QPair>

class QWidget;
class QDBusError;

class KDEUI_EXPORT KNotification : public QObject
{
        Q_OBJECT

public:
    typedef QPair<QString,QString> Context;
    typedef QList< Context > ContextList;

    enum NotificationFlag
    {
        RaiseWidgetOnActivation=0x01,

        CloseOnTimeout=0x00,
        
        Persistent=0x02,

        CloseWhenWidgetActivated=0x04,
        Persistant = Persistent,
        DefaultEvent=0xF000
        
    };
    
    Q_DECLARE_FLAGS(NotificationFlags , NotificationFlag)

    
    enum StandardEvent { Notification , Warning , Error , Catastrophe };

    explicit KNotification(const QString & eventId , QWidget *widget=0L, const NotificationFlags &flags=CloseOnTimeout);

    // KDE5: Clean up this mess
    // Only this constructor should stay with saner argument order and
    // defaults. Because of binary and source compatibility issues it has to
    // stay this way for now. The second argument CANNOT have a default
    // argument. if someone needs a widget associated with the notification he
    // should use setWidget after creating the object (or some xyz_cast magic)
    explicit KNotification(const QString & eventId , const NotificationFlags &flags, QObject *parent = NULL );

    ~KNotification();

    QWidget *widget() const;
    
    void setWidget(QWidget *widget);
    
    
    QString eventId() const;

    QString title() const;

    void setTitle(const QString &title);

    QString text() const ;
    
    void setText(const QString &text);
    
    QPixmap pixmap() const;
    void setPixmap(const QPixmap &pix);
    
    QStringList actions() const;
    
    void setActions(const QStringList& actions);
    
    ContextList contexts() const;
    void setContexts( const ContextList &contexts);
    void addContext( const Context & context);
    void addContext( const QString & context_key, const QString & context_value );

    NotificationFlags flags() const;

    void setFlags(const NotificationFlags &flags);

    void setComponentData(const KComponentData &componentData);

   Q_SIGNALS:
    void activated();
    void activated(unsigned int action);

    void action1Activated();

    void action2Activated();

    void action3Activated();

    void closed();

    void ignored();

public Q_SLOTS:
    void activate(unsigned int action=0);

    void close();

    void raiseWidget();

    void ref();
    void deref();
    
    void sendEvent();
    
    void update();

private Q_SLOTS:
    void slotReceivedId(int);
    void slotReceivedIdError(const QDBusError&);
    
private:
    struct Private;
    Private *const d;
    
protected:
    virtual bool eventFilter( QObject * watched, QEvent * event );


public:
    static KNotification *event(const QString &eventId , const QString &title, const QString &text,
                    const QPixmap &pixmap = QPixmap(), QWidget *widget = 0L,
                    const NotificationFlags &flags = CloseOnTimeout,
                    const KComponentData &componentData = KComponentData());

    static KNotification *event(const QString &eventId , const QString &text = QString(),
                    const QPixmap &pixmap = QPixmap(), QWidget *widget = 0L,
                    const NotificationFlags &flags = CloseOnTimeout,
                    const KComponentData &componentData = KComponentData());

    static KNotification *event( StandardEvent eventId , const QString& text=QString(),
                                 const QPixmap& pixmap=QPixmap(), QWidget *widget=0L,
                                 const NotificationFlags& flags=CloseOnTimeout);

    static KNotification *event( StandardEvent eventId , const QString& title, const QString& text,
                             const QPixmap& pixmap=QPixmap(), QWidget *widget=0L,
                             const NotificationFlags& flags=CloseOnTimeout);

    static void beep( const QString& reason = QString() , QWidget *widget=0L);
    
    //prevent warning
    using QObject::event;
};

Q_DECLARE_OPERATORS_FOR_FLAGS(KNotification::NotificationFlags)

#endif