kopete/libkopete/kopeteaddedinfoevent.h

   1 /*
   2     kopeteaddedinfoevent.h - Kopete Added Info Event
   3
   4     Copyright (c) 2008      by Roman Jarosz          <kedgedev@centrum.cz>
   5     Kopete    (c) 2008      by the Kopete developers <kopete-devel@kde.org>
   6
   7     *************************************************************************
   8     *                                                                       *
   9     * This library is free software; you can redistribute it and/or         *
  10     * modify it under the terms of the GNU Lesser General Public            *
  11     * License as published by the Free Software Foundation; either          *
  12     * version 2 of the License, or (at your option) any later version.      *
  13     *                                                                       *
  14     *************************************************************************
  15 */
  16 #ifndef KOPETEADDEDINFOEVENT_H
  17 #define KOPETEADDEDINFOEVENT_H
  18
  19 #include "kopeteinfoevent.h"
  20
  21 namespace Kopete {
  22
  23 class MetaContact;
  24 class Account;
  25 /**
  26  * @brief Event which is shown when a contact added you into the contact list or requested authorization.
  27  *
  28  * This event allows the user to give authorization for the addition to the
  29  * person who added the user and also allows the user to add the person into
  30  * the user's contact list.
  31  *
  32  * The @p title() and @p text() will be filled with predefined text.
  33  * If you want to add additional information use @p setAdditionalText()
  34  *
  35  * The @p actionActivated(uint) signal can be emitted more than once.
  36  * All AddedInfoEvent object will be closed and deleted automatically.
  37  *
  38  * example of usage
  39  * @code
  40         Kopete::AddedInfoEvent* event = new Kopete::AddedInfoEvent( contactId, account );
  41         QObject::connect( event, SIGNAL(actionActivated(uint)), this, SLOT(addedInfoEventActionActivated(uint)) );
  42         event->sendEvent();
  43  * @endcode
  44  *
  45  * and in your addedInfoEventActionActivated slot
  46  * @code
  47         Kopete::AddedInfoEvent *event = dynamic_cast<Kopete::AddedInfoEvent *>(sender());
  48         if ( !event )
  49                 return;
  50
  51         switch ( actionId )
  52         {
  53         case Kopete::AddedInfoEvent::AddContactAction:
  54                 event->addContact();
  55                 break;
  56         case Kopete::AddedInfoEvent::AuthorizeAction:
  57                 socket->authorize( event->contactId() );
  58                 break;
  59         case Kopete::AddedInfoEvent::InfoAction:
  60                 showInfo();
  61                 break;
  62         }
  63  * @endcode
  64  *
  65  * @author Roman Jarosz <kedgedev@centrum.cz>
  66  */
  67 class KOPETE_EXPORT AddedInfoEvent : public InfoEvent
  68 {
  69         Q_OBJECT
  70 public:
  71         /**
  72          * All actions that may be shown and emitted.
  73          */
  74         enum ShowAction
  75         {
  76                 AddAction = 0x001, /** Add action was activated. The default implementation shows
  77                                        ContactAddedNotifyDialog if activate(uint) isn't replaced */
  78                 AuthorizeAction = 0x002, /** You should authorize the contact */
  79                 BlockAction = 0x004, /** You should block this and future requests */
  80                 InfoAction = 0x008, /** You should show info about contact */
  81
  82                 AddContactAction = 0x100, /** You should add contact to Kopete contact list with @p addContact()
  83                                               this is only emitted if activate(uint) isn't replaced */
  84                 AllActions = 0x00F
  85         };
  86         Q_DECLARE_FLAGS(ShowActionOptions, ShowAction)
  87
  88         /**
  89          * @brief Constructor
  90          *
  91          * @param contactId the contactId of the contact which has added you
  92          * @param account the account which has generated this event
  93          */
  94         AddedInfoEvent( const QString& contactId, Kopete::Account *account );
  95
  96         ~AddedInfoEvent();
  97
  98         /**
  99          * Return the contactId of a contact which has added you.
 100          */
 101         QString contactId() const;
 102
 103         /**
 104          * Return the account that has generated this event.
 105          */
 106         Kopete::Account* account() const;
 107
 108         /**
 109          * Set which actions should be shown.
 110          *
 111          * @param actions a bitmask of ShowAction used to show specific actions.
 112          * @note by default everything is shown.
 113          */
 114         void showActions( ShowActionOptions actions );
 115
 116         /**
 117          * Set contact nickname
 118          *
 119          * @param nickname the nickname of the contact.
 120          */
 121         void setContactNickname( const QString& nickname );
 122
 123         /**
 124          * @brief create a metacontact.
 125          *
 126          * This function only works if the AddContactAction action was activated, otherwise
 127          * it will return 0L.
 128          *
 129          * it uses the Account::addContact function to add the contact
 130          *
 131          * @return the new metacontact created, or 0L if the operation failed.
 132          */
 133         MetaContact* addContact() const;
 134
 135 public Q_SLOTS:
 136         /**
 137          * Activate the action specified action
 138          */
 139         virtual void activate( uint actionId );
 140
 141         /**
 142          * Emit the event.
 143          */
 144         virtual void sendEvent();
 145
 146 private Q_SLOTS:
 147         void addDialogOk();
 148         void addDialogInfo();
 149         void addDialogFinished();
 150
 151 private:
 152         class Private;
 153         Private *d;
 154 };
 155 Q_DECLARE_OPERATORS_FOR_FLAGS( AddedInfoEvent::ShowActionOptions )
 156
 157 }
 158
 159 #endif