mac paths updated
[wxWidgets.git] / 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