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     static long GetMacAboutMenuItemId();
 859     static long GetMacPreferencesMenuItemId();
 860     static long GetMacExitMenuItemId();
 861     static wxString GetMacHelpMenuTitleName();
 862
 863     static void SetMacAboutMenuItemId(long val);
 864     static void SetMacPreferencesMenuItemId(long val);
 865     static void SetMacExitMenuItemId(long val);
 866     static void SetMacHelpMenuTitleName(const wxString& val);
 867
 868     //@}
 869
 870 };
 871
 872
 873
 874 // ============================================================================
 875 // Global functions/macros
 876 // ============================================================================
 877
 878
 879 /** @addtogroup group_funcmacro_rtti */
 880 //@{
 881
 882 /**
 883     This is used in headers to create a forward declaration of the ::wxGetApp()
 884     function implemented by wxIMPLEMENT_APP().
 885
 886     It creates the declaration <tt>className& wxGetApp()</tt>
 887     (requires a final semicolon).
 888
 889     @header{wx/app.h}
 890
 891     Example:
 892
 893     @code
 894     wxDECLARE_APP(MyApp);
 895     @endcode
 896 */
 897 #define wxDECLARE_APP( className )
 898
 899 /**
 900     This is used in the application class implementation file to make the
 901     application class known to wxWidgets for dynamic construction.
 902     Note that this macro requires a final semicolon.
 903
 904     @header{wx/app.h}
 905
 906     Example:
 907
 908     @code
 909     wxIMPLEMENT_APP(MyApp);
 910     @endcode
 911
 912     @see wxDECLARE_APP()
 913 */
 914 #define wxIMPLEMENT_APP( className )
 915
 916 //@}
 917
 918
 919
 920 /**
 921     The global pointer to the singleton wxApp object.
 922
 923     @see wxApp::GetInstance()
 924 */
 925 wxApp *wxTheApp;
 926
 927
 928
 929 /** @addtogroup group_funcmacro_appinitterm */
 930 //@{
 931
 932 /**
 933     This function doesn't exist in wxWidgets but it is created by using the
 934     wxIMPLEMENT_APP() macro.
 935
 936     Thus, before using it anywhere but in the same module where this macro is
 937     used, you must make it available using wxDECLARE_APP().
 938
 939     The advantage of using this function compared to directly using the global
 940     ::wxTheApp pointer is that the latter is of type wxApp* and so wouldn't
 941     allow you to access the functions specific to your application class but
 942     not present in wxApp while wxGetApp() returns the object of the right type.
 943
 944     @header{wx/app.h}
 945 */
 946 wxAppDerivedClass& wxGetApp();
 947
 948 /**
 949     If @a doIt is @true, the fatal exceptions (also known as general protection
 950     faults under Windows or segmentation violations in the Unix world) will be
 951     caught and passed to wxApp::OnFatalException.
 952
 953     By default, i.e. before this function is called, they will be handled in
 954     the normal way which usually just means that the application will be
 955     terminated. Calling wxHandleFatalExceptions() with @a doIt equal to @false
 956     will restore this default behaviour.
 957
 958     Notice that this function is only available if @c wxUSE_ON_FATAL_EXCEPTION
 959     is 1 and under Windows platform this requires a compiler with support for
 960     SEH (structured exception handling) which currently means only Microsoft
 961     Visual C++ or a recent Borland C++ version.
 962
 963     @header{wx/app.h}
 964 */
 965 bool wxHandleFatalExceptions(bool doIt = true);
 966
 967 /**
 968     This function is used in wxBase only and only if you don't create
 969     wxApp object at all. In this case you must call it from your
 970     @c main() function before calling any other wxWidgets functions.
 971
 972     If the function returns @false the initialization could not be performed,
 973     in this case the library cannot be used and wxUninitialize() shouldn't be
 974     called neither.
 975
 976     This function may be called several times but wxUninitialize() must be
 977     called for each successful call to this function.
 978
 979     @header{wx/app.h}
 980 */
 981 bool wxInitialize();
 982
 983 /**
 984     This function is for use in console (wxBase) programs only. It must be called
 985     once for each previous successful call to wxInitialize().
 986
 987     @header{wx/app.h}
 988 */
 989 void wxUninitialize();
 990
 991 /**
 992     This function wakes up the (internal and platform dependent) idle system,
 993     i.e. it will force the system to send an idle event even if the system
 994     currently @e is idle and thus would not send any idle event until after
 995     some other event would get sent. This is also useful for sending events
 996     between two threads and is used by the corresponding functions
 997     wxPostEvent() and wxEvtHandler::AddPendingEvent().
 998
 999     @header{wx/app.h}
1000 */
1001 void wxWakeUpIdle();
1002
1003 /**
1004     Calls wxAppConsole::Yield.
1005
1006     @deprecated
1007     This function is kept only for backwards compatibility. Please use
1008     the wxAppConsole::Yield method instead in any new code.
1009
1010     @header{wx/app.h}
1011 */
1012 bool wxYield();
1013
1014 /**
1015     Calls wxApp::SafeYield.
1016
1017     @header{wx/app.h}
1018 */
1019 bool wxSafeYield(wxWindow* win = NULL, bool onlyIfNeeded = false);
1020
1021 /**
1022     This function initializes wxWidgets in a platform-dependent way. Use this if you
1023     are not using the default wxWidgets entry code (e.g. main or WinMain).
1024
1025     For example, you can initialize wxWidgets from an Microsoft Foundation Classes
1026     (MFC) application using this function.
1027
1028     @note This overload of wxEntry is available under all platforms.
1029
1030     @see wxEntryStart()
1031
1032     @header{wx/app.h}
1033 */
1034 int wxEntry(int& argc, wxChar** argv);
1035
1036 /**
1037     See wxEntry(int&,wxChar**) for more info about this function.
1038
1039     Notice that under Windows CE platform, and only there, the type of @a pCmdLine
1040     is @c wchar_t *, otherwise it is @c char *, even in Unicode build.
1041
1042     @remarks To clean up wxWidgets, call wxApp::OnExit followed by the static
1043              function wxApp::CleanUp. For example, if exiting from an MFC application
1044              that also uses wxWidgets:
1045              @code
1046              int CTheApp::ExitInstance()
1047              {
1048                 // OnExit isn't called by CleanUp so must be called explicitly.
1049                 wxTheApp->OnExit();
1050                 wxApp::CleanUp();
1051
1052                 return CWinApp::ExitInstance();
1053              }
1054              @endcode
1055
1056     @header{wx/app.h}
1057 */
1058 int wxEntry(HINSTANCE hInstance,
1059             HINSTANCE hPrevInstance = NULL,
1060             char* pCmdLine = NULL,
1061             int nCmdShow = SW_SHOWNORMAL);
1062
1063 //@}
1064
1065
1066
1067 /** @addtogroup group_funcmacro_procctrl */
1068 //@{
1069
1070 /**
1071     Exits application after calling wxApp::OnExit.
1072
1073     Should only be used in an emergency: normally the top-level frame
1074     should be deleted (after deleting all other frames) to terminate the
1075     application. See wxCloseEvent and wxApp.
1076
1077     @header{wx/app.h}
1078 */
1079 void wxExit();
1080
1081 //@}
1082
1083 /** @addtogroup group_funcmacro_debug */
1084 //@{
1085
1086 /**
1087     @def wxDISABLE_DEBUG_SUPPORT()
1088
1089     Use this macro to disable all debugging code in release build when not
1090     using wxIMPLEMENT_APP().
1091
1092     Currently this macro disables assert checking and debug and trace level
1093     logging messages in release build (i.e. when @c NDEBUG is defined). It is
1094     used by wxIMPLEMENT_APP() macro so you only need to use it explicitly if you
1095     don't use this macro but initialize wxWidgets directly (e.g. calls
1096     wxEntry() or wxEntryStart() itself).
1097
1098     If you do not want to disable debugging code even in release build of your
1099     application, you can use wxSetDefaultAssertHandler() and
1100     wxLog::SetLogLevel() with @c wxLOG_Max parameter to enable assertions and
1101     debug logging respectively.
1102
1103     @see wxDISABLE_ASSERTS_IN_RELEASE_BUILD(),
1104          wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD(),
1105          @ref overview_debugging
1106
1107     @since 2.9.1
1108
1109     @header{wx/app.h}
1110  */
1111 #define wxDISABLE_DEBUG_SUPPORT() \
1112     wxDISABLE_ASSERTS_IN_RELEASE_BUILD(); \
1113     wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD()
1114
1115 //@}
1116