interface/app.h

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