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