command.h

Go to the documentation of this file.

/**
 * \file <mgui/command.h
 * \brief MGUI::COMMAND_... class definitions
 *
 * \if NODOC
 * $Log: command.h_v $
 * Revision 1.14  2005/03/31 16:57:07  fileserver!dwilliss
 * Rename one of our types to MIUNICODE because it conflicted with a Microsoft #define
 *
 * Revision 1.13  2003/10/03 19:58:19  linux32build!build
 * Doxygen
 *
 * Revision 1.12  2003/09/15 13:49:32  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.11  2003/04/09 20:47:55  dwilliss
 * Don't use _T in templates. Mac's ctype.h defines a global _T
 *
 * Revision 1.10  2002/10/10 14:25:31  mju
 * Exclude everything unless X or MFC.
 *
 * Revision 1.9  2002/10/09 15:43:10  mju
 * Move to 'mgui' folder.
 *
 * Revision 1.8  2002/09/05 21:10:38  dwilliss
 * Actaully implement GetMenuItems() as an inline
 *
 * Revision 1.7  2002/08/13 21:01:21  mju
 * Use mi32 instead of miwin.
 *
 * Revision 1.6  2001/12/13 22:22:27  mju
 * Change reference from DIALOG to DLG.
 *
 * Revision 1.5  2001/12/13 16:58:47  mju
 * Use consistent inclusion guard.
 * Remove references to mguicommand.h as that file includes this one.
 *
 * Revision 1.4  2001/12/13 15:13:17  dwilliss
 * Compiles for both WIN32_NATIVE and X now
 *
 * Revision 1.3  2001/12/04 20:10:56  dwilliss
 * Had a method with no declared return type.
 * MENU has to be a friend of COMMAND_TARGET
 *
 * Revision 1.2  2001/12/04 19:45:48  dwilliss
 * Slight cleanup
 *
 * Revision 1.1  2001/12/04 19:26:26  dwilliss
 * Initial revision
 * \endif
**/

#if !defined(INC_MGUI_COMMAND_H) && (defined(X_NATIVE) || defined(WIN32_MFC))
#define  INC_MGUI_COMMAND_H

#ifdef WIN32_MFC
#ifndef  INC_MI32_STDAFX_H
#include <mi32/stdafx.h>
#endif
class CCmdUI;
#endif

#ifndef  INC_MI32_STDDEFNS_H
#include <mi32/stddefns.h>
#endif

#ifndef  INC_MI32_SIMPLEAR_H
#include <mi32/simplear.h>
#endif

#ifdef X_NATIVE
#ifndef INC_MI32_XDEFNS_H
#include <mi32/xdefns.h>
#endif
#define UINT UINT32  
#endif

namespace MGUI {

class COMMAND_ROUTER;

//------------------------------------------------------------------------------------------------

//! Base class for command target.
//! Command targets must be attached to a COMMAND_ROUTER for command routing.  See the
//! description of COMMAND_ROUTER for more information.
//! Usually the COMMAND_TARGET_T template will be used instead.
class COMMAND_TARGET {
   public:

      enum STATE {
         STATE_UNCHECKED = 0,
         STATE_CHECKED = 1,
         STATE_INDETERMINATE = 2    //!< XXX Can't actually do this in X.  Maybe just use a bool instead?
         };


#ifdef X_NATIVE
      class CMDUI {
         //! OnUpdateUI is called with a pointer to one of these.  It is 
         //! similar to the CCmdUI class in MFC.  In fact, in MFC, CMDUI
         //! is just a typedef alias to CCmdUI
         public:
            //! Enable or disable the user-interface item
            void Enable (
               bool enable = true
               ) {
               m_tgt->Enable(enable);
               }

            //! For toggle buttons, set the current state
            void SetCheck (
               bool check = true
               ) {
               m_tgt->SetCheck(check);
               }

            //! Same as Set Check but for buttons in a radio group.
            //! Note that it does not enforce radio behaviour, as the
            //! MFC version doesn't either.  It is here for completeness.
            void SetRadio (
               bool check = true
               ) {
               SetCheck(check);
               }

            //! Change the text of an item (via resource file lookup)
            void SetText (
               const char* text
               );

            //! Change the text of an item 
            void SetText (
               const MIUNICODE* text
               );
               
         private:
            #ifndef GENERATING_DOXYGEN_OUTPUT
            COMMAND_TARGET* m_tgt;

            //! Private constructor.  Only a COMMAND_TARGET can create one
            CMDUI(COMMAND_TARGET* tgt) :
               m_tgt(tgt) {
               }

            friend class COMMAND_TARGET;
            #endif // GENERATING_DOXYGEN_OUTPUT

         };
      
#endif
#ifdef WIN32_MFC
      #ifndef GENERATING_DOXYGEN_OUTPUT
      //! For MFC, CMDUI _is_ CCmdUI
      typedef class CCmdUI CMDUI;
      #endif // GENERATING_DOXYGEN_OUTPUT
#endif
      //! Constructor.
      //! XXX Not sure what good the NumIDs is in the X world.
      COMMAND_TARGET (
         COMMAND_ROUTER *router = 0,         //!< Router to attach to
         int NumIDs = 1                      //!< Number of sequential command IDs to assign
         );

      //! Destructor.
      virtual ~COMMAND_TARGET (
         );

      //! Attach target to specified router.
      //! Target will be detached from previous router if any.
      void Attach (
         COMMAND_ROUTER *pRouter,            //!< Router to attach to
         int NumIDs = 1                      //!< Number of sequential command IDs to assign
         );

      //! Detach target from router.
      void Detach (
         );

      //! Enable or disable the target.
      //! This will have no effect if you override the OnUpdateUI method.
      void Enable (
         bool enabled = true
         ) { 
#ifdef X_NATIVE
         MxSetSensitive(m_widget, enabled); 
#else
         m_enabled = enabled;
#endif
         }

      //! Get first command ID associated with target.
      UINT16 GetCmdID (
         ) const { return (m_CmdID); }

      //! Returns true if the item is a toggle button and is checked.
      bool GetCheck (
         ) const {
#ifdef X_NATIVE
         if (m_widget != 0) return (XmToggleButtonGetState(m_widget) != 0);
         return (false);
#else
         return (m_state == STATE_CHECKED);
#endif
         }

      //! Returns the current state if the item is a toggle or radio button
      STATE GetState (
         ) const {
#ifdef X_NATIVE
         return (GetCheck() ? STATE_CHECKED : STATE_UNCHECKED);
#else
         return m_state;
#endif
         }

      //! Set the check mark state.
      //! This just calls SetState(), but as long as you don't need the indeterminate state,
      //! a bool is a lot shorter than MGUI::COMMAND_TARGET::STATE_WHATEVER
      //! This will have no effect if you override the OnUpdateUI method.
      //! (And since the X Version doesn't have an indeterminate state, who cares?
      void SetCheck (
         bool check = true
         ) { SetState(check ? STATE_CHECKED : STATE_UNCHECKED); }

      //! Set the check mark state (can be indeterminate)
      //! This is like SetCheck, but takes an enum so you can set it to an indeterminate state.
      //!
      //!   Possible values:
      //!      MGUI::COMMAND_TARGET::STATE_CHECKED
      //!      MGUI::COMMAND_TARGET::STATE_UNCHECKED
      //!      MGUI::COMMAND_TARGET::STATE_INDETERMINATE XXX
      //!
      //! Note, Indeterminate state not available in X
      //! This will have no effect if you override the OnUpdateUI method.
      void SetState (
         STATE state
         ) { 
#ifdef X_NATIVE
         MxToggleButtonSetState(m_widget, (state == STATE_CHECKED), False); 
#else
         m_state = state;
#endif
         }


   protected:

      //! Called by router when command is invoked.
      virtual void OnCommand (
         UINT nID
         ) = 0;

      //! Called by router to update user interface.
      virtual void OnUpdateUI (
         CMDUI* pCmdUI
         );

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT
      UINT16 m_CmdID;
      COMMAND_ROUTER *m_pRouter;
      STATE m_state;
      bool m_enabled;

#ifdef X_NATIVE
      Widget m_widget;

      static void CB_Activate (Widget, void*, void*);
#endif

      //! Called by router to perform attachment.
      void SetRouterAndID (
         COMMAND_ROUTER *pRouter,
         int id
         ) { m_pRouter = pRouter; m_CmdID = (UINT16)id; }

#ifdef X_NATIVE
      void SetWidget (
         Widget widget
         ) { m_widget = widget; }
      
      //! X Implementation only.  Call the OnUpdateIO method.
      void CallOnUpdateUI (
         ) {
         CMDUI cmdui(this);
         OnUpdateUI(&cmdui);
         }
#endif

      // UNIMPLEMENTED / UNSUPPORTED
      COMMAND_TARGET (const COMMAND_TARGET&);
      COMMAND_TARGET& operator= (const COMMAND_TARGET&);

      friend class COMMAND_ROUTER;
#ifdef X_NATIVE
      friend class COMMAND_TARGET::CMDUI;
      friend class MENU;
      #endif // GENERATING_DOXYGEN_OUTPUT
#endif
   };


//------------------------------------------------------------------------------------------------

//! Template command target to allow method(s) in container class to be called for convenience.
template <class _CT> class COMMAND_TARGET_T : public COMMAND_TARGET {
   public:

      //! Constructor.
      COMMAND_TARGET_T (
         _CT *pContainer = 0,                //!< Pointer to callback container class
         void (_CT::*pfOnCommandFunc)(UINT) = 0,      
         void (_CT::*pfOnUpdateUIFunc)(CMDUI*) = 0
         ): m_pContainer(pContainer), m_pfOnCommandFunc(pfOnCommandFunc), m_pfOnUpdateUIFunc(pfOnUpdateUIFunc)
         { }

      //! Set methods to call for command and updating interface.
      void SetFunctions (
         _CT *pContainer,
         void (_CT::*pfOnCommandFunc)(UINT),
         void (_CT::*pfOnUpdateUIFunc)(CMDUI*) = 0
         ) { m_pContainer = pContainer; m_pfOnCommandFunc = pfOnCommandFunc; m_pfOnUpdateUIFunc = pfOnUpdateUIFunc; }

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT
      _CT *m_pContainer;
      void (_CT::*m_pfOnCommandFunc)(UINT);
      void (_CT::*m_pfOnUpdateUIFunc)(CMDUI*);

      //! Called by router when command is invoked.
      virtual void OnCommand (
         UINT nID
         ) { if (m_pfOnCommandFunc != 0) (m_pContainer->*m_pfOnCommandFunc)(nID); }

      //! Called by router to update user interface.
      virtual void OnUpdateUI (
         CMDUI *pCmdUI
         ) { 
         if (m_pfOnUpdateUIFunc != 0) 
            (m_pContainer->*m_pfOnUpdateUIFunc)(pCmdUI); 
         else
            COMMAND_TARGET::OnUpdateUI(pCmdUI);
         }
      #endif // GENERATING_DOXYGEN_OUTPUT

   };


//------------------------------------------------------------------------------------------------

//! Command Router class.
//! To make a window into a command router so that command targets can be contained in it, perform
//! the following steps:
//!
//! 1. Add a COMMAND_ROUTER member to your class.
//!
//!   2. Override the MFC OnCmdMsg() method (inherited from CCmdTarget).
//!
//! 3. (Optional) Add a cast operator from your MFC class to COMMAND_ROUTER*.
//!
//!  For example, if your window is derived from CView, your class will look like:
//! @code
//!      class MYVIEW : public CView {
//!         public:
//!            ...
//!            operator COMMAND_ROUTER* (
//!               ) const { return (&m_CmdRouter); }
//!
//!            virtual BOOL OnCmdMsg (UINT nID, int nCode, void* pExtra, AFX_CMDHANDLERINFO* pHandlerInfo);
//!            ...
//!         private
//!            ...
//!            COMMAND_ROUTER m_CmdRouter;
//!            ...
//!         };
//! @endcode
//!
//! 4. Implement OnCmdMsg() as follows (assuming class named MYVIEW as above).
//!
//! @code
//!      // [Virtual] Dynamically route command messages to targets.
//!      BOOL MYVIEW::OnCmdMsg (
//!         UINT nID,                           // Command ID
//!         int nCode,                          // Notification code
//!         void* pExtra,
//!         AFX_CMDHANDLERINFO* pHandlerInfo
//!         ) {
//!         // Attempt to have command router handle the message.
//!         if (m_CmdRouter.RouteCommandMessage(nID,nCode,pExtra,pHandlerInfo)) return (TRUE);
//!         // If we didn't process the command, call the base class
//!         // version of OnCmdMsg so the message-map can handle the message
//!         return (CView::OnCmdMsg(nID, nCode, pExtra, pHandlerInfo));
//!         }
//! @endcode
//!
//!
//!   Note:  If you're creating a dialog with MGUI::DLG, all this has already been done for you.
//!      An MGUI::DLG has an COMMAND_ROUTER and a cast operator to return a pointer to it.
//!
//!      Note:  For the X version, the COMMAND_ROUTER doesn't really do anything.
//!         It exists in X for two reasons.
//!         1.  To make the X code the same as the MFC code to avoid ugly #ifdefs
//!         2.  Could add an UpdateUI method that would call the OnUpdateUI of all
//!             COMMAND_TARGETS.
class COMMAND_ROUTER {
   public:

      //! Constructor.
      COMMAND_ROUTER (
         );

      //! Destructor.
      ~COMMAND_ROUTER (
         );

   #ifdef WIN32_MFC
      //! Route command message (MFC only).
      //! This must be called by override of OnCmdMsg() in any class which
      //! supports command routing.
      //! @return 'true' if message handled, 'false' if not.
      bool RouteCommandMessage (
         UINT nID,
         int nCode,
         void *pExtra,
         AFX_CMDHANDLERINFO* pHandlerInfo
         );
   #endif

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT
      SIMPLE_ARRAY<COMMAND_TARGET*> m_CmdTargets;

      //! Attach command target to router.
      void AttachTarget (
         COMMAND_TARGET &target,
         int NumIDs
         );

      //! Detach command target from router.
      void DetachTarget (
         COMMAND_TARGET &target
         );

      //! UNIMPLEMENTED / UNSUPPORTED
      COMMAND_ROUTER (const COMMAND_ROUTER&);
      COMMAND_ROUTER& operator= (const COMMAND_ROUTER&);

   friend class COMMAND_TARGET;
      #endif // GENERATING_DOXYGEN_OUTPUT
   };


//------------------------------------------------------------------------------------------------

class MENU 
#ifdef WIN32_MFC
   : public CMenu
#endif
   {
   public:

   #ifdef X_NATIVE
      enum FLAGS {
         FLAG_None = 0,
         FLAG_Selected = MxMENU_SELECTED,
         FLAG_OneOfMany = MxMENU_ONE_OF_MANY,
         FLAG_Toggle = MxMENU_TOGGLE,
         FLAG_Disabled = MxMENU_DISABLED,
         FLAG_Label = MxMENU_LABEL,
         FLAG_Ignore = MxMENU_IGNORE,
         FLAG_Programmer = MxMENU_PROGRAMMER
         };
   #else
      enum FLAGS {
         FLAG_None = 0,
         FLAG_Selected =   0x00000001,
         FLAG_OneOfMany =  0x00000002,
         FLAG_Toggle =     0x00000004,
         FLAG_Disabled =   0x00000008,
         FLAG_Label =      0x00000010,
         FLAG_Ignore =     0x00000020,
         FLAG_Programmer = 0x00000040
         };
   #endif

      MENU();
      ~MENU();

      //! Append an item to the menu.
      //! Note that the flags are ignored in the MFC version
      void Append (
         const char* label,            //!< Label to look up in resource file
         COMMAND_TARGET& target,       //!< Command target to notify on selection
         FLAGS flags = FLAG_None       
         );

      //! Append an item to the menu.
      //! Note that the flags are ignored in the MFC version
      void Append (
         const MIUNICODE* label,       
         COMMAND_TARGET& target,       //!< Command target to notify on selection
         FLAGS flags = FLAG_None
         );

      //! Append a submenu (pull-right) to a menu
      //!
      //! The submenu must already have all its items added and must not
      //! be modified or go out of scope until we're done using it.
      void Append (
         MENU& submenu,                //!< Submenu to add
         const char* label             //!< Label to lookup in resource file
         );

      //! Add a separator to a menu.
      void AppendSeparator (
         );

   #ifdef X_NATIVE   //!< The following methods come from the CMenu base class in MFC version

      //! Used to specify that this is to be a menu bar.
      //! Menu bar can only have other menus as children
      //! Note: in the MFC version, you MUST call this before adding anything.
      //! In the X version, this really does nothing and is just here for
      //! completeness.
      void CreateMenu() {}

      //! Used to specify that this is to be a popup menu.
      //! This includes menus on a menu bar.
      //! Note: in the MFC version, you MUST call this before adding anything.
      //! In the X version, this really does nothing and is just here for
      //! completeness.
      void CreatePopupMenu() {}

      //! Get the array of MENUITEMS for menu creation
      //! X version only.
      MENUITEM* GetMenuItems (
         ) {
         return (m_items);
         }

      //! Pop up a popup menu (X Version).
      //! The function is named to match the MFC version that does the same
      //! thing, although the parameters are not the same.
      void TrackPopupMenu (
         Widget parent,
         XButtonEvent* event
         );

   #endif

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT

   #ifdef X_NATIVE   
      SIMPLE_ARRAY<MENUITEM> m_items;
      Widget m_popup;   //!< Used by TrackPopupMenu

      void Append(const MENUITEM&);

   #endif
      #endif // GENERATING_DOXYGEN_OUTPUT
   };



//------------------------------------------------------------------------------------------------

}  //! End of MGUI namespace

typedef  MGUI::COMMAND_TARGET    MGUI_COMMAND_TARGET;
typedef  MGUI::COMMAND_ROUTER    MGUI_COMMAND_ROUTER;

#define  MGUI_COMMAND_TARGET_T   MGUI::COMMAND_TARGET_T

DEFINE_ENUM_OPERATORS(MGUI::MENU::FLAGS);

#endif   // INC_MGUI_COMMAND_H

---