include/wx/app.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        app.h
   3 // Purpose:     wxAppBase class and macros used for declaration of wxApp
   4 //              derived class in the user code
   5 // Author:      Julian Smart
   6 // Modified by:
   7 // Created:     01/02/97
   8 // RCS-ID:      $Id$
   9 // Copyright:   (c) Julian Smart and Markus Holzem
  10 // Licence:     wxWindows licence
  11 /////////////////////////////////////////////////////////////////////////////
  12
  13 #ifndef _WX_APP_H_BASE_
  14 #define _WX_APP_H_BASE_
  15
  16 #ifdef __GNUG__
  17     #pragma interface "appbase.h"
  18 #endif
  19
  20 // ----------------------------------------------------------------------------
  21 // typedefs
  22 // ----------------------------------------------------------------------------
  23
  24 #ifdef __WXMSW__
  25     class WXDLLEXPORT wxApp;
  26     typedef wxApp* (*wxAppInitializerFunction)();
  27 #else
  28     // returning wxApp* won't work with gcc
  29     #include "wx/object.h"
  30
  31     typedef wxObject* (*wxAppInitializerFunction)();
  32 #endif
  33
  34 // ----------------------------------------------------------------------------
  35 // constants
  36 // ----------------------------------------------------------------------------
  37
  38 static const int wxPRINT_WINDOWS = 1;
  39 static const int wxPRINT_POSTSCRIPT = 2;
  40
  41 // ----------------------------------------------------------------------------
  42 // the common part of wxApp implementations for all platforms
  43 // ----------------------------------------------------------------------------
  44
  45 class WXDLLEXPORT wxAppBase : public wxEvtHandler
  46 {
  47 public:
  48     // the virtual functions which may/must be overridden in the derived class
  49     // -----------------------------------------------------------------------
  50
  51         // called during the program initialization, returning FALSE from here
  52         // prevents the program from continuing - it's a good place to create
  53         // the top level program window and return TRUE.
  54         //
  55         // Override: always.
  56     virtual bool OnInit() { return FALSE; };
  57
  58         // a platform-dependent version of OnInit(): the code here is likely to
  59         // depend on the toolkit. default version does nothing.
  60         //
  61         // Override: rarely.
  62     virtual bool OnInitGui() { return TRUE; }
  63
  64         // called to start program execution - the default version just enters
  65         // the main GUI loop in which events are received and processed until
  66         // the last window is not deleted (if GetExitOnFrameDelete) or
  67         // ExitMainLoop() is called.
  68         //
  69         // Override: rarely.
  70     virtual int OnRun() { return MainLoop(); };
  71
  72         // called after the main loop termination. This is a good place for
  73         // cleaning up (it may be too late in dtor) and is also useful if you
  74         // want to return some non-default exit code - this is just the return
  75         // value of this method.
  76         //
  77         // Override: often.
  78     virtual int OnExit() { return 0; }
  79
  80         // called when a fatal exception occurs, this function should take care
  81         // not to do anything which might provoke a nested exception! It may be
  82         // overridden if you wish to react somehow in non-default way (core
  83         // dump under Unix, application crash under Windows) to fatal program
  84         // errors, however extreme care should be taken if you don't want this
  85         // function to crash.
  86         //
  87         // Override: rarely.
  88     virtual void OnFatalException() { }
  89
  90     // the worker functions - usually not used directly by the user code
  91     // -----------------------------------------------------------------
  92
  93         // execute the main GUI loop, the function returns when the loop ends
  94     virtual int MainLoop() = 0;
  95
  96         // exit the main GUI loop during the next iteration (i.e. it does not
  97         // stop the program immediately!)
  98     virtual void ExitMainLoop() = 0;
  99
 100         // returns TRUE if the program is initialized
 101     virtual bool Initialized() = 0;
 102
 103         // returns TRUE if there are unprocessed events in the event queue
 104     virtual bool Pending() = 0;
 105
 106         // process the first event in the event queue (blocks until an event
 107         // apperas if there are none currently)
 108     virtual void Dispatch() = 0;
 109
 110     // application info: name, description, vendor
 111     // -------------------------------------------
 112
 113     // NB: all these should be set by the application itself, there are no
 114     //     reasonable default except for the application name which is taken to
 115     //     be argv[0]
 116
 117         // set/get the application name
 118     wxString GetAppName() const
 119     {
 120         if ( !m_appName )
 121             return m_className;
 122         else
 123             return m_appName;
 124     }
 125     void SetAppName(const wxString& name) { m_appName = name; }
 126
 127         // set/get the app class name
 128     wxString GetClassName() const { return m_className; }
 129     void SetClassName(const wxString& name) { m_className = name; }
 130
 131         // set/get the vendor name
 132     const wxString& GetVendorName() const { return m_vendorName; }
 133     void SetVendorName(const wxString& name) { m_vendorName = name; }
 134
 135     // top level window functions
 136     // --------------------------
 137
 138         // set the "main" top level window
 139     void SetTopWindow(wxWindow *win) { m_topWindow = win; }
 140
 141         // return the "main" top level window (if it hadn't been set previously
 142         // with SetTopWindow(), will return just some top level window and, if
 143         // there are none, will return NULL)
 144     wxWindow *GetTopWindow() const
 145     {
 146         if (m_topWindow)
 147             return m_topWindow;
 148         else if (wxTopLevelWindows.GetCount() > 0)
 149             return wxTopLevelWindows.GetFirst()->GetData();
 150         else
 151             return (wxWindow *)NULL;
 152     }
 153
 154         // control the exit behaviour: by default, the program will exit the
 155         // main loop (and so, usually, terminate) when the last top-level
 156         // program window is deleted. Beware that if you disabel this (with
 157         // SetExitOnFrameDelete(FALSE)), you'll have to call ExitMainLoop()
 158         // explicitly from somewhere.
 159     void SetExitOnFrameDelete(bool flag) { m_exitOnFrameDelete = flag; }
 160     bool GetExitOnFrameDelete() const { return m_exitOnFrameDelete; }
 161
 162     // miscellaneous customization functions
 163     // -------------------------------------
 164
 165 #if wxUSE_LOG
 166         // override this function to create default log target of arbitrary
 167         // user-defined class (default implementation creates a wxLogGui
 168         // object) - this log object is used by default by all wxLogXXX()
 169         // functions.
 170     virtual wxLog *CreateLogTarget() { return new wxLogGui; }
 171 #endif // wxUSE_LOG
 172
 173
 174         // get the standard icon used by wxWin dialogs - this allows the user
 175         // to customize the standard dialogs. The 'which' parameter is one of
 176         // wxICON_XXX values
 177     virtual wxIcon GetStdIcon(int which) const = 0;
 178
 179         // VZ: what does this do exactly?
 180     void SetWantDebugOutput( bool flag ) { m_wantDebugOutput = flag; }
 181     bool GetWantDebugOutput() const { return m_wantDebugOutput; }
 182
 183         // set/get printing mode: see wxPRINT_XXX constants.
 184         //
 185         // default behaviour is the normal one for Unix: always use PostScript
 186         // printing.
 187     virtual void SetPrintMode(int WXUNUSED(mode)) { }
 188     int GetPrintMode() const { return wxPRINT_POSTSCRIPT; }
 189
 190     // implementation only from now on
 191     // -------------------------------
 192
 193     // helpers for dynamic wxApp construction
 194     static void SetInitializerFunction(wxAppInitializerFunction fn)
 195         { m_appInitFn = fn; }
 196     static wxAppInitializerFunction GetInitializerFunction()
 197         { return m_appInitFn; }
 198
 199     // access to the command line arguments
 200     int     argc;
 201     char  **argv;
 202
 203 //private:
 204 protected:
 205     // function used for dynamic wxApp creation
 206     static wxAppInitializerFunction m_appInitFn;
 207
 208     // application info (must be set from the user code)
 209     wxString m_vendorName,      // vendor name (ACME Inc)
 210              m_appName,         // app name
 211              m_className;       // class name
 212
 213     // if TRUE, exit the main loop when the last top level window is deleted
 214     bool m_exitOnFrameDelete;
 215
 216     // TRUE if the application wants to get debug output
 217     bool m_wantDebugOutput;
 218
 219     // the main top level window - may be NULL
 220     wxWindow *m_topWindow;
 221 };
 222
 223 // ----------------------------------------------------------------------------
 224 // now include the declaration of the real class
 225 // ----------------------------------------------------------------------------
 226
 227 #if defined(__WXMSW__)
 228     #include "wx/msw/app.h"
 229 #elif defined(__WXMOTIF__)
 230     #include "wx/motif/app.h"
 231 #elif defined(__WXQT__)
 232     #include "wx/qt/app.h"
 233 #elif defined(__WXGTK__)
 234     #include "wx/gtk/app.h"
 235 #elif defined(__WXMAC__)
 236     #include "wx/mac/app.h"
 237 #elif defined(__WXSTUBS__)
 238     #include "wx/stubs/app.h"
 239 #endif
 240
 241 // ----------------------------------------------------------------------------
 242 // macros for dynamic creation of the application object
 243 // ----------------------------------------------------------------------------
 244
 245 // Having a global instance of this class allows wxApp to be aware of the app
 246 // creator function. wxApp can then call this function to create a new app
 247 // object. Convoluted, but necessary.
 248
 249 class WXDLLEXPORT wxAppInitializer
 250 {
 251 public:
 252     wxAppInitializer(wxAppInitializerFunction fn)
 253         { wxApp::SetInitializerFunction(fn); }
 254 };
 255
 256 // Here's a macro you can use if your compiler really, really wants main() to
 257 // be in your main program (e.g. hello.cpp). Now IMPLEMENT_APP should add this
 258 // code if required.
 259
 260 #if defined(__AIX__) || defined(__HPUX__)
 261     #define IMPLEMENT_WXWIN_MAIN \
 262         extern int wxEntry( int argc, char *argv[] ); \
 263         int main(int argc, char *argv[]) { return wxEntry(argc, argv); }
 264 #elif defined(__WXMSW__) && defined(WXUSINGDLL)
 265     // NT defines APIENTRY, 3.x not
 266     #if !defined(WXAPIENTRY)
 267         #ifdef __WATCOMC__
 268             #define WXAPIENTRY PASCAL
 269         #else
 270             #define WXAPIENTRY FAR PASCAL
 271         #endif
 272     #endif
 273
 274     #define IMPLEMENT_WXWIN_MAIN \
 275         int WXAPIENTRY WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,\
 276                                LPSTR m_lpCmdLine, int nCmdShow )\
 277         {\
 278             return wxEntry((WXHINSTANCE) hInstance, \
 279                            (WXHINSTANCE) hPrevInstance,\
 280                            m_lpCmdLine, nCmdShow);\
 281         }
 282
 283 #else
 284     #define IMPLEMENT_WXWIN_MAIN
 285 #endif
 286
 287 // use this macro exactly once, the argument is the name of the wxApp-derived
 288 // class which is the class of your application
 289 #define IMPLEMENT_APP(appname)                          \
 290     wxApp *wxCreateApp() { return new appname; }      \
 291     wxAppInitializer wxTheAppInitializer((wxAppInitializerFunction) wxCreateApp); \
 292     appname& wxGetApp() { return *(appname *)wxTheApp; } \
 293     IMPLEMENT_WXWIN_MAIN
 294
 295 #define DECLARE_APP(appname) extern appname& wxGetApp();
 296
 297 #endif
 298     // _WX_APP_H_BASE_