interface/module.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        module.h
   3 // Purpose:     interface of wxModule
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxModule
  11     @wxheader{module.h}
  12
  13     The module system is a very simple mechanism to allow applications (and parts
  14     of wxWidgets itself) to define initialization and cleanup functions that are
  15     automatically called on wxWidgets startup and exit.
  16
  17     To define a new kind of module, derive a class from wxModule, override the
  18     wxModule::OnInit and wxModule::OnExit
  19     functions, and add the DECLARE_DYNAMIC_CLASS and IMPLEMENT_DYNAMIC_CLASS to
  20     header and implementation files (which can be the same file). On
  21     initialization, wxWidgets will find all classes derived from wxModule, create
  22     an instance of each, and call each OnInit function. On exit, wxWidgets will
  23     call the OnExit function for each module instance.
  24
  25     Note that your module class does not have to be in a header file.
  26
  27     For example:
  28
  29     @code
  30     // A module to allow DDE initialization/cleanup
  31       // without calling these functions from app.cpp or from
  32       // the user's application.
  33       class wxDDEModule: public wxModule
  34       {
  35       public:
  36           wxDDEModule() { }
  37           virtual bool OnInit() { wxDDEInitialize(); return @true; };
  38           virtual void OnExit() { wxDDECleanUp(); };
  39
  40       private:
  41           DECLARE_DYNAMIC_CLASS(wxDDEModule)
  42       };
  43
  44       IMPLEMENT_DYNAMIC_CLASS(wxDDEModule, wxModule)
  45
  46       // Another module which uses DDE in its OnInit()
  47       class MyModule: public wxModule
  48       {
  49       public:
  50           MyModule() { AddDependency(CLASSINFO(wxDDEModule)); }
  51           virtual bool OnInit() { ... code using DDE ... }
  52           virtual void OnExit() { ... }
  53
  54       private:
  55           DECLARE_DYNAMIC_CLASS(MyModule)
  56       };
  57
  58       IMPLEMENT_DYNAMIC_CLASS(MyModule, wxModule)
  59
  60       // Another module which uses DDE in its OnInit()
  61       // but uses a named dependency
  62       class MyModule2: public wxModule
  63       {
  64       public:
  65           MyModule2() { AddDependency("wxDDEModule"); }
  66           virtual bool OnInit() { ... code using DDE ... }
  67           virtual void OnExit() { ... }
  68
  69       private:
  70           DECLARE_DYNAMIC_CLASS(MyModule2)
  71       };
  72
  73       IMPLEMENT_DYNAMIC_CLASS(MyModule2, wxModule)
  74     @endcode
  75
  76     @library{wxbase}
  77     @category{FIXME}
  78 */
  79 class wxModule : public wxObject
  80 {
  81 public:
  82     /**
  83         Constructs a wxModule object.
  84     */
  85     wxModule();
  86
  87     /**
  88         Destructor.
  89     */
  90     ~wxModule();
  91
  92     //@{
  93     /**
  94         Call this function from the constructor of the derived class. @a dep must be
  95         the CLASSINFO() of a wxModule-derived class and the
  96         corresponding module will be loaded before and unloaded after
  97         this module.
  98         The second version of this function allows a dependency to be added by
  99         name without access to the class info.  This is useful when a module is
 100         declared entirely in a source file and there is no header for the declaration
 101         of the module needed by CLASSINFO(), however errors are
 102         not detected until run-time, instead of compile-time, then.
 103         Note that circular dependencies are detected and result in a fatal error.
 104
 105         @param dep
 106             The class information object for the dependent module.
 107         @param classname
 108             The class name of the dependent module.
 109     */
 110     void AddDependency(wxClassInfo* dep);
 111     void AddDependency(const char* classname);
 112     //@}
 113
 114     /**
 115         Provide this function with appropriate cleanup for your module.
 116     */
 117     virtual void OnExit();
 118
 119     /**
 120         Provide this function with appropriate initialization for your module. If the
 121         function
 122         returns @false, wxWidgets will exit immediately.
 123     */
 124     virtual bool OnInit();
 125 };
 126