/**
@name Event-handling
+
+ Note that you should look at wxEvtLoopBase for more event-processing
+ documentation.
*/
//@{
/**
- 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.
-
- @code
- while (app.Pending())
- Dispatch();
- @endcode
-
- @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(), wxEventLoopBase
+ @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();
*/
virtual int FilterEvent(wxEvent& event);
+ /**
+ 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().
+ */
+ wxEventLoopBase* GetMainLoop() const;
/**
This function simply invokes the given method @a func of the specified
wxEventFunction func,
wxEvent& event) const;
- /**
- Returns @true if called from inside Yield().
- */
- virtual bool IsYielding() const;
+ //@}
+
/**
- Process all pending events; it is necessary to call this function to
- process posted events.
+ @name Pending events
- This happens during each event loop iteration in GUI mode but if there is
- no main loop, it may be also called directly.
+ 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).
*/
- virtual void ProcessPendingEvents();
+ //@{
/**
- 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.
+ 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.
*/
- virtual int MainLoop();
-
+ virtual void ProcessPendingEvents();
+
/**
- Returns @true if unprocessed events are in the window system event queue.
-
- @see Dispatch()
+ Deletes the pending events of all wxEvtHandlers of this application.
+
+ See wxEvtHandler::DeletePendingEvents() for warnings about deleting the pending
+ events.
*/
- virtual bool Pending();
+ void DeletePendingEvents();
/**
- 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.
- You can avoid unwanted reentrancies also using IsYielding().
-
- 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.
+ 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.
*/
- bool Yield(bool onlyIfNeeded = false);
+ bool HasPendingEvents() const;
/**
- Works like Yield() with @e onlyIfNeeded == @true, except that it allows
- the caller to specify a mask of the ::wxEventCategory values which
- indicates which events should be processed and which should instead
- be "delayed" (i.e. processed by the main loop later).
+ Temporary suspends processing of the pending events.
- Note that this is a safer alternative to Yield() since it ensures that
- only the events you're interested to are processed; i.e. helps to avoid
- unwanted reentrancies.
+ @see ResumeProcessingOfPendingEvents()
*/
- bool YieldFor(long eventsToProcess);
+ void SuspendProcessingOfPendingEvents();
/**
- Returns @true if the given event category is allowed inside
- a YieldFor() call (i.e. compares the given category against the
- last mask passed to YieldFor()).
+ Resume processing of the pending events previously stopped because of a
+ call to SuspendProcessingOfPendingEvents().
*/
- virtual bool IsEventAllowedInsideYield(wxEventCategory cat) const;
+ void ResumeProcessingOfPendingEvents();
//@}
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();
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();
*/
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
In general, application-wide settings for GUI-only apps are accessible
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}
/**
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;
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);
projects / wxWidgets.git / blobdiff