# wxApp Class Reference
[Application and Process Management]

`#include </home/work/projects/wx/2.9/wx/interface/wx/app.h>`

Inheritance diagram for wxApp:
[legend]

## 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

## Mac-specific functions

virtual void | MacNewFile ()
| Called in response of an "open-application" Apple event.
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.
static long | GetMacAboutMenuItemId ()
| Called in response of an "open-application" Apple event.
static long | GetMacPreferencesMenuItemId ()
| Called in response of an "open-application" Apple event.
static long | GetMacExitMenuItemId ()
| Called in response of an "open-application" Apple event.
static wxString | GetMacHelpMenuTitleName ()
| Called in response of an "open-application" Apple event.
static void | SetMacAboutMenuItemId (long val)
| Called in response of an "open-application" Apple event.
static void | SetMacPreferencesMenuItemId (long val)
| Called in response of an "open-application" Apple event.
static void | SetMacExitMenuItemId (long val)
| Called in response of an "open-application" Apple event.
static void | SetMacHelpMenuTitleName (const wxString &val)
| Called in response of an "open-application" Apple event.

## 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.
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.

List of all members.

## 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 wxMGL or 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.

static long wxApp::GetMacAboutMenuItemId | ( |  | ) | `[static]`

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

Override this to create a new document in your app.

Availability: only available for the wxOSX port.

static long wxApp::GetMacExitMenuItemId | ( |  | ) | `[static]`

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

Override this to create a new document in your app.

Availability: only available for the wxOSX port.

static wxString wxApp::GetMacHelpMenuTitleName | ( |  | ) | `[static]`

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

Override this to create a new document in your app.

Availability: only available for the wxOSX port.

static long wxApp::GetMacPreferencesMenuItemId | ( |  | ) | `[static]`

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

Override this to create a new document in your app.

Availability: only available for the wxOSX port.

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.

Availability: only available for the wxOSX port.

virtual void wxApp::MacOpenFile | ( | const wxString & | fileName | ) | `[virtual]`

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

You need to override this method in order to open a document file after the user double clicked on it or if the document file was dropped on either the running application or the application icon in Finder.

Availability: only available for the wxOSX port.

virtual void wxApp::MacOpenURL | ( | const wxString & | url | ) | `[virtual]`

Called in response of a "get-url" Apple event.

Availability: only available for the wxOSX port.

virtual void wxApp::MacPrintFile | ( | const wxString & | fileName | ) | `[virtual]`

Called in response of a "print-document" Apple event.

Availability: only available for the wxOSX port.

virtual void wxApp::MacReopenApp | ( |  | ) | `[virtual]`

Called in response of a "reopen-application" Apple event.

Availability: only available for the wxOSX port.

bool wxApp::ProcessMessage | ( | 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 wxWidgets with another class library with its own message loop, you should make sure that this function is called to allow wxWidgets to receive messages. For example, to allow co-existence with the Microsoft Foundation Classes, override the PreTranslateMessage function:

            // Provide wxWidgets message loop compatibility
            BOOL CTheApp::PreTranslateMessage(MSG *msg)
            {
                if (wxTheApp && wxTheApp->ProcessMessage((WXMSW *)msg))
                    return true;
                else
                    return CWinApp::PreTranslateMessage(msg);
            }

Availability: only available for the wxMSW port.

virtual bool wxApp::SafeYield | ( | wxWindow * | win,
|  | bool | onlyIfNeeded |
| ) |  |  | `[virtual]`

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.

If win is not NULL, this window will remain enabled, allowing the implementation of some limited user interaction. Returns the result of the call to wxAppConsole::Yield.

See also:
  wxSafeYield

virtual bool wxApp::SafeYieldFor | ( | wxWindow * | win,
|  | long | eventsToProcess |
| ) |  |  | `[virtual]`

Works like SafeYield() with onlyIfNeeded == true except that it allows the caller to specify a mask of events to be processed.

See wxAppConsole::YieldFor for more info.

virtual bool wxApp::SetDisplayMode | ( | const wxVideoMode & | info | ) | `[virtual]`

Set display mode to use.

This is only used in framebuffer wxWidgets ports (such as wxMGL or wxDFB).

void wxApp::SetExitOnFrameDelete | ( | bool | flag | ) |

Allows the programmer to specify whether the application will exit when the top-level frame is deleted.

Parameters:

  | flag | If true (the default), the application will exit when the top-level frame is deleted. If false, the application will continue to run.

See also:
  GetExitOnFrameDelete(), Application Shutdown

static void wxApp::SetMacAboutMenuItemId | ( | long | val | ) | `[static]`

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

Override this to create a new document in your app.

Availability: only available for the wxOSX port.

static void wxApp::SetMacExitMenuItemId | ( | long | val | ) | `[static]`

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

Override this to create a new document in your app.

Availability: only available for the wxOSX port.

static void wxApp::SetMacHelpMenuTitleName | ( | const wxString & | val | ) | `[static]`

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

Override this to create a new document in your app.

Availability: only available for the wxOSX port.

static void wxApp::SetMacPreferencesMenuItemId | ( | long | val | ) | `[static]`

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

Override this to create a new document in your app.

Availability: only available for the wxOSX port.

virtual bool wxApp::SetNativeTheme | ( | const wxString & | theme | ) | `[virtual]`

Allows runtime switching of the UI environment theme.

Currently implemented for wxGTK2-only. Return true if theme was successfully changed.

Parameters:

  | theme | The name of the new theme or an absolute path to a gtkrc-theme-file

void wxApp::SetTopWindow | ( | wxWindow * | window | ) |

Sets the 'top' window.

You can call this from within OnInit() to 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, wxWidgets just uses the first frame or dialog (or better, any wxTopLevelWindow) in its top-level window list, when it needs to use the top window. If you previously called SetTopWindow() and now you need to restore this automatic behaviour you can call

     wxApp::SetTopWindow(NULL)

.

Parameters:

  | window | The new top window.

See also:
  GetTopWindow(), OnInit()

void wxApp::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.

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.

Note that this function has to be called in the constructor of the wxApp instance and won't have any effect when called later on. This function currently only has effect under GTK.

Parameters:

  | flag | If true, the app will use the best visual.
  | forceTrueColour | If true then the application will try to force using a TrueColour visual and abort the app if none is found.

|  | [ top ]