ebea0891d0
added it for all ports, though. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@2953 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
456 lines
14 KiB
TeX
456 lines
14 KiB
TeX
\section{\class{wxApp}}\label{wxapp}
|
|
|
|
The {\bf wxApp} class represents the application itself. It is used
|
|
to:
|
|
|
|
\begin{itemize}\itemsep=0pt
|
|
\item set and get application-wide properties;
|
|
\item implement the windowing system message or event loop;
|
|
\item initiate application processing via \helpref{wxApp::OnInit}{wxapponinit};
|
|
\item allow default processing of events not handled by other
|
|
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.
|
|
|
|
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.
|
|
|
|
\wxheading{Derived from}
|
|
|
|
\helpref{wxEvtHandler}{wxevthandler}\\
|
|
\helpref{wxObject}{wxobject}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/app.h>
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxApp overview}{wxappoverview}
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
\membersection{wxApp::wxApp}
|
|
|
|
\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.
|
|
|
|
\membersection{wxApp::\destruct{wxApp}}
|
|
|
|
\func{void}{\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}
|
|
|
|
Command line arguments (after environment-specific processing).
|
|
|
|
\membersection{wxApp::CreateLogTarget}\label{wxappcreatelogtarget}
|
|
|
|
\func{virtual wxLog*}{CreateLogTarget}{\void}
|
|
|
|
Creates a wxLog class for the application to use for logging errors. The default
|
|
implementation returns a new wxLogGui class.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxLog}{wxlog}
|
|
|
|
\membersection{wxApp::Dispatch}\label{wxappdispatch}
|
|
|
|
\func{void}{Dispatch}{\void}
|
|
|
|
Dispatches the next event in the windowing system event queue.
|
|
|
|
This can be used for programming event loops, e.g.
|
|
|
|
\begin{verbatim}
|
|
while (app.Pending())
|
|
Dispatch();
|
|
\end{verbatim}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxApp::Pending}{wxapppending}
|
|
|
|
\membersection{wxApp::GetAppName}\label{wxappgetappname}
|
|
|
|
\constfunc{wxString}{GetAppName}{\void}
|
|
|
|
Returns the application name.
|
|
|
|
\wxheading{Remarks}
|
|
|
|
wxWindows 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}
|
|
|
|
Gets the class name of the application. The class name may be used in a platform specific
|
|
manner to refer to the application.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxApp::SetClassName}{wxappsetclassname}
|
|
|
|
\membersection{wxApp::GetExitOnDelete}\label{wxappgetexitondelete}
|
|
|
|
\constfunc{bool}{GetExitOnDelete}{\void}
|
|
|
|
Returns TRUE if the application will exit when the top-level window is deleted, FALSE
|
|
otherwise.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxApp::SetExitOnDelete}{wxappsetexitondelete}
|
|
|
|
\membersection{wxApp::GetTopWindow}\label{wxappgettopwindow}
|
|
|
|
\constfunc{wxWindow *}{GetTopWindow}{\void}
|
|
|
|
Returns a pointer to the top window.
|
|
|
|
\wxheading{Remarks}
|
|
|
|
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.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxApp::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::Initialized}\label{wxappinitialized}
|
|
|
|
\func{bool}{Initialized}{\void}
|
|
|
|
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}
|
|
|
|
Called by wxWindows 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}
|
|
|
|
\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::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.
|
|
|
|
\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::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::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.
|
|
|
|
\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, optionally calling \helpref{wxApp::SetTopWindow}{wxappsettopwindow}.
|
|
|
|
Return TRUE to continue processing, FALSE to exit the application.
|
|
|
|
\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{wxWindow::OnCloseWindow}{wxwindowonclosewindow},\rtfsp
|
|
\helpref{wxCloseEvent}{wxcloseevent},\rtfsp
|
|
\helpref{wxApp::OnEndSession}{wxapponendsession}
|
|
|
|
\membersection{wxApp::ProcessMessage}\label{wxappprocessmessage}
|
|
|
|
\func{bool}{ProcessMessage}{\param{MSG *}{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
|
|
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
|
|
the PreTranslateMessage function:
|
|
|
|
\begin{verbatim}
|
|
// Provide wxWindows message loop compatibility
|
|
BOOL CTheApp::PreTranslateMessage(MSG *msg)
|
|
{
|
|
if (wxTheApp && wxTheApp->ProcessMessage(msg))
|
|
return TRUE;
|
|
else
|
|
return CWinApp::PreTranslateMessage(msg);
|
|
}
|
|
\end{verbatim}
|
|
|
|
\membersection{wxApp::Pending}\label{wxapppending}
|
|
|
|
\func{bool}{Pending}{\void}
|
|
|
|
Returns TRUE if unprocessed events are in the window system event queue
|
|
(MS Windows and Motif).
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxApp::Dispatch}{wxappdispatch}
|
|
|
|
\membersection{wxApp::SendIdleEvents}\label{wxappsendidleevents}
|
|
|
|
\func{bool}{SendIdleEvents}{\void}
|
|
|
|
Sends idle events to all top-level windows.
|
|
|
|
\func{bool}{SendIdleEvents}{\param{wxWindow*}{ win}}
|
|
|
|
Sends idle events to a window and its children.
|
|
|
|
\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.
|
|
|
|
\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}}
|
|
|
|
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::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}}
|
|
|
|
Sets the class name of the application. This may be used in a platform specific
|
|
manner to refer to the application.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxApp::GetClassName}{wxappgetclassname}
|
|
|
|
\membersection{wxApp::SetExitOnDelete}\label{wxappsetexitondelete}
|
|
|
|
\func{void}{SetExitOnDelete}{\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.}
|
|
|
|
\wxheading{Remarks}
|
|
|
|
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
|
|
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.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{window}{The new top window.}
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxApp::GetTopWindow}{wxappgettopwindow}, \helpref{wxApp::OnInit}{wxapponinit}
|
|
|
|
\membersection{wxApp::GetStdIcon}\label{wxappgetstdicon}
|
|
|
|
\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{which}{One of the wxICON_XXX defines and chooses which icon to return.}
|
|
|