interface/wx/app.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        app.h
   3 // Purpose:     interface of wxApp
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     @class wxAppConsole
  12
  13     This class is essential for writing console-only or hybrid apps without
  14     having to define @c wxUSE_GUI=0.
  15
  16     It is used to:
  17     @li set and get application-wide properties (see wxAppConsole::CreateTraits
  18         and wxAppConsole::SetXXX functions)
  19     @li implement the windowing system message or event loop: events in fact are
  20         supported even in console-mode applications (see wxAppConsole::HandleEvent
  21         and wxAppConsole::ProcessPendingEvents);
  22     @li initiate application processing via wxApp::OnInit;
  23     @li allow default processing of events not handled by other
  24         objects in the application (see wxAppConsole::FilterEvent)
  25     @li implement Apple-specific event handlers (see wxAppConsole::MacXXX functions)
  26
  27     You should use the macro IMPLEMENT_APP(appClass) in your application
  28     implementation file to tell wxWidgets how to create an instance of your
  29     application class.
  30
  31     Use DECLARE_APP(appClass) in a header file if you want the ::wxGetApp() function
  32     (which returns a reference to your application object) to be visible to other
  33     files.
  34
  35     @library{wxbase}
  36     @category{appmanagement}
  37
  38     @see @ref overview_app, wxApp, wxAppTraits, wxEventLoopBase
  39 */
  40 class wxAppConsole : public wxEvtHandler
  41 {
  42 protected:
  43     /**
  44         Creates the wxAppTraits object when GetTraits() needs it for the first time.
  45
  46         @see wxAppTraits
  47     */
  48     virtual wxAppTraits* CreateTraits();
  49
  50 public:
  51
  52     /**
  53         Destructor.
  54     */
  55     virtual ~wxAppConsole();
  56
  57
  58     /**
  59         @name Event-handling
  60     */
  61     //@{
  62
  63     /**
  64         Dispatches the next event in the windowing system event queue.
  65         Blocks until an event appears if there are none currently
  66         (use Pending() if this is not wanted).
  67
  68         This can be used for programming event loops, e.g.
  69
  70         @code
  71         while (app.Pending())
  72             Dispatch();
  73         @endcode
  74
  75         @return @false if the event loop should stop and @true otherwise.
  76
  77         @see Pending(), wxEventLoopBase
  78     */
  79     virtual bool Dispatch();
  80
  81     /**
  82         Call this to explicitly exit the main message (event) loop.
  83         You should normally exit the main loop (and the application) by deleting
  84         the top window.
  85     */
  86     virtual void ExitMainLoop();
  87
  88     /**
  89         This function is called before processing any event and allows the application
  90         to preempt the processing of some events.
  91
  92         If this method returns -1 the event is processed normally, otherwise either
  93         @true or @false should be returned and the event processing stops immediately
  94         considering that the event had been already processed (for the former return
  95         value) or that it is not going to be processed at all (for the latter one).
  96     */
  97     virtual int FilterEvent(wxEvent& event);
  98
  99
 100     /**
 101         This function simply invokes the given method @a func of the specified
 102         event handler @a handler with the @a event as parameter. It exists solely
 103         to allow to catch the C++ exceptions which could be thrown by all event
 104         handlers in the application in one place: if you want to do this, override
 105         this function in your wxApp-derived class and add try/catch clause(s) to it.
 106     */
 107     virtual void HandleEvent(wxEvtHandler* handler,
 108                              wxEventFunction func,
 109                              wxEvent& event) const;
 110
 111     /**
 112         Returns @true if called from inside Yield().
 113     */
 114     virtual bool IsYielding() const;
 115
 116     /**
 117         Process all pending events; it is necessary to call this function to
 118         process posted events.
 119
 120         This happens during each event loop iteration in GUI mode but if there is
 121         no main loop, it may be also called directly.
 122     */
 123     virtual void ProcessPendingEvents();
 124
 125     /**
 126         Called by wxWidgets on creation of the application. Override this if you wish
 127         to provide your own (environment-dependent) main loop.
 128
 129         @return 0 under X, and the wParam of the WM_QUIT message under Windows.
 130     */
 131     virtual int MainLoop();
 132
 133     /**
 134         Returns @true if unprocessed events are in the window system event queue.
 135
 136         @see Dispatch()
 137     */
 138     virtual bool Pending();
 139
 140     /**
 141         Yields control to pending messages in the windowing system.
 142
 143         This can be useful, for example, when a time-consuming process writes to a
 144         text window. Without an occasional yield, the text window will not be updated
 145         properly, and on systems with cooperative multitasking, such as Windows 3.1
 146         other processes will not respond.
 147
 148         Caution should be exercised, however, since yielding may allow the
 149         user to perform actions which are not compatible with the current task.
 150         Disabling menu items or whole menus during processing can avoid unwanted
 151         reentrance of code: see ::wxSafeYield for a better function.
 152         You can avoid unwanted reentrancies also using IsYielding().
 153
 154         Note that Yield() will not flush the message logs. This is intentional as
 155         calling Yield() is usually done to quickly update the screen and popping up
 156         a message box dialog may be undesirable. If you do wish to flush the log
 157         messages immediately (otherwise it will be done during the next idle loop
 158         iteration), call wxLog::FlushActive.
 159
 160         Calling Yield() recursively is normally an error and an assert failure is
 161         raised in debug build if such situation is detected. However if the
 162         @a onlyIfNeeded parameter is @true, the method will just silently
 163         return @false instead.
 164     */
 165     bool Yield(bool onlyIfNeeded = false);
 166
 167     /**
 168         Works like Yield() with @e onlyIfNeeded == @true, except that it allows
 169         the caller to specify a mask of the ::wxEventCategory values which
 170         indicates which events should be processed and which should instead
 171         be "delayed" (i.e. processed by the main loop later).
 172
 173         Note that this is a safer alternative to Yield() since it ensures that
 174         only the events you're interested to are processed; i.e. helps to avoid
 175         unwanted reentrancies.
 176     */
 177     bool YieldFor(long eventsToProcess);
 178
 179     /**
 180         Returns @true if the given event category is allowed inside
 181         a YieldFor() call (i.e. compares the given category against the
 182         last mask passed to YieldFor()).
 183     */
 184     virtual bool IsEventAllowedInsideYield(wxEventCategory cat) const;
 185
 186     //@}
 187
 188
 189     /**
 190         Allows external code to modify global ::wxTheApp, but you should really
 191         know what you're doing if you call it.
 192
 193         @param app
 194             Replacement for the global application object.
 195
 196         @see GetInstance()
 197     */
 198     static void SetInstance(wxAppConsole* app);
 199
 200     /**
 201         Returns the one and only global application object.
 202         Usually ::wxTheApp is used instead.
 203
 204         @see SetInstance()
 205     */
 206     static wxAppConsole* GetInstance();
 207
 208     /**
 209         Returns @true if the main event loop is currently running, i.e. if the
 210         application is inside OnRun().
 211
 212         This can be useful to test whether events can be dispatched. For example,
 213         if this function returns @false, non-blocking sockets cannot be used because
 214         the events from them would never be processed.
 215     */
 216     static bool IsMainLoopRunning();
 217
 218
 219     /**
 220         @name Mac-specific functions
 221     */
 222     //@{
 223
 224     /**
 225         Called in response of an "open-application" Apple event.
 226         Override this to create a new document in your app.
 227
 228         @onlyfor{wxmac}
 229     */
 230     virtual void MacNewFile();
 231
 232     /**
 233         Called in response of an "open-document" Apple event.
 234
 235         You need to override this method in order to open a document file after the
 236         user double clicked on it or if the document file was dropped on either the
 237         running application or the application icon in Finder.
 238
 239         @onlyfor{wxmac}
 240     */
 241     virtual void MacOpenFile(const wxString& fileName);
 242
 243     /**
 244         Called in response of a "get-url" Apple event.
 245
 246         @onlyfor{wxmac}
 247     */
 248     virtual void MacOpenURL(const wxString& url);
 249
 250     /**
 251         Called in response of a "print-document" Apple event.
 252
 253         @onlyfor{wxmac}
 254     */
 255     virtual void MacPrintFile(const wxString& fileName);
 256
 257     /**
 258         Called in response of a "reopen-application" Apple event.
 259
 260         @onlyfor{wxmac}
 261     */
 262     virtual void MacReopenApp();
 263
 264     //@}
 265
 266
 267     /**
 268         @name Callbacks for application-wide "events"
 269     */
 270     //@{
 271
 272     /**
 273         This function is called when an assert failure occurs, i.e. the condition
 274         specified in wxASSERT() macro evaluated to @false.
 275
 276         It is only called in debug mode (when @c __WXDEBUG__ is defined) as
 277         asserts are not left in the release code at all.
 278         The base class version shows the default assert failure dialog box proposing to
 279         the user to stop the program, continue or ignore all subsequent asserts.
 280
 281         @param file
 282             the name of the source file where the assert occurred
 283         @param line
 284             the line number in this file where the assert occurred
 285         @param func
 286             the name of the function where the assert occurred, may be
 287             empty if the compiler doesn't support C99 __FUNCTION__
 288         @param cond
 289             the condition of the failed assert in text form
 290         @param msg
 291             the message specified as argument to wxASSERT_MSG or wxFAIL_MSG, will
 292             be @NULL if just wxASSERT or wxFAIL was used
 293     */
 294     virtual void OnAssertFailure(const wxChar *file,
 295                                  int line,
 296                                  const wxChar *func,
 297                                  const wxChar *cond,
 298                                  const wxChar *msg);
 299
 300     /**
 301         Called when command line parsing fails (i.e. an incorrect command line option
 302         was specified by the user). The default behaviour is to show the program usage
 303         text and abort the program.
 304
 305         Return @true to continue normal execution or @false to return
 306         @false from OnInit() thus terminating the program.
 307
 308         @see OnInitCmdLine()
 309     */
 310     virtual bool OnCmdLineError(wxCmdLineParser& parser);
 311
 312     /**
 313         Called when the help option (@c --help) was specified on the command line.
 314         The default behaviour is to show the program usage text and abort the program.
 315
 316         Return @true to continue normal execution or @false to return
 317         @false from OnInit() thus terminating the program.
 318
 319         @see OnInitCmdLine()
 320     */
 321     virtual bool OnCmdLineHelp(wxCmdLineParser& parser);
 322
 323     /**
 324         Called after the command line had been successfully parsed. You may override
 325         this method to test for the values of the various parameters which could be
 326         set from the command line.
 327
 328         Don't forget to call the base class version unless you want to suppress
 329         processing of the standard command line options.
 330         Return @true to continue normal execution or @false to return @false from
 331         OnInit() thus terminating the program.
 332
 333         @see OnInitCmdLine()
 334     */
 335     virtual bool OnCmdLineParsed(wxCmdLineParser& parser);
 336
 337     /**
 338         This function is called if an unhandled exception occurs inside the main
 339         application event loop. It can return @true to ignore the exception and to
 340         continue running the loop or @false to exit the loop and terminate the
 341         program. In the latter case it can also use C++ @c throw keyword to
 342         rethrow the current exception.
 343
 344         The default behaviour of this function is the latter in all ports except under
 345         Windows where a dialog is shown to the user which allows him to choose between
 346         the different options. You may override this function in your class to do
 347         something more appropriate.
 348
 349         Finally note that if the exception is rethrown from here, it can be caught in
 350         OnUnhandledException().
 351     */
 352     virtual bool OnExceptionInMainLoop();
 353
 354     /**
 355         Override this member function for any processing which needs to be
 356         done as the application is about to exit. OnExit is called after
 357         destroying all application windows and controls, but before
 358         wxWidgets cleanup. Note that it is not called at all if
 359         OnInit() failed.
 360
 361         The return value of this function is currently ignored, return the same
 362         value as returned by the base class method if you override it.
 363     */
 364     virtual int OnExit();
 365
 366     /**
 367         This function may be called if something fatal happens: an unhandled
 368         exception under Win32 or a a fatal signal under Unix, for example. However,
 369         this will not happen by default: you have to explicitly call
 370         wxHandleFatalExceptions() to enable this.
 371
 372         Generally speaking, this function should only show a message to the user and
 373         return. You may attempt to save unsaved data but this is not guaranteed to
 374         work and, in fact, probably won't.
 375
 376         @see wxHandleFatalExceptions()
 377     */
 378     virtual void OnFatalException();
 379
 380     /**
 381         This must be provided by the application, and will usually create the
 382         application's main window, optionally calling SetTopWindow().
 383
 384         You may use OnExit() to clean up anything initialized here, provided
 385         that the function returns @true.
 386
 387         Notice that if you want to to use the command line processing provided by
 388         wxWidgets you have to call the base class version in the derived class
 389         OnInit().
 390
 391         Return @true to continue processing, @false to exit the application
 392         immediately.
 393     */
 394     virtual bool OnInit();
 395
 396     /**
 397         Called from OnInit() and may be used to initialize the parser with the
 398         command line options for this application. The base class versions adds
 399         support for a few standard options only.
 400     */
 401     virtual void OnInitCmdLine(wxCmdLineParser& parser);
 402
 403     /**
 404         This virtual function is where the execution of a program written in wxWidgets
 405         starts. The default implementation just enters the main loop and starts
 406         handling the events until it terminates, either because ExitMainLoop() has
 407         been explicitly called or because the last frame has been deleted and
 408         GetExitOnFrameDelete() flag is @true (this is the default).
 409
 410         The return value of this function becomes the exit code of the program, so it
 411         should return 0 in case of successful termination.
 412     */
 413     virtual int OnRun();
 414
 415     /**
 416         This function is called when an unhandled C++ exception occurs inside
 417         OnRun() (the exceptions which occur during the program startup and shutdown
 418         might not be caught at all). Notice that by now the main event loop has been
 419         terminated and the program will exit, if you want to prevent this from happening
 420         (i.e. continue running after catching an exception) you need to override
 421         OnExceptionInMainLoop().
 422
 423         The default implementation shows information about the exception in debug build
 424         but does nothing in the release build.
 425     */
 426     virtual void OnUnhandledException();
 427
 428     //@}
 429
 430
 431     /**
 432         @name Application informations
 433     */
 434     //@{
 435
 436     /**
 437         Returns the user-readable application name.
 438
 439         The difference between this string and the one returned by GetAppName()
 440         is that this one is meant to be shown to the user and so should be used
 441         for the window titles, page headers and so on while the other one
 442         should be only used internally, e.g. for the file names or
 443         configuration file keys. By default, returns the application name as
 444         returned by GetAppName() capitalized using wxString::Capitalize().
 445
 446         @since 2.9.0
 447     */
 448     wxString GetAppDisplayName() const;
 449
 450     /**
 451         Returns the application name.
 452
 453         @remarks wxWidgets sets this to a reasonable default before calling
 454                  OnInit(), but the application can reset it at will.
 455
 456         @see GetAppDisplayName()
 457     */
 458     wxString GetAppName() const;
 459
 460     /**
 461         Gets the class name of the application. The class name may be used in a
 462         platform specific manner to refer to the application.
 463
 464         @see SetClassName()
 465     */
 466     wxString GetClassName() const;
 467
 468     /**
 469         Returns a pointer to the wxAppTraits object for the application.
 470         If you want to customize the wxAppTraits object, you must override the
 471         CreateTraits() function.
 472     */
 473     wxAppTraits* GetTraits();
 474
 475     /**
 476         Returns the user-readable vendor name. The difference between this string
 477         and the one returned by GetVendorName() is that this one is meant to be shown
 478         to the user and so should be used for the window titles, page headers and so on
 479         while the other one should be only used internally, e.g. for the file names or
 480         configuration file keys.
 481
 482         By default, returns the same string as GetVendorName().
 483
 484         @since 2.9.0
 485     */
 486     const wxString& GetVendorDisplayName() const;
 487
 488     /**
 489         Returns the application's vendor name.
 490     */
 491     const wxString& GetVendorName() const;
 492
 493     /**
 494         Set the application name to be used in the user-visible places such as
 495         window titles.
 496
 497         See GetAppDisplayName() for more about the differences between the
 498         display name and name.
 499
 500         Notice that if this function is called, the name is used as is, without
 501         any capitalization as done by default by GetAppDisplayName().
 502     */
 503     void SetAppDisplayName(const wxString& name);
 504
 505     /**
 506         Sets the name of the application. This name should be used for file names,
 507         configuration file entries and other internal strings. For the user-visible
 508         strings, such as the window titles, the application display name set by
 509         SetAppDisplayName() is used instead.
 510
 511         By default the application name is set to the name of its executable file.
 512
 513         @see GetAppName()
 514     */
 515     void SetAppName(const wxString& name);
 516
 517     /**
 518         Sets the class name of the application. This may be used in a platform specific
 519         manner to refer to the application.
 520
 521         @see GetClassName()
 522     */
 523     void SetClassName(const wxString& name);
 524
 525     /**
 526         Set the vendor name to be used in the user-visible places.
 527         See GetVendorDisplayName() for more about the differences between the
 528         display name and name.
 529     */
 530     void SetVendorDisplayName(const wxString& name);
 531
 532     /**
 533         Sets the name of application's vendor. The name will be used
 534         in registry access. A default name is set by wxWidgets.
 535
 536         @see GetVendorName()
 537     */
 538     void SetVendorName(const wxString& name);
 539
 540     //@}
 541
 542
 543     /**
 544         Number of command line arguments (after environment-specific processing).
 545     */
 546     int argc;
 547
 548     /**
 549         Command line arguments (after environment-specific processing).
 550
 551         Under Windows and Linux/Unix, you should parse the command line
 552         arguments and check for files to be opened when starting your
 553         application. Under OS X, you need to override MacOpenFile()
 554         since command line arguments are used differently there.
 555
 556         You may use the wxCmdLineParser to parse command line arguments.
 557     */
 558     wxChar** argv;
 559 };
 560
 561
 562
 563
 564 /**
 565     @class wxApp
 566
 567     The wxApp class represents the application itself when @c wxUSE_GUI=1.
 568
 569     In addition to the features provided by wxAppConsole it keeps track of
 570     the <em>top window</em> (see SetTopWindow()) and adds support for
 571     video modes (see SetVideoMode()).
 572
 573     In general, application-wide settings for GUI-only apps are accessible
 574     from wxApp (or from wxSystemSettings or wxSystemOptions classes).
 575
 576     @library{wxbase}
 577     @category{appmanagement}
 578
 579     @see @ref overview_app, wxAppTraits, wxEventLoopBase, wxSystemSettings
 580 */
 581 class wxApp : public wxAppConsole
 582 {
 583 public:
 584     /**
 585         Constructor. Called implicitly with a definition of a wxApp object.
 586     */
 587     wxApp();
 588
 589     /**
 590         Destructor. Will be called implicitly on program exit if the wxApp
 591         object is created on the stack.
 592     */
 593     virtual ~wxApp();
 594
 595     /**
 596         Get display mode that is used use. This is only used in framebuffer
 597         wxWin ports (such as wxMGL or wxDFB).
 598     */
 599     virtual wxVideoMode GetDisplayMode() const;
 600
 601     /**
 602         Returns @true if the application will exit when the top-level frame is deleted.
 603
 604         @see SetExitOnFrameDelete()
 605     */
 606     bool GetExitOnFrameDelete() const;
 607
 608     /**
 609         Return the layout direction for the current locale or @c wxLayout_Default
 610         if it's unknown.
 611     */
 612     virtual wxLayoutDirection GetLayoutDirection() const;
 613
 614     /**
 615         Returns @true if the application will use the best visual on systems that support
 616         different visuals, @false otherwise.
 617
 618         @see SetUseBestVisual()
 619     */
 620     bool GetUseBestVisual() const;
 621
 622     /**
 623         Returns a pointer to the top window.
 624
 625         @remarks
 626             If the top window hasn't been set using SetTopWindow(), this function
 627             will find the first top-level window (frame or dialog or instance of
 628             wxTopLevelWindow) from the internal top level window list and return that.
 629
 630         @see SetTopWindow()
 631     */
 632     virtual wxWindow* GetTopWindow() const;
 633
 634     /**
 635         Returns @true if the application is active, i.e. if one of its windows is
 636         currently in the foreground.
 637
 638         If this function returns @false and you need to attract users attention to
 639         the application, you may use wxTopLevelWindow::RequestUserAttention to do it.
 640     */
 641     virtual bool IsActive() const;
 642
 643     /**
 644         This function is similar to wxYield(), except that it disables the user
 645         input to all program windows before calling wxAppConsole::Yield and re-enables it
 646         again afterwards. If @a win is not @NULL, this window will remain enabled,
 647         allowing the implementation of some limited user interaction.
 648         Returns the result of the call to wxAppConsole::Yield.
 649
 650         @see wxSafeYield
 651     */
 652     virtual bool SafeYield(wxWindow *win, bool onlyIfNeeded);
 653
 654     /**
 655         Works like SafeYield() with @e onlyIfNeeded == @true except that
 656         it allows the caller to specify a mask of events to be processed.
 657
 658         See wxAppConsole::YieldFor for more info.
 659     */
 660     virtual bool SafeYieldFor(wxWindow *win, long eventsToProcess);
 661
 662     /**
 663         Windows-only function for processing a message. This function is called
 664         from the main message loop, checking for windows that may wish to process it.
 665
 666         The function returns @true if the message was processed, @false otherwise.
 667         If you use wxWidgets with another class library with its own message loop,
 668         you should make sure that this function is called to allow wxWidgets to
 669         receive messages. For example, to allow co-existence with the Microsoft
 670         Foundation Classes, override the PreTranslateMessage function:
 671
 672         @code
 673         // Provide wxWidgets message loop compatibility
 674         BOOL CTheApp::PreTranslateMessage(MSG *msg)
 675         {
 676             if (wxTheApp && wxTheApp->ProcessMessage((WXMSW *)msg))
 677                 return true;
 678             else
 679                 return CWinApp::PreTranslateMessage(msg);
 680         }
 681         @endcode
 682
 683         @onlyfor{wxmsw}
 684     */
 685     bool ProcessMessage(WXMSG* msg);
 686
 687     /**
 688         Sends idle events to a window and its children.
 689         Please note that this function is internal to wxWidgets and shouldn't be used
 690         by user code.
 691
 692         @remarks These functions poll the top-level windows, and their children,
 693                  for idle event processing. If @true is returned, more OnIdle
 694                  processing is requested by one or more window.
 695
 696         @see wxIdleEvent
 697     */
 698     virtual bool SendIdleEvents(wxWindow* win, wxIdleEvent& event);
 699
 700     /**
 701         Set display mode to use. This is only used in framebuffer wxWin
 702         ports (such as wxMGL or wxDFB). This method should be called from
 703         wxApp::OnInitGui.
 704     */
 705     virtual bool SetDisplayMode(const wxVideoMode& info);
 706
 707     /**
 708         Allows the programmer to specify whether the application will exit when the
 709         top-level frame is deleted.
 710
 711         @param flag
 712             If @true (the default), the application will exit when the top-level frame
 713             is deleted. If @false, the application will continue to run.
 714
 715         @see GetExitOnFrameDelete(), @ref overview_app_shutdown
 716     */
 717     void SetExitOnFrameDelete(bool flag);
 718
 719     /**
 720         Allows runtime switching of the UI environment theme.
 721
 722         Currently implemented for wxGTK2-only.
 723         Return @true if theme was successfully changed.
 724
 725         @param theme
 726             The name of the new theme or an absolute path to a gtkrc-theme-file
 727     */
 728     virtual bool SetNativeTheme(const wxString& theme);
 729
 730     /**
 731         Sets the 'top' window. You can call this from within OnInit() to let wxWidgets
 732         know which is the main window. You don't have to set the top window;
 733         it is only a convenience so that (for example) certain dialogs without parents
 734         can use a specific window as the top window.
 735
 736         If no top window is specified by the application, wxWidgets just uses the
 737         first frame or dialog (or better, any wxTopLevelWindow) in its top-level
 738         window list, when it needs to use the top window.
 739         If you previously called SetTopWindow() and now you need to restore this
 740         automatic behaviour you can call @code wxApp::SetTopWindow(NULL) @endcode.
 741
 742         @param window
 743             The new top window.
 744
 745         @see GetTopWindow(), OnInit()
 746     */
 747     void SetTopWindow(wxWindow* window);
 748
 749     /**
 750         Allows the programmer to specify whether the application will use the best
 751         visual on systems that support several visual on the same display. This is typically
 752         the case under Solaris and IRIX, where the default visual is only 8-bit whereas
 753         certain applications are supposed to run in TrueColour mode.
 754
 755         Note that this function has to be called in the constructor of the wxApp
 756         instance and won't have any effect when called later on.
 757         This function currently only has effect under GTK.
 758
 759         @param flag
 760             If @true, the app will use the best visual.
 761         @param forceTrueColour
 762             If @true then the application will try to force using a TrueColour
 763             visual and abort the app if none is found.
 764     */
 765     void SetUseBestVisual(bool flag, bool forceTrueColour = false);
 766 };
 767
 768
 769
 770 // ============================================================================
 771 // Global functions/macros
 772 // ============================================================================
 773
 774
 775 /** @addtogroup group_funcmacro_rtti */
 776 //@{
 777
 778 /**
 779     This is used in headers to create a forward declaration of the ::wxGetApp()
 780     function implemented by IMPLEMENT_APP().
 781
 782     It creates the declaration <tt>className& wxGetApp()</tt>.
 783
 784     @header{wx/app.h}
 785
 786     Example:
 787
 788     @code
 789     DECLARE_APP(MyApp)
 790     @endcode
 791 */
 792 #define DECLARE_APP( className )
 793
 794 /**
 795     This is used in the application class implementation file to make the
 796     application class known to wxWidgets for dynamic construction.
 797
 798     @header{wx/app.h}
 799
 800     Example:
 801
 802     @code
 803     IMPLEMENT_APP(MyApp)
 804     @endcode
 805
 806     @see DECLARE_APP().
 807 */
 808 #define IMPLEMENT_APP( className )
 809
 810 //@}
 811
 812
 813
 814 /**
 815     The global pointer to the singleton wxApp object.
 816
 817     @see wxApp::GetInstance()
 818 */
 819 wxApp *wxTheApp;
 820
 821
 822
 823 /** @addtogroup group_funcmacro_appinitterm */
 824 //@{
 825
 826 /**
 827     This function doesn't exist in wxWidgets but it is created by using the
 828     IMPLEMENT_APP() macro.
 829
 830     Thus, before using it anywhere but in the same module where this macro is
 831     used, you must make it available using DECLARE_APP().
 832
 833     The advantage of using this function compared to directly using the global
 834     ::wxTheApp pointer is that the latter is of type wxApp* and so wouldn't
 835     allow you to access the functions specific to your application class but
 836     not present in wxApp while wxGetApp() returns the object of the right type.
 837
 838     @header{wx/app.h}
 839 */
 840 wxAppDerivedClass& wxGetApp();
 841
 842 /**
 843     If @a doIt is @true, the fatal exceptions (also known as general protection
 844     faults under Windows or segmentation violations in the Unix world) will be
 845     caught and passed to wxApp::OnFatalException.
 846
 847     By default, i.e. before this function is called, they will be handled in
 848     the normal way which usually just means that the application will be
 849     terminated. Calling wxHandleFatalExceptions() with @a doIt equal to @false
 850     will restore this default behaviour.
 851
 852     Notice that this function is only available if @c wxUSE_ON_FATAL_EXCEPTION
 853     is 1 and under Windows platform this requires a compiler with support for
 854     SEH (structured exception handling) which currently means only Microsoft
 855     Visual C++ or a recent Borland C++ version.
 856
 857     @header{wx/app.h}
 858 */
 859 bool wxHandleFatalExceptions(bool doIt = true);
 860
 861 /**
 862     This function is used in wxBase only and only if you don't create
 863     wxApp object at all. In this case you must call it from your
 864     @c main() function before calling any other wxWidgets functions.
 865
 866     If the function returns @false the initialization could not be performed,
 867     in this case the library cannot be used and wxUninitialize() shouldn't be
 868     called neither.
 869
 870     This function may be called several times but wxUninitialize() must be
 871     called for each successful call to this function.
 872
 873     @header{wx/app.h}
 874 */
 875 bool wxInitialize();
 876
 877 /**
 878     This function is for use in console (wxBase) programs only. It must be called
 879     once for each previous successful call to wxInitialize().
 880
 881     @header{wx/app.h}
 882 */
 883 void wxUninitialize();
 884
 885 /**
 886     This function wakes up the (internal and platform dependent) idle system,
 887     i.e. it will force the system to send an idle event even if the system
 888     currently @e is idle and thus would not send any idle event until after
 889     some other event would get sent. This is also useful for sending events
 890     between two threads and is used by the corresponding functions
 891     wxPostEvent() and wxEvtHandler::AddPendingEvent().
 892
 893     @header{wx/app.h}
 894 */
 895 void wxWakeUpIdle();
 896
 897 /**
 898     Calls wxAppConsole::Yield.
 899
 900     @deprecated
 901     This function is kept only for backwards compatibility. Please use
 902     the wxAppConsole::Yield method instead in any new code.
 903
 904     @header{wx/app.h}
 905 */
 906 bool wxYield();
 907
 908 /**
 909     Calls wxApp::SafeYield.
 910
 911     @header{wx/app.h}
 912 */
 913 bool wxSafeYield(wxWindow* win = NULL, bool onlyIfNeeded = false);
 914
 915 /**
 916     This function initializes wxWidgets in a platform-dependent way. Use this if you
 917     are not using the default wxWidgets entry code (e.g. main or WinMain).
 918
 919     For example, you can initialize wxWidgets from an Microsoft Foundation Classes
 920     (MFC) application using this function.
 921
 922     @note This overload of wxEntry is available under all platforms.
 923
 924     @see wxEntryStart()
 925
 926     @header{wx/app.h}
 927 */
 928 int wxEntry(int& argc, wxChar** argv);
 929
 930 /**
 931     See wxEntry(int&,wxChar**) for more info about this function.
 932
 933     Notice that under Windows CE platform, and only there, the type of @a pCmdLine
 934     is @c wchar_t *, otherwise it is @c char *, even in Unicode build.
 935
 936     @remarks To clean up wxWidgets, call wxApp::OnExit followed by the static
 937              function wxApp::CleanUp. For example, if exiting from an MFC application
 938              that also uses wxWidgets:
 939              @code
 940              int CTheApp::ExitInstance()
 941              {
 942                 // OnExit isn't called by CleanUp so must be called explicitly.
 943                 wxTheApp->OnExit();
 944                 wxApp::CleanUp();
 945
 946                 return CWinApp::ExitInstance();
 947              }
 948              @endcode
 949
 950     @header{wx/app.h}
 951 */
 952 int wxEntry(HINSTANCE hInstance,
 953             HINSTANCE hPrevInstance = NULL,
 954             char* pCmdLine = NULL,
 955             int nCmdShow = SW_SHOWNORMAL);
 956
 957 //@}
 958
 959
 960
 961 /** @addtogroup group_funcmacro_procctrl */
 962 //@{
 963
 964 /**
 965     Exits application after calling wxApp::OnExit.
 966
 967     Should only be used in an emergency: normally the top-level frame
 968     should be deleted (after deleting all other frames) to terminate the
 969     application. See wxCloseEvent and wxApp.
 970
 971     @header{wx/app.h}
 972 */
 973 void wxExit();
 974
 975 //@}
 976