X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/2a47d3c193a8358f9be6a9249af28b6cb10eacff..c266eff98c5e44012647f54f38a1e29ecabd8759:/docs/latex/wx/app.tex diff --git a/docs/latex/wx/app.tex b/docs/latex/wx/app.tex index b8833be0e6..4707e63d7f 100644 --- a/docs/latex/wx/app.tex +++ b/docs/latex/wx/app.tex @@ -12,7 +12,7 @@ objects in the application. \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. @@ -26,40 +26,46 @@ a reference to your application object) to be visible to other files. +\wxheading{Library} + +\helpref{wxBase}{librarieslist} + \wxheading{See also} \helpref{wxApp overview}{wxappoverview} \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. -The argument is a language identifier; this is an experimental -feature and will be expanded and documented in future versions. -\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. + \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} @@ -71,9 +77,22 @@ 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{void}{Dispatch}{\void} +\func{virtual void}{Dispatch}{\void} Dispatches the next event in the windowing system event queue. @@ -88,6 +107,43 @@ 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}} + +This function is called before processing any event and allows the application +to preempt the processing of some events. If this method returns $-1$ the event +is processed normally, otherwise either {\tt true} or {\tt 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). + + +\membersection{wxApp::GetAppDisplayName}\label{wxappgetappdisplayname} + +\constfunc{wxString}{GetAppDisplayName}{\void} + +Returns the user-readable application name. The difference between this string +and the one returned by \helpref{GetAppName}{wxappgetappname} 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 \helpref{GetAppName}{wxappgetappname}. + +\newsince{3.0} + + \membersection{wxApp::GetAppName}\label{wxappgetappname} \constfunc{wxString}{GetAppName}{\void} @@ -96,18 +152,13 @@ Returns the application name. \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} +\helpref{GetAppDisplayName}{wxappgetappdisplayname} + \membersection{wxApp::GetClassName}\label{wxappgetclassname} @@ -120,20 +171,35 @@ manner to refer to the application. \helpref{wxApp::SetClassName}{wxappsetclassname} -\membersection{wxApp::GetExitOnDelete}\label{wxappgetexitondelete} -\constfunc{bool}{GetExitOnDelete}{\void} +\membersection{wxApp::GetExitOnFrameDelete}\label{wxappgetexitonframedelete} + +\constfunc{bool}{GetExitOnFrameDelete}{\void} -Returns TRUE if the application will exit when the top-level window is deleted, FALSE +Returns true if the application will exit when the top-level window is deleted, false otherwise. \wxheading{See also} -\helpref{wxApp::SetExitOnDelete}{wxappsetexitondelete} +\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{wxWindow *}{GetTopWindow}{\void} +\constfunc{virtual wxWindow *}{GetTopWindow}{\void} Returns a pointer to the top window. @@ -144,256 +210,426 @@ function will find the first top-level window (frame or dialog) and return that. \wxheading{See also} -\helpref{wxApp::SetTopWindow}{wxappsettopwindow} +\helpref{SetTopWindow}{wxappsettopwindow} -\membersection{wxApp::ExitMainLoop}\label{wxappexitmainloop} -\func{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::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} + +Returns true if the application will use the best visual on systems that support +different visuals, false otherwise. + +\wxheading{See also} + +\helpref{SetUseBestVisual}{wxappsetusebestvisual} -\membersection{wxApp::Initialized}\label{wxappinitialized} -\func{bool}{Initialized}{\void} +\membersection{wxApp::GetVendorName}\label{wxappgetvendorname} + +\constfunc{wxString}{GetVendorName}{\void} + +Returns the application's vendor name. + + +\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. + + +\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 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} Returns 0 under X, and the wParam of the WM\_QUIT message under Windows. -\membersection{wxApp::OnActivate}\label{wxapponactivate} +%% VZ: OnXXX() functions should *not* be documented +%% +%%\membersection{wxApp::OnActivate}\label{wxapponactivate} +%% +%%\func{void}{OnActivate}{\param{wxActivateEvent\& }{event}} +%% +%%Provide this member function to know whether the application is being +%%activated or deactivated (Windows only). +%% +%%\wxheading{See also} +%% +%%\helpref{wxWindow::OnActivate}{wxwindowonactivate}, \helpref{wxActivateEvent}{wxactivateevent} +%% +%%\membersection{wxApp::OnCharHook}\label{wxapponcharhook} +%% +%%\func{void}{OnCharHook}{\param{wxKeyEvent\&}{ event}} +%% +%%This event handler function is called (under Windows only) to allow the window to intercept keyboard events +%%before they are processed by child windows. +%% +%%\wxheading{Parameters} +%% +%%\docparam{event}{The keypress event.} +%% +%%\wxheading{Remarks} +%% +%%Use the wxEVT\_CHAR\_HOOK macro in your event table. +%% +%%If you use this member, you can selectively consume keypress events by calling\rtfsp +%%\helpref{wxEvent::Skip}{wxeventskip} for characters the application is not interested in. +%% +%%\wxheading{See also} +%% +%%\helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnChar}{wxwindowonchar},\rtfsp +%%\helpref{wxWindow::OnCharHook}{wxwindowoncharhook}, \helpref{wxDialog::OnCharHook}{wxdialogoncharhook} + + +\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 shows the default assert failure dialog box proposing to +the user to stop the program, continue or ignore all subsequent asserts. -\func{void}{OnActivate}{\param{wxActivateEvent\& }{event}} +\wxheading{Parameters} -Provide this member function to know whether the application is being -activated or deactivated (Windows only). +\docparam{file}{the name of the source file where the assert occurred} -\wxheading{See also} +\docparam{line}{the line number in this file where the assert occurred} -\helpref{wxWindow::OnActivate}{wxwindowonactivate}, \helpref{wxActivateEvent}{wxactivateevent} +\docparam{func}{the name of the function where the assert occurred, may be +empty if the compiler doesn't support C99 \texttt{\_\_FUNCTION\_\_}} -\membersection{wxApp::OnExit}\label{wxapponexit} +\docparam{cond}{the condition of the failed assert in text form} -\func{int}{OnExit}{\void} +\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} -Provide this member function for any processing which needs to be done as -the application is about to exit. -\membersection{wxApp::OnCharHook}\label{wxapponcharhook} +\membersection{wxApp::OnCmdLineError}\label{wxapponcmdlineerror} -\func{void}{OnCharHook}{\param{wxKeyEvent\&}{ event}} +\func{bool}{OnCmdLineError}{\param{wxCmdLineParser\& }{parser}} -This event handler function is called (under Windows only) to allow the window to intercept keyboard events -before they are processed by child windows. +Called when command line parsing fails (i.e. an incorrect command line option +was specified by the user). The default behaviour is to show the program usage +text and abort the program. -\wxheading{Parameters} +Return {\tt true} to continue normal execution or {\tt false} to return +{\tt false} from \helpref{OnInit}{wxapponinit} thus terminating the program. -\docparam{event}{The keypress event.} +\wxheading{See also} -\wxheading{Remarks} +\helpref{OnInitCmdLine}{wxapponinitcmdline} + + +\membersection{wxApp::OnCmdLineHelp}\label{wxapponcmdlinehelp} + +\func{bool}{OnCmdLineHelp}{\param{wxCmdLineParser\& }{parser}} -Use the wxEVT\_CHAR\_HOOK macro in your event table. +Called when the help option ({\tt --help}) was specified on the command line. +The default behaviour is to show the program usage text and abort the program. -If you use this member, you can selectively consume keypress events by calling\rtfsp -\helpref{wxEvent::Skip}{wxeventskip} for characters the application is not interested in. +Return {\tt true} to continue normal execution or {\tt false} to return +{\tt false} from \helpref{OnInit}{wxapponinit} thus terminating the program. \wxheading{See also} -\helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnChar}{wxwindowonchar},\rtfsp -\helpref{wxWindow::OnCharHook}{wxwindowoncharhook}, \helpref{wxDialog::OnCharHook}{wxdialogoncharhook} +\helpref{OnInitCmdLine}{wxapponinitcmdline} -\membersection{wxApp::OnIdle}\label{wxapponidle} -\func{void}{OnIdle}{\param{wxIdleEvent\& }{event}} +\membersection{wxApp::OnCmdLineParsed}\label{wxapponcmdlineparsed} -Override this member function for any processing which needs to be done -when the application is idle. You should call wxApp::OnIdle from your own function, -since this forwards OnIdle events to windows and also performs garbage collection for -windows whose destruction has been delayed. +\func{bool}{OnCmdLineParsed}{\param{wxCmdLineParser\& }{parser}} -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 -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 -caling \helpref{wxIdleEvent::ReqestMore}{wxidleeventrequestmore}, wxWindows 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. +Called after the command line had been successfully parsed. You may override +this method to test for the values of the various parameters which could be +set from the command line. + +Don't forget to call the base class version unless you want to suppress +processing of the standard command line options. + +Return {\tt true} to continue normal execution or {\tt false} to return +{\tt false} from \helpref{OnInit}{wxapponinit} thus terminating the program. \wxheading{See also} -\helpref{wxWindow::OnIdle}{wxwindowonidle}, \helpref{wxIdleEvent}{wxidleevent},\rtfsp -\helpref{wxWindow::SendIdleEvents}{wxappsendidleevents} +\helpref{OnInitCmdLine}{wxapponinitcmdline} -\membersection{wxApp::OnEndSession}\label{wxapponendsession} -\func{void}{OnEndSession}{\param{wxCloseEvent\& }{event}} +\membersection{wxApp::OnExceptionInMainLoop}\label{wxapponexceptioninmainloop} -This is an event handler function called when the operating system or GUI session is -about to close down. The application has a chance to silently save information, -and can optionally close itself. +\func{virtual bool}{OnExceptionInMainLoop}{\void} -Use the EVT\_END\_SESSION event table macro to handle query end session events. +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 handler calls \helpref{wxWindow::Close}{wxwindowclose} with a TRUE argument -(forcing the application to close itself silently). +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. -\wxheading{Remarks} -Under X, OnEndSession is called in response to the 'die' event. +\membersection{wxApp::OnFatalException}\label{wxapponfatalexception} -Under Windows, OnEndSession is called in response to the WM\_ENDSESSION message. +\func{void}{OnFatalException}{\void} + +This function may be called if something fatal happens: an unhandled +exception under Win32 or a a fatal signal under Unix, for example. However, +this will not happen by default: you have to explicitly call +\helpref{wxHandleFatalExceptions}{wxhandlefatalexceptions} to enable this. + +Generally speaking, this function should only show a message to the user and +return. You may attempt to save unsaved data but this is not guaranteed to +work and, in fact, probably won't. \wxheading{See also} -\helpref{wxWindow::Close}{wxwindowclose},\rtfsp -\helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp -\helpref{wxCloseEvent}{wxcloseevent},\rtfsp -\helpref{wxApp::OnQueryEndSession}{wxapponqueryendsession} +\helpref{wxHandleFatalExceptions}{wxhandlefatalexceptions} + +%% VZ: the wxApp event handler are private and should not be documented here! +%% +%%\membersection{wxApp::OnIdle}\label{wxapponidle} +%% +%%\func{void}{OnIdle}{\param{wxIdleEvent\& }{event}} +%% +%%Override this member function for any processing which needs to be done +%%when the application is idle. You should call wxApp::OnIdle from your own function, +%%since this forwards OnIdle events to windows and also performs garbage collection for +%%windows whose destruction has been delayed. +%% +%%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}, 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. +%% +%%\wxheading{See also} +%% +%%\helpref{wxWindow::OnIdle}{wxwindowonidle}, \helpref{wxIdleEvent}{wxidleevent},\rtfsp +%%\helpref{wxWindow::SendIdleEvents}{wxappsendidleevents} +%% +%%\membersection{wxApp::OnEndSession}\label{wxapponendsession} +%% +%%\func{void}{OnEndSession}{\param{wxCloseEvent\& }{event}} +%% +%%This is an event handler function called when the operating system or GUI session is +%%about to close down. The application has a chance to silently save information, +%%and can optionally close itself. +%% +%%Use the EVT\_END\_SESSION event table macro to handle query end session events. +%% +%%The default handler calls \helpref{wxWindow::Close}{wxwindowclose} with a true argument +%%(forcing the application to close itself silently). +%% +%%\wxheading{Remarks} +%% +%%Under X, OnEndSession is called in response to the `die' event. +%% +%%Under Windows, OnEndSession is called in response to the WM\_ENDSESSION message. +%% +%%\wxheading{See also} +%% +%%\helpref{wxWindow::Close}{wxwindowclose},\rtfsp +%%\helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp +%%\helpref{wxCloseEvent}{wxcloseevent},\rtfsp + \membersection{wxApp::OnInit}\label{wxapponinit} \func{bool}{OnInit}{\void} This must be provided by the application, and will usually create the -application's main window, optionally calling \helpref{wxApp::SetTopWindow}{wxappsettopwindow}. +application's main window, optionally calling +\helpref{wxApp::SetTopWindow}{wxappsettopwindow}. You may use +\helpref{OnExit}{wxapponexit} to clean up anything initialized here, provided +that the function returns \true. -Return TRUE to continue processing, FALSE to exit the application. +Notice that if you want to to use the command line processing provided by +wxWidgets you have to call the base class version in the derived class +OnInit(). -\membersection{wxApp::OnQueryEndSession}\label{wxapponqueryendsession} +Return \true to continue processing, \false to exit the application +immediately. -\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. +\membersection{wxApp::OnInitCmdLine}\label{wxapponinitcmdline} -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. +\func{void}{OnInitCmdLine}{\param{wxCmdLineParser\& }{parser}} -Use the EVT\_QUERY\_END\_SESSION event table macro to handle query end session events. +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. -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. +\membersection{wxApp::OnRun}\label{wxapponrun} -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. +\func{virtual int}{OnRun}{\void} -\wxheading{Remarks} +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). -Under X, OnQueryEndSession is called in response to the 'save session' event. +The return value of this function becomes the exit code of the program, so it +should return $0$ in case of successful termination. -Under Windows, OnQueryEndSession is called in response to the WM\_QUERYENDSESSION message. -\wxheading{See also} +\membersection{wxApp::OnUnhandledException}\label{wxapponunhandledexception} + +\func{virtual void}{OnUnhandledException}{\void} + +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). 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 \helpref{OnExceptionInMainLoop}{wxapponexceptioninmainloop}. + +The default implementation shows information about the exception in debug build +but does nothing in the release build. -\helpref{wxWindow::Close}{wxwindowclose},\rtfsp -\helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp -\helpref{wxCloseEvent}{wxcloseevent},\rtfsp -\helpref{wxApp::OnEndSession}{wxapponendsession} \membersection{wxApp::ProcessMessage}\label{wxappprocessmessage} -\func{bool}{ProcessMessage}{\param{MSG *}{msg}} +\func{bool}{ProcessMessage}{\param{WXMSG *}{msg}} 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 +may wish to process it. The function returns true if the message +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, -to allow co-existance with the Microsoft Foundation Classes, override +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(msg)) - return TRUE; + if (wxTheApp && wxTheApp->ProcessMessage((WXMSW *)msg)) + return true; else return CWinApp::PreTranslateMessage(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 -(MS Windows and Motif). +Returns true if unprocessed events are in the window system event queue. \wxheading{See also} \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. -If TRUE is returned, more OnIdle processing is requested by one or more window. +If true is returned, more OnIdle processing is requested by one or more window. \wxheading{See also} -\helpref{wxApp::OnIdle}{wxapponidle}, \helpref{wxWindow::OnIdle}{wxwindowonidle}, \helpref{wxIdleEvent}{wxidleevent} - -\membersection{wxApp::SetAppName}\label{wxappsetappname} - -\func{void}{SetAppName}{\param{const wxString\& }{name}} +\helpref{wxIdleEvent}{wxidleevent} -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. -\wxheading{See also} - -\helpref{wxApp::GetAppName}{wxappgetappname} +\membersection{wxApp::SetAppDisplayName}\label{wxappsetappdisplayname} -\membersection{wxApp::SetAuto3D}\label{wxappsetauto3d} +\func{void}{SetAppDisplayName}{\param{const wxString\& }{name}} -\func{void}{SetAuto3D}{\param{const bool}{ auto3D}} +Set the application name to be used in the user-visible places such as window +titles. See \helpref{GetAppDisplayName}{wxappgetappdisplayname} for more about +the differences between the display name and name. -Switches automatic 3D controls on or off. -\wxheading{Parameters} +\membersection{wxApp::SetAppName}\label{wxappsetappname} -\docparam{auto3D}{If TRUE, all controls will be created with 3D appearances unless -overridden for a control or dialog. The default is TRUE} +\func{void}{SetAppName}{\param{const wxString\& }{name}} -\wxheading{Remarks} +Sets the name of the application. This name should be used for file names, +configuration file entries and other internal strings. For the user-visible +strings, such as the window titles, the application display name set by +\helpref{SetAppDisplayName}{wxappsetappdisplayname} is used instead. -This has an effect on Windows only. +By default the application name is set to the name of its executable file. \wxheading{See also} -\helpref{wxApp::GetAuto3D}{wxappgetauto3d} +\helpref{wxApp::GetAppName}{wxappgetappname} + \membersection{wxApp::SetClassName}\label{wxappsetclassname} @@ -406,31 +642,50 @@ manner to refer to the application. \helpref{wxApp::GetClassName}{wxappgetclassname} -\membersection{wxApp::SetExitOnDelete}\label{wxappsetexitondelete} -\func{void}{SetExitOnDelete}{\param{bool}{ flag}} +\membersection{wxApp::SetExitOnFrameDelete}\label{wxappsetexitonframedelete} + +\func{void}{SetExitOnFrameDelete}{\param{bool}{ flag}} Allows the programmer to specify whether the application will exit when the top-level frame is deleted. \wxheading{Parameters} -\docparam{flag}{If TRUE (the default), the application will exit when the top-level frame is -deleted. If FALSE, the application will continue to run.} +\docparam{flag}{If true (the default), the application will exit when the top-level frame is +deleted. If false, the application will continue to run.} -\wxheading{Remarks} +\wxheading{See also} + +\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} -Currently, setting this to FALSE only has an effect under Windows. \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; -it's only a convenience so that (for example) certain dialogs without parents can use a +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} @@ -441,3 +696,77 @@ needs to use the top window. \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 +wxWidgets. + +\wxheading{See also} + +\helpref{wxApp::GetVendorName}{wxappgetvendorname} + + +\membersection{wxApp::SetUseBestVisual}\label{wxappsetusebestvisual} + +\func{void}{SetUseBestVisual}{\param{bool}{ flag}, \param{bool}{ forceTrueColour = false}} + +Allows the programmer to specify whether the application will use the best visual +on systems that support several visual on the same display. This is typically the +case under Solaris and IRIX, where the default visual is only 8-bit whereas certain +applications are supposed to run in TrueColour mode. + +If \arg{forceTrueColour} is true then the application will try to force +using a TrueColour visual and abort the app if none is found. + +Note that this function has to be called in the constructor of the {\tt wxApp} +instance and won't have any effect when called later on. + +This function currently only has effect under GTK. + +\wxheading{Parameters} + +\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}} + +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 \helpref{::wxSafeYield}{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 \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 +{\it onlyIfNeeded} parameter is {\tt true}, the method will just silently +return {\tt false} instead. +