git.maemo.org Git - tietoopcom/blob - include/TocUi/toccontactlistwidget.h

   1 /** \file TocContactListWidget.h
   2  * \brief Declaration of TocContactListWidget class
   3  *
   4  * Tieto Open Communicator - Client for the Telepathy communications framework.
   5  * Copyright (c) 2010, Tieto Corporation
   6  *
   7  * All rights reserved.
   8  * Redistribution and use in source and binary forms, with or without modification,
   9  * are permitted provided that the following conditions are met:
  10  *
  11  *      Redistributions of source code must retain the above copyright notice,
  12  *      this list of conditions and the following disclaimer.
  13  *      Redistributions in binary form must reproduce the above copyright notice,
  14  *      this list of conditions and the following disclaimer in the documentation
  15  *      and/or other materials provided with the distribution.
  16  *      Neither the name of the Tieto Corporation nor the names of its contributors
  17  *      may be used to endorse or promote products derived from this software without
  18  *      specific prior written permission.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  23  * IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  24  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  25  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  27  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  28  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29  *
  30  */
  31
  32 #ifndef TOCCONTACTLISTWIDGET_H
  33 #define TOCCONTACTLISTWIDGET_H
  34
  35 #include <QtGui/QListWidget>
  36 #include <QAction>
  37 #include <QColor>
  38
  39 #include "defs.h"
  40 #include "TocSettings"
  41
  42 QT_BEGIN_NAMESPACE
  43
  44 /** \brief TocContactListWidget class
  45  *
  46  * Widget representing the list of current account contact's.
  47  * QListWidget is used in `IconMode`, and allows user to show a unique
  48  * avatar for each contact. It allows user to delete add and change contact's data,
  49  * and to start conversation with the contact.
  50  */
  51 class TocContactListWidget : public QListWidget
  52 {
  53         Q_OBJECT
  54         // Property holding color of the logo.
  55         // It's a Q_PROPERTY to enable easy setting of the color with style sheet's.
  56         Q_PROPERTY(QColor logoColor READ logoColor WRITE setLogoColor NOTIFY logoColorChanged)
  57
  58 public:
  59
  60         /**
  61          * Public Constructor
  62          */
  63         TocContactListWidget( QWidget * parent = 0 );
  64
  65         /**
  66          * Destructor
  67          */
  68         ~TocContactListWidget();
  69
  70         /** \brief Method used when contact's presence has changed
  71          *
  72          * This method handles presence change of a contact.
  73          *
  74          * @param uid Contact's ID
  75          * @param presence Contact's new presence
  76          * @param description Contact's new presence description
  77          */
  78         void onContactPresenceUpdate(const QString& uid, Presence presence, const QString& description);
  79
  80         /** \brief This method translates Contact's ID to its Name
  81          *
  82          * This method is used when TocMainWindow needs the Name for
  83          * the given Uid, in order to create a new TocChatWidget.
  84          *
  85          * @param uid Contact's ID
  86          * @return Displayed Name of the contact
  87          */
  88         QString getDisplayedName(const QString& uid);
  89
  90         /** \brief This method is used to find specific contact on the list by contact's uid
  91          *
  92          * It searches for the user in contact list and returns it's item,
  93          * if there is no such contact it returns 0. It's possible to exlude particular
  94          * item from search. It's used when editing an exisiting contact because contact data
  95          * are associated with the same QListWidgetItem pointer.
  96          *
  97          * @param item Item to be excluded from searching
  98          * @param uid Contact's ID
  99          * @param pExcludedItem Item from the list
 100          * @return Pointer to found item
 101          */
 102         QListWidgetItem* findItem(const QString& uid, const QListWidgetItem* pExcludedItem = 0);
 103
 104         /** \brief Clears statuses of contacts
 105          *
 106          * Typicaly used to clear statuses after setting the self-status to Offline
 107          */
 108         void clearStatuses();
 109
 110         /** \brief Getter for logoColor property
 111          *
 112          */
 113         QColor logoColor() const;
 114
 115         /** \brief Setter for logoColor property
 116          *
 117          */
 118         void setLogoColor(QColor rgb);
 119
 120 protected:
 121
 122         /** \brief Implementation of the interface that allows to handle mouse double click event
 123          */
 124         void mouseDoubleClickEvent(QMouseEvent *event);
 125
 126         /** \brief Implementation of the interface that allows to handle context menu event
 127          *
 128          *  It creates context menu for managing contact items on the list.
 129          */
 130         void contextMenuEvent(QContextMenuEvent *event);
 131
 132         /** \brief Implementation of the interface that allows to handle custom paint events
 133          *
 134          *  It allows to paint Tieto logo in contact list view.
 135          */
 136         void paintEvent(QPaintEvent * event);
 137
 138
 139 signals:
 140
 141         /** \brief Emited when user chooses a contact to chat with
 142          *
 143          * This signal is emited when user selects and then clicks an item on the list.
 144          *
 145          * @param uid Contact's ID
 146          * @param name Contact's name
 147          * @param presence Contact's presence
 148          *
 149          */
 150         void triggered(const QString& uid, const QString& name, Presence presence);
 151
 152         /** \brief Emited when user requests to see a contact info
 153          *
 154          * This signal is emited when user selects to edit contact's data
 155          * or if the user wants to add new contact to the list ( then *item == QListWidgetItem() ).
 156          *
 157          * @param pItem Contact item to be edited or added
 158          */
 159         void contactInfoRequest(QListWidgetItem* pItem);
 160
 161         /** \brief Emited when contact is removed
 162          *
 163          * This signal is emited when user wants to delete the contact with given Uid.
 164          * Note that the contact should be already deleted from the TocListWidget
 165          * before it's emision.
 166          *
 167          * @param uid Contact's ID
 168          */
 169         void removedContact(const QString& uid);
 170
 171         /** \brief Emited when user commits the changes
 172          *
 173          * This signal is emited when user finished adding contact.
 174          *
 175          * @param pContact      Pointer to a contact to be added.
 176          */
 177         void addContact(TocContact* pContact);
 178
 179         /** \brief Emited when user commits the changes
 180          *
 181          * This signal is emited when user finished editing contact data.
 182          *
 183          * @param pContact      Pointer to a contact to be altered.
 184          * @param oldUid Previous ID of a contact (omited if widget is in "Add Mode")
 185          */
 186         void editContact(TocContact* pContact, QString oldUid);
 187
 188         /** \brief Emited when name of the contact has been changed
 189          *
 190          * This signal is emited to notify that user chas changed the displayed name
 191          * of the contact so it can be used to change the name at runtime
 192          * in TocChatWindow and in active sessions menu of TocMainToolbar.
 193          *
 194          * @param uid Contact's ID
 195          * @param name New displayed name of the contact
 196          */
 197         void displayedNameChanged( const QString& uid, const QString& name);
 198
 199         /** \brief Emited when name of the logoCount property has been changed
 200          *
 201          * When logoCount property is changed, this signal is emited, with new value as a parameter.
 202          *
 203          * @param rgb new value of logoColor property
 204          */
 205         void logoColorChanged(QColor rgb);
 206
 207 public slots:
 208
 209         /** \brief Used to set a contact list to the widget
 210          *
 211          * This slot is used when a new TocContactList has arived from TocEngine.
 212          * Data from the list should be copied to QListWidgetItem's.
 213          *
 214          * @param contactList New contact list to be handled
 215          */
 216         void onNewContactList(const TocContactList& contactList);
 217
 218         /** \brief Used when user finishes editing new contact data
 219          *
 220          * This slot is used when user actualy commits new contact's addition
 221          * from the TocUserInfoWidget. It adds created item to the contact list.
 222          *
 223          * @param pNewItem Item to be added
 224          */
 225         void commitAdd(QListWidgetItem* pNewItem);
 226
 227         /** \brief Used when user finishes edition of contact data
 228          *
 229          * This slot is used when user actualy commits changes to the contact
 230          * from the TocUserInfoWidget.
 231          *
 232          * @param pEditedItem Item with changed data
 233          */
 234         void commitEdit(QListWidgetItem* pEditedItem);
 235
 236 private slots:
 237
 238         /** \brief Slot that reacts on Edit action from context menu
 239          *
 240          * It extracts QListWidgetItem from sender and posts it to UserInfoWidget
 241          * for edition.
 242          */
 243         void onEditRequested();
 244
 245         /** \brief Slot that reacts on Remove action from context menu
 246          *
 247          * It extracts QListWidgetItem from sender, removes it from the contacts list
 248          * and notifies engine about it.
 249          */
 250         void onRemoveRequested();
 251
 252         /** \brief Slot that sets the color of the logo
 253          *
 254          * This method paints the logo with the color provided.
 255          *
 256          * @param rgb Color to be set for the logo
 257          */
 258         void changeLogoColor(QColor rgb);
 259
 260 private: // Methods
 261
 262         /** \brief Sorts all the items in the list widget
 263          *
 264          * This method sorts all the items in the list widget according to
 265          * the specified order.
 266          * TODO: only Literal sorting is now implemented, implement other methods as well
 267          *
 268          * @param order Order to sort by
 269          */
 270         void sortItems(SortOrder order = Alphabetical);
 271
 272 private: // Members
 273
 274         TocContact                      _currentEditedContact;  /// Temporary TocContact used in the process of editing an item
 275         QListWidgetItem*                _pCurrentEditedItem;    /// Temporary item used in the process of editing an item
 276         QAction                         _editAction;            /// An action from context menu that triggers edition of selected item. It's connected to onEditRequested() slot
 277         QAction                         _removeAction;          /// An action from context menu that triggers deletion of selected item. It's connected to onRemoveRequested() slot
 278         QImage*                         _logo;                  /// Logo image mask. Created inside constructor.
 279         QColor                          _logoColor;             /// Color in RGB of the logo. (Q_PROPERTY logoColor)
 280 };
 281
 282 QT_END_NAMESPACE
 283
 284 #endif // TOCCONTACTLISTWIDGET_H