interface/wx/module.h

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