interface/wx/app.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        app.h
   3 // Purpose:     interface of wxApp
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8
   9 /**
  10     @class wxAppConsole
  11
  12     This class is essential for writing console-only or hybrid apps without
  13     having to define @c wxUSE_GUI=0.
  14
  15     It is used to:
  16     @li set and get application-wide properties (see wxAppConsole::CreateTraits
  17         and wxAppConsole::SetXXX functions)
  18     @li implement the windowing system message or event loop: events in fact are
  19         supported even in console-mode applications (see wxAppConsole::HandleEvent
  20         and wxAppConsole::ProcessPendingEvents);
  21     @li initiate application processing via wxApp::OnInit;
  22     @li allow default processing of events not handled by other
  23         objects in the application (see wxAppConsole::FilterEvent)
  24     @li implement Apple-specific event handlers (see wxAppConsole::MacXXX functions)
  25
  26     You should use the macro wxIMPLEMENT_APP(appClass) in your application
  27     implementation file to tell wxWidgets how to create an instance of your
  28     application class.
  29
  30     Use wxDECLARE_APP(appClass) in a header file if you want the ::wxGetApp() function
  31     (which returns a reference to your application object) to be visible to other
  32     files.
  33
  34     @library{wxbase}
  35     @category{appmanagement}
  36
  37     @see @ref overview_app, wxApp, wxAppTraits, wxEventLoopBase
  38 */
  39 class wxAppConsole : public wxEvtHandler,
  40                      public wxEventFilter
  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         Note that you should look at wxEvtLoopBase for more event-processing
  62         documentation.
  63     */
  64     //@{
  65
  66     /**
  67         Called by wxWidgets on creation of the application. Override this if you wish
  68         to provide your own (environment-dependent) main loop.
  69
  70         @return 0 under X, and the wParam of the WM_QUIT message under Windows.
  71     */
  72     virtual int MainLoop();
  73
  74     /**
  75         Call this to explicitly exit the main message (event) loop.
  76         You should normally exit the main loop (and the application) by deleting
  77         the top window.
  78
  79         This function simply calls wxEvtLoopBase::Exit() on the active loop.
  80     */
  81     virtual void ExitMainLoop();
  82
  83     /**
  84         Overridden wxEventFilter method.
  85
  86         This function is called before processing any event and allows the application
  87         to preempt the processing of some events, see wxEventFilter
  88         documentation for more information.
  89
  90         wxApp implementation of this method always return -1 indicating that
  91         the event should be processed normally.
  92     */
  93     virtual int FilterEvent(wxEvent& event);
  94
  95     /**
  96         Returns the main event loop instance, i.e.\ the event loop which is started
  97         by OnRun() and which dispatches all events sent from the native toolkit
  98         to the application (except when new event loops are temporarily set-up).
  99         The returned value maybe @NULL. Put initialization code which needs a
 100         non-@NULL main event loop into OnEventLoopEnter().
 101     */
 102     wxEventLoopBase* GetMainLoop() const;
 103
 104     /**
 105         This function simply invokes the given method @a func of the specified
 106         event handler @a handler with the @a event as parameter. It exists solely
 107         to allow to catch the C++ exceptions which could be thrown by all event
 108         handlers in the application in one place: if you want to do this, override
 109         this function in your wxApp-derived class and add try/catch clause(s) to it.
 110     */
 111     virtual void HandleEvent(wxEvtHandler* handler,
 112                              wxEventFunction func,
 113                              wxEvent& event) const;
 114
 115     /**
 116         Returns @true if the application is using an event loop.
 117
 118         This function always returns @true for the GUI applications which
 119         must use an event loop but by default only returns @true for the
 120         console programs if an event loop is already running as it can't know
 121         whether one will be created in the future.
 122
 123         Thus, it only makes sense to override it in console applications which
 124         do use an event loop, to return @true instead of checking if there is a
 125         currently active event loop.
 126      */
 127     virtual bool UsesEventLoop() const;
 128
 129     //@}
 130
 131
 132     /**
 133         @name Pending events
 134
 135         Pending events are handled by wxAppConsole rather than wxEventLoopBase
 136         to allow queuing of events even when there's no event loop
 137         (e.g. in wxAppConsole::OnInit).
 138     */
 139     //@{
 140
 141     /**
 142         Process all pending events; it is necessary to call this function to
 143         process events posted with wxEvtHandler::QueueEvent or wxEvtHandler::AddPendingEvent.
 144
 145         This happens during each event loop iteration (see wxEventLoopBase) in GUI mode but
 146         it may be also called directly.
 147
 148         Note that this function does not only process the pending events for the wxApp object
 149         itself (which derives from wxEvtHandler) but also the pending events for @e any
 150         event handler of this application.
 151
 152         This function will immediately return and do nothing if SuspendProcessingOfPendingEvents()
 153         was called.
 154     */
 155     virtual void ProcessPendingEvents();
 156
 157     /**
 158         Deletes the pending events of all wxEvtHandlers of this application.
 159
 160         See wxEvtHandler::DeletePendingEvents() for warnings about deleting the pending
 161         events.
 162     */
 163     void DeletePendingEvents();
 164
 165     /**
 166         Returns @true if there are pending events on the internal pending event list.
 167
 168         Whenever wxEvtHandler::QueueEvent or wxEvtHandler::AddPendingEvent() are
 169         called (not only for wxApp itself, but for any event handler of the application!),
 170         the internal wxApp's list of handlers with pending events is updated and this
 171         function will return true.
 172     */
 173     bool HasPendingEvents() const;
 174
 175     /**
 176         Temporary suspends processing of the pending events.
 177
 178         @see ResumeProcessingOfPendingEvents()
 179     */
 180     void SuspendProcessingOfPendingEvents();
 181
 182     /**
 183         Resume processing of the pending events previously stopped because of a
 184         call to SuspendProcessingOfPendingEvents().
 185     */
 186     void ResumeProcessingOfPendingEvents();
 187
 188     //@}
 189
 190     /**
 191         Delayed objects destruction.
 192
 193         In applications using events it may be unsafe for an event handler to
 194         delete the object which generated the event because more events may be
 195         still pending for the same object. In this case the handler may call
 196         ScheduleForDestruction() instead.
 197      */
 198     //@{
 199
 200     /**
 201         Schedule the object for destruction in the near future.
 202
 203         Notice that if the application is not using an event loop, i.e. if
 204         UsesEventLoop() returns @false, this method will simply delete the
 205         object immediately.
 206
 207         Examples of using this function inside wxWidgets itself include
 208         deleting the top level windows when they are closed and sockets when
 209         they are disconnected.
 210      */
 211     void ScheduleForDestruction(wxObject *object);
 212
 213     /**
 214         Check if the object had been scheduled for destruction with
 215         ScheduleForDestruction().
 216
 217         This function may be useful as an optimization to avoid doing something
 218         with an object which will be soon destroyed in any case.
 219      */
 220     bool IsScheduledForDestruction(wxObject *object) const;
 221
 222     //@}
 223
 224
 225     bool Yield(bool onlyIfNeeded = false);
 226
 227     /**
 228         Allows external code to modify global ::wxTheApp, but you should really
 229         know what you're doing if you call it.
 230
 231         @param app
 232             Replacement for the global application object.
 233
 234         @see GetInstance()
 235     */
 236     static void SetInstance(wxAppConsole* app);
 237
 238     /**
 239         Returns the one and only global application object.
 240         Usually ::wxTheApp is used instead.
 241
 242         @see SetInstance()
 243     */
 244     static wxAppConsole* GetInstance();
 245
 246     /**
 247         Returns @true if the main event loop is currently running, i.e.\ if the
 248         application is inside OnRun().
 249
 250         This can be useful to test whether events can be dispatched. For example,
 251         if this function returns @false, non-blocking sockets cannot be used because
 252         the events from them would never be processed.
 253     */
 254     static bool IsMainLoopRunning();
 255
 256     /**
 257         @name Callbacks for application-wide "events"
 258     */
 259     //@{
 260
 261     /**
 262         This function is called when an assert failure occurs, i.e.\ the condition
 263         specified in wxASSERT() macro evaluated to @false.
 264
 265         It is only called in debug mode (when @c __WXDEBUG__ is defined) as
 266         asserts are not left in the release code at all.
 267         The base class version shows the default assert failure dialog box proposing to
 268         the user to stop the program, continue or ignore all subsequent asserts.
 269
 270         @param file
 271             the name of the source file where the assert occurred
 272         @param line
 273             the line number in this file where the assert occurred
 274         @param func
 275             the name of the function where the assert occurred, may be
 276             empty if the compiler doesn't support C99 __FUNCTION__
 277         @param cond
 278             the condition of the failed assert in text form
 279         @param msg
 280             the message specified as argument to wxASSERT_MSG or wxFAIL_MSG, will
 281             be @NULL if just wxASSERT or wxFAIL was used
 282     */
 283     virtual void OnAssertFailure(const wxChar *file,
 284                                  int line,
 285                                  const wxChar *func,
 286                                  const wxChar *cond,
 287                                  const wxChar *msg);
 288
 289     /**
 290         Called when command line parsing fails (i.e.\ an incorrect command line option
 291         was specified by the user). The default behaviour is to show the program usage
 292         text and abort the program.
 293
 294         Return @true to continue normal execution or @false to return
 295         @false from OnInit() thus terminating the program.
 296
 297         @see OnInitCmdLine()
 298     */
 299     virtual bool OnCmdLineError(wxCmdLineParser& parser);
 300
 301     /**
 302         Called when the help option (@c --help) was specified on the command line.
 303         The default behaviour is to show the program usage 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 OnCmdLineHelp(wxCmdLineParser& parser);
 311
 312     /**
 313         Called after the command line had been successfully parsed. You may override
 314         this method to test for the values of the various parameters which could be
 315         set from the command line.
 316
 317         Don't forget to call the base class version unless you want to suppress
 318         processing of the standard command line options.
 319         Return @true to continue normal execution or @false to return @false from
 320         OnInit() thus terminating the program.
 321
 322         @see OnInitCmdLine()
 323     */
 324     virtual bool OnCmdLineParsed(wxCmdLineParser& parser);
 325
 326     /**
 327         Called by wxEventLoopBase::SetActive(): you can override this function
 328         and put here the code which needs an active event loop.
 329
 330         Note that this function is called whenever an event loop is activated;
 331         you may want to use wxEventLoopBase::IsMain() to perform initialization
 332         specific for the app's main event loop.
 333
 334         @see OnEventLoopExit()
 335     */
 336     virtual void OnEventLoopEnter(wxEventLoopBase* loop);
 337
 338     /**
 339         Called by wxEventLoopBase::OnExit() for each event loop which
 340         is exited.
 341
 342         @see OnEventLoopEnter()
 343     */
 344     virtual void OnEventLoopExit(wxEventLoopBase* loop);
 345
 346     /**
 347         This function is called if an unhandled exception occurs inside the main
 348         application event loop. It can return @true to ignore the exception and to
 349         continue running the loop or @false to exit the loop and terminate the
 350         program. In the latter case it can also use C++ @c throw keyword to
 351         rethrow the current exception.
 352
 353         The default behaviour of this function is the latter in all ports except under
 354         Windows where a dialog is shown to the user which allows him to choose between
 355         the different options. You may override this function in your class to do
 356         something more appropriate.
 357
 358         Finally note that if the exception is rethrown from here, it can be caught in
 359         OnUnhandledException().
 360     */
 361     virtual bool OnExceptionInMainLoop();
 362
 363     /**
 364         Override this member function for any processing which needs to be
 365         done as the application is about to exit. OnExit is called after
 366         destroying all application windows and controls, but before
 367         wxWidgets cleanup. Note that it is not called at all if
 368         OnInit() failed.
 369
 370         The return value of this function is currently ignored, return the same
 371         value as returned by the base class method if you override it.
 372     */
 373     virtual int OnExit();
 374
 375     /**
 376         This function may be called if something fatal happens: an unhandled
 377         exception under Win32 or a fatal signal under Unix, for example. However,
 378         this will not happen by default: you have to explicitly call
 379         wxHandleFatalExceptions() to enable this.
 380
 381         Generally speaking, this function should only show a message to the user and
 382         return. You may attempt to save unsaved data but this is not guaranteed to
 383         work and, in fact, probably won't.
 384
 385         @see wxHandleFatalExceptions()
 386     */
 387     virtual void OnFatalException();
 388
 389     /**
 390         This must be provided by the application, and will usually create the
 391         application's main window, optionally calling SetTopWindow().
 392
 393         You may use OnExit() to clean up anything initialized here, provided
 394         that the function returns @true.
 395
 396         Notice that if you want to use the command line processing provided by
 397         wxWidgets you have to call the base class version in the derived class
 398         OnInit().
 399
 400         Return @true to continue processing, @false to exit the application
 401         immediately.
 402     */
 403     virtual bool OnInit();
 404
 405     /**
 406         Called from OnInit() and may be used to initialize the parser with the
 407         command line options for this application. The base class versions adds
 408         support for a few standard options only.
 409     */
 410     virtual void OnInitCmdLine(wxCmdLineParser& parser);
 411
 412     /**
 413         This virtual function is where the execution of a program written in wxWidgets
 414         starts. The default implementation just enters the main loop and starts
 415         handling the events until it terminates, either because ExitMainLoop() has
 416         been explicitly called or because the last frame has been deleted and
 417         GetExitOnFrameDelete() flag is @true (this is the default).
 418
 419         The return value of this function becomes the exit code of the program, so it
 420         should return 0 in case of successful termination.
 421     */
 422     virtual int OnRun();
 423
 424     /**
 425         This function is called when an unhandled C++ exception occurs in user
 426         code called by wxWidgets.
 427
 428         Any unhandled exceptions thrown from (overridden versions of) OnInit()
 429         and OnExit() methods as well as any exceptions thrown from inside the
 430         main loop and re-thrown by OnUnhandledException() will result in a call
 431         to this function.
 432
 433         By the time this function is called, the program is already about to
 434         exit and the exception can't be handled nor ignored any more, override
 435         OnUnhandledException() or use explicit @c try/catch blocks around
 436         OnInit() body to be able to handle the exception earlier.
 437
 438         The default implementation dumps information about the exception using
 439         wxMessageOutputBest.
 440     */
 441     virtual void OnUnhandledException();
 442
 443     //@}
 444
 445
 446     /**
 447         @name Application informations
 448     */
 449     //@{
 450
 451     /**
 452         Returns the user-readable application name.
 453
 454         The difference between this string and the one returned by GetAppName()
 455         is that this one is meant to be shown to the user and so should be used
 456         for the window titles, page headers and so on while the other one
 457         should be only used internally, e.g. for the file names or
 458         configuration file keys.
 459
 460         If the application name for display had been previously set by
 461         SetAppDisplayName(), it will be returned by this function. Otherwise,
 462         if SetAppName() had been called its value will be returned; also as is.
 463         Finally if none was called, this function returns the program name
 464         capitalized using wxString::Capitalize().
 465
 466         @since 2.9.0
 467     */
 468     wxString GetAppDisplayName() const;
 469
 470     /**
 471         Returns the application name.
 472
 473         If SetAppName() had been called, returns the string passed to it.
 474         Otherwise returns the program name, i.e. the value of @c argv[0] passed
 475         to the @c main() function.
 476
 477         @see GetAppDisplayName()
 478     */
 479     wxString GetAppName() const;
 480
 481     /**
 482         Gets the class name of the application. The class name may be used in a
 483         platform specific manner to refer to the application.
 484
 485         @see SetClassName()
 486     */
 487     wxString GetClassName() const;
 488
 489     /**
 490         Returns a pointer to the wxAppTraits object for the application.
 491         If you want to customize the wxAppTraits object, you must override the
 492         CreateTraits() function.
 493     */
 494     wxAppTraits* GetTraits();
 495
 496     /**
 497         Returns the user-readable vendor name. The difference between this string
 498         and the one returned by GetVendorName() is that this one is meant to be shown
 499         to the user and so should be used for the window titles, page headers and so on
 500         while the other one should be only used internally, e.g. for the file names or
 501         configuration file keys.
 502
 503         By default, returns the same string as GetVendorName().
 504
 505         @since 2.9.0
 506     */
 507     const wxString& GetVendorDisplayName() const;
 508
 509     /**
 510         Returns the application's vendor name.
 511     */
 512     const wxString& GetVendorName() const;
 513
 514     /**
 515         Set the application name to be used in the user-visible places such as
 516         window titles.
 517
 518         See GetAppDisplayName() for more about the differences between the
 519         display name and name.
 520
 521         Notice that if this function is called, the name is used as is, without
 522         any capitalization as done by default by GetAppDisplayName().
 523     */
 524     void SetAppDisplayName(const wxString& name);
 525
 526     /**
 527         Sets the name of the application. This name should be used for file names,
 528         configuration file entries and other internal strings. For the user-visible
 529         strings, such as the window titles, the application display name set by
 530         SetAppDisplayName() is used instead.
 531
 532         By default the application name is set to the name of its executable file.
 533
 534         @see GetAppName()
 535     */
 536     void SetAppName(const wxString& name);
 537
 538     /**
 539         Sets the class name of the application. This may be used in a platform specific
 540         manner to refer to the application.
 541
 542         @see GetClassName()
 543     */
 544     void SetClassName(const wxString& name);
 545
 546     /**
 547         Set the vendor name to be used in the user-visible places.
 548         See GetVendorDisplayName() for more about the differences between the
 549         display name and name.
 550     */
 551     void SetVendorDisplayName(const wxString& name);
 552
 553     /**
 554         Sets the name of application's vendor. The name will be used
 555         in registry access. A default name is set by wxWidgets.
 556
 557         @see GetVendorName()
 558     */
 559     void SetVendorName(const wxString& name);
 560
 561     //@}
 562
 563     /**
 564         Sets the C locale to the default locale for the current environment.
 565
 566         It is advised to call this to ensure that the underlying toolkit uses
 567         the locale in which the numbers and monetary amounts are shown in the
 568         format expected by user and so on.
 569
 570         Calling this function is roughly equivalent to calling
 571         @code
 572             setlocale(LC_ALL, "");
 573         @endcode
 574         but performs additional toolkit-specific tasks under some platforms and
 575         so should be used instead of @c setlocale() itself. Alternatively, you
 576         can use wxLocale to change the locale with more control.
 577
 578         Notice that this does @em not change the global C++ locale, you need to
 579         do it explicitly if you want, e.g.
 580         @code
 581             std::locale::global(std::locale(""));
 582         @endcode
 583         but be warned that locale support in C++ standard library can be poor
 584         or worse under some platforms, e.g. the above line results in an
 585         immediate crash under OS X up to the version 10.8.2.
 586
 587         @since 2.9.5
 588      */
 589     void SetCLocale();
 590
 591     /**
 592         Number of command line arguments (after environment-specific processing).
 593     */
 594     int argc;
 595
 596     /**
 597         Command line arguments (after environment-specific processing).
 598
 599         Under Windows and Linux/Unix, you should parse the command line
 600         arguments and check for files to be opened when starting your
 601         application. Under OS X, you need to override MacOpenFiles()
 602         since command line arguments are used differently there.
 603
 604         You may use the wxCmdLineParser to parse command line arguments.
 605     */
 606     wxChar** argv;
 607 };
 608
 609
 610
 611
 612 /**
 613     @class wxApp
 614
 615     The wxApp class represents the application itself when @c wxUSE_GUI=1.
 616
 617     In addition to the features provided by wxAppConsole it keeps track of
 618     the <em>top window</em> (see SetTopWindow()) and adds support for
 619     video modes (see SetVideoMode()).
 620
 621     In general, application-wide settings for GUI-only apps are accessible
 622     from wxApp (or from wxSystemSettings or wxSystemOptions classes).
 623
 624     @beginEventEmissionTable
 625     @event{EVT_QUERY_END_SESSION(func)}
 626         Process a query end session event, supplying the member function.
 627         See wxCloseEvent.
 628     @event{EVT_END_SESSION(func)}
 629         Process an end session event, supplying the member function.
 630         See wxCloseEvent.
 631     @event{EVT_ACTIVATE_APP(func)}
 632         Process a @c wxEVT_ACTIVATE_APP event. See wxActivateEvent.
 633     @event{EVT_HIBERNATE(func)}
 634         Process a hibernate event. See wxActivateEvent.
 635     @event{EVT_DIALUP_CONNECTED(func)}
 636         A connection with the network was established. See wxDialUpEvent.
 637     @event{EVT_DIALUP_DISCONNECTED(func)}
 638         The connection with the network was lost. See wxDialUpEvent.
 639     @event{EVT_IDLE(func)}
 640         Process a @c wxEVT_IDLE event. See wxIdleEvent.
 641     @endEventTable
 642
 643     @library{wxbase}
 644     @category{appmanagement}
 645
 646     @see @ref overview_app, wxAppTraits, wxEventLoopBase, wxSystemSettings
 647 */
 648 class wxApp : public wxAppConsole
 649 {
 650 public:
 651     /**
 652         Constructor. Called implicitly with a definition of a wxApp object.
 653     */
 654     wxApp();
 655
 656     /**
 657         Destructor. Will be called implicitly on program exit if the wxApp
 658         object is created on the stack.
 659     */
 660     virtual ~wxApp();
 661
 662     /**
 663         Get display mode that is used use. This is only used in framebuffer
 664         wxWidgets ports such as wxDFB.
 665     */
 666     virtual wxVideoMode GetDisplayMode() const;
 667
 668     /**
 669         Returns @true if the application will exit when the top-level frame is deleted.
 670
 671         @see SetExitOnFrameDelete()
 672     */
 673     bool GetExitOnFrameDelete() const;
 674
 675     /**
 676         Return the layout direction for the current locale or @c wxLayout_Default
 677         if it's unknown.
 678     */
 679     virtual wxLayoutDirection GetLayoutDirection() const;
 680
 681     /**
 682         Returns @true if the application will use the best visual on systems that support
 683         different visuals, @false otherwise.
 684
 685         @see SetUseBestVisual()
 686     */
 687     bool GetUseBestVisual() const;
 688
 689     /**
 690         Returns a pointer to the top window.
 691
 692         @remarks
 693             If the top window hasn't been set using SetTopWindow(), this function
 694             will find the first top-level window (frame or dialog or instance of
 695             wxTopLevelWindow) from the internal top level window list and return that.
 696
 697         @see SetTopWindow()
 698     */
 699     virtual wxWindow* GetTopWindow() const;
 700
 701     /**
 702         Returns @true if the application is active, i.e.\ if one of its windows is
 703         currently in the foreground.
 704
 705         If this function returns @false and you need to attract users attention to
 706         the application, you may use wxTopLevelWindow::RequestUserAttention to do it.
 707     */
 708     virtual bool IsActive() const;
 709
 710     /**
 711         This function is similar to wxYield(), except that it disables the user
 712         input to all program windows before calling wxAppConsole::Yield and re-enables it
 713         again afterwards. If @a win is not @NULL, this window will remain enabled,
 714         allowing the implementation of some limited user interaction.
 715         Returns the result of the call to wxAppConsole::Yield.
 716
 717         @see wxSafeYield
 718     */
 719     virtual bool SafeYield(wxWindow *win, bool onlyIfNeeded);
 720
 721     /**
 722         Works like SafeYield() with @e onlyIfNeeded == @true except that
 723         it allows the caller to specify a mask of events to be processed.
 724
 725         See wxAppConsole::YieldFor for more info.
 726     */
 727     virtual bool SafeYieldFor(wxWindow *win, long eventsToProcess);
 728
 729     /**
 730         Windows-only function for processing a message. This function is called
 731         from the main message loop, checking for windows that may wish to process it.
 732
 733         The function returns @true if the message was processed, @false otherwise.
 734         If you use wxWidgets with another class library with its own message loop,
 735         you should make sure that this function is called to allow wxWidgets to
 736         receive messages. For example, to allow co-existence with the Microsoft
 737         Foundation Classes, override the PreTranslateMessage function:
 738
 739         @code
 740         // Provide wxWidgets message loop compatibility
 741         BOOL CTheApp::PreTranslateMessage(MSG *msg)
 742         {
 743             if (wxTheApp && wxTheApp->ProcessMessage((WXMSW *)msg))
 744                 return true;
 745             else
 746                 return CWinApp::PreTranslateMessage(msg);
 747         }
 748         @endcode
 749
 750         @onlyfor{wxmsw}
 751     */
 752     bool ProcessMessage(WXMSG* msg);
 753
 754     /**
 755         Set display mode to use. This is only used in framebuffer wxWidgets
 756         ports such as wxDFB.
 757     */
 758     virtual bool SetDisplayMode(const wxVideoMode& info);
 759
 760     /**
 761         Allows the programmer to specify whether the application will exit when the
 762         top-level frame is deleted.
 763
 764         @param flag
 765             If @true (the default), the application will exit when the top-level frame
 766             is deleted. If @false, the application will continue to run.
 767
 768         @see GetExitOnFrameDelete(), @ref overview_app_shutdown
 769     */
 770     void SetExitOnFrameDelete(bool flag);
 771
 772     /**
 773         Allows runtime switching of the UI environment theme.
 774
 775         Currently implemented for wxGTK2-only.
 776         Return @true if theme was successfully changed.
 777
 778         @param theme
 779             The name of the new theme or an absolute path to a gtkrc-theme-file
 780     */
 781     virtual bool SetNativeTheme(const wxString& theme);
 782
 783     /**
 784         Sets the 'top' window. You can call this from within OnInit() to let wxWidgets
 785         know which is the main window. You don't have to set the top window;
 786         it is only a convenience so that (for example) certain dialogs without parents
 787         can use a specific window as the top window.
 788
 789         If no top window is specified by the application, wxWidgets just uses the
 790         first frame or dialog (or better, any wxTopLevelWindow) in its top-level
 791         window list, when it needs to use the top window.
 792         If you previously called SetTopWindow() and now you need to restore this
 793         automatic behaviour you can call @code wxApp::SetTopWindow(NULL) @endcode.
 794
 795         @param window
 796             The new top window.
 797
 798         @see GetTopWindow(), OnInit()
 799     */
 800     void SetTopWindow(wxWindow* window);
 801
 802     /**
 803         Allows the programmer to specify whether the application will use the best
 804         visual on systems that support several visual on the same display. This is typically
 805         the case under Solaris and IRIX, where the default visual is only 8-bit whereas
 806         certain applications are supposed to run in TrueColour mode.
 807
 808         Note that this function has to be called in the constructor of the wxApp
 809         instance and won't have any effect when called later on.
 810         This function currently only has effect under GTK.
 811
 812         @param flag
 813             If @true, the app will use the best visual.
 814         @param forceTrueColour
 815             If @true then the application will try to force using a TrueColour
 816             visual and abort the app if none is found.
 817     */
 818     void SetUseBestVisual(bool flag, bool forceTrueColour = false);
 819
 820
 821     /**
 822         @name Mac-specific functions
 823     */
 824     //@{
 825
 826     /**
 827         Called in response of an "open-application" Apple event.
 828         Override this to create a new document in your app.
 829
 830         @onlyfor{wxosx}
 831     */
 832     virtual void MacNewFile();
 833
 834     /**
 835         Called in response of an openFiles message with Cocoa, or an
 836         "open-document" Apple event with Carbon.
 837
 838         You need to override this method in order to open one or more document
 839         files after the user double clicked on it or if the files and/or
 840         folders were dropped on either the application in the dock or the
 841         application icon in Finder.
 842
 843         By default this method calls MacOpenFile for each file/folder.
 844
 845         @onlyfor{wxosx}
 846
 847         @since 2.9.3
 848     */
 849     virtual void MacOpenFiles(const wxArrayString& fileNames);
 850
 851     /**
 852         Called in response of an "open-document" Apple event.
 853
 854         @deprecated
 855         This function is kept mostly for backwards compatibility. Please
 856         override wxApp::MacOpenFiles method instead in any new code.
 857
 858         @onlyfor{wxosx}
 859     */
 860     virtual void MacOpenFile(const wxString& fileName);
 861
 862     /**
 863         Called in response of a "get-url" Apple event.
 864
 865         @onlyfor{wxosx}
 866     */
 867     virtual void MacOpenURL(const wxString& url);
 868
 869     /**
 870         Called in response of a "print-document" Apple event.
 871
 872         @onlyfor{wxosx}
 873     */
 874     virtual void MacPrintFile(const wxString& fileName);
 875
 876     /**
 877         Called in response of a "reopen-application" Apple event.
 878
 879         @onlyfor{wxosx}
 880     */
 881     virtual void MacReopenApp();
 882
 883     //@}
 884
 885 };
 886
 887
 888
 889 // ============================================================================
 890 // Global functions/macros
 891 // ============================================================================
 892
 893
 894 /** @addtogroup group_funcmacro_rtti */
 895 //@{
 896
 897 /**
 898     This is used in headers to create a forward declaration of the ::wxGetApp()
 899     function implemented by wxIMPLEMENT_APP().
 900
 901     It creates the declaration <tt>className& wxGetApp()</tt>
 902     (requires a final semicolon).
 903
 904     @header{wx/app.h}
 905
 906     Example:
 907
 908     @code
 909     wxDECLARE_APP(MyApp);
 910     @endcode
 911 */
 912 #define wxDECLARE_APP( className )
 913
 914 /**
 915     This is used in the application class implementation file to make the
 916     application class known to wxWidgets for dynamic construction.
 917     Note that this macro requires a final semicolon.
 918
 919     @header{wx/app.h}
 920
 921     Example:
 922
 923     @code
 924     wxIMPLEMENT_APP(MyApp);
 925     @endcode
 926
 927     @see wxDECLARE_APP()
 928 */
 929 #define wxIMPLEMENT_APP( className )
 930
 931 //@}
 932
 933
 934
 935 /**
 936     The global pointer to the singleton wxApp object.
 937
 938     @see wxApp::GetInstance()
 939 */
 940 wxApp *wxTheApp;
 941
 942
 943
 944 /** @addtogroup group_funcmacro_appinitterm */
 945 //@{
 946
 947 /**
 948     This function doesn't exist in wxWidgets but it is created by using the
 949     wxIMPLEMENT_APP() macro.
 950
 951     Thus, before using it anywhere but in the same module where this macro is
 952     used, you must make it available using wxDECLARE_APP().
 953
 954     The advantage of using this function compared to directly using the global
 955     ::wxTheApp pointer is that the latter is of type wxApp* and so wouldn't
 956     allow you to access the functions specific to your application class but
 957     not present in wxApp while wxGetApp() returns the object of the right type.
 958
 959     @header{wx/app.h}
 960 */
 961 wxAppDerivedClass& wxGetApp();
 962
 963 /**
 964     If @a doIt is @true, the fatal exceptions (also known as general protection
 965     faults under Windows or segmentation violations in the Unix world) will be
 966     caught and passed to wxApp::OnFatalException.
 967
 968     By default, i.e. before this function is called, they will be handled in
 969     the normal way which usually just means that the application will be
 970     terminated. Calling wxHandleFatalExceptions() with @a doIt equal to @false
 971     will restore this default behaviour.
 972
 973     Notice that this function is only available if @c wxUSE_ON_FATAL_EXCEPTION
 974     is 1 and under Windows platform this requires a compiler with support for
 975     SEH (structured exception handling) which currently means only Microsoft
 976     Visual C++ or a recent Borland C++ version.
 977
 978     @header{wx/app.h}
 979 */
 980 bool wxHandleFatalExceptions(bool doIt = true);
 981
 982 /**
 983     This function is used in wxBase only and only if you don't create
 984     wxApp object at all. In this case you must call it from your
 985     @c main() function before calling any other wxWidgets functions.
 986
 987     If the function returns @false the initialization could not be performed,
 988     in this case the library cannot be used and wxUninitialize() shouldn't be
 989     called neither.
 990
 991     This function may be called several times but wxUninitialize() must be
 992     called for each successful call to this function.
 993
 994     @header{wx/app.h}
 995 */
 996 bool wxInitialize();
 997
 998 /**
 999     This function is for use in console (wxBase) programs only. It must be called
1000     once for each previous successful call to wxInitialize().
1001
1002     @header{wx/app.h}
1003 */
1004 void wxUninitialize();
1005
1006 /**
1007     This function wakes up the (internal and platform dependent) idle system,
1008     i.e. it will force the system to send an idle event even if the system
1009     currently @e is idle and thus would not send any idle event until after
1010     some other event would get sent. This is also useful for sending events
1011     between two threads and is used by the corresponding functions
1012     wxPostEvent() and wxEvtHandler::AddPendingEvent().
1013
1014     @header{wx/app.h}
1015 */
1016 void wxWakeUpIdle();
1017
1018 /**
1019     Calls wxAppConsole::Yield.
1020
1021     @deprecated
1022     This function is kept only for backwards compatibility. Please use
1023     the wxAppConsole::Yield method instead in any new code.
1024
1025     @header{wx/app.h}
1026 */
1027 bool wxYield();
1028
1029 /**
1030     Calls wxApp::SafeYield.
1031
1032     @header{wx/app.h}
1033 */
1034 bool wxSafeYield(wxWindow* win = NULL, bool onlyIfNeeded = false);
1035
1036 /**
1037     This function initializes wxWidgets in a platform-dependent way. Use this if you
1038     are not using the default wxWidgets entry code (e.g. main or WinMain).
1039
1040     For example, you can initialize wxWidgets from an Microsoft Foundation Classes
1041     (MFC) application using this function.
1042
1043     @note This overload of wxEntry is available under all platforms.
1044
1045     @see wxEntryStart()
1046
1047     @header{wx/app.h}
1048 */
1049 int wxEntry(int& argc, wxChar** argv);
1050
1051 /**
1052     See wxEntry(int&,wxChar**) for more info about this function.
1053
1054     Notice that under Windows CE platform, and only there, the type of @a pCmdLine
1055     is @c wchar_t *, otherwise it is @c char *, even in Unicode build.
1056
1057     @remarks To clean up wxWidgets, call wxApp::OnExit followed by the static
1058              function wxApp::CleanUp. For example, if exiting from an MFC application
1059              that also uses wxWidgets:
1060              @code
1061              int CTheApp::ExitInstance()
1062              {
1063                 // OnExit isn't called by CleanUp so must be called explicitly.
1064                 wxTheApp->OnExit();
1065                 wxApp::CleanUp();
1066
1067                 return CWinApp::ExitInstance();
1068              }
1069              @endcode
1070
1071     @header{wx/app.h}
1072 */
1073 int wxEntry(HINSTANCE hInstance,
1074             HINSTANCE hPrevInstance = NULL,
1075             char* pCmdLine = NULL,
1076             int nCmdShow = SW_SHOWNORMAL);
1077
1078 //@}
1079
1080
1081
1082 /** @addtogroup group_funcmacro_procctrl */
1083 //@{
1084
1085 /**
1086     Exits application after calling wxApp::OnExit.
1087
1088     Should only be used in an emergency: normally the top-level frame
1089     should be deleted (after deleting all other frames) to terminate the
1090     application. See wxCloseEvent and wxApp.
1091
1092     @header{wx/app.h}
1093 */
1094 void wxExit();
1095
1096 //@}
1097
1098 /** @addtogroup group_funcmacro_debug */
1099 //@{
1100
1101 /**
1102     @def wxDISABLE_DEBUG_SUPPORT()
1103
1104     Use this macro to disable all debugging code in release build when not
1105     using wxIMPLEMENT_APP().
1106
1107     Currently this macro disables assert checking and debug and trace level
1108     logging messages in release build (i.e. when @c NDEBUG is defined). It is
1109     used by wxIMPLEMENT_APP() macro so you only need to use it explicitly if you
1110     don't use this macro but initialize wxWidgets directly (e.g. calls
1111     wxEntry() or wxEntryStart() itself).
1112
1113     If you do not want to disable debugging code even in release build of your
1114     application, you can use wxSetDefaultAssertHandler() and
1115     wxLog::SetLogLevel() with @c wxLOG_Max parameter to enable assertions and
1116     debug logging respectively.
1117
1118     @see wxDISABLE_ASSERTS_IN_RELEASE_BUILD(),
1119          wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD(),
1120          @ref overview_debugging
1121
1122     @since 2.9.1
1123
1124     @header{wx/app.h}
1125  */
1126 #define wxDISABLE_DEBUG_SUPPORT() \
1127     wxDISABLE_ASSERTS_IN_RELEASE_BUILD(); \
1128     wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD()
1129
1130 //@}
1131