Detailed Description

The wxApp class represents the application itself when wxUSE_GUI=1.

In addition to the features provided by wxAppConsole it keeps track of the top window (see SetTopWindow()) and adds support for video modes (see SetVideoMode()).

In general, application-wide settings for GUI-only apps are accessible from wxApp (or from wxSystemSettings or wxSystemOptions classes).

Events emitted by this class

Event macros for events emitted by this class:

EVT_QUERY_END_SESSION(func):
Process a query end session event, supplying the member function. See wxCloseEvent.
EVT_END_SESSION(func):
Process an end session event, supplying the member function. See wxCloseEvent.
EVT_ACTIVATE_APP(func):
Process a wxEVT_ACTIVATE_APP event. See wxActivateEvent.
EVT_HIBERNATE(func):
Process a hibernate event. See wxActivateEvent.
EVT_DIALUP_CONNECTED(func):
A connection with the network was established. See wxDialUpEvent.
EVT_DIALUP_DISCONNECTED(func):
The connection with the network was lost. See wxDialUpEvent.
EVT_IDLE(func):
Process a wxEVT_IDLE event. See wxIdleEvent.

Library: wxBase

Category: Application and Process Management

See Also: wxApp Overview, wxAppTraits, wxEventLoopBase, wxSystemSettings

Public Member Functions
	wxApp ()
	Constructor.

virtual	~wxApp ()
	Destructor.

virtual wxVideoMode	GetDisplayMode () const
	Get display mode that is used use.

bool	GetExitOnFrameDelete () const
	Returns true if the application will exit when the top-level frame is deleted.

virtual wxLayoutDirection	GetLayoutDirection () const
	Return the layout direction for the current locale or `wxLayout_Default` if it's unknown.

bool	GetUseBestVisual () const
	Returns true if the application will use the best visual on systems that support different visuals, false otherwise.

virtual wxWindow *	GetTopWindow () const
	Returns a pointer to the top window.

virtual bool	IsActive () const
	Returns true if the application is active, i.e. if one of its windows is currently in the foreground.

virtual bool	SafeYield (wxWindow *win, bool onlyIfNeeded)
	This function is similar to wxYield(), except that it disables the user input to all program windows before calling wxAppConsole::Yield and re-enables it again afterwards.

virtual bool	SafeYieldFor (wxWindow *win, long eventsToProcess)
	Works like SafeYield() with onlyIfNeeded == true except that it allows the caller to specify a mask of events to be processed.

bool	ProcessMessage (WXMSG *msg)
	Windows-only function for processing a message.

virtual bool	SetDisplayMode (const wxVideoMode &info)
	Set display mode to use.

void	SetExitOnFrameDelete (bool flag)
	Allows the programmer to specify whether the application will exit when the top-level frame is deleted.

virtual bool	SetNativeTheme (const wxString &theme)
	Allows runtime switching of the UI environment theme.

void	SetTopWindow (wxWindow *window)
	Sets the 'top' window.

void	SetUseBestVisual (bool flag, 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.

Mac-specific functions
virtual void	MacNewFile ()
	Called in response of an "open-application" Apple event.

virtual void	MacOpenFiles (const wxArrayString &fileNames)
	Called in response of an openFiles message with Cocoa, or an "open-document" Apple event with Carbon.

virtual void	MacOpenFile (const wxString &fileName)
	Called in response of an "open-document" Apple event.

virtual void	MacOpenURL (const wxString &url)
	Called in response of a "get-url" Apple event.

virtual void	MacPrintFile (const wxString &fileName)
	Called in response of a "print-document" Apple event.

virtual void	MacReopenApp ()
	Called in response of a "reopen-application" Apple event.

virtual bool	OSXIsGUIApplication ()
	May be overridden to indicate that the application is not a foreground GUI application under OS X.

Public Member Functions inherited from wxAppConsole
virtual	~wxAppConsole ()
	Destructor.

bool	Yield (bool onlyIfNeeded=false)

void	SetCLocale ()
	Sets the C locale to the default locale for the current environment.

virtual int	MainLoop ()
	Called by wxWidgets on creation of the application.

virtual void	ExitMainLoop ()
	Call this to explicitly exit the main message (event) loop.

virtual int	FilterEvent (wxEvent &event)
	Overridden wxEventFilter method.

wxEventLoopBase *	GetMainLoop () const
	Returns the main event loop instance, i.e. the event loop which is started by OnRun() and which dispatches all events sent from the native toolkit to the application (except when new event loops are temporarily set-up).

virtual void	HandleEvent (wxEvtHandler *handler, wxEventFunction func, wxEvent &event) const
	This function simply invokes the given method func of the specified event handler handler with the event as parameter.

virtual bool	UsesEventLoop () const
	Returns true if the application is using an event loop.

virtual void	ProcessPendingEvents ()
	Process all pending events; it is necessary to call this function to process events posted with wxEvtHandler::QueueEvent or wxEvtHandler::AddPendingEvent.

void	DeletePendingEvents ()
	Deletes the pending events of all wxEvtHandlers of this application.

bool	HasPendingEvents () const
	Returns true if there are pending events on the internal pending event list.

void	SuspendProcessingOfPendingEvents ()
	Temporary suspends processing of the pending events.

void	ResumeProcessingOfPendingEvents ()
	Resume processing of the pending events previously stopped because of a call to SuspendProcessingOfPendingEvents().

void	ScheduleForDestruction (wxObject *object)
	Delayed objects destruction.

bool	IsScheduledForDestruction (wxObject *object) const
	Check if the object had been scheduled for destruction with ScheduleForDestruction().

virtual void	OnAssertFailure (const wxChar file, int line, const wxChar func, const wxChar cond, const wxChar msg)
	This function is called when an assert failure occurs, i.e. the condition specified in wxASSERT() macro evaluated to false.

virtual bool	OnCmdLineError (wxCmdLineParser &parser)
	Called when command line parsing fails (i.e. an incorrect command line option was specified by the user).

virtual bool	OnCmdLineHelp (wxCmdLineParser &parser)
	Called when the help option (`–help`) was specified on the command line.

virtual bool	OnCmdLineParsed (wxCmdLineParser &parser)
	Called after the command line had been successfully parsed.

virtual void	OnEventLoopEnter (wxEventLoopBase *loop)
	Called by wxEventLoopBase::SetActive(): you can override this function and put here the code which needs an active event loop.

virtual void	OnEventLoopExit (wxEventLoopBase *loop)
	Called by wxEventLoopBase::OnExit() for each event loop which is exited.

virtual bool	OnExceptionInMainLoop ()
	This function is called if an unhandled exception occurs inside the main application event loop.

virtual int	OnExit ()
	Override this member function for any processing which needs to be done as the application is about to exit.

virtual void	OnFatalException ()
	This function may be called if something fatal happens: an unhandled exception under Win32 or a fatal signal under Unix, for example.

virtual bool	OnInit ()
	This must be provided by the application, and will usually create the application's main window, optionally calling SetTopWindow().

virtual void	OnInitCmdLine (wxCmdLineParser &parser)
	Called from OnInit() and may be used to initialize the parser with the command line options for this application.

virtual int	OnRun ()
	This virtual function is where the execution of a program written in wxWidgets starts.

virtual void	OnUnhandledException ()
	This function is called when an unhandled C++ exception occurs in user code called by wxWidgets.

wxString	GetAppDisplayName () const
	Returns the user-readable application name.

wxString	GetAppName () const
	Returns the application name.

wxString	GetClassName () const
	Gets the class name of the application.

wxAppTraits *	GetTraits ()
	Returns a pointer to the wxAppTraits object for the application.

const wxString &	GetVendorDisplayName () const
	Returns the user-readable vendor name.

const wxString &	GetVendorName () const
	Returns the application's vendor name.

void	SetAppDisplayName (const wxString &name)
	Set the application name to be used in the user-visible places such as window titles.

void	SetAppName (const wxString &name)
	Sets the name of the application.

void	SetClassName (const wxString &name)
	Sets the class name of the application.

void	SetVendorDisplayName (const wxString &name)
	Set the vendor name to be used in the user-visible places.

void	SetVendorName (const wxString &name)
	Sets the name of application's vendor.

Public Member Functions inherited from wxEvtHandler
	wxEvtHandler ()
	Constructor.

virtual	~wxEvtHandler ()
	Destructor.

virtual void	QueueEvent (wxEvent *event)
	Queue event for a later processing.

virtual void	AddPendingEvent (const wxEvent &event)
	Post an event to be processed later.

template<typename T , typename T1 , ... >
void	CallAfter (void(T::*method)(T1,...), T1 x1,...)
	Asynchronously call the given method.

template<typename T >
void	CallAfter (const T &functor)
	Asynchronously call the given functor.

virtual bool	ProcessEvent (wxEvent &event)
	Processes an event, searching event tables and calling zero or more suitable event handler function(s).

bool	ProcessEventLocally (wxEvent &event)
	Try to process the event in this handler and all those chained to it.

bool	SafelyProcessEvent (wxEvent &event)
	Processes an event by calling ProcessEvent() and handles any exceptions that occur in the process.

void	ProcessPendingEvents ()
	Processes the pending events previously queued using QueueEvent() or AddPendingEvent(); you must call this function only if you are sure there are pending events for this handler, otherwise a `wxCHECK` will fail.

void	DeletePendingEvents ()
	Deletes all events queued on this event handler using QueueEvent() or AddPendingEvent().

virtual bool	SearchEventTable (wxEventTable &table, wxEvent &event)
	Searches the event table, executing an event handler function if an appropriate one is found.

void	Connect (int id, int lastId, wxEventType eventType, wxObjectEventFunction function, wxObject userData=NULL, wxEvtHandler eventSink=NULL)
	Connects the given function dynamically with the event handler, id and event type.

void	Connect (int id, wxEventType eventType, wxObjectEventFunction function, wxObject userData=NULL, wxEvtHandler eventSink=NULL)
	See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject, wxEvtHandler) overload for more info.

void	Connect (wxEventType eventType, wxObjectEventFunction function, wxObject userData=NULL, wxEvtHandler eventSink=NULL)
	See the Connect(int, int, wxEventType, wxObjectEventFunction, wxObject, wxEvtHandler) overload for more info.

bool	Disconnect (wxEventType eventType, wxObjectEventFunction function, wxObject userData=NULL, wxEvtHandler eventSink=NULL)
	Disconnects the given function dynamically from the event handler, using the specified parameters as search criteria and returning true if a matching function has been found and removed.

bool	Disconnect (int id=wxID_ANY, wxEventType eventType=wxEVT_NULL, wxObjectEventFunction function=NULL, wxObject userData=NULL, wxEvtHandler eventSink=NULL)
	See the Disconnect(wxEventType, wxObjectEventFunction, wxObject, wxEvtHandler) overload for more info.

bool	Disconnect (int id, int lastId, wxEventType eventType, wxObjectEventFunction function=NULL, wxObject userData=NULL, wxEvtHandler eventSink=NULL)
	See the Disconnect(wxEventType, wxObjectEventFunction, wxObject, wxEvtHandler) overload for more info.

template<typename EventTag , typename Functor >
void	Bind (const EventTag &eventType, Functor functor, int id=wxID_ANY, int lastId=wxID_ANY, wxObject *userData=NULL)
	Binds the given function, functor or method dynamically with the event.

template<typename EventTag , typename Class , typename EventArg , typename EventHandler >
void	Bind (const EventTag &eventType, void(Class::method)(EventArg &), EventHandler handler, int id=wxID_ANY, int lastId=wxID_ANY, wxObject *userData=NULL)
	See the Bind<>(const EventTag&, Functor, int, int, wxObject*) overload for more info.

template<typename EventTag , typename Functor >
bool	Unbind (const EventTag &eventType, Functor functor, int id=wxID_ANY, int lastId=wxID_ANY, wxObject *userData=NULL)
	Unbinds the given function, functor or method dynamically from the event handler, using the specified parameters as search criteria and returning true if a matching function has been found and removed.

template<typename EventTag , typename Class , typename EventArg , typename EventHandler >
bool	Unbind (const EventTag &eventType, void(Class::method)(EventArg &), EventHandler handler, int id=wxID_ANY, int lastId=wxID_ANY, wxObject *userData=NULL)
	See the Unbind<>(const EventTag&, Functor, int, int, wxObject*) overload for more info.

void *	GetClientData () const
	Returns user-supplied client data.

wxClientData *	GetClientObject () const
	Returns a pointer to the user-supplied client data object.

void	SetClientData (void *data)
	Sets user-supplied client data.

void	SetClientObject (wxClientData *data)
	Set the client data object.

bool	GetEvtHandlerEnabled () const
	Returns true if the event handler is enabled, false otherwise.

wxEvtHandler *	GetNextHandler () const
	Returns the pointer to the next handler in the chain.

wxEvtHandler *	GetPreviousHandler () const
	Returns the pointer to the previous handler in the chain.

void	SetEvtHandlerEnabled (bool enabled)
	Enables or disables the event handler.

virtual void	SetNextHandler (wxEvtHandler *handler)
	Sets the pointer to the next handler.

virtual void	SetPreviousHandler (wxEvtHandler *handler)
	Sets the pointer to the previous handler.

void	Unlink ()
	Unlinks this event handler from the chain it's part of (if any); then links the "previous" event handler to the "next" one (so that the chain won't be interrupted).

bool	IsUnlinked () const
	Returns true if the next and the previous handler pointers of this event handler instance are NULL.

Public Member Functions inherited from wxObject
	wxObject ()
	Default ctor; initializes to NULL the internal reference data.

	wxObject (const wxObject &other)
	Copy ctor.

virtual	~wxObject ()
	Destructor.

virtual wxClassInfo *	GetClassInfo () const
	This virtual function is redefined for every class that requires run-time type information, when using the wxDECLARE_CLASS macro (or similar).

wxObjectRefData *	GetRefData () const
	Returns the wxObject::m_refData pointer, i.e. the data referenced by this object.

bool	IsKindOf (const wxClassInfo *info) const
	Determines whether this class is a subclass of (or the same class as) the given class.

bool	IsSameAs (const wxObject &obj) const
	Returns true if this object has the same data pointer as obj.

void	Ref (const wxObject &clone)
	Makes this object refer to the data in clone.

void	SetRefData (wxObjectRefData *data)
	Sets the wxObject::m_refData pointer.

void	UnRef ()
	Decrements the reference count in the associated data, and if it is zero, deletes the data.

void	UnShare ()
	This is the same of AllocExclusive() but this method is public.

void	operator delete (void *buf)
	The delete operator is defined for debugging versions of the library only, when the identifier `WXDEBUG` is defined.

void *	operator new (size_t size, const wxString &filename=NULL, int lineNum=0)
	The new operator is defined for debugging versions of the library only, when the identifier `WXDEBUG` is defined.

Public Member Functions inherited from wxEventFilter
	wxEventFilter ()
	Default constructor.

virtual	~wxEventFilter ()
	Destructor.

Additional Inherited Members
Public Types inherited from wxEventFilter
enum	{ Event_Skip = -1, Event_Ignore = 0, Event_Processed = 1 }
	Possible return values for FilterEvent(). More...

Static Public Member Functions inherited from wxAppConsole
static void	SetInstance (wxAppConsole *app)
	Allows external code to modify global wxTheApp, but you should really know what you're doing if you call it.

static wxAppConsole *	GetInstance ()
	Returns the one and only global application object.

static bool	IsMainLoopRunning ()
	Returns true if the main event loop is currently running, i.e. if the application is inside OnRun().

Public Attributes inherited from wxAppConsole
int	argc
	Number of command line arguments (after environment-specific processing).

wxChar **	argv
	Command line arguments (after environment-specific processing).

Protected Member Functions inherited from wxAppConsole
virtual wxAppTraits *	CreateTraits ()
	Creates the wxAppTraits object when GetTraits() needs it for the first time.

Protected Attributes inherited from wxObject
wxObjectRefData *	m_refData
	Pointer to an object which is the object's reference-counted data.

Constructor & Destructor Documentation

wxApp::wxApp ( )

Constructor.

Called implicitly with a definition of a wxApp object.

virtual wxApp::~wxApp ( )

virtual

Destructor.

Will be called implicitly on program exit if the wxApp object is created on the stack.

Member Function Documentation

virtual wxVideoMode wxApp::GetDisplayMode ( ) const

virtual

Get display mode that is used use.

This is only used in framebuffer wxWidgets ports such as wxDFB.

bool wxApp::GetExitOnFrameDelete ( ) const

Returns true if the application will exit when the top-level frame is deleted.

See Also: SetExitOnFrameDelete()

virtual wxLayoutDirection wxApp::GetLayoutDirection ( ) const

virtual

Return the layout direction for the current locale or wxLayout_Default if it's unknown.

virtual wxWindow* wxApp::GetTopWindow ( ) const

virtual

Returns a pointer to the top window.

Remarks: If the top window hasn't been set using SetTopWindow(), this function will find the first top-level window (frame or dialog or instance of wxTopLevelWindow) from the internal top level window list and return that.

See Also: SetTopWindow()

bool wxApp::GetUseBestVisual ( ) const

Returns true if the application will use the best visual on systems that support different visuals, false otherwise.

See Also: SetUseBestVisual()

virtual bool wxApp::IsActive ( ) const

virtual

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 wxTopLevelWindow::RequestUserAttention to do it.

virtual void wxApp::MacNewFile ( )

virtual

Called in response of an "open-application" Apple event.

Override this to create a new document in your app.