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