// Purpose: interface of wxApp
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
objects in the application (see wxAppConsole::FilterEvent)
@li implement Apple-specific event handlers (see wxAppConsole::MacXXX functions)
- You should use the macro IMPLEMENT_APP(appClass) in your application
+ You should use the macro wxIMPLEMENT_APP(appClass) in your application
implementation file to tell wxWidgets how to create an instance of your
application class.
- Use DECLARE_APP(appClass) in a header file if you want the ::wxGetApp() function
+ Use wxDECLARE_APP(appClass) in a header file if you want the ::wxGetApp() function
(which returns a reference to your application object) to be visible to other
files.
@library{wxbase}
@category{appmanagement}
- @see @ref overview_app, wxApp, wxAppTraits, wxEventLoop
+ @see @ref overview_app, wxApp, wxAppTraits, wxEventLoopBase
*/
class wxAppConsole : public wxEvtHandler
{
*/
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();
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().
+ 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;
- @since 2.9.0
+ /**
+ 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.
*/
- wxString GetAppDisplayName() const;
+ virtual void HandleEvent(wxEvtHandler* handler,
+ wxEventFunction func,
+ wxEvent& event) const;
/**
- Returns the application name.
+ Returns @true if the application is using an event loop.
- @remarks wxWidgets sets this to a reasonable default before calling
- OnInit(), but the application can reset it at will.
+ This function always returns @true for the GUI applications which
+ must use an event loop but by default only returns @true for the
+ console programs if an event loop is already running as it can't know
+ whether one will be created in the future.
- @see GetAppDisplayName()
+ Thus, it only makes sense to override it in console applications which
+ do use an event loop, to return @true instead of checking if there is a
+ currently active event loop.
+ */
+ virtual bool UsesEventLoop() const;
+
+ //@}
+
+
+ /**
+ @name Pending events
+
+ 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 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.
+ Process all pending events; it is necessary to call this function to
+ process events posted with wxEvtHandler::QueueEvent or wxEvtHandler::AddPendingEvent.
- @see SetClassName()
+ 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.
*/
- wxString GetClassName() const;
+ virtual void ProcessPendingEvents();
/**
- Returns the one and only global application object.
- Usually wxTheApp is used instead.
+ Deletes the pending events of all wxEvtHandlers of this application.
- @see SetInstance()
+ See wxEvtHandler::DeletePendingEvents() for warnings about deleting the pending
+ events.
*/
- static wxAppConsole* GetInstance();
+ 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.
+ Delayed objects destruction.
+
+ In applications using events it may be unsafe for an event handler to
+ delete the object which generated the event because more events may be
+ still pending for the same object. In this case the handler may call
+ ScheduleForDestruction() instead.
+ */
+ //@{
+
+ /**
+ Schedule the object for destruction in the near future.
+
+ Notice that if the application is not using an event loop, i.e. if
+ UsesEventLoop() returns @false, this method will simply delete the
+ object immediately.
+
+ Examples of using this function inside wxWidgets itself include
+ deleting the top level windows when they are closed and sockets when
+ they are disconnected.
+ */
+ void ScheduleForDestruction(wxObject *object);
+
+ /**
+ Check if the object had been scheduled for destruction with
+ ScheduleForDestruction().
+
+ This function may be useful as an optimization to avoid doing something
+ with an object which will be soon destroyed in any case.
+ */
+ bool IsScheduledForDestruction(wxObject *object) const;
+
+ //@}
+
+
+ /**
+ 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
*/
static bool IsMainLoopRunning();
- /**
- Returns @true if called from inside Yield().
- */
- bool IsYielding() const;
/**
- 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();
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
*/
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
*/
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.
+
+ If the application name for display had been previously set by
+ SetAppDisplayName(), it will be returned by this function. Otherwise,
+ if SetAppName() had been called its value will be returned; also as is.
+ Finally if none was called, this function returns the program name
+ capitalized using wxString::Capitalize().
+
+ @since 2.9.0
+ */
+ wxString GetAppDisplayName() const;
+
+ /**
+ Returns the application name.
+
+ If SetAppName() had been called, returns the string passed to it.
+ Otherwise returns the program name, i.e. the value of @c argv[0] passed
+ to the @c main() function.
+
+ @see GetAppDisplayName()
+ */
+ wxString GetAppName() const;
+
/**
- Returns @true if unprocessed events are in the window system event queue.
+ Gets the class name of the application. The class name may be used in a
+ platform specific manner to refer to the application.
- @see Dispatch()
+ @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.
*/
- virtual bool Pending();
+ wxAppTraits* GetTraits();
+
+ /**
+ 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.
+
+ By default, returns the same string as GetVendorName().
+
+ @since 2.9.0
+ */
+ 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
*/
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
*/
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.
- 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.
- */
- virtual bool Yield(bool onlyIfNeeded = false);
/**
Number of command line arguments (after environment-specific processing).
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
{
/**
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 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.
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);
*/
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.
// ============================================================================
-/** @ingroup group_funcmacro_rtti */
+/** @addtogroup group_funcmacro_rtti */
//@{
/**
This is used in headers to create a forward declaration of the ::wxGetApp()
- function implemented by IMPLEMENT_APP().
+ function implemented by wxIMPLEMENT_APP().
- It creates the declaration <tt>className& wxGetApp()</tt>.
+ It creates the declaration <tt>className& wxGetApp()</tt>
+ (requires a final semicolon).
@header{wx/app.h}
Example:
@code
- DECLARE_APP(MyApp)
+ wxDECLARE_APP(MyApp);
@endcode
*/
-#define DECLARE_APP( className )
+#define wxDECLARE_APP( className )
/**
This is used in the application class implementation file to make the
application class known to wxWidgets for dynamic construction.
+ Note that this macro requires a final semicolon.
@header{wx/app.h}
Example:
@code
- IMPLEMENT_APP(MyApp)
+ wxIMPLEMENT_APP(MyApp);
@endcode
- @see DECLARE_APP().
+ @see wxDECLARE_APP()
*/
-#define IMPLEMENT_APP( className )
+#define wxIMPLEMENT_APP( className )
//@}
-/** @ingroup group_funcmacro_appinitterm */
+/** @addtogroup group_funcmacro_appinitterm */
//@{
/**
This function doesn't exist in wxWidgets but it is created by using the
- IMPLEMENT_APP() macro.
+ wxIMPLEMENT_APP() macro.
Thus, before using it anywhere but in the same module where this macro is
- used, you must make it available using DECLARE_APP().
+ used, you must make it available using wxDECLARE_APP().
The advantage of using this function compared to directly using the global
::wxTheApp pointer is that the latter is of type wxApp* and so wouldn't
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}
*/
-/** @ingroup group_funcmacro_procctrl */
+/** @addtogroup group_funcmacro_procctrl */
//@{
/**
//@}
+/** @addtogroup group_funcmacro_debug */
+//@{
+
+/**
+ @def wxDISABLE_DEBUG_SUPPORT()
+
+ Use this macro to disable all debugging code in release build when not
+ using wxIMPLEMENT_APP().
+
+ Currently this macro disables assert checking and debug and trace level
+ logging messages in release build (i.e. when @c NDEBUG is defined). It is
+ used by wxIMPLEMENT_APP() macro so you only need to use it explicitly if you
+ don't use this macro but initialize wxWidgets directly (e.g. calls
+ wxEntry() or wxEntryStart() itself).
+
+ If you do not want to disable debugging code even in release build of your
+ application, you can use wxSetDefaultAssertHandler() and
+ wxLog::SetLogLevel() with @c wxLOG_Max parameter to enable assertions and
+ debug logging respectively.
+
+ @see wxDISABLE_ASSERTS_IN_RELEASE_BUILD(),
+ wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD(),
+ @ref overview_debugging
+
+ @since 2.9.1
+
+ @header{wx/app.h}
+ */
+#define wxDISABLE_DEBUG_SUPPORT() \
+ wxDISABLE_ASSERTS_IN_RELEASE_BUILD(); \
+ wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD()
+
+//@}
+
projects / wxWidgets.git / blobdiff