appmain.h

Go to the documentation of this file.

/**
 * \file mgui/appmain.h
 * \brief Definitions for MGUI::APP_MAIN and MGUI::APP_BASE classes
 *
 * \if NODOC
 * $Id: appmain.h_v 1.11 2004/02/26 16:24:05 mju Exp $
 *
 * $Log: appmain.h_v $
 * Revision 1.11  2004/02/26 16:24:05  mju
 * Make app_base dtor virtual.
 *
 * Revision 1.10  2004/02/12 16:20:19  mju
 * Update comment for app_base relating to construction via 'new'.
 *
 * Revision 1.9  2004/01/08 17:58:40  mju
 * Remove bad comment.
 *
 * Revision 1.8  2003/10/03 19:58:19  linux32build!build
 * Doxygen
 *
 * Revision 1.7  2003/09/15 13:49:32  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.6  2003/09/02 17:41:39  scowan
 * Fixed for win32 native.
 *
 * Revision 1.5  2003/07/29 16:33:30  mju
 * Add SetLegacyAllowShellResize.
 *
 * Revision 1.4  2003/07/15 17:05:47  dwilliss
 * Fixed to compile on Unix
 *
 * Revision 1.3  2003/05/14 20:50:57  mju
 * Add GetBaseInstance.
 *
 * Revision 1.2  2003/04/28 16:52:17  mju
 * Add OnTerminate.
 *
 * Revision 1.1  2003/04/23 21:59:55  mju
 * Initial revision
 *
 * \endif
**/

#ifndef  INC_MGUI_APPMAIN_H
#define  INC_MGUI_APPMAIN_H

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

#ifndef _XtIntrinsic_h
   #include <X11/Intrinsic.h>
#endif

struct McbAnyCallbackStruct;

namespace MGUI {

class APP_MAIN;

//! Base class for application process instance.
//! A class derived from this must be constructed by a class derived from APP_MAIN,
//! either in v_InitInstance or in its constructor.  Failure to follow this
//! convention will result in an exception during application startup or shutdown.
//! Note that this is handled automatically for applications based on MGUI::APP_MULTI.
class APP_BASE {
   public:

   #ifdef X_NATIVE
      enum LEGACYINIT {
         LEGACYINIT_Default =             0x00,
         LEGACYINIT_NoSetPosition =       0x01, //!< Don't automatically set position
         LEGACYINIT_NoSetTitle =          0x02, //!< Don't automatically set title
         LEGACYINIT_NoRealize =           0x04, //!< Don't 'realize' toplevel application shell after InitInstance
         LEGACYINIT_NoAutoSetExit =       0x08, //!< Don't do MxSetExitProcess() when toplevel shell 'closed' via Window Manager
         LEGACYINIT_LockShellSize =       0x10, //!< Lock toplevel shell size after realizing
         LEGACYINIT_NoDestroyTopOnExit =  0x20  //!< Don't destroy TopLevel shell on exit as application destroys it
         };
   #endif

      //! Get number of command-line parameters.
      inline int GetCmdParmCount () const;

      //! Get command-line parameter for specified index.
      inline const char* GetCmdParm (
         int idx                       //!< Command parameter index
         ) const;

   protected:

      //! Constructor.
      APP_BASE (
         UINT32 AllowedProduct1 = 0,      //!< Product code for license checking
         UINT32 AllowedProduct2 = 0,
         UINT32 AllowedProduct3 = 0,
         UINT32 AllowedProduct4 = 0
         );

      //! Destructor
      virtual ~APP_BASE ();

   #ifdef X_NATIVE
      //! Perform legacy initialization for processes using TopLevel shell (X only).
      //! Replaces MxInitProc(), should call from within v_InitInstance().
      //! @return Unrealized TopLevel shell.
      Widget MxInitLegacy (LEGACYINIT flags = LEGACYINIT_Default);
   #endif

   #ifdef X_NATIVE
      //! Set to allow resize of legacy toplevel shell.
      //! Must be done in derived class constructor.
      //! Required for some applications which need to dynamically grow the legacy toplevel shell.
      void SetLegacyAllowShellResize (
         ) { m_LegacyAllowShellResize = true; }
   #endif

   private:

      #ifndef GENERATING_DOXYGEN_OUTPUT

   #ifdef X_NATIVE
      LEGACYINIT m_LegacyInitFlags;
      bool m_LegacyAllowShellResize;
   #endif
      UINT32 m_ProductCode;
      UINT32 m_AllowedProducts[4];

      UINT32 DetermineProductCode ()
         { return (v_DetermineProductCode()); }
      void ExitInstance ();
      const char* GetProcessName () const
         { return (v_GetProcessName()); }
      bool InitInstance ();
      bool IsProductAllowed (UINT32) const;

      friend class MGUI::APP_MAIN;

      APP_BASE (const APP_BASE&);
      APP_BASE& operator= (const APP_BASE&);

      #endif // GENERATING_DOXYGEN_OUTPUT

      // Overridables.

      //! Override to determine product code for license check.
      //! Default implementation determines product code based on command
      //! line parameters and initialization settings.  Not normally overridden.
      virtual UINT32 v_DetermineProductCode () const;

      //! Override to perform resource cleanup prior to application exit.
      virtual void v_ExitInstance ();

      //! Must be overridden to return 'process name' for use as 'INI group' and 'registry subkey'.
      //! Should return character string having no whitespace.
      virtual const char* v_GetProcessName () const = 0;

      //! Must be overridden to perform initialization of this application.
      //! Initialization normally includes creation of primary user interface
      //! windows prior to entering main message handling loop.
      //! @return 'true' if successful, 'false' if not (will exit if false).
      virtual bool v_InitInstance () = 0;
   };
#ifdef X_NATIVE
DEFINE_ENUM_OP_BITWISE(APP_BASE::LEGACYINIT);
#endif


//! Base class for main application instance.
//! A class must be derived from APP_MAIN and a single instance must be
//! declared at file (static global) scope in the main application module.
//! Only one instance of this class may be defined per executable.
//! See also: APP_BASE.
class APP_MAIN {
   public:

      //! Terminate the event loop and exit application normally.
      static void Exit () { s_pMainInstance->DoExit(); }

      //! Get reference to the single APP_BASE instance for this executable.
      static APP_BASE* GetBaseInstance ()
         { return (s_pBaseInstance); }

      //! Get reference to the single APP_MAIN instance for this executable.
      static APP_MAIN* GetMainInstance ()
         { return (s_pMainInstance); }

      //! Constructor.
      APP_MAIN ();

      //! Destructor.
      virtual ~APP_MAIN () = 0;

      //! Get number of command-line parameters.
      int GetCmdParmCount () const
         { return (m_CmdParmCount); }

      //! Get command-line parameter for specified index.
      const char* GetCmdParm (
         int idx                       //!< Command parameter index
         ) const { return ((idx < 0 || idx >= m_CmdParmCount) ? NULL : m_CmdParmArray[idx]); }

   #ifdef WIN32
      //! Get Windows application instance handle (Windows only).
      void *GetInstanceHandle () const
         { return (m_hInstance); }
   #endif

      //! Remove command-line parameter at specified index.
      //! Note, idx must be > 0 as first entry cannot be removed.
      void RemoveCmdParm (
         int idx
         );

      #ifndef GENERATING_DOXYGEN_OUTPUT
   #if defined(WIN32) && !defined(WIN32_NATIVE)
      void DoWinMain (void *hInstance, const char *cmdline);
   #else
      // These should be private, but then main() can't access them.  I tried
      // friend int main(int, char**), but it didn't help.
      void Run();
      void SetCmdParms (const char**, int);
   #endif
      #endif // GENERATING_DOXYGEN_OUTPUT

   private:

      #ifndef GENERATING_DOXYGEN_OUTPUT

      static APP_MAIN *s_pMainInstance;
      static APP_BASE *s_pBaseInstance;
   #ifdef WIN32
      void *m_hInstance;
      char *m_ModNameStr;
      char *m_CmdLineStr;
   #endif
      char **m_CmdParmArray;
      int m_CmdParmCount;

      void DoExit ();
      void ExitInstance ();
      bool InitInstance ();
      static void OnExitXServer (McbAnyCallbackStruct*, void*);
      static void OnTerminate ();
   #if defined(WIN32) && !defined(WIN32_NATIVE)
      void Run ();
      void SetCmdLine (const char*);
   #endif

      friend class MGUI::APP_BASE;

      APP_MAIN (const APP_MAIN&);
      APP_MAIN& operator= (const APP_MAIN&);

      #endif // GENERATING_DOXYGEN_OUTPUT

      // Overridables.

      //! Called just prior to application exit.
      //! May be overridden to clean up allocated instance resource.
      virtual void v_ExitInstance ();

      //! Called at application startup.
      //! Normally overridden if multiple 'processes' are built into a single executable.
      //! In this case the command line parameters may be processed to determine which
      //! process to invoke and call a function or method to create a static instance of
      //! a derived APP_BASE class for that process.
      virtual bool v_InitInstance ();
   };


#ifndef GENERATING_DOXYGEN_OUTPUT

//! Get number of command-line parameters.
inline int APP_BASE::GetCmdParmCount (
   ) const {
   APP_MAIN *pMain = APP_MAIN::GetMainInstance();
   return ((pMain == 0) ? 0 : pMain->GetCmdParmCount());
   }

//! Get command-line parameter for specified index.
inline const char* APP_BASE::GetCmdParm (
   int idx                       //!< Command parameter index
   ) const {
   APP_MAIN *pMain = APP_MAIN::GetMainInstance();
   return ((pMain == 0) ? 0 : pMain->GetCmdParm(idx));
   }

#endif // GENERATING_DOXYGEN_OUTPUT

}  // End namespace MGUI

#endif   // INC_MGUI_APPMAIN_H

---