\end{itemize}
You should use the macro IMPLEMENT\_APP(appClass) in your application implementation
-file to tell wxWindows how to create an instance of your application class.
+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.
\latexignore{\rtfignore{\wxheading{Members}}}
-\membersection{wxApp::wxApp}
-\func{void}{wxApp}{\void}
+\membersection{wxApp::wxApp}\label{wxappctor}
+
+\func{}{wxApp}{\void}
Constructor. Called implicitly with a definition of a wxApp object.
-\membersection{wxApp::\destruct{wxApp}}
-\func{void}{\destruct{wxApp}}{\void}
+\membersection{wxApp::\destruct{wxApp}}\label{wxappdtor}
+
+\func{virtual}{\destruct{wxApp}}{\void}
Destructor. Will be called implicitly on program exit if the wxApp
object is created on the stack.
+
\membersection{wxApp::argc}\label{wxappargc}
\member{int}{argc}
Number of command line arguments (after environment-specific processing).
+
\membersection{wxApp::argv}\label{wxappargv}
-\member{char **}{argv}
+\member{wxChar **}{argv}
Command line arguments (after environment-specific processing).
+
\membersection{wxApp::CreateLogTarget}\label{wxappcreatelogtarget}
\func{virtual wxLog*}{CreateLogTarget}{\void}
\helpref{wxLog}{wxlog}
+
\membersection{wxApp::Dispatch}\label{wxappdispatch}
-\func{void}{Dispatch}{\void}
+\func{virtual void}{Dispatch}{\void}
Dispatches the next event in the windowing system event queue.
\helpref{wxApp::Pending}{wxapppending}
+
+\membersection{wxApp::ExitMainLoop}\label{wxappexitmainloop}
+
+\func{virtual void}{ExitMainLoop}{\void}
+
+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.
+
+
\membersection{wxApp::FilterEvent}\label{wxappfilterevent}
\func{int}{FilterEvent}{\param{wxEvent\& }{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).
+
\membersection{wxApp::GetAppName}\label{wxappgetappname}
\constfunc{wxString}{GetAppName}{\void}
\wxheading{Remarks}
-wxWindows sets this to a reasonable default before
+wxWidgets sets this to a reasonable default before
calling \helpref{wxApp::OnInit}{wxapponinit}, but the application can reset it at will.
-\membersection{wxApp::GetAuto3D}\label{wxappgetauto3d}
-
-\constfunc{bool}{GetAuto3D}{\void}
-
-Returns true if 3D control mode is on, false otherwise.
-
-\wxheading{See also}
-
-\helpref{wxApp::SetAuto3D}{wxappsetauto3d}
\membersection{wxApp::GetClassName}\label{wxappgetclassname}
\helpref{wxApp::SetClassName}{wxappsetclassname}
+
\membersection{wxApp::GetExitOnFrameDelete}\label{wxappgetexitonframedelete}
-\constfunc{bool}{GetExitFrameOnDelete}{\void}
+\constfunc{bool}{GetExitOnFrameDelete}{\void}
Returns true if the application will exit when the top-level window is deleted, false
otherwise.
\helpref{wxApp::SetExitOnFrameDelete}{wxappsetexitonframedelete},\\
\helpref{wxApp shutdown overview}{wxappshutdownoverview}
+
+\membersection{wxApp::GetInstance}\label{wxappgetinstance}
+
+\func{static wxAppConsole *}{GetInstance}{\void}
+
+Returns the one and only global application object.
+Usually \texttt{wxTheApp} is usead instead.
+
+\wxheading{See also}
+
+\helpref{wxApp::SetInstance}{wxappsetinstance}
+
+
\membersection{wxApp::GetTopWindow}\label{wxappgettopwindow}
\constfunc{virtual wxWindow *}{GetTopWindow}{\void}
\helpref{SetTopWindow}{wxappsettopwindow}
+
\membersection{wxApp::GetUseBestVisual}\label{wxappgetusebestvisual}
\constfunc{bool}{GetUseBestVisual}{\void}
\helpref{SetUseBestVisual}{wxappsetusebestvisual}
+
\membersection{wxApp::GetVendorName}\label{wxappgetvendorname}
\constfunc{wxString}{GetVendorName}{\void}
Returns the application's vendor name.
-\membersection{wxApp::ExitMainLoop}\label{wxappexitmainloop}
-\func{void}{ExitMainLoop}{\void}
+\membersection{wxApp::IsActive}\label{wxappisactive}
+
+\constfunc{bool}{IsActive}{\void}
+
+Returns \true if the application is active, i.e. if one of its windows is
+currently in the foreground. If this function returns \false and you need to
+attract users attention to the application, you may use
+\helpref{wxTopLevelWindow::RequestUserAttention}{wxtoplevelwindowrequestuserattention}
+to do it.
-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.
-\membersection{wxApp::Initialized}\label{wxappinitialized}
+\membersection{wxApp::IsMainLoopRunning}\label{wxappismainlooprunning}
-\func{bool}{Initialized}{\void}
+\func{static bool}{IsMainLoopRunning}{\void}
+
+Returns \true if the main event loop is currently running, i.e. if the
+application is inside \helpref{OnRun}{wxapponrun}.
+
+This can be useful to test whether the 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.
-Returns true if the application has been initialized (i.e. if\rtfsp
-\helpref{wxApp::OnInit}{wxapponinit} has returned successfully). This can be useful for error
-message routines to determine which method of output is best for the
-current state of the program (some windowing systems may not like
-dialogs to pop up before the main loop has been entered).
\membersection{wxApp::MainLoop}\label{wxappmainloop}
-\func{int}{MainLoop}{\void}
+\func{virtual int}{MainLoop}{\void}
-Called by wxWindows on creation of the application. Override this if you wish
+Called by wxWidgets on creation of the application. Override this if you wish
to provide your own (environment-dependent) main loop.
\wxheading{Return value}
%%\helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnChar}{wxwindowonchar},\rtfsp
%%\helpref{wxWindow::OnCharHook}{wxwindowoncharhook}, \helpref{wxDialog::OnCharHook}{wxdialogoncharhook}
-\membersection{wxApp::OnAssert}\label{wxapponassert}
-\func{void}{OnAssert}{\param{const wxChar }{*file}, \param{int }{line}, \param{const wxChar }{*cond}, \param{const wxChar }{*msg}}
+\membersection{wxApp::OnAssertFailure}\label{wxapponassertfailure}
+
+\func{void}{OnAssertFailure}{\param{const wxChar }{*file}, \param{int }{line}, \param{const wxChar }{*func}, \param{const wxChar }{*cond}, \param{const wxChar }{*msg}}
This function is called when an assert failure occurs, i.e. the condition
specified in \helpref{wxASSERT}{wxassert} macro evaluated to {\tt false}.
It is only called in debug mode (when {\tt \_\_WXDEBUG\_\_} is defined) as
asserts are not left in the release code at all.
-The base class version show the default assert failure dialog box proposing to
+The base class version shows the default assert failure dialog box proposing to
the user to stop the program, continue or ignore all subsequent asserts.
\wxheading{Parameters}
-\docparam{file}{the name of the source file where the assert occured}
+\docparam{file}{the name of the source file where the assert occurred}
-\docparam{line}{the line number in this file where the assert occured}
+\docparam{line}{the line number in this file where the assert occurred}
-\docparam{cond}{the condition of the failed assert in string form}
+\docparam{func}{the name of the function where the assert occurred, may be
+empty if the compiler doesn't support C99 \texttt{\_\_FUNCTION\_\_}}
+
+\docparam{cond}{the condition of the failed assert in text form}
\docparam{msg}{the message specified as argument to
\helpref{wxASSERT\_MSG}{wxassertmsg} or \helpref{wxFAIL\_MSG}{wxfailmsg}, will
be {\tt NULL} if just \helpref{wxASSERT}{wxassert} or \helpref{wxFAIL}{wxfail}
was used}
-\membersection{wxApp::OnExit}\label{wxapponexit}
-
-\func{int}{OnExit}{\void}
-
-Provide this member function for any processing which needs to be
-done as the application is about to exit. OnExit is called after
-destroying all application windows and controls, but before
-wxWindows cleanup.
\membersection{wxApp::OnCmdLineError}\label{wxapponcmdlineerror}
\helpref{OnInitCmdLine}{wxapponinitcmdline}
+
\membersection{wxApp::OnCmdLineHelp}\label{wxapponcmdlinehelp}
\func{bool}{OnCmdLineHelp}{\param{wxCmdLineParser\& }{parser}}
\helpref{OnInitCmdLine}{wxapponinitcmdline}
+
\membersection{wxApp::OnCmdLineParsed}\label{wxapponcmdlineparsed}
\func{bool}{OnCmdLineParsed}{\param{wxCmdLineParser\& }{parser}}
\helpref{OnInitCmdLine}{wxapponinitcmdline}
+
+\membersection{wxApp::OnExceptionInMainLoop}\label{wxapponexceptioninmainloop}
+
+\func{virtual bool}{OnExceptionInMainLoop}{\void}
+
+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
+continue running the loop or \false to exit the loop and terminate the
+program. In the latter case it can also use C++ \texttt{throw} keyword to
+rethrow the current exception.
+
+The default behaviour of this function is the latter in all ports except under
+Windows where a dialog is shown to the user which allows him to choose between
+the different options. You may override this function in your class to do
+something more appropriate.
+
+Finally note that if the exception is rethrown from here, it can be caught in
+\helpref{OnUnhandledException}{wxapponunhandledexception}.
+
+
+\membersection{wxApp::OnExit}\label{wxapponexit}
+
+\func{virtual int}{OnExit}{\void}
+
+Override this member function for any processing which needs to be
+done as the application is about to exit. OnExit is called after
+destroying all application windows and controls, but before
+wxWidgets cleanup. Note that it is not called at all if
+\helpref{OnInit}{wxapponinit} failed.
+
+The return value of this function is currently ignored, return the same value
+as returned by the base class method if you override it.
+
+
\membersection{wxApp::OnFatalException}\label{wxapponfatalexception}
\func{void}{OnFatalException}{\void}
\wxheading{See also}
-\helpref{wxHandleFatalExcetions}{wxhandlefatalexceptions}
+\helpref{wxHandleFatalExceptions}{wxhandlefatalexceptions}
%% VZ: the wxApp event handler are private and should not be documented here!
%%
%%since this forwards OnIdle events to windows and also performs garbage collection for
%%windows whose destruction has been delayed.
%%
-%%wxWindows' strategy for OnIdle processing is as follows. After pending user interface events for an
-%%application have all been processed, wxWindows sends an OnIdle event to the application object. wxApp::OnIdle itself
+%%wxWidgets' strategy for OnIdle processing is as follows. After pending user interface events for an
+%%application have all been processed, wxWidgets sends an OnIdle event to the application object. wxApp::OnIdle itself
%%sends an OnIdle event to each application window, allowing windows to do idle processing such as updating
%%their appearance. If either wxApp::OnIdle or a window OnIdle function requested more time, by
-%%calling \helpref{wxIdleEvent::RequestMore}{wxidleeventrequestmore}, wxWindows will send another OnIdle
+%%calling \helpref{wxIdleEvent::RequestMore}{wxidleeventrequestmore}, wxWidgets will send another OnIdle
%%event to the application object. This will occur in a loop until either a user event is found to be
%%pending, or OnIdle requests no more time. Then all pending user events are processed until the system
%%goes idle again, when OnIdle is called, and so on.
%%\helpref{wxWindow::Close}{wxwindowclose},\rtfsp
%%\helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp
%%\helpref{wxCloseEvent}{wxcloseevent},\rtfsp
-%%\helpref{wxApp::OnQueryEndSession}{wxapponqueryendsession}
+
\membersection{wxApp::OnInit}\label{wxapponinit}
This must be provided by the application, and will usually create the
application's main window, optionally calling
-\helpref{wxApp::SetTopWindow}{wxappsettopwindow}.
+\helpref{wxApp::SetTopWindow}{wxappsettopwindow}. You may use
+\helpref{OnExit}{wxapponexit} 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
-wxWindows you have to call the base class version in the derived class
+wxWidgets you have to call the base class version in the derived class
OnInit().
-Return true to continue processing, false to exit the application.
+Return \true to continue processing, \false to exit the application
+immediately.
+
\membersection{wxApp::OnInitCmdLine}\label{wxapponinitcmdline}
parser with the command line options for this application. The base class
versions adds support for a few standard options only.
-\membersection{wxApp::OnQueryEndSession}\label{wxapponqueryendsession}
-
-\func{void}{OnQueryEndSession}{\param{wxCloseEvent\& }{event}}
+\membersection{wxApp::OnRun}\label{wxapponrun}
-This is an event handler function called when the operating system or GUI session is
-about to close down. Typically, an application will try to save unsaved documents
-at this point.
+\func{virtual int}{OnRun}{\void}
-If \helpref{wxCloseEvent::CanVeto}{wxcloseeventcanveto} returns true, the application
-is allowed to veto the shutdown by calling \helpref{wxCloseEvent::Veto}{wxcloseeventveto}.
-The application might veto the shutdown after prompting for documents to be saved, and the
-user has cancelled the save.
+This virtual function is where the execution of a program written in wxWidgets
+starts. The default implementation just enters the main loop and starts
+handling the events until it terminates, either because
+\helpref{ExitMainLoop}{wxappexitmainloop} has been explicitly called or because
+the last frame has been deleted and
+\helpref{GetExitOnFrameDelete}{wxappgetexitonframedelete} flag is \true (this
+is the default).
-Use the EVT\_QUERY\_END\_SESSION event table macro to handle query end session events.
+The return value of this function becomes the exit code of the program, so it
+should return $0$ in case of successful termination.
-You should check whether the application is forcing the deletion of the window
-using \helpref{wxCloseEvent::GetForce}{wxcloseeventgetforce}. If this is true,
-destroy the window using \helpref{wxWindow::Destroy}{wxwindowdestroy}.
-If not, it is up to you whether you respond by destroying the window.
-The default handler calls \helpref{wxWindow::Close}{wxwindowclose} on the top-level window,
-and vetoes the shutdown if Close returns false. This will be sufficient for many applications.
+\membersection{wxApp::OnUnhandledException}\label{wxapponunhandledexception}
-\wxheading{Remarks}
+\func{virtual void}{OnUnhandledException}{\void}
-Under X, OnQueryEndSession is called in response to the `save session' event.
+This function is called when an unhandled C++ exception occurs inside
+\helpref{OnRun()}{wxapponrun} (the exceptions which occur during the program
+startup and shutdown might not be caught at all).
+Note that the exception type is lost by now, so if you want to really handle
+the exception you should override \helpref{OnRun()}{wxapponrun} and put a
+try/catch clause around the call to the base class version there.
-Under Windows, OnQueryEndSession is called in response to the WM\_QUERYENDSESSION message.
-
-\wxheading{See also}
-
-\helpref{wxWindow::Close}{wxwindowclose},\rtfsp
-\helpref{wxCloseEvent}{wxcloseevent}
-%% GD: OnXXX functions are not documented
-%%\helpref{wxApp::OnEndSession}{wxapponendsession}
\membersection{wxApp::ProcessMessage}\label{wxappprocessmessage}
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. The function returns true if the message
-was processed, false otherwise. If you use wxWindows with another class
+was processed, false otherwise. If you use wxWidgets with another class
library with its own message loop, you should make sure that this
-function is called to allow wxWindows to receive messages. For example,
+function is called to allow wxWidgets to receive messages. For example,
to allow co-existence with the Microsoft Foundation Classes, override
the PreTranslateMessage function:
\begin{verbatim}
-// Provide wxWindows message loop compatibility
+// Provide wxWidgets message loop compatibility
BOOL CTheApp::PreTranslateMessage(MSG *msg)
{
if (wxTheApp && wxTheApp->ProcessMessage((WXMSW *)msg))
}
\end{verbatim}
+
\membersection{wxApp::Pending}\label{wxapppending}
-\func{bool}{Pending}{\void}
+\func{virtual bool}{Pending}{\void}
Returns true if unprocessed events are in the window system event queue.
\helpref{wxApp::Dispatch}{wxappdispatch}
-\membersection{wxApp::SendIdleEvents}\label{wxappsendidleevents}
-
-\func{bool}{SendIdleEvents}{\void}
-Sends idle events to all top-level windows.
+\membersection{wxApp::SendIdleEvents}\label{wxappsendidleevents}
-\func{bool}{SendIdleEvents}{\param{wxWindow*}{ win}}
+\func{bool}{SendIdleEvents}{\param{wxWindow*}{ win}, \param{wxIdleEvent\& }{event}}
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.
+
\wxheading{Remarks}
These functions poll the top-level windows, and their children, for idle event processing.
\wxheading{See also}
-%% GD: OnXXX functions are not documented
-%%\helpref{wxApp::OnIdle}{wxapponidle}
\helpref{wxIdleEvent}{wxidleevent}
+
\membersection{wxApp::SetAppName}\label{wxappsetappname}
\func{void}{SetAppName}{\param{const wxString\& }{name}}
Sets the name of the application. The name may be used in dialogs
(for example by the document/view framework). A default name is set by
-wxWindows.
+wxWidgets.
\wxheading{See also}
\helpref{wxApp::GetAppName}{wxappgetappname}
-\membersection{wxApp::SetAuto3D}\label{wxappsetauto3d}
-
-\func{void}{SetAuto3D}{\param{const bool}{ auto3D}}
-
-Switches automatic 3D controls on or off.
-
-\wxheading{Parameters}
-
-\docparam{auto3D}{If true, all controls will be created with 3D appearances unless
-overridden for a control or dialog. The default is true}
-
-\wxheading{Remarks}
-
-This has an effect on Windows only.
-
-\wxheading{See also}
-
-\helpref{wxApp::GetAuto3D}{wxappgetauto3d}
\membersection{wxApp::SetClassName}\label{wxappsetclassname}
\helpref{wxApp::GetClassName}{wxappgetclassname}
+
\membersection{wxApp::SetExitOnFrameDelete}\label{wxappsetexitonframedelete}
\func{void}{SetExitOnFrameDelete}{\param{bool}{ flag}}
\helpref{wxApp::GetExitOnFrameDelete}{wxappgetexitonframedelete},\\
\helpref{wxApp shutdown overview}{wxappshutdownoverview}
+
+\membersection{wxApp::SetInstance}\label{wxappsetinstance}
+
+\func{static void}{SetInstance}{\param{wxAppConsole* }{app}}
+
+Allows external code to modify global \texttt{wxTheApp}, but you should really
+know what you're doing if you call it.
+
+\wxheading{Parameters}
+
+\docparam{app}{Replacement for the global application object.}
+
+\wxheading{See also}
+
+\helpref{wxApp::GetInstance}{wxappgetinstance}
+
+
\membersection{wxApp::SetTopWindow}\label{wxappsettopwindow}
\func{void}{SetTopWindow}{\param{wxWindow* }{window}}
Sets the `top' window. You can call this from within \helpref{wxApp::OnInit}{wxapponinit} to
-let wxWindows know which is the main window. You don't have to set the top window;
+let wxWidgets know which is the main window. You don't have to set the top window;
it is only a convenience so that (for example) certain dialogs without parents can use a
specific window as the top window. If no top window is specified by the application,
-wxWindows just uses the first frame or dialog in its top-level window list, when it
+wxWidgets just uses the first frame or dialog in its top-level window list, when it
needs to use the top window.
\wxheading{Parameters}
\helpref{wxApp::GetTopWindow}{wxappgettopwindow}, \helpref{wxApp::OnInit}{wxapponinit}
+
\membersection{wxApp::SetVendorName}\label{wxappsetvendorname}
\func{void}{SetVendorName}{\param{const wxString\& }{name}}
Sets the name of application's vendor. The name will be used
in registry access. A default name is set by
-wxWindows.
+wxWidgets.
\wxheading{See also}
\helpref{wxApp::GetVendorName}{wxappgetvendorname}
+
\membersection{wxApp::SetUseBestVisual}\label{wxappsetusebestvisual}
\func{void}{SetUseBestVisual}{\param{bool}{ flag}}
\docparam{flag}{If true, the app will use the best visual.}
+
+\membersection{wxApp::HandleEvent}\label{wxapphandleevent}
+
+\constfunc{virtual void}{HandleEvent}{\param{wxEvtHandler}{ *handler}, \param{wxEventFunction}{ func}, \param{wxEvent\& }{event}}
+
+This function simply invokes the given method \arg{func} of the specified
+event handler \arg{handler} with the \arg{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.
+
+
\membersection{wxApp::Yield}\label{wxappyield}
\func{bool}{Yield}{\param{bool}{ onlyIfNeeded = false}}
iteration), call \helpref{wxLog::FlushActive}{wxlogflushactive}.
Calling Yield() recursively is normally an error and an assert failure is
-raised in debug build if such situation is detected. However if the the
+raised in debug build if such situation is detected. However if the
{\it onlyIfNeeded} parameter is {\tt true}, the method will just silently
return {\tt false} instead.
projects / wxWidgets.git / blobdiff