kopete/libkopete/ui/contactaddednotifydialog.h

   1 /*
   2     Copyright (c) 2005      Olivier Goffart           <ogoffart@kde.org>
   3
   4     Kopete    (c) 2005 by the Kopete developers  <kopete-devel@kde.org>
   5
   6     *************************************************************************
   7     *                                                                       *
   8     * This library is free software; you can redistribute it and/or         *
   9     * modify it under the terms of the GNU Lesser General Public            *
  10     * License as published by the Free Software Foundation; either          *
  11     * version 2 of the License, or (at your option) any later version.      *
  12     *                                                                       *
  13     *************************************************************************
  14 */
  15
  16
  17 #ifndef KOPETE_UICONTACTADDEDNOTIFYDIALOG_H
  18 #define KOPETE_UICONTACTADDEDNOTIFYDIALOG_H
  19
  20 #include <kdialog.h>
  21 #include "kopete_export.h"
  22
  23 namespace KABC {
  24         class Addressee;
  25 }
  26
  27 namespace Kopete {
  28
  29 class Group;
  30 class Account;
  31 class MetaContact;
  32
  33 namespace UI {
  34
  35 /**
  36  * @brief Dialog which is shown when a contact added you in the contact list.
  37  *
  38  * This dialog asks the user to give authorization for the addition to the
  39  * person who added the user and also asks the user if the contact who you've
  40  * received the notification for should be added to the user's contact list
  41  *
  42  * example of usage
  43  * @code
  44
  45         Kopete::UI::ContactAddedNotifyDialog *dialog =
  46                         new ContactAddedNotifyDialog(contactId, QString::null,account); //krazy:exclude=nullstrassign for old broken gcc
  47         QObject::connect(dialog,SIGNAL(applyClicked(const QString&)),this,SLOT(contactAddedDialogApplied()));
  48         QObject::connect(dialog,SIGNAL(infoClicked(const QString&)),this,SLOT(contactAddedDialogInfo()));
  49         dialog->show();
  50
  51  * @endcode
  52  *
  53  * and in your contactAddedDialogApplied slot
  54  * @code
  55         const Kopete::UI::ContactAddedNotifyDialog *dialog =
  56                         dynamic_cast<const Kopete::UI::ContactAddedNotifyDialog *>(sender());
  57         if(!dialog)
  58                 return;
  59         if(dialog->authorized())
  60                 socket->authorize(contactId);
  61         if(dialog->added())
  62                 dialog->addContact();
  63  * @endcode
  64  *
  65  * Note that you can also use exec() but this is not recommended
  66  *
  67  * @author Olivier Goffart
  68  */
  69 class KOPETE_EXPORT ContactAddedNotifyDialog : public KDialog
  70 {
  71 Q_OBJECT
  72 public:
  73         /**
  74          * All widget in the dialog that may be hidden.
  75          */
  76         enum HideWidget
  77         {
  78                 DefaultHide = 0x00, ///< Internal default.
  79                 InfoButton = 0x01, /**< the button which ask for more info about the contact */
  80                 AuthorizeCheckBox = 0x02, /**< the checkbox which ask for authorize the contact */
  81                 AddCheckBox = 0x04, /**< the checkbox which ask if the contact should be added */
  82                 AddGroupBox = 0x08 /**< all the widget about metacontact properties */
  83         };
  84         Q_DECLARE_FLAGS(HideWidgetOptions, HideWidget)
  85
  86         /**
  87          * @brief Constructor
  88          *
  89          * The dialog is by default not modal, and will delete itself when closed
  90          *
  91          * @param contactId the contactId of the contact which just added the user
  92          * @param contactNick the nickname of the contact if available.
  93          * @param account is used to display the account icon and informaiton about the account
  94          * @param hide a bitmask of HideWidget used to hide some widget. By default, everything is shown.
  95          *
  96          */
  97         explicit ContactAddedNotifyDialog(const QString& contactId, const QString& contactNick=QString::null,   //krazy:exclude=nullstrassign for old broken gcc
  98                                         Kopete::Account *account=0L, const HideWidgetOptions &hide=DefaultHide);
  99
 100         /**
 101          * @brief Destructor
 102          */
 103         ~ContactAddedNotifyDialog();
 104
 105         /**
 106          * @brief return if the user has checked the "authorize" checkbox
 107          * @return true if the authorize checkbox is checked, false otherwise
 108          */
 109         bool authorized() const;
 110
 111         /**
 112          * @brief return if the user has checked the "add" checkbox
 113          * @return true if the add checkbox is checked, false otherwise
 114          */
 115         bool added() const;
 116
 117         /**
 118          * @brief return the display name the user has entered
 119          */
 120         QString displayName() const;
 121
 122         /**
 123          * @brief return the group the user has selected
 124          *
 125          * If the user has entered a group which doesn't exist yet, it will be created now
 126          */
 127         Group* group() const;
 128
 129 public slots:
 130
 131         /**
 132          * @brief create a metacontact.
 133          *
 134          * This function only works if the add checkbox is checked, otherwise,
 135          * it will return 0L.
 136          *
 137          * it uses the Account::addContact function to add the contact
 138          *
 139          * @return the new metacontact created, or 0L if the operation failed.
 140          */
 141         MetaContact *addContact() const;
 142
 143 signals:
 144         /**
 145          * @brief the dialog has been applied
 146          * @param contactId is the id of the contact passed in the constructor.
 147          */
 148         void applyClicked(const QString &contactId);
 149
 150         /**
 151          * @brief the button "info" has been pressed
 152          * If you haven't hidden the more info button, you should connect this
 153          * signal to a slot which show a dialog with more info about the
 154          * contact.
 155          *
 156          * hint: you can use sender() as parent of the new dialog
 157          * @param contactId is the id of the contact passed in the constructor.
 158          */
 159         void infoClicked(const QString &contactId);
 160
 161
 162 private slots:
 163         void slotAddresseeSelected( const KABC::Addressee &);
 164         void slotInfoClicked();
 165         void slotFinished();
 166
 167 private:
 168         struct Private;
 169         Private * const d;
 170 };
 171
 172 Q_DECLARE_OPERATORS_FOR_FLAGS( ContactAddedNotifyDialog::HideWidgetOptions )
 173
 174 } // namespace UI
 175 } // namespace Kopete
 176 #endif