X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/f045c7f52dfcfebcd0ea6a7b689ccb8a25021d1f..c602c59b6e623d7775c16ce6412b64b34dc5dd94:/interface/wx/app.h diff --git a/interface/wx/app.h b/interface/wx/app.h index ab2d90b964..4053532457 100644 --- a/interface/wx/app.h +++ b/interface/wx/app.h @@ -35,7 +35,7 @@ @library{wxbase} @category{appmanagement} - @see @ref overview_app, wxApp, wxAppTraits, wxEventLoop + @see @ref overview_app, wxApp, wxAppTraits, wxEventLoopBase */ class wxAppConsole : public wxEvtHandler { @@ -54,28 +54,29 @@ public: */ virtual ~wxAppConsole(); - /** - Dispatches the next event in the windowing system event queue. - Blocks until an event appears if there are none currently - (use Pending() if this is not wanted). - This can be used for programming event loops, e.g. + /** + @name Event-handling - @code - while (app.Pending()) - Dispatch(); - @endcode + Note that you should look at wxEvtLoopBase for more event-processing + documentation. + */ + //@{ - @return @false if the event loop should stop and @true otherwise. + /** + Called by wxWidgets on creation of the application. Override this if you wish + to provide your own (environment-dependent) main loop. - @see Pending() + @return 0 under X, and the wParam of the WM_QUIT message under Windows. */ - virtual bool Dispatch(); + virtual int MainLoop(); /** Call this to explicitly exit the main message (event) loop. You should normally exit the main loop (and the application) by deleting the top window. + + This function simply calls wxEvtLoopBase::Exit() on the active loop. */ virtual void ExitMainLoop(); @@ -91,80 +92,105 @@ public: virtual int FilterEvent(wxEvent& event); /** - Returns the user-readable application name. - - The difference between this string and the one returned by GetAppName() - is that this one is meant to be shown to the user and so should be used - for the window titles, page headers and so on while the other one - should be only used internally, e.g. for the file names or - configuration file keys. By default, returns the application name as - returned by GetAppName() capitalized using wxString::Capitalize(). - - @since 2.9.0 + Returns the main event loop instance, i.e. the event loop which is started + by OnRun() and which dispatches all events sent from the native toolkit + to the application (except when new event loops are temporarily set-up). + The returned value maybe @NULL. Put initialization code which needs a + non-@NULL main event loop into OnEventLoopEnter(). */ - wxString GetAppDisplayName() const; + wxEventLoopBase* GetMainLoop() const; /** - Returns the application name. + This function simply invokes the given method @a func of the specified + event handler @a handler with the @a event as parameter. It exists solely + to allow to catch the C++ exceptions which could be thrown by all event + handlers in the application in one place: if you want to do this, override + this function in your wxApp-derived class and add try/catch clause(s) to it. + */ + virtual void HandleEvent(wxEvtHandler* handler, + wxEventFunction func, + wxEvent& event) const; - @remarks wxWidgets sets this to a reasonable default before calling - OnInit(), but the application can reset it at will. + //@} - @see GetAppDisplayName() - */ - wxString GetAppName() const; /** - Gets the class name of the application. The class name may be used in a - platform specific manner to refer to the application. + @name Pending events - @see SetClassName() + Pending events are handled by wxAppConsole rather than wxEventLoopBase + to allow queuing of events even when there's no event loop + (e.g. in wxAppConsole::OnInit). */ - wxString GetClassName() const; + //@{ /** - Returns the one and only global application object. - Usually wxTheApp is used instead. - - @see SetInstance() + Process all pending events; it is necessary to call this function to + process events posted with wxEvtHandler::QueueEvent or wxEvtHandler::AddPendingEvent. + + This happens during each event loop iteration (see wxEventLoopBase) in GUI mode but + it may be also called directly. + + Note that this function does not only process the pending events for the wxApp object + itself (which derives from wxEvtHandler) but also the pending events for @e any + event handler of this application. + + This function will immediately return and do nothing if SuspendProcessingOfPendingEvents() + was called. */ - static wxAppConsole* GetInstance(); + virtual void ProcessPendingEvents(); + + /** + Deletes the pending events of all wxEvtHandlers of this application. + + See wxEvtHandler::DeletePendingEvents() for warnings about deleting the pending + events. + */ + void DeletePendingEvents(); /** - Returns a pointer to the wxAppTraits object for the application. - If you want to customize the wxAppTraits object, you must override the - CreateTraits() function. + Returns @true if there are pending events on the internal pending event list. + + Whenever wxEvtHandler::QueueEvent or wxEvtHandler::AddPendingEvent() are + called (not only for wxApp itself, but for any event handler of the application!), + the internal wxApp's list of handlers with pending events is updated and this + function will return true. */ - wxAppTraits* GetTraits(); + bool HasPendingEvents() const; /** - Returns the user-readable vendor name. The difference between this string - and the one returned by GetVendorName() is that this one is meant to be shown - to the user and so should be used for the window titles, page headers and so on - while the other one should be only used internally, e.g. for the file names or - configuration file keys. + Temporary suspends processing of the pending events. - By default, returns the same string as GetVendorName(). + @see ResumeProcessingOfPendingEvents() + */ + void SuspendProcessingOfPendingEvents(); - @since 2.9.0 + /** + Resume processing of the pending events previously stopped because of a + call to SuspendProcessingOfPendingEvents(). */ - const wxString& GetVendorDisplayName() const; + void ResumeProcessingOfPendingEvents(); + + //@} + /** - Returns the application's vendor name. + Allows external code to modify global ::wxTheApp, but you should really + know what you're doing if you call it. + + @param app + Replacement for the global application object. + + @see GetInstance() */ - const wxString& GetVendorName() const; + static void SetInstance(wxAppConsole* app); /** - This function simply invokes the given method @a func of the specified - event handler @a handler with the @a event as parameter. It exists solely - to allow to catch the C++ exceptions which could be thrown by all event - handlers in the application in one place: if you want to do this, override - this function in your wxApp-derived class and add try/catch clause(s) to it. + Returns the one and only global application object. + Usually ::wxTheApp is used instead. + + @see SetInstance() */ - virtual void HandleEvent(wxEvtHandler* handler, - wxEventFunction func, - wxEvent& event) const; + static wxAppConsole* GetInstance(); /** Returns @true if the main event loop is currently running, i.e. if the @@ -176,20 +202,17 @@ public: */ static bool IsMainLoopRunning(); - /** - Process all pending events; it is necessary to call this function to - process posted events. - This happens during each event loop iteration in GUI mode but if there is - no main loop, it may be also called directly. + /** + @name Mac-specific functions */ - virtual void ProcessPendingEvents(); + //@{ /** Called in response of an "open-application" Apple event. Override this to create a new document in your app. - @onlyfor{wxmac} + @onlyfor{wxosx} */ virtual void MacNewFile(); @@ -200,38 +223,38 @@ public: user double clicked on it or if the document file was dropped on either the running application or the application icon in Finder. - @onlyfor{wxmac} + @onlyfor{wxosx} */ virtual void MacOpenFile(const wxString& fileName); /** Called in response of a "get-url" Apple event. - @onlyfor{wxmac} + @onlyfor{wxosx} */ virtual void MacOpenURL(const wxString& url); /** Called in response of a "print-document" Apple event. - @onlyfor{wxmac} + @onlyfor{wxosx} */ virtual void MacPrintFile(const wxString& fileName); /** Called in response of a "reopen-application" Apple event. - @onlyfor{wxmac} + @onlyfor{wxosx} */ virtual void MacReopenApp(); - /** - Called by wxWidgets on creation of the application. Override this if you wish - to provide your own (environment-dependent) main loop. + //@} - @return 0 under X, and the wParam of the WM_QUIT message under Windows. + + /** + @name Callbacks for application-wide "events" */ - virtual int MainLoop(); + //@{ /** This function is called when an assert failure occurs, i.e. the condition @@ -298,6 +321,26 @@ public: */ virtual bool OnCmdLineParsed(wxCmdLineParser& parser); + /** + Called by wxEventLoopBase::SetActive(): you can override this function + and put here the code which needs an active event loop. + + Note that this function is called whenever an event loop is activated; + you may want to use wxEventLoopBase::IsMain() to perform initialization + specific for the app's main event loop. + + @see OnEventLoopExit() + */ + virtual void OnEventLoopEnter(wxEventLoopBase* loop); + + /** + Called by wxEventLoopBase::OnExit() for each event loop which + is exited. + + @see OnEventLoopEnter() + */ + virtual void OnEventLoopExit(wxEventLoopBase* loop); + /** This function is called if an unhandled exception occurs inside the main application event loop. It can return @true to ignore the exception and to @@ -389,12 +432,70 @@ public: */ virtual void OnUnhandledException(); + //@} + + + /** + @name Application informations + */ + //@{ + + /** + Returns the user-readable application name. + + The difference between this string and the one returned by GetAppName() + is that this one is meant to be shown to the user and so should be used + for the window titles, page headers and so on while the other one + should be only used internally, e.g. for the file names or + configuration file keys. By default, returns the application name as + returned by GetAppName() capitalized using wxString::Capitalize(). + + @since 2.9.0 + */ + wxString GetAppDisplayName() const; + + /** + Returns the application name. + + @remarks wxWidgets sets this to a reasonable default before calling + OnInit(), but the application can reset it at will. + + @see GetAppDisplayName() + */ + wxString GetAppName() const; + + /** + Gets the class name of the application. The class name may be used in a + platform specific manner to refer to the application. + + @see SetClassName() + */ + wxString GetClassName() const; + + /** + Returns a pointer to the wxAppTraits object for the application. + If you want to customize the wxAppTraits object, you must override the + CreateTraits() function. + */ + wxAppTraits* GetTraits(); + /** - Returns @true if unprocessed events are in the window system event queue. + Returns the user-readable vendor name. The difference between this string + and the one returned by GetVendorName() is that this one is meant to be shown + to the user and so should be used for the window titles, page headers and so on + while the other one should be only used internally, e.g. for the file names or + configuration file keys. - @see Dispatch() + By default, returns the same string as GetVendorName(). + + @since 2.9.0 */ - virtual bool Pending(); + const wxString& GetVendorDisplayName() const; + + /** + Returns the application's vendor name. + */ + const wxString& GetVendorName() const; /** Set the application name to be used in the user-visible places such as @@ -428,17 +529,6 @@ public: */ void SetClassName(const wxString& name); - /** - Allows external code to modify global ::wxTheApp, but you should really - know what you're doing if you call it. - - @param app - Replacement for the global application object. - - @see GetInstance() - */ - static void SetInstance(wxAppConsole* app); - /** Set the vendor name to be used in the user-visible places. See GetVendorDisplayName() for more about the differences between the @@ -454,31 +544,8 @@ public: */ void SetVendorName(const wxString& name); - /** - Yields control to pending messages in the windowing system. - - This can be useful, for example, when a time-consuming process writes to a - text window. Without an occasional yield, the text window will not be updated - properly, and on systems with cooperative multitasking, such as Windows 3.1 - other processes will not respond. - - Caution should be exercised, however, since yielding may allow the - user to perform actions which are not compatible with the current task. - Disabling menu items or whole menus during processing can avoid unwanted - reentrance of code: see ::wxSafeYield for a better function. + //@} - Note that Yield() will not flush the message logs. This is intentional as - calling Yield() is usually done to quickly update the screen and popping up - a message box dialog may be undesirable. If you do wish to flush the log - messages immediately (otherwise it will be done during the next idle loop - iteration), call wxLog::FlushActive. - - Calling Yield() recursively is normally an error and an assert failure is - raised in debug build if such situation is detected. However if the - @a onlyIfNeeded parameter is @true, the method will just silently - return @false instead. - */ - virtual bool Yield(bool onlyIfNeeded = false); /** Number of command line arguments (after environment-specific processing). @@ -511,12 +578,31 @@ public: video modes (see SetVideoMode()). In general, application-wide settings for GUI-only apps are accessible - from wxApp (or from wxSystemSettings). + from wxApp (or from wxSystemSettings or wxSystemOptions classes). + + @beginEventEmissionTable + @event{EVT_QUERY_END_SESSION(func)} + Process a query end session event, supplying the member function. + See wxCloseEvent. + @event{EVT_END_SESSION(func)} + Process an end session event, supplying the member function. + See wxCloseEvent. + @event{EVT_ACTIVATE_APP(func)} + Process a @c wxEVT_ACTIVATE_APP event. See wxActivateEvent. + @event{EVT_HIBERNATE(func)} + Process a hibernate event. See wxActivateEvent. + @event{EVT_DIALUP_CONNECTED(func)} + A connection with the network was established. See wxDialUpEvent. + @event{EVT_DIALUP_DISCONNECTED(func)} + The connection with the network was lost. See wxDialUpEvent. + @event{EVT_IDLE(func)} + Process a @c wxEVT_IDLE event. See wxIdleEvent. + @endEventTable @library{wxbase} @category{appmanagement} - @see @ref overview_app, wxAppTraits, wxEventLoop, wxSystemSettings + @see @ref overview_app, wxAppTraits, wxEventLoopBase, wxSystemSettings */ class wxApp : public wxAppConsole { @@ -534,7 +620,7 @@ public: /** Get display mode that is used use. This is only used in framebuffer - wxWin ports (such as wxMGL or wxDFB). + wxWidgets ports (such as wxMGL or wxDFB). */ virtual wxVideoMode GetDisplayMode() const; @@ -580,6 +666,25 @@ public: */ virtual bool IsActive() const; + /** + This function is similar to wxYield(), except that it disables the user + input to all program windows before calling wxAppConsole::Yield and re-enables it + again afterwards. If @a win is not @NULL, this window will remain enabled, + allowing the implementation of some limited user interaction. + Returns the result of the call to wxAppConsole::Yield. + + @see wxSafeYield + */ + virtual bool SafeYield(wxWindow *win, bool onlyIfNeeded); + + /** + Works like SafeYield() with @e onlyIfNeeded == @true except that + it allows the caller to specify a mask of events to be processed. + + See wxAppConsole::YieldFor for more info. + */ + virtual bool SafeYieldFor(wxWindow *win, long eventsToProcess); + /** Windows-only function for processing a message. This function is called from the main message loop, checking for windows that may wish to process it. @@ -619,9 +724,8 @@ public: virtual bool SendIdleEvents(wxWindow* win, wxIdleEvent& event); /** - Set display mode to use. This is only used in framebuffer wxWin - ports (such as wxMGL or wxDFB). This method should be called from - wxApp::OnInitGui. + Set display mode to use. This is only used in framebuffer wxWidgets + ports (such as wxMGL or wxDFB). */ virtual bool SetDisplayMode(const wxVideoMode& info); @@ -637,17 +741,6 @@ public: */ void SetExitOnFrameDelete(bool flag); - /** - Allows external code to modify global ::wxTheApp, but you should really - know what you're doing if you call it. - - @param app - Replacement for the global application object. - - @see GetInstance() - */ - static void SetInstance(wxAppConsole* app); - /** Allows runtime switching of the UI environment theme. @@ -704,7 +797,7 @@ public: // ============================================================================ -/** @ingroup group_funcmacro_rtti */ +/** @addtogroup group_funcmacro_rtti */ //@{ /** @@ -752,7 +845,7 @@ wxApp *wxTheApp; -/** @ingroup group_funcmacro_appinitterm */ +/** @addtogroup group_funcmacro_appinitterm */ //@{ /** @@ -827,22 +920,18 @@ void wxUninitialize(); void wxWakeUpIdle(); /** - Calls wxApp::Yield. + Calls wxAppConsole::Yield. @deprecated This function is kept only for backwards compatibility. Please use - the wxApp::Yield method instead in any new code. + the wxAppConsole::Yield method instead in any new code. @header{wx/app.h} */ bool wxYield(); /** - This function is similar to wxYield(), except that it disables the user - input to all program windows before calling wxYield() and re-enables it - again afterwards. If @a win is not @NULL, this window will remain enabled, - allowing the implementation of some limited user interaction. - Returns the result of the call to ::wxYield. + Calls wxApp::SafeYield. @header{wx/app.h} */ @@ -894,7 +983,7 @@ int wxEntry(HINSTANCE hInstance, -/** @ingroup group_funcmacro_procctrl */ +/** @addtogroup group_funcmacro_procctrl */ //@{ /**