X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/c805f6c3af15017a3e5f592356bc9208f1182ff3..c63312c472c83be6d3b935f0ceeef484a7d611ce:/docs/latex/wx/app.tex diff --git a/docs/latex/wx/app.tex b/docs/latex/wx/app.tex index 9c5457aba1..76e50a1c1e 100644 --- a/docs/latex/wx/app.tex +++ b/docs/latex/wx/app.tex @@ -33,16 +33,16 @@ a reference to your application object) to be visible to other files. \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxApp::wxApp} +\membersection{wxApp::wxApp}\label{wxappctor} -\func{void}{wxApp}{\void} +\func{}{wxApp}{\void} Constructor. Called implicitly with a definition of a wxApp object. -\membersection{wxApp::\destruct{wxApp}} +\membersection{wxApp::\destruct{wxApp}}\label{wxappdtor} -\func{void}{\destruct{wxApp}}{\void} +\func{virtual}{\destruct{wxApp}}{\void} Destructor. Will be called implicitly on program exit if the wxApp object is created on the stack. @@ -57,7 +57,7 @@ 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). @@ -74,6 +74,18 @@ implementation returns a new wxLogGui class. \helpref{wxLog}{wxlog} +\membersection{wxApp::CreateTraits}\label{wxappcreatetraits} + +\func{virtual wxAppTraits *}{CreateTraits}{\void} + +Creates the \helpref{wxAppTraits}{wxapptraits} object when \helpref{GetTraits}{wxappgettraits} +needs it for the first time. + +\wxheading{See also} + +\helpref{wxAppTraits}{wxapptraits} + + \membersection{wxApp::Dispatch}\label{wxappdispatch} \func{virtual void}{Dispatch}{\void} @@ -92,6 +104,15 @@ This can be used for programming event loops, e.g. \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}} @@ -116,17 +137,6 @@ 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} \constfunc{wxString}{GetClassName}{\void} @@ -152,6 +162,18 @@ otherwise. \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} @@ -168,6 +190,17 @@ function will find the first top-level window (frame or dialog) and return that. \helpref{SetTopWindow}{wxappsettopwindow} + +\membersection{wxApp::GetTraits}\label{wxappgettraits} + +\func{wxAppTraits *}{GetTraits}{\void} + +Returns a pointer to the \helpref{wxAppTraits}{wxapptraits} object for the application. +If you want to customize the \helpref{wxAppTraits}{wxapptraits} object, you must override the +\helpref{CreateTraits}{wxappcreatetraits} function. + + + \membersection{wxApp::GetUseBestVisual}\label{wxappgetusebestvisual} \constfunc{bool}{GetUseBestVisual}{\void} @@ -187,13 +220,27 @@ different visuals, false otherwise. Returns the application's vendor name. -\membersection{wxApp::ExitMainLoop}\label{wxappexitmainloop} +\membersection{wxApp::IsActive}\label{wxappisactive} -\func{virtual void}{ExitMainLoop}{\void} +\constfunc{bool}{IsActive}{\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. +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. + + +\membersection{wxApp::IsMainLoopRunning}\label{wxappismainlooprunning} + +\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. \membersection{wxApp::MainLoop}\label{wxappmainloop} @@ -244,25 +291,28 @@ Returns 0 under X, and the wParam of the WM\_QUIT message under Windows. %%\helpref{wxWindow::OnCharHook}{wxwindowoncharhook}, \helpref{wxDialog::OnCharHook}{wxdialogoncharhook} -\membersection{wxApp::OnAssert}\label{wxapponassert} +\membersection{wxApp::OnAssertFailure}\label{wxapponassertfailure} -\func{void}{OnAssert}{\param{const wxChar }{*file}, \param{int }{line}, \param{const wxChar }{*cond}, \param{const wxChar }{*msg}} +\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 @@ -320,7 +370,7 @@ Return {\tt true} to continue normal execution or {\tt false} to return \helpref{OnInitCmdLine}{wxapponinitcmdline} -\membersection{wxApp::OnExceptionInMainLoop}{wxapponexceptioninmainloop} +\membersection{wxApp::OnExceptionInMainLoop}\label{wxapponexceptioninmainloop} \func{virtual bool}{OnExceptionInMainLoop}{\void} @@ -419,7 +469,6 @@ work and, in fact, probably won't. %%\helpref{wxWindow::Close}{wxwindowclose},\rtfsp %%\helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp %%\helpref{wxCloseEvent}{wxcloseevent},\rtfsp -%%\helpref{wxApp::OnQueryEndSession}{wxapponqueryendsession} \membersection{wxApp::OnInit}\label{wxapponinit} @@ -448,42 +497,6 @@ Called from \helpref{OnInit}{wxapponinit} and may be used to initialize the 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}} - -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. - -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. - -Use the EVT\_QUERY\_END\_SESSION event table macro to handle query end session events. - -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. - -\wxheading{Remarks} - -Under X, OnQueryEndSession is called in response to the `save session' event. - -Under Windows, OnQueryEndSession is called in response to the WM\_QUERYENDSESSION message. - -\wxheading{See also} - -\helpref{wxWindow::Close}{wxwindowclose},\rtfsp -\helpref{wxCloseEvent}{wxcloseevent}\rtfsp - - \membersection{wxApp::OnRun}\label{wxapponrun} \func{virtual int}{OnRun}{\void} @@ -580,26 +593,6 @@ wxWidgets. \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} \func{void}{SetClassName}{\param{const wxString\& }{name}} @@ -630,6 +623,22 @@ deleted. If false, the application will continue to run.} \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}} @@ -716,7 +725,7 @@ messages immediately (otherwise it will be done during the next idle loop 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.