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