include/pwlib/commands.h

   1 /*
   2  * commands.h
   3  *
   4  * User command processing classes.
   5  *
   6  * Portable Windows Library
   7  *
   8  * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
   9  *
  10  * The contents of this file are subject to the Mozilla Public License
  11  * Version 1.0 (the "License"); you may not use this file except in
  12  * compliance with the License. You may obtain a copy of the License at
  13  * http://www.mozilla.org/MPL/
  14  *
  15  * Software distributed under the License is distributed on an "AS IS"
  16  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
  17  * the License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * The Original Code is Portable Windows Library.
  21  *
  22  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
  23  *
  24  * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
  25  * All Rights Reserved.
  26  *
  27  * Contributor(s): ______________________________________.
  28  *
  29  * $Log$
  30  * Revision 1.11  1999/03/10 03:49:51  robertj
  31  * More documentation adjustments.
  32  *
  33  * Revision 1.10  1999/03/09 08:01:48  robertj
  34  * Changed comments for doc++ support (more to come).
  35  *
  36  * Revision 1.9  1999/02/16 08:08:45  robertj
  37  * MSVC 6.0 compatibility changes.
  38  *
  39  * Revision 1.8  1998/10/15 05:41:32  robertj
  40  * New memory leak check code.
  41  *
  42  * Revision 1.7  1998/09/23 06:23:11  robertj
  43  * Added open source copyright license.
  44  *
  45  * Revision 1.6  1997/07/08 13:02:07  robertj
  46  * DLL support.
  47  *
  48  * Revision 1.5  1996/08/17 10:00:30  robertj
  49  * Changes for Windows DLL support.
  50  *
  51  * Revision 1.4  1995/10/14 14:54:37  robertj
  52  * Fixed bug in command value callback.
  53  *
  54  * Revision 1.3  1995/06/17 11:12:25  robertj
  55  * Documentation update.
  56  *
  57  * Revision 1.2  1995/03/14 12:41:11  robertj
  58  * Updated documentation to use HTML codes.
  59  *
  60  * Revision 1.1  1995/02/21  11:24:57  robertj
  61  * Initial revision
  62  *
  63  */
  64
  65 #ifndef _PCOMMANDS
  66 #define _PCOMMANDS
  67
  68 #ifdef __GNUC__
  69 #pragma interface
  70 #endif
  71
  72
  73 ///////////////////////////////////////////////////////////////////////////////
  74 // PCommandSink
  75
  76 /**This class represents a command sink. This works in conjunction with the
  77    \Ref{PCommandSource} and \Ref{PCommandManager} classes to implement
  78    dynamically bound commands on \Ref{PTopLevelWindow} or \Ref{PMDIDocWindow}
  79    classes.
  80
  81    The user does not directly create descendents of this abstract class. These
  82    are created by a series of macros that are used in the declaration of the
  83    users \Ref{PTopLevelWindow} or \Ref{PMDIDocWindow} class descendent.
  84
  85    To create a command sink, use one of the following macros:
  86       \Ref{PDECLARE_COMMAND_X}
  87       \Ref{PDECLARE_COMMAND_XE}
  88       \Ref{PDECLARE_COMMAND_XS}
  89       \Ref{PDECLARE_COMMAND_XES}
  90       \Ref{PDECLARE_COMMAND}
  91       \Ref{PDECLARE_COMMAND_ENABLE}
  92       \Ref{PDECLARE_COMMAND_VALUE}
  93       \Ref{PDECLARE_COMMAND_FULL}
  94  */
  95 class PCommandSink : public PObject
  96 {
  97   PCLASSINFO(PCommandSink, PObject);
  98
  99   public:
 100    /**This constructor is used for instances created by the declaration macros
 101        within the window class. There is actually no instance data it is merely
 102        a place holder for the virtual function call.
 103      */
 104     PCommandSink() { }
 105
 106    /**Execute the command. The overridden version of this function will
 107        execute the member function on the #wind# parameter. The
 108        override and code to do this is generated by the command declaration
 109        macros.
 110      */
 111     virtual void Execute(
 112       PTitledWindow * wind  /// Window instance to receive the command.
 113     ) const  = 0;
 114
 115    /**Determine the commands enable state. The overridden version of this
 116        function will execute the member function on the #wind#
 117        parameter. The override and code to do this is generated by the command
 118        declaration macros.
 119      */
 120     virtual BOOL Enabled(
 121       PTitledWindow * wind  /// Window instance to receive the command.
 122     ) const;
 123
 124    /**Determine the commands value state. The overridden version of this
 125        function will execute the member function on the #wind#
 126        parameter. The override and code to do this is generated by the command
 127        declaration macros.
 128      */
 129     virtual PINDEX Value(
 130       PTitledWindow * wind  /// Window instance to receive the command.
 131     ) const;
 132
 133
 134   protected:
 135    /**Register the command name which is attached to the specific window
 136        class. This allows the same command, eg "save", to have a different
 137        implementation depending on the class of the window, eg when several
 138        different types of MDI child window are used.
 139      */
 140     PCommandSink(
 141       const char * className,
 142      /**Name of the window class that the command sink descendent was
 143          declared within.
 144        */
 145       const char * commandName /// Arbitrary name of the command.
 146     );
 147 };
 148
 149
 150 #define PDECLARE_COMMAND_START(name, cls, func) \
 151   class func##_PCommand : public PCommandSink { \
 152     public: \
 153       func##_PCommand() \
 154         { PNEW func##_PCommand(cls::Class(), name); } \
 155       func##_PCommand(const char * className, const char * commandName) \
 156         : PCommandSink(className, commandName) { } \
 157       virtual void Execute(PTitledWindow * wind) const \
 158         { ((cls*)wind)->func(); } \
 159
 160 #define PDECLARE_COMMAND_END(func) \
 161   } func##_PCommandInstance; \
 162   friend class func##_PCommand
 163
 164
 165 /**Declare a command.
 166   This macro declares a descendent class of \Ref{PCommandSink} which is
 167   attached to a \Ref{PTopLevelWindow} or \Ref{PMDIDocWindow} instance.
 168
 169   This version only allows the command to be executed. It is assumed that the
 170   command is always enabled and has a value state of zero.
 171
 172   This version also assumes the member function #func# is declared
 173   elsewhere.
 174 */
 175 #define PDECLARE_COMMAND_X(name, cls, func) \
 176   PDECLARE_COMMAND_START(name, cls, func) \
 177   PDECLARE_COMMAND_END(func)
 178
 179 /**Declare a command.
 180   This macro declares a descendent class of \Ref{PCommandSink} which is
 181   attached to a \Ref{PTopLevelWindow} or \Ref{PMDIDocWindow} instance.
 182
 183   This version allows the command to be executed and use a function to
 184   detemine if it is currently enabled. It is assumed that the command always
 185   has a value state of zero.
 186
 187   This version also assumes the member functions #func# and
 188   #enab# are declared elsewhere.
 189 */
 190 #define PDECLARE_COMMAND_XE(name, cls, func, enab) \
 191   PDECLARE_COMMAND_START(name, cls, func) \
 192     virtual BOOL Enabled(PTitledWindow * wind) const \
 193       { return ((cls*)wind)->enab(); } \
 194   PDECLARE_COMMAND_END(func)
 195
 196 /**Declare a command.
 197   This macro declares a descendent class of \Ref{PCommandSink} which is
 198   attached to a \Ref{PTopLevelWindow} or \Ref{PMDIDocWindow} instance.
 199
 200   This version allows the command to be executed and use a function to
 201   detemine its current value state. It is assumed that the command is always
 202   enabled.
 203
 204   This version also assumes the member functions #func# and
 205   #val# are declared elsewhere.
 206 */
 207 #define PDECLARE_COMMAND_XS(name, cls, func, val) \
 208   PDECLARE_COMMAND_START(name, cls, func) \
 209     virtual PINDEX Value(PTitledWindow * wind) const \
 210       { return ((cls*)wind)->val(); } \
 211   PDECLARE_COMMAND_END(func)
 212
 213 /**Declare a command.
 214   This macro declares a descendent class of \Ref{PCommandSink} which is
 215   attached to a \Ref{PTopLevelWindow} or \Ref{PMDIDocWindow} instance.
 216
 217   This version allows the command to be executed, use a function to detemine if
 218   it is enabled and use a function to detemine its current value state.
 219
 220   This version also assumes the member functions #func#,
 221   #enab# and #val# are declared elsewhere.
 222 */
 223 #define PDECLARE_COMMAND_XES(name, cls, func, enab, val) \
 224   PDECLARE_COMMAND_START(name, cls, func) \
 225     virtual BOOL Enabled(PTitledWindow * wind) const \
 226       { return ((cls*)wind)->enab(); } \
 227     virtual PINDEX Value(PTitledWindow * wind) const \
 228       { return ((cls*)wind)->val(); } \
 229   PDECLARE_COMMAND_END(func)
 230
 231 /**Declare a command.
 232   This macro declares a descendent class of \Ref{PCommandSink} which is
 233   attached to a \Ref{PTopLevelWindow} or \Ref{PMDIDocWindow} instance.
 234
 235   This version only allows the command to be executed. It is assumed that the
 236   command is always enabled and has a value state of zero.
 237
 238   This version also declares the member function #func#.
 239 */
 240 #define PDECLARE_COMMAND(name, cls, func) \
 241   virtual void func(); \
 242   PDECLARE_COMMAND_X(name, cls, func) \
 243
 244 /**Declare a command.
 245   This macro declares a descendent class of \Ref{PCommandSink} which is
 246   attached to a \Ref{PTopLevelWindow} or \Ref{PMDIDocWindow} instance.
 247
 248   This version allows the command to be executed, and use a function to
 249   detemine if it is currently enabled. It is assumed that the command always
 250   has a value state of zero.
 251
 252   This version also declares the member functions #func# and
 253   #enab#.
 254 */
 255 #define PDECLARE_COMMAND_ENABLE(name, cls, func, enab) \
 256   virtual void func(); \
 257   virtual BOOL enab(); \
 258   PDECLARE_COMMAND_XE(name, cls, func, enab)
 259
 260 /**Declare a command.
 261   This macro declares a descendent class of \Ref{PCommandSink} which is
 262   attached to a \Ref{PTopLevelWindow} or \Ref{PMDIDocWindow} instance.
 263
 264   This version allows the command to be executed and use a function to
 265   detemine its current value state. It is assumed that the command is always
 266   enabled.
 267
 268   This version also declares the member functions #func# and
 269   #val#.
 270 */
 271 #define PDECLARE_COMMAND_VALUE(name, cls, func, val) \
 272   virtual void func(); \
 273   virtual PINDEX val(); \
 274   PDECLARE_COMMAND_XS(name, cls, func, val)
 275
 276 /**Declare a command.
 277   This macro declares a descendent class of \Ref{PCommandSink} which is
 278   attached to a \Ref{PTopLevelWindow} or \Ref{PMDIDocWindow} instance.
 279
 280   This version allows the command to be executed, use a function to detemine if
 281   it is enabled and use a function to detemine its current value state.
 282
 283   This version also declares the member functions #func#,
 284   #enab# and #val#.
 285 */
 286 #define PDECLARE_COMMAND_FULL(name, cls, func, enab, val) \
 287   virtual void func(); \
 288   virtual BOOL enab(); \
 289   virtual PINDEX val(); \
 290   PDECLARE_COMMAND_XES(name, cls, func, enab, val)
 291
 292
 293
 294 ///////////////////////////////////////////////////////////////////////////////
 295 // PCommandSource
 296
 297 /**This class represents a command source. This works in conjunction with the
 298    \Ref{PCommandSink} and \Ref{PCommandManager} classes to implement
 299    dynamically bound commands on \Ref{PTopLevelWindow} or \Ref{PMDIDocWindow}
 300    classes.
 301
 302    The user does not directly create descendents of this class. Instances of
 303    this class are created by the \Ref{PCREATE_COMMAND} macro. These are
 304    instances of the \Ref{PNotifier} class and may be attached to
 305    \Ref{PMenuItem} or \Ref{PControl} instances via the
 306    \Ref{PControl::SetNotifier()} function in the same way as other callback
 307    functions.
 308  */
 309 class PCommandSource : public PNotifierFunction
 310 {
 311   PCLASSINFO(PCommandSource, PNotifierFunction);
 312
 313   public:
 314    /**Create a command source notifier that will connect a \Ref{PCommandSink}
 315        using the same command name string.
 316      */
 317     PCommandSource(
 318       const char * commandName    /// Name of the command to call.
 319     );
 320
 321    /**Notifier class callback function. This will connect to the
 322        \Ref{PCommandSink} of the same command name by using the information in
 323        the \Ref{PCommandManager} instance contained in the \Ref{PApplication}
 324        descendent instance.
 325
 326        The appropriate callback function, execute, enable or value is called
 327        according to the value of the #extra# field.
 328      */
 329     virtual void Call(
 330       PObject & notifier,   /// Object executing the notification.
 331       INT extra             /// Extra information about the notification.
 332     ) const;
 333
 334   protected:
 335     /** Name of the command to execute. */
 336     PString name;
 337 };
 338
 339
 340 /**Create command instance.
 341   This macro creates an instance of the \Ref{PCommandSource} smart pointer.
 342   This may be passed to any command source, eg menu item, which accepts a
 343   \Ref{PNotifier} instance.
 344 */
 345 #define PCREATE_COMMAND(name) PNotifier(new PCommandSource(name))
 346
 347
 348 ///////////////////////////////////////////////////////////////////////////////
 349 // PCommandManager
 350
 351 /**This class represents a manager for command sources and sinks. This works in
 352    conjunction with the \Ref{PCommandSink} and \Ref{PCommandSource} classes
 353    to implement dynamically bound commands on \Ref{PTopLevelWindow} or
 354    \Ref{PMDIDocWindow} classes.
 355
 356    The \Ref{PApplication} class contains a single instance of this class. This
 357    will contain all of the registered command sinks. When a command source
 358    executes a command, this database is consulted to locate the command sink
 359    that will actually execute the command functions.
 360  */
 361 class PCommandManager : public PObject
 362 {
 363   PCLASSINFO(PCommandManager, PObject);
 364   public:
 365     /** Register the command sink. */
 366     void Register(
 367       const char * className,
 368      /**Name of the \Ref{PTitledWindow} class the \Ref{PCommandSink} is
 369          declared in.
 370        */
 371       const char * commandName,  /// Name of the command.
 372       PCommandSink * sink
 373     );
 374
 375    /**Locate the command sink that was registered with the specified
 376        attributes.
 377      */
 378     PCommandSink * Find(
 379       const PString & className,
 380      /**Name of the \Ref{PTitledWindow} class the \Ref{PCommandSink} is
 381          declared in.
 382        */
 383       const PString & commandName  /// Name of the command.
 384     );
 385
 386   private:
 387     PDICTIONARY(CommandsByName, PString, PCommandSink);
 388     PDICTIONARY(CommandsByClass, PString, CommandsByName);
 389     CommandsByClass commands;
 390 };
 391
 392
 393 #endif  /// _PCOMMANDS
 394
 395
 396 // End Of File ///////////////////////////////////////////////////////////////