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     /**
 566         Number of command line arguments (after environment-specific processing).
 567     */
 568     int argc;
 569
 570     /**
 571         Command line arguments (after environment-specific processing).
 572
 573         Under Windows and Linux/Unix, you should parse the command line
 574         arguments and check for files to be opened when starting your
 575         application. Under OS X, you need to override MacOpenFiles()
 576         since command line arguments are used differently there.
 577
 578         You may use the wxCmdLineParser to parse command line arguments.
 579     */
 580     wxChar** argv;
 581 };
 582
 583
 584
 585
 586 /**
 587     @class wxApp
 588
 589     The wxApp class represents the application itself when @c wxUSE_GUI=1.
 590
 591     In addition to the features provided by wxAppConsole it keeps track of
 592     the <em>top window</em> (see SetTopWindow()) and adds support for
 593     video modes (see SetVideoMode()).
 594
 595     In general, application-wide settings for GUI-only apps are accessible
 596     from wxApp (or from wxSystemSettings or wxSystemOptions classes).
 597
 598     @beginEventEmissionTable
 599     @event{EVT_QUERY_END_SESSION(func)}
 600         Process a query end session event, supplying the member function.
 601         See wxCloseEvent.
 602     @event{EVT_END_SESSION(func)}
 603         Process an end session event, supplying the member function.
 604         See wxCloseEvent.
 605     @event{EVT_ACTIVATE_APP(func)}
 606         Process a @c wxEVT_ACTIVATE_APP event. See wxActivateEvent.
 607     @event{EVT_HIBERNATE(func)}
 608         Process a hibernate event. See wxActivateEvent.
 609     @event{EVT_DIALUP_CONNECTED(func)}
 610         A connection with the network was established. See wxDialUpEvent.
 611     @event{EVT_DIALUP_DISCONNECTED(func)}
 612         The connection with the network was lost. See wxDialUpEvent.
 613     @event{EVT_IDLE(func)}
 614         Process a @c wxEVT_IDLE event. See wxIdleEvent.
 615     @endEventTable
 616
 617     @library{wxbase}
 618     @category{appmanagement}
 619
 620     @see @ref overview_app, wxAppTraits, wxEventLoopBase, wxSystemSettings
 621 */
 622 class wxApp : public wxAppConsole
 623 {
 624 public:
 625     /**
 626         Constructor. Called implicitly with a definition of a wxApp object.
 627     */
 628     wxApp();
 629
 630     /**
 631         Destructor. Will be called implicitly on program exit if the wxApp
 632         object is created on the stack.
 633     */
 634     virtual ~wxApp();
 635
 636     /**
 637         Get display mode that is used use. This is only used in framebuffer
 638         wxWidgets ports such as wxDFB.
 639     */
 640     virtual wxVideoMode GetDisplayMode() const;
 641
 642     /**
 643         Returns @true if the application will exit when the top-level frame is deleted.
 644
 645         @see SetExitOnFrameDelete()
 646     */
 647     bool GetExitOnFrameDelete() const;
 648
 649     /**
 650         Return the layout direction for the current locale or @c wxLayout_Default
 651         if it's unknown.
 652     */
 653     virtual wxLayoutDirection GetLayoutDirection() const;
 654
 655     /**
 656         Returns @true if the application will use the best visual on systems that support
 657         different visuals, @false otherwise.
 658
 659         @see SetUseBestVisual()
 660     */
 661     bool GetUseBestVisual() const;
 662
 663     /**
 664         Returns a pointer to the top window.
 665
 666         @remarks
 667             If the top window hasn't been set using SetTopWindow(), this function
 668             will find the first top-level window (frame or dialog or instance of
 669             wxTopLevelWindow) from the internal top level window list and return that.
 670
 671         @see SetTopWindow()
 672     */
 673     virtual wxWindow* GetTopWindow() const;
 674
 675     /**
 676         Returns @true if the application is active, i.e. if one of its windows is
 677         currently in the foreground.
 678
 679         If this function returns @false and you need to attract users attention to
 680         the application, you may use wxTopLevelWindow::RequestUserAttention to do it.
 681     */
 682     virtual bool IsActive() const;
 683
 684     /**
 685         This function is similar to wxYield(), except that it disables the user
 686         input to all program windows before calling wxAppConsole::Yield and re-enables it
 687         again afterwards. If @a win is not @NULL, this window will remain enabled,
 688         allowing the implementation of some limited user interaction.
 689         Returns the result of the call to wxAppConsole::Yield.
 690
 691         @see wxSafeYield
 692     */
 693     virtual bool SafeYield(wxWindow *win, bool onlyIfNeeded);
 694
 695     /**
 696         Works like SafeYield() with @e onlyIfNeeded == @true except that
 697         it allows the caller to specify a mask of events to be processed.
 698
 699         See wxAppConsole::YieldFor for more info.
 700     */
 701     virtual bool SafeYieldFor(wxWindow *win, long eventsToProcess);
 702
 703     /**
 704         Windows-only function for processing a message. This function is called
 705         from the main message loop, checking for windows that may wish to process it.
 706
 707         The function returns @true if the message was processed, @false otherwise.
 708         If you use wxWidgets with another class library with its own message loop,
 709         you should make sure that this function is called to allow wxWidgets to
 710         receive messages. For example, to allow co-existence with the Microsoft
 711         Foundation Classes, override the PreTranslateMessage function:
 712
 713         @code
 714         // Provide wxWidgets message loop compatibility
 715         BOOL CTheApp::PreTranslateMessage(MSG *msg)
 716         {
 717             if (wxTheApp && wxTheApp->ProcessMessage((WXMSW *)msg))
 718                 return true;
 719             else
 720                 return CWinApp::PreTranslateMessage(msg);
 721         }
 722         @endcode
 723
 724         @onlyfor{wxmsw}
 725     */
 726     bool ProcessMessage(WXMSG* msg);
 727
 728     /**
 729         Set display mode to use. This is only used in framebuffer wxWidgets
 730         ports such as wxDFB.
 731     */
 732     virtual bool SetDisplayMode(const wxVideoMode& info);
 733
 734     /**
 735         Allows the programmer to specify whether the application will exit when the
 736         top-level frame is deleted.
 737
 738         @param flag
 739             If @true (the default), the application will exit when the top-level frame
 740             is deleted. If @false, the application will continue to run.
 741
 742         @see GetExitOnFrameDelete(), @ref overview_app_shutdown
 743     */
 744     void SetExitOnFrameDelete(bool flag);
 745
 746     /**
 747         Allows runtime switching of the UI environment theme.
 748
 749         Currently implemented for wxGTK2-only.
 750         Return @true if theme was successfully changed.
 751
 752         @param theme
 753             The name of the new theme or an absolute path to a gtkrc-theme-file
 754     */
 755     virtual bool SetNativeTheme(const wxString& theme);
 756
 757     /**
 758         Sets the 'top' window. You can call this from within OnInit() to let wxWidgets
 759         know which is the main window. You don't have to set the top window;
 760         it is only a convenience so that (for example) certain dialogs without parents
 761         can use a specific window as the top window.
 762
 763         If no top window is specified by the application, wxWidgets just uses the
 764         first frame or dialog (or better, any wxTopLevelWindow) in its top-level
 765         window list, when it needs to use the top window.
 766         If you previously called SetTopWindow() and now you need to restore this
 767         automatic behaviour you can call @code wxApp::SetTopWindow(NULL) @endcode.
 768
 769         @param window
 770             The new top window.
 771
 772         @see GetTopWindow(), OnInit()
 773     */
 774     void SetTopWindow(wxWindow* window);
 775
 776     /**
 777         Allows the programmer to specify whether the application will use the best
 778         visual on systems that support several visual on the same display. This is typically
 779         the case under Solaris and IRIX, where the default visual is only 8-bit whereas
 780         certain applications are supposed to run in TrueColour mode.
 781
 782         Note that this function has to be called in the constructor of the wxApp
 783         instance and won't have any effect when called later on.
 784         This function currently only has effect under GTK.
 785
 786         @param flag
 787             If @true, the app will use the best visual.
 788         @param forceTrueColour
 789             If @true then the application will try to force using a TrueColour
 790             visual and abort the app if none is found.
 791     */
 792     void SetUseBestVisual(bool flag, bool forceTrueColour = false);
 793
 794
 795     /**
 796         @name Mac-specific functions
 797     */
 798     //@{
 799
 800     /**
 801         Called in response of an "open-application" Apple event.
 802         Override this to create a new document in your app.
 803
 804         @onlyfor{wxosx}
 805     */
 806     virtual void MacNewFile();
 807
 808     /**
 809         Called in response of an openFiles message with Cocoa, or an
 810         "open-document" Apple event with Carbon.
 811
 812         You need to override this method in order to open one or more document
 813         files after the user double clicked on it or if the files and/or
 814         folders were dropped on either the application in the dock or the
 815         application icon in Finder.
 816
 817         By default this method calls MacOpenFile for each file/folder.
 818
 819         @onlyfor{wxosx}
 820
 821         @since 2.9.3
 822     */
 823     virtual void MacOpenFiles(const wxArrayString& fileNames);
 824
 825     /**
 826         Called in response of an "open-document" Apple event.
 827
 828         @deprecated
 829         This function is kept mostly for backwards compatibility. Please
 830         override wxApp::MacOpenFiles method instead in any new code.
 831
 832         @onlyfor{wxosx}
 833     */
 834     virtual void MacOpenFile(const wxString& fileName);
 835
 836     /**
 837         Called in response of a "get-url" Apple event.
 838
 839         @onlyfor{wxosx}
 840     */
 841     virtual void MacOpenURL(const wxString& url);
 842
 843     /**
 844         Called in response of a "print-document" Apple event.
 845
 846         @onlyfor{wxosx}
 847     */
 848     virtual void MacPrintFile(const wxString& fileName);
 849
 850     /**
 851         Called in response of a "reopen-application" Apple event.
 852
 853         @onlyfor{wxosx}
 854     */
 855     virtual void MacReopenApp();
 856
 857     //@}
 858
 859 };
 860
 861
 862
 863 // ============================================================================
 864 // Global functions/macros
 865 // ============================================================================
 866
 867
 868 /** @addtogroup group_funcmacro_rtti */
 869 //@{
 870
 871 /**
 872     This is used in headers to create a forward declaration of the ::wxGetApp()
 873     function implemented by wxIMPLEMENT_APP().
 874
 875     It creates the declaration <tt>className& wxGetApp()</tt>
 876     (requires a final semicolon).
 877
 878     @header{wx/app.h}
 879
 880     Example:
 881
 882     @code
 883     wxDECLARE_APP(MyApp);
 884     @endcode
 885 */
 886 #define wxDECLARE_APP( className )
 887
 888 /**
 889     This is used in the application class implementation file to make the
 890     application class known to wxWidgets for dynamic construction.
 891     Note that this macro requires a final semicolon.
 892
 893     @header{wx/app.h}
 894
 895     Example:
 896
 897     @code
 898     wxIMPLEMENT_APP(MyApp);
 899     @endcode
 900
 901     @see wxDECLARE_APP()
 902 */
 903 #define wxIMPLEMENT_APP( className )
 904
 905 //@}
 906
 907
 908
 909 /**
 910     The global pointer to the singleton wxApp object.
 911
 912     @see wxApp::GetInstance()
 913 */
 914 wxApp *wxTheApp;
 915
 916
 917
 918 /** @addtogroup group_funcmacro_appinitterm */
 919 //@{
 920
 921 /**
 922     This function doesn't exist in wxWidgets but it is created by using the
 923     wxIMPLEMENT_APP() macro.
 924
 925     Thus, before using it anywhere but in the same module where this macro is
 926     used, you must make it available using wxDECLARE_APP().
 927
 928     The advantage of using this function compared to directly using the global
 929     ::wxTheApp pointer is that the latter is of type wxApp* and so wouldn't
 930     allow you to access the functions specific to your application class but
 931     not present in wxApp while wxGetApp() returns the object of the right type.
 932
 933     @header{wx/app.h}
 934 */
 935 wxAppDerivedClass& wxGetApp();
 936
 937 /**
 938     If @a doIt is @true, the fatal exceptions (also known as general protection
 939     faults under Windows or segmentation violations in the Unix world) will be
 940     caught and passed to wxApp::OnFatalException.
 941
 942     By default, i.e. before this function is called, they will be handled in
 943     the normal way which usually just means that the application will be
 944     terminated. Calling wxHandleFatalExceptions() with @a doIt equal to @false
 945     will restore this default behaviour.
 946
 947     Notice that this function is only available if @c wxUSE_ON_FATAL_EXCEPTION
 948     is 1 and under Windows platform this requires a compiler with support for
 949     SEH (structured exception handling) which currently means only Microsoft
 950     Visual C++ or a recent Borland C++ version.
 951
 952     @header{wx/app.h}
 953 */
 954 bool wxHandleFatalExceptions(bool doIt = true);
 955
 956 /**
 957     This function is used in wxBase only and only if you don't create
 958     wxApp object at all. In this case you must call it from your
 959     @c main() function before calling any other wxWidgets functions.
 960
 961     If the function returns @false the initialization could not be performed,
 962     in this case the library cannot be used and wxUninitialize() shouldn't be
 963     called neither.
 964
 965     This function may be called several times but wxUninitialize() must be
 966     called for each successful call to this function.
 967
 968     @header{wx/app.h}
 969 */
 970 bool wxInitialize();
 971
 972 /**
 973     This function is for use in console (wxBase) programs only. It must be called
 974     once for each previous successful call to wxInitialize().
 975
 976     @header{wx/app.h}
 977 */
 978 void wxUninitialize();
 979
 980 /**
 981     This function wakes up the (internal and platform dependent) idle system,
 982     i.e. it will force the system to send an idle event even if the system
 983     currently @e is idle and thus would not send any idle event until after
 984     some other event would get sent. This is also useful for sending events
 985     between two threads and is used by the corresponding functions
 986     wxPostEvent() and wxEvtHandler::AddPendingEvent().
 987
 988     @header{wx/app.h}
 989 */
 990 void wxWakeUpIdle();
 991
 992 /**
 993     Calls wxAppConsole::Yield.
 994
 995     @deprecated
 996     This function is kept only for backwards compatibility. Please use
 997     the wxAppConsole::Yield method instead in any new code.
 998
 999     @header{wx/app.h}
1000 */
1001 bool wxYield();
1002
1003 /**
1004     Calls wxApp::SafeYield.
1005
1006     @header{wx/app.h}
1007 */
1008 bool wxSafeYield(wxWindow* win = NULL, bool onlyIfNeeded = false);
1009
1010 /**
1011     This function initializes wxWidgets in a platform-dependent way. Use this if you
1012     are not using the default wxWidgets entry code (e.g. main or WinMain).
1013
1014     For example, you can initialize wxWidgets from an Microsoft Foundation Classes
1015     (MFC) application using this function.
1016
1017     @note This overload of wxEntry is available under all platforms.
1018
1019     @see wxEntryStart()
1020
1021     @header{wx/app.h}
1022 */
1023 int wxEntry(int& argc, wxChar** argv);
1024
1025 /**
1026     See wxEntry(int&,wxChar**) for more info about this function.
1027
1028     Notice that under Windows CE platform, and only there, the type of @a pCmdLine
1029     is @c wchar_t *, otherwise it is @c char *, even in Unicode build.
1030
1031     @remarks To clean up wxWidgets, call wxApp::OnExit followed by the static
1032              function wxApp::CleanUp. For example, if exiting from an MFC application
1033              that also uses wxWidgets:
1034              @code
1035              int CTheApp::ExitInstance()
1036              {
1037                 // OnExit isn't called by CleanUp so must be called explicitly.
1038                 wxTheApp->OnExit();
1039                 wxApp::CleanUp();
1040
1041                 return CWinApp::ExitInstance();
1042              }
1043              @endcode
1044
1045     @header{wx/app.h}
1046 */
1047 int wxEntry(HINSTANCE hInstance,
1048             HINSTANCE hPrevInstance = NULL,
1049             char* pCmdLine = NULL,
1050             int nCmdShow = SW_SHOWNORMAL);
1051
1052 //@}
1053
1054
1055
1056 /** @addtogroup group_funcmacro_procctrl */
1057 //@{
1058
1059 /**
1060     Exits application after calling wxApp::OnExit.
1061
1062     Should only be used in an emergency: normally the top-level frame
1063     should be deleted (after deleting all other frames) to terminate the
1064     application. See wxCloseEvent and wxApp.
1065
1066     @header{wx/app.h}
1067 */
1068 void wxExit();
1069
1070 //@}
1071
1072 /** @addtogroup group_funcmacro_debug */
1073 //@{
1074
1075 /**
1076     @def wxDISABLE_DEBUG_SUPPORT()
1077
1078     Use this macro to disable all debugging code in release build when not
1079     using wxIMPLEMENT_APP().
1080
1081     Currently this macro disables assert checking and debug and trace level
1082     logging messages in release build (i.e. when @c NDEBUG is defined). It is
1083     used by wxIMPLEMENT_APP() macro so you only need to use it explicitly if you
1084     don't use this macro but initialize wxWidgets directly (e.g. calls
1085     wxEntry() or wxEntryStart() itself).
1086
1087     If you do not want to disable debugging code even in release build of your
1088     application, you can use wxSetDefaultAssertHandler() and
1089     wxLog::SetLogLevel() with @c wxLOG_Max parameter to enable assertions and
1090     debug logging respectively.
1091
1092     @see wxDISABLE_ASSERTS_IN_RELEASE_BUILD(),
1093          wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD(),
1094          @ref overview_debugging
1095
1096     @since 2.9.1
1097
1098     @header{wx/app.h}
1099  */
1100 #define wxDISABLE_DEBUG_SUPPORT() \
1101     wxDISABLE_ASSERTS_IN_RELEASE_BUILD(); \
1102     wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD()
1103
1104 //@}
1105