X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a660d684eda27638bca0384b2058911a31c8e845..8f0db49cd26130a7bc49816853ce832324ee85da:/docs/latex/wx/app.tex diff --git a/docs/latex/wx/app.tex b/docs/latex/wx/app.tex index c2464a6123..4ccfd04f3b 100644 --- a/docs/latex/wx/app.tex +++ b/docs/latex/wx/app.tex @@ -22,6 +22,10 @@ a reference to your application object) to be visible to other files. \helpref{wxEvtHandler}{wxevthandler}\\ \helpref{wxObject}{wxobject} +\wxheading{Include files} + + + \wxheading{See also} \helpref{wxApp overview}{wxappoverview} @@ -30,15 +34,10 @@ a reference to your application object) to be visible to other files. \membersection{wxApp::wxApp} -\func{void}{wxApp}{\param{int}{ language = wxLANGUAGE\_ENGLISH}} +\func{void}{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. - -TODO: completely rewrite the language stuff. - \membersection{wxApp::\destruct{wxApp}} \func{void}{\destruct{wxApp}}{\void} @@ -118,32 +117,48 @@ manner to refer to the application. \helpref{wxApp::SetClassName}{wxappsetclassname} -\membersection{wxApp::GetExitOnDelete}\label{wxappgetexitondelete} +\membersection{wxApp::GetExitOnFrameDelete}\label{wxappgetexitonframedelete} -\constfunc{bool}{GetExitOnDelete}{\void} +\constfunc{bool}{GetExitFrameOnDelete}{\void} 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} + +\membersection{wxApp::GetTopWindow}\label{wxappgettopwindow} + +\constfunc{virtual wxWindow *}{GetTopWindow}{\void} -\membersection{wxApp::GetPrintMode}\label{wxappgetprintmode} +Returns a pointer to the top window. -\constfunc{bool}{GetPrintMode}{\void} +\wxheading{Remarks} -Returns the print mode: see \helpref{wxApp::SetPrintMode}{wxappsetprintmode}. +If the top window hasn't been set using \helpref{wxApp::SetTopWindow}{wxappsettopwindow}, this +function will find the first top-level window (frame or dialog) and return that. -\membersection{wxApp::GetTopWindow}\label{wxappgettopwindow} +\wxheading{See also} -\constfunc{wxWindow *}{GetTopWindow}{\void} +\helpref{SetTopWindow}{wxappsettopwindow} -Returns a pointer to the top window. +\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{wxApp::SetTopWindow}{wxappsettopwindow} +\helpref{SetUseBestVisual}{wxappsetusebestvisual} + +\membersection{wxApp::GetVendorName}\label{wxappgetvendorname} + +\constfunc{wxString}{GetVendorName}{\void} + +Returns the application's vendor name. \membersection{wxApp::ExitMainLoop}\label{wxappexitmainloop} @@ -215,48 +230,178 @@ If you use this member, you can selectively consume keypress events by calling\r \helpref{wxKeyEvent}{wxkeyevent}, \helpref{wxWindow::OnChar}{wxwindowonchar},\rtfsp \helpref{wxWindow::OnCharHook}{wxwindowoncharhook}, \helpref{wxDialog::OnCharHook}{wxdialogoncharhook} -\membersection{wxApp::OnIdle}\label{wxapponidle} +\membersection{wxApp::OnCmdLineError}\label{wxapponcmdlineerror} -\func{void}{OnIdle}{\param{wxIdleEvent\& }{event}} +\func{bool}{OnCmdLineError}{\param{wxCmdLineParser\& }{parser}} -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. +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. -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 event. 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. +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::OnCmdLineHelp}\label{wxapponcmdlinehelp} + +\func{bool}{OnCmdLineHelp}{\param{wxCmdLineParser\& }{parser}} + +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. + +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{OnInitCmdLine}{wxapponinitcmdline} + +\membersection{wxApp::OnCmdLineParsed}\label{wxapponcmdlineparsed} + +\func{bool}{OnCmdLineParsed}{\param{wxCmdLineParser\& }{parser}} + +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{OnInitCmdLine}{wxapponinitcmdline} + +\membersection{wxApp::OnFatalException}\label{wxapponfatalexception} + +\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{wxHandleFatalExcetions}{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. +%% +%%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::RequestMore}{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. +%% +%%\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 +%%\helpref{wxApp::OnQueryEndSession}{wxapponqueryendsession} \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, calling \helpref{wxApp::SetTopWindow}{wxappsettopwindow}. +application's main window, optionally calling +\helpref{wxApp::SetTopWindow}{wxappsettopwindow}. + +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 +OnInit(). Return TRUE to continue processing, FALSE to exit the application. -\membersection{wxApp::Pending}\label{wxapppending} +\membersection{wxApp::OnInitCmdLine}\label{wxapponinitcmdline} -\func{bool}{Pending}{\void} +\func{void}{OnInitCmdLine}{\param{wxCmdLineParser\& }{parser}} + +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}} -Returns TRUE if unprocessed events are in the window system event queue -(MS Windows and Motif). +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{wxApp::Dispatch}{wxappdispatch} +\helpref{wxWindow::Close}{wxwindowclose},\rtfsp +\helpref{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp +\helpref{wxCloseEvent}{wxcloseevent},\rtfsp +\helpref{wxApp::OnEndSession}{wxapponendsession} \membersection{wxApp::ProcessMessage}\label{wxappprocessmessage} @@ -282,6 +427,16 @@ BOOL CTheApp::PreTranslateMessage(MSG *msg) } \end{verbatim} +\membersection{wxApp::Pending}\label{wxapppending} + +\func{bool}{Pending}{\void} + +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} @@ -343,9 +498,9 @@ manner to refer to the application. \helpref{wxApp::GetClassName}{wxappgetclassname} -\membersection{wxApp::SetExitOnDelete}\label{wxappsetexitondelete} +\membersection{wxApp::SetExitOnFrameDelete}\label{wxappsetexitonframedelete} -\func{void}{SetExitOnDelete}{\param{bool}{ flag}} +\func{void}{SetExitOnFrameDelete}{\param{bool}{ flag}} Allows the programmer to specify whether the application will exit when the top-level frame is deleted. @@ -355,41 +510,67 @@ top-level frame is deleted. \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} +\membersection{wxApp::SetTopWindow}\label{wxappsettopwindow} -Currently, setting this to FALSE only has an effect under Windows. +\func{void}{SetTopWindow}{\param{wxWindow* }{window}} -\membersection{wxApp::SetPrintMode}\label{wxappsetprintmode} +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 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 +needs to use the top window. -\func{void}{SetPrintMode}{\param{int}{ mode}} +\wxheading{Parameters} -Sets the print mode determining what printing facilities will be -used by the printing framework. +\docparam{window}{The new top window.} -\wxheading{Parameters} +\wxheading{See also} + +\helpref{wxApp::GetTopWindow}{wxappgettopwindow}, \helpref{wxApp::OnInit}{wxapponinit} -\docparam{mode}{This can be one of: -\begin{twocollist}\itemsep=0pt -\twocolitem{{\bf wxPRINT\_WINDOWS}}{Under Windows, use Windows printing (wxPrinterDC). This is the -default under Windows.} -\twocolitem{{\bf wxPRINT\_POSTSCRIPT}}{Use PostScript printing (wxPostScriptDC). This is the -default for non-Windows platforms.} -\end{twocollist} -}% +\membersection{wxApp::SetVendorName}\label{wxappsetvendorname} -\membersection{wxApp::SetTopWindow}\label{wxappsettopwindow} +\func{void}{SetVendorName}{\param{const wxString\& }{name}} -\func{void}{SetTopWindow}{\param{wxWindow* }{window}} +Sets the name of application's vendor. The name will be used +in registry access. A default name is set by +wxWindows. + +\wxheading{See also} + +\helpref{wxApp::GetVendorName}{wxappgetvendorname} + +\membersection{wxApp::GetStdIcon}\label{wxappgetstdicon} -Sets the `top' window. You should normally call this from within \helpref{wxApp::OnInit}{wxapponinit} to -let wxWindows know which is the main window. +\func{virtual wxIcon}{GetStdIcon}{\param{int }{which}} const + +Returns the icons used by wxWindows internally, e.g. the ones used for +message boxes. This function is used internally and +can be overridden by the user to change the default icons. \wxheading{Parameters} -\docparam{window}{The new top window.} +\docparam{which}{One of the wxICON\_XXX specifies which icon to return.} -\wxheading{See also} +See \helpref{wxMessageBox}{wxmessagebox} for a list of icon identifiers. -\helpref{wxApp::GetTopWindow}{wxappgettopwindow}, \helpref{wxApp::OnInit}{wxapponinit} +\membersection{wxApp::SetUseBestVisual}\label{wxappsetusebestvisual} + +\func{void}{SetUseBestVisual}{\param{bool}{ flag}} + +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 +appications are supposed to run in TrueColour mode. + +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.}