kopete/libkopete/kopetecommandhandler.h

   1 /*
   2     kopetecommandhandler.h - Command Handler
   3
   4     Copyright (c) 2003      by Jason Keirstead       <jason@keirstead.org>
   5     Kopete    (c) 2002-2003 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
  17 #ifndef _KOPETECOMMANDHANDLER_H_
  18 #define _KOPETECOMMANDHANDLER_H_
  19
  20 #include <QtCore/QMultiHash>
  21
  22 #include <kshortcut.h>
  23 #include "kopetemessage.h"
  24
  25 #include "kopete_export.h"
  26
  27 class K3Process;
  28
  29 struct CommandHandlerPrivate;
  30
  31 class KopeteView;
  32 class KopeteCommandGUIClient;
  33
  34 namespace Kopete
  35 {
  36
  37 class ChatSession;
  38 class Plugin;
  39 class Protocol;
  40 class Command;
  41
  42 typedef QMultiHash<QString, Command*> CommandList;
  43
  44 /**
  45  * @author Jason Keirstead   <jason@keirstead.org>
  46  *
  47  * The Kopete::CommandHandler can handle /action like messages
  48  */
  49 class KOPETE_EXPORT CommandHandler : public QObject
  50 {
  51         friend class ::KopeteCommandGUIClient;
  52
  53         Q_OBJECT
  54
  55         public:
  56                 /**
  57                  * an enum defining the type of a command
  58                  */
  59                 enum CommandType { Normal, SystemAlias, UserAlias, Undefined };
  60
  61                 /**
  62                  * Returns a pointer to the command handler
  63                  */
  64                 static CommandHandler *commandHandler();
  65
  66                 /**
  67                  * \brief Register a command with the command handler.
  68                  *
  69                  * Command matching is case insensitive. All commands are registered,
  70                  * regardless of whether  or not they are already handled by another
  71                  * handler. This is so that if the first plugin is unloaded, the next
  72                  * handler in the sequence will handle the command. However, there are
  73                  * certain commands which are reserved (internally handled by the
  74                  * Kopete::CommandHandler). These commands can also be overridden by
  75                  * registering a new duplicate command.
  76                  *
  77                  * @param parent The plugin who owns this command
  78                  * @param command The command we want to handle, not including the '/'
  79                  * @param handlerSlot The slot used to handle the command. This slot must
  80                  *   accept two parameters, a QString of arguments, and a Kopete::ChatSession
  81                  *   pointer to the manager under which the command was sent.
  82                  * @param help An optional help string to be shown when the user uses
  83                  *   /help \<command\>
  84                  * @param minArgs the minimum number of arguments for this command
  85                  * @param maxArgs the maximum number of arguments this command takes
  86                  * @param cut a default keyboard shortcut
  87                  * @param pix icon name, the icon will be shown in menus
  88                  */
  89                 void registerCommand( QObject *parent, const QString &command, const char* handlerSlot,
  90                         const QString &help = QString(), uint minArgs = 0, int maxArgs = -1,
  91                         const KShortcut &cut = KShortcut(), const QString &pix = QString() );
  92
  93                 /**
  94                  * \brief Register a command alias.
  95                  *
  96                  * @param parent The plugin who owns this alias
  97                  * @param alias The command for the alias
  98                  * @param formatString This is the string that will be transformed into another
  99                  *    command. The formatString should begin with an already existing command,
 100                  *    followed by any other arguments. The variables %1, %2... %9 will be substituted
 101                  *    with the arguments passed into the alias. The variable %s will be substituted with
 102                  *    the entire argument string
 103                  * @param help An optional help string to be shown when the user uses
 104                  *   /help \<command\>
 105                  * @param minArgs the minimum number of arguments for this command
 106                  * @param maxArgs the maximum number of arguments this command takes
 107                  * @param cut a default keyboard shortcut
 108                  * @param pix icon name, the icon will be shown in menus
 109                  */
 110                 void registerAlias( QObject *parent,
 111                         const QString &alias,
 112                         const QString &formatString,
 113                         const QString &help = QString(),
 114                         CommandType = SystemAlias,
 115                         uint minArgs = 0,
 116                         int maxArgs = -1,
 117                         const KShortcut &cut = KShortcut(),
 118                         const QString &pix = QString() );
 119
 120                 /**
 121                  * \brief Unregister a command.
 122                  *
 123                  * When a plugin unloads, all commands are automaticlly unregistered and deleted.
 124                  * This function should only be called in the case of a plugin which loads and
 125                  * unloads commands dynamically.
 126                  *
 127                  * @param parent The plugin who owns this command
 128                  * @param command The command to unload
 129                  */
 130                 void unregisterCommand( QObject *parent, const QString &command );
 131
 132                 /**
 133                  * \brief Unregister an alias.
 134                  *
 135                  * \see unregisterCommand( QObject *parent, const QString &command )
 136                  * @param parent The plugin who owns this alias
 137                  * @param alias The alais to unload
 138                  */
 139                 void unregisterAlias( QObject *parent, const QString &alias );
 140
 141                 /**
 142                  * \brief Process a message to see if any commands should be handled
 143                  *
 144                  * @param msg The message to process
 145                  * @param manager The manager who owns this message
 146                  * @return True if the command was handled, false if not
 147                  */
 148                 bool processMessage( Message &msg, ChatSession *manager );
 149
 150                 /**
 151                  * \brief Process a message to see if any commands should be handled
 152                  *
 153                  * \see processMessage( Kopete::Message &msg, Kopete::ChatSession *manager)
 154                  * \param msg A QString contain the message
 155                  * \param manager the Kopete::ChatSession who will own the message
 156                  * \return true if the command was handled, false if the command was not handled.
 157                  */
 158                 bool processMessage( const QString &msg, ChatSession *manager );
 159
 160                 /**
 161                  * Parses a string of command arguments into a QStringList. Quoted
 162                  * blocks within the arguments string are treated as one argument.
 163                  */
 164                 static QStringList parseArguments( const QString &args );
 165
 166                 /**
 167                  * \brief Check if a command is already handled
 168                  *
 169                  * @param command The command to check
 170                  * @return True if the command is already being handled, False if not
 171                  */
 172                 bool commandHandled( const QString &command );
 173
 174                 /**
 175                  * \brief Check if a command is already handled by a spesific protocol
 176                  *
 177                  * @param command The command to check
 178                  * @param protocol The protocol to check
 179                  * @return True if the command is already being handled, False if not
 180                  */
 181                 bool commandHandledByProtocol( const QString &command, Protocol *protocol);
 182
 183         private slots:
 184                 void slotPluginLoaded( Kopete::Plugin * );
 185                 void slotPluginDestroyed( QObject * );
 186                 void slotExecReturnedData(K3Process *proc, char *buff, int bufflen );
 187                 void slotExecFinished(K3Process *proc);
 188                 void slotViewCreated( KopeteView *view );
 189
 190                 void slotHelpCommand( const QString & args, Kopete::ChatSession *manager );
 191                 void slotClearCommand( const QString & args, Kopete::ChatSession *manager );
 192                 void slotPartCommand( const QString & args, Kopete::ChatSession *manager );
 193                 void slotCloseCommand( const QString & args, Kopete::ChatSession *manager );
 194                 //void slotMeCommand( const QString & args, Kopete::ChatSession *manager );
 195                 void slotExecCommand( const QString & args, Kopete::ChatSession *manager );
 196                 void slotAwayCommand( const QString & args, Kopete::ChatSession *manager );
 197                 void slotAwayAllCommand( const QString & args, Kopete::ChatSession *manager );
 198                 void slotSayCommand( const QString & args, Kopete::ChatSession *manager );
 199
 200         private:
 201                 /**
 202                  * Helper function. Returns all the commands that can be used by a KMM of this protocol
 203                  * (all non-protocol commands, plus this protocols commands)
 204                  */
 205                 CommandList commands( Protocol * );
 206
 207                 /**
 208                  * Helper function for commands()
 209                  */
 210                 void addCommands( CommandList &from, CommandList &to, CommandType type = Undefined );
 211
 212                 CommandHandler();
 213                 ~CommandHandler();
 214
 215                 static CommandHandlerPrivate *p;
 216 };
 217
 218 }
 219
 220 #endif