X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/c933f8f85b3bbe24dc05be6cbe7c85941f36212a..50d4763f1710f6e45ac6af7112d1ce9effe93bc4:/interface/wx/app.h?ds=inline diff --git a/interface/wx/app.h b/interface/wx/app.h index 3a5e6a0858..3261fd74aa 100644 --- a/interface/wx/app.h +++ b/interface/wx/app.h @@ -3,7 +3,7 @@ // Purpose: interface of wxApp // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -11,16 +11,34 @@ @class wxAppConsole This class is essential for writing console-only or hybrid apps without - having to define wxUSE_GUI=0. + having to define @c wxUSE_GUI=0. + + It is used to: + @li set and get application-wide properties (see wxAppConsole::CreateTraits + and wxAppConsole::SetXXX functions) + @li implement the windowing system message or event loop: events in fact are + supported even in console-mode applications (see wxAppConsole::HandleEvent + and wxAppConsole::ProcessPendingEvents); + @li initiate application processing via wxApp::OnInit; + @li allow default processing of events not handled by other + objects in the application (see wxAppConsole::FilterEvent) + @li implement Apple-specific event handlers (see wxAppConsole::MacXXX functions) + + 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. - @todo MORE INFO + 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 + @see @ref overview_app, wxApp, wxAppTraits, wxEventLoopBase */ -class wxAppConsole : public wxEvtHandler +class wxAppConsole : public wxEvtHandler, + public wxEventFilter { protected: /** @@ -37,175 +55,209 @@ 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(); /** + Overridden wxEventFilter method. + This function is called before processing any event and allows the application - to preempt the processing of some events. + to preempt the processing of some events, see wxEventFilter + documentation for more information. - If this method returns -1 the event is processed normally, otherwise either - @true or @false should be returned and the event processing stops immediately - considering that the event had been already processed (for the former return - value) or that it is not going to be processed at all (for the latter one). + wxApp implementation of this method always return -1 indicating that + the event should be processed normally. */ 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. + + 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; + + //@} - @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. + Process all pending events; it is necessary to call this function to + process events posted with wxEvtHandler::QueueEvent or wxEvtHandler::AddPendingEvent. - @see SetInstance() + 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(); /** - Returns a pointer to the wxAppTraits object for the application. - If you want to customize the wxAppTraits object, you must override the - CreateTraits() function. + Deletes the pending events of all wxEvtHandlers of this application. + + See wxEvtHandler::DeletePendingEvents() for warnings about deleting the pending + events. */ - wxAppTraits* GetTraits(); + void DeletePendingEvents(); /** - 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. + Returns @true if there are pending events on the internal pending event list. - By default, returns the same string as GetVendorName(). - - @since 2.9.0 + 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. */ - const wxString& GetVendorDisplayName() const; + bool HasPendingEvents() const; /** - Returns the application's vendor name. + Temporary suspends processing of the pending events. + + @see ResumeProcessingOfPendingEvents() */ - const wxString& GetVendorName() const; + void SuspendProcessingOfPendingEvents(); /** - 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. + Resume processing of the pending events previously stopped because of a + call to SuspendProcessingOfPendingEvents(). */ - virtual void HandleEvent(wxEvtHandler* handler, - wxEventFunction func, - wxEvent& event) const; + void ResumeProcessingOfPendingEvents(); + + //@} /** - Returns @true if the main event loop is currently running, i.e. if the - application is inside OnRun(). + Delayed objects destruction. - This can be useful to test whether events can be dispatched. For example, - if this function returns @false, non-blocking sockets cannot be used because - the events from them would never be processed. - */ - static bool IsMainLoopRunning(); + 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. + */ + //@{ /** - Called in response of an "open-application" Apple event. - Override this to create a new document in your app. + Schedule the object for destruction in the near future. - @onlyfor{wxmac} - */ - virtual void MacNewFile(); + 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); /** - Called in response of an "open-document" Apple event. + Check if the object had been scheduled for destruction with + ScheduleForDestruction(). - You need to override this method in order to open a document file after the - user double clicked on it or if the document file was dropped on either the - running application or the application icon in Finder. + 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; + + //@} - @onlyfor{wxmac} - */ - virtual void MacOpenFile(const wxString& fileName); + + bool Yield(bool onlyIfNeeded = false); /** - Called in response of a "get-url" Apple event. + 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. - @onlyfor{wxmac} + @see GetInstance() */ - virtual void MacOpenURL(const wxString& url); + static void SetInstance(wxAppConsole* app); /** - Called in response of a "print-document" Apple event. + Returns the one and only global application object. + Usually ::wxTheApp is used instead. - @onlyfor{wxmac} + @see SetInstance() */ - virtual void MacPrintFile(const wxString& fileName); + static wxAppConsole* GetInstance(); /** - Called in response of a "reopen-application" Apple event. + Returns @true if the main event loop is currently running, i.e. if the + application is inside OnRun(). - @onlyfor{wxmac} + This can be useful to test whether events can be dispatched. For example, + if this function returns @false, non-blocking sockets cannot be used because + the events from them would never be processed. */ - virtual void MacReopenApp(); + static bool IsMainLoopRunning(); /** - 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 @@ -272,6 +324,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 @@ -303,7 +375,7 @@ public: /** This function may be called if something fatal happens: an unhandled - exception under Win32 or a a fatal signal under Unix, for example. However, + exception under Win32 or a fatal signal under Unix, for example. However, this will not happen by default: you have to explicitly call wxHandleFatalExceptions() to enable this. @@ -322,7 +394,7 @@ public: You may use OnExit() to clean up anything initialized here, provided that the function returns @true. - Notice that if you want to to use the command line processing provided by + Notice that if you want to use the command line processing provided by wxWidgets you have to call the base class version in the derived class OnInit(). @@ -351,24 +423,94 @@ public: virtual int OnRun(); /** - This function is called when an unhandled C++ exception occurs inside - OnRun() (the exceptions which occur during the program startup and shutdown - might not be caught at all). Notice that by now the main event loop has been - terminated and the program will exit, if you want to prevent this from happening - (i.e. continue running after catching an exception) you need to override - OnExceptionInMainLoop(). + This function is called when an unhandled C++ exception occurs in user + code called by wxWidgets. + + Any unhandled exceptions thrown from (overridden versions of) OnInit() + and OnExit() methods as well as any exceptions thrown from inside the + main loop and re-thrown by OnUnhandledException() will result in a call + to this function. - The default implementation shows information about the exception in debug build - but does nothing in the release build. + By the time this function is called, the program is already about to + exit and the exception can't be handled nor ignored any more, override + OnUnhandledException() or use explicit @c try/catch blocks around + OnInit() body to be able to handle the exception earlier. + + The default implementation dumps information about the exception using + wxMessageOutputBest. */ virtual void OnUnhandledException(); + //@} + + /** - Returns @true if unprocessed events are in the window system event queue. + @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(). - @see Dispatch() + @since 2.9.0 */ - virtual bool Pending(); + 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; + + /** + 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 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 @@ -402,17 +544,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 @@ -428,31 +559,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). @@ -464,7 +572,7 @@ public: Under Windows and Linux/Unix, you should parse the command line arguments and check for files to be opened when starting your - application. Under OS X, you need to override MacOpenFile() + application. Under OS X, you need to override MacOpenFiles() since command line arguments are used differently there. You may use the wxCmdLineParser to parse command line arguments. @@ -478,26 +586,38 @@ public: /** @class wxApp - The wxApp class represents the application itself. It is used to: - - @li set and get application-wide properties; - @li implement the windowing system message or event loop; - @li initiate application processing via wxApp::OnInit; - @li allow default processing of events not handled by other - objects in the application. - - You should use the macro IMPLEMENT_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 - (which returns a reference to your application object) to be visible to other - files. + The wxApp class represents the application itself when @c wxUSE_GUI=1. + + In addition to the features provided by wxAppConsole it keeps track of + the top window (see SetTopWindow()) and adds support for + video modes (see SetVideoMode()). + + 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} - @see @ref overview_app + @see @ref overview_app, wxAppTraits, wxEventLoopBase, wxSystemSettings */ class wxApp : public wxAppConsole { @@ -513,6 +633,12 @@ public: */ virtual ~wxApp(); + /** + Get display mode that is used use. This is only used in framebuffer + wxWidgets ports such as wxDFB. + */ + virtual wxVideoMode GetDisplayMode() const; + /** Returns @true if the application will exit when the top-level frame is deleted. @@ -520,6 +646,12 @@ public: */ bool GetExitOnFrameDelete() const; + /** + Return the layout direction for the current locale or @c wxLayout_Default + if it's unknown. + */ + virtual wxLayoutDirection GetLayoutDirection() const; + /** Returns @true if the application will use the best visual on systems that support different visuals, @false otherwise. @@ -549,6 +681,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. @@ -575,17 +726,10 @@ public: bool ProcessMessage(WXMSG* msg); /** - Sends idle events to a window and its children. - Please note that this function is internal to wxWidgets and shouldn't be used - by user code. - - @remarks These functions poll the top-level windows, and their children, - for idle event processing. If @true is returned, more OnIdle - processing is requested by one or more window. - - @see wxIdleEvent + Set display mode to use. This is only used in framebuffer wxWidgets + ports such as wxDFB. */ - virtual bool SendIdleEvents(wxWindow* win, wxIdleEvent& event); + virtual bool SetDisplayMode(const wxVideoMode& info); /** Allows the programmer to specify whether the application will exit when the @@ -599,17 +743,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. @@ -657,6 +790,72 @@ public: visual and abort the app if none is found. */ void SetUseBestVisual(bool flag, bool forceTrueColour = false); + + + /** + @name Mac-specific functions + */ + //@{ + + /** + Called in response of an "open-application" Apple event. + Override this to create a new document in your app. + + @onlyfor{wxosx} + */ + virtual void MacNewFile(); + + /** + Called in response of an openFiles message with Cocoa, or an + "open-document" Apple event with Carbon. + + You need to override this method in order to open one or more document + files after the user double clicked on it or if the files and/or + folders were dropped on either the application in the dock or the + application icon in Finder. + + By default this method calls MacOpenFile for each file/folder. + + @onlyfor{wxosx} + + @since 2.9.3 + */ + virtual void MacOpenFiles(const wxArrayString& fileNames); + + /** + Called in response of an "open-document" Apple event. + + @deprecated + This function is kept mostly for backwards compatibility. Please + override wxApp::MacOpenFiles method instead in any new code. + + @onlyfor{wxosx} + */ + virtual void MacOpenFile(const wxString& fileName); + + /** + Called in response of a "get-url" Apple event. + + @onlyfor{wxosx} + */ + virtual void MacOpenURL(const wxString& url); + + /** + Called in response of a "print-document" Apple event. + + @onlyfor{wxosx} + */ + virtual void MacPrintFile(const wxString& fileName); + + /** + Called in response of a "reopen-application" Apple event. + + @onlyfor{wxosx} + */ + virtual void MacReopenApp(); + + //@} + }; @@ -666,40 +865,42 @@ public: // ============================================================================ -/** @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(). + This is used in headers to create a forward declaration of the ::wxGetApp() + function implemented by wxIMPLEMENT_APP(). - It creates the declaration className& wxGetApp(). + It creates the declaration className& wxGetApp() + (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 ) //@} @@ -714,15 +915,15 @@ wxApp *wxTheApp; -/** @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 @@ -789,22 +990,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} */ @@ -856,7 +1053,7 @@ int wxEntry(HINSTANCE hInstance, -/** @ingroup group_funcmacro_procctrl */ +/** @addtogroup group_funcmacro_procctrl */ //@{ /** @@ -872,3 +1069,37 @@ void wxExit(); //@} +/** @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() + +//@} +