kopete/libkopete/ui/kopeteview.h

   1 /*
   2     kopeteview.h - View Manager
   3
   4     Copyright (c) 2003      by Jason Keirstead       <jason@keirstead.org>
   5     Copyright (c) 2004      by Matt Rogers           <matt.rogers@kdemail.net>
   6     Kopete    (c) 2002-2003 by the Kopete developers <kopete-devel@kde.org>
   7
   8     *************************************************************************
   9     *                                                                       *
  10     * This library is free software; you can redistribute it and/or         *
  11     * modify it under the terms of the GNU Lesser General Public            *
  12     * License as published by the Free Software Foundation; either          *
  13     * version 2 of the License, or (at your option) any later version.      *
  14     *                                                                       *
  15     *************************************************************************
  16 */
  17
  18
  19 #ifndef KOPETEVIEW_H
  20 #define KOPETEVIEW_H
  21
  22 #include "kopetemessage.h"
  23 #include "kopete_export.h"
  24
  25 namespace Kopete
  26 {
  27         class ViewPlugin;
  28 }
  29
  30 /**
  31  * @author Jason Keirstead
  32  *
  33  * Abstract parent class for all types of views used for messaging.These view objects
  34  * are provided by a @ref Kopete::ViewPlugin
  35  *
  36  * @see Kopete::ViewPlugin
  37  */
  38 class KOPETE_EXPORT KopeteView
  39 {
  40         public:
  41                 virtual ~KopeteView(){}
  42                 /**
  43                  * constructor
  44                  */
  45                 KopeteView( Kopete::ChatSession *manager, Kopete::ViewPlugin *parent );
  46
  47                 /**
  48                  * @brief Returns the message currently in the edit area
  49                  * @return The Kopete::Message object containing the message
  50                  */
  51                 virtual Kopete::Message currentMessage() = 0;
  52                 /**
  53                  * Set the message that the view is currently editing.
  54                  * @param newMessage The Kopete::Message object containing the message to be edited.
  55                  */
  56                 virtual void setCurrentMessage( const Kopete::Message &newMessage ) = 0;
  57
  58                 /**
  59                  * @brief Get the message manager
  60                  * @return The Kopete::ChatSession that the view is in communication with.
  61                  */
  62                 Kopete::ChatSession *msgManager() const;
  63
  64                 /**
  65                  * @brief add a message to the view
  66                  *
  67                  * The message gets added at the end of the view and is automatically
  68                  * displayed. Classes that inherit from KopeteView should make this a slot.
  69                  */
  70                 virtual void appendMessage( Kopete::Message & ) = 0;
  71
  72                 /**
  73                  * @brief append multiple messages to the view
  74                  *
  75                  * This function does the same thing as the above function but
  76                  * can be reimplemented if it is faster to apend several messages
  77                  * in the same time.
  78                  *
  79                  * The default implementation just call @ref appendMessage() X times
  80                  */
  81                 virtual void appendMessages( Q3ValueList<Kopete::Message> );
  82
  83                 /**
  84                  * @brief Raises the view above other windows
  85                  * @param activate change the focus to the window
  86                  */
  87                 virtual void raise(bool activate = false) = 0;
  88
  89                 /**
  90                  * @brief Clear the buffer
  91                  */
  92                  virtual void clear();
  93
  94                 /**
  95                  * @brief Make the view visible
  96                  *
  97                  * Makes the view visible if it is currently hidden.
  98                  */
  99                 virtual void makeVisible() = 0;
 100
 101                 /**
 102                  * @brief Close this view
 103                  */
 104                 virtual bool closeView( bool force = false ) = 0;
 105
 106                 /**
 107                  * @brief Get the current visibility of the view
 108                  * @return Whether the view is visible or not.
 109                  */
 110                 virtual bool isVisible() = 0;
 111
 112                 /**
 113                  * @brief Get the view widget
 114                  *
 115                  * Can be reimplemented to return this if derived object is a widget
 116                  */
 117                 virtual QWidget *mainWidget() = 0;
 118
 119                 /**
 120                  * @brief Inform the view the message was sent successfully
 121                  *
 122                  * This should be reimplemented as a SLOT in any derived objects
 123                  */
 124                 virtual void messageSentSuccessfully() = 0;
 125
 126                 /**
 127                  * @brief Register a handler for the context menu
 128                  *
 129                  * Plugins should call this slot at view creation to register
 130                  * themselves as handlers for the context menu of this view. Plugins
 131                  * can attach to the viewCreated signal of KopeteMessageManagerFactory
 132                  * to know when views are created.
 133                  *
 134                  * A view does not need to implement this method unless they have context
 135                  * menus that can be extended
 136                  *
 137                  * @param target A target QObject for the contextMenuEvent signal of the view
 138                  * @param slot A slot that matches the signature ( QString&, KMenu *)
 139                  */
 140                 virtual void registerContextMenuHandler( QObject *target, const char*slot ){ Q_UNUSED(target); Q_UNUSED(slot); };
 141
 142                 /**
 143                 * @brief Register a handler for the tooltip
 144                 *
 145                 * Plugins should call this slot at view creation to register
 146                 * themselves as handlers for the tooltip of this view. Plugins
 147                 * can attach to the viewCreated signal of KopeteMessageManagerFactory
 148                 * to know when views are created.
 149                 *
 150                 * A view does not need to impliment this method unless it has the ability
 151                 * to show tooltips
 152                 *
 153                 * @param target A target QObject for the contextMenuEvent signal of the view
 154                 * @param slot A slot that matches the signature ( QString&, KMenu *)
 155                 */
 156                 virtual void registerTooltipHandler( QObject *target, const char*slot ){ Q_UNUSED(target); Q_UNUSED(slot); };
 157
 158                 /**
 159                  * @brief Returns the Kopete::ViewPlugin responsible for this view
 160                  *
 161                  * KopeteView objects are created by plugins. This returns a pointer to the plugin
 162                  * that created this view. You can use this to infer other information on this view
 163                  * and it's capabilities.
 164                  */
 165                 Kopete::ViewPlugin *plugin();
 166
 167         protected:
 168                 /**
 169                  * a pointer to the Kopete::ChatSession given in the constructor
 170                  */
 171                 Kopete::ChatSession *m_manager;
 172                 Kopete::ViewPlugin *m_plugin;
 173 };
 174
 175 #endif