wxApp Class Reference | wxWidgets

wxApp Class Reference | wxWidgets
Version: 3.3.3
Public Types
Public Member Functions
Static Public Member Functions
List of all members
wxApp Class Reference
Class List by Category
Application and Process Management
#include
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
SetDisplayMode()
).
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 Types
enum class
Appearance
System
Light
Dark
Possible parameters for
SetAppearance()
More...
enum class
AppearanceResult
Failure
Ok
CannotChange
Possible values returned by
SetAppearance()
More...
Public Types inherited from
wxEventFilter
enum
Event_Skip
= -1
Event_Ignore
= 0
Event_Processed
= 1
Possible return values for
FilterEvent()
More...
Public Member Functions
wxApp
()
Constructor.
More...
virtual
~wxApp
()
Destructor.
More...
virtual
wxVideoMode
GetDisplayMode
() const
Get display mode that is used use.
More...
bool
GetExitOnFrameDelete
() const
Returns
true
if the application will exit when the top-level frame is deleted.
More...
virtual
wxLayoutDirection
GetLayoutDirection
() const
Return the layout direction for the current locale or
wxLayout_Default
if it's unknown.
More...
bool
GetUseBestVisual
() const
Returns
true
if the application will use the best visual on systems that support different visuals,
false
otherwise.
More...
virtual
wxWindow
GetTopWindow
() const
Returns a pointer to the top window.
More...
virtual bool
IsActive
() const
Returns
true
if the application is active, i.e. if one of its windows is currently in the foreground.
More...
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.
More...
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.
More...
bool
ProcessMessage
(WXMSG *msg)
Windows-only function for processing a message.
More...
AppearanceResult
SetAppearance
Appearance
appearance)
Request using either system default or explicitly light or dark theme for the application.
More...
virtual bool
SetDisplayMode
(const
wxVideoMode
&info)
Set display mode to use.
More...
void
SetExitOnFrameDelete
(bool flag)
Allows the programmer to specify whether the application will exit when the top-level frame is deleted.
More...
virtual bool
SetNativeTheme
(const
wxString
&theme)
Allows runtime switching of the UI environment theme.
More...
void
SetTopWindow
wxWindow
*window)
Sets the 'top' window.
More...
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.
More...
Mac-specific functions
virtual void
MacNewFile
()
Called in response of an "open-application" Apple event.
More...
virtual void
MacOpenFiles
(const
wxArrayString
&fileNames)
Called in response of an openFiles message.
More...
virtual void
MacOpenFile
(const
wxString
&fileName)
Called in response of an "open-document" Apple event.
More...
virtual void
MacOpenURL
(const
wxString
&url)
Called in response of a "get-url" Apple event.
More...
virtual void
MacPrintFile
(const
wxString
&fileName)
Called in response of a "print-document" Apple event.
More...
virtual void
MacReopenApp
()
Called in response of a "reopen-application" Apple event.
More...
virtual bool
OSXIsGUIApplication
()
May be overridden to indicate that the application is not a foreground GUI application under macOS.
More...
void
OSXEnableAutomaticTabbing
(bool enable)
Enable the automatic tabbing features of macOS.
More...
MSW-specific functions
bool
MSWEnableDarkMode
(int flags=0,
wxDarkModeSettings
*settings=nullptr)
Enable experimental dark mode support for MSW applications.
More...
Public Member Functions inherited from
wxAppConsole
virtual
~wxAppConsole
()
Destructor.
More...
bool
Yield
(bool onlyIfNeeded=false)
Yields control to pending messages in the event loop.
More...
void
SetCLocale
()
Sets the C locale to the default locale for the current environment.
More...
virtual void
SetErrorExitCode
(int code)
Sets the error code to use in case of exit on error.
More...
virtual int
MainLoop
()
Called by wxWidgets on creation of the application.
More...
virtual void
ExitMainLoop
()
Call this to explicitly exit the main message (event) loop.
More...
virtual int
FilterEvent
wxEvent
&event)
Overridden
wxEventFilter
method.
More...
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).
More...
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.
More...
virtual bool
UsesEventLoop
() const
Returns
true
if the application is using an event loop.
More...
virtual void
ProcessPendingEvents
()
Process all pending events; it is necessary to call this function to process events posted with
wxEvtHandler::QueueEvent
or
wxEvtHandler::AddPendingEvent
More...
void
DeletePendingEvents
()
Deletes the pending events of all wxEvtHandlers of this application.
More...
bool
HasPendingEvents
() const
Returns
true
if there are pending events on the internal pending event list.
More...
void
SuspendProcessingOfPendingEvents
()
Temporary suspends processing of the pending events.
More...
void
ResumeProcessingOfPendingEvents
()
Resume processing of the pending events previously stopped because of a call to
SuspendProcessingOfPendingEvents()
More...
void
ScheduleForDestruction
wxObject
*object)
Delayed objects destruction.
More...
bool
IsScheduledForDestruction
wxObject
*object) const
Check if the object had been scheduled for destruction with
ScheduleForDestruction()
More...
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
More...
virtual bool
OnCmdLineError
wxCmdLineParser
&parser)
Called when command line parsing fails (i.e. an incorrect command line option was specified by the user).
More...
virtual bool
OnCmdLineHelp
wxCmdLineParser
&parser)
Called when the help option (
--help
) was specified on the command line.
More...
virtual bool
OnCmdLineParsed
wxCmdLineParser
&parser)
Called after the command line had been successfully parsed.
More...
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.
More...
virtual void
OnEventLoopExit
wxEventLoopBase
*loop)
Called by
wxEventLoopBase::OnExit()
for each event loop which is exited.
More...
virtual int
OnExit
()
Override this member function for any processing which needs to be done as the application is about to exit.
More...
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.
More...
virtual bool
OnInit
()
This must be provided by the application, and will usually create the application's main window, optionally calling SetTopWindow().
More...
virtual void
OnInitCmdLine
wxCmdLineParser
&parser)
Called from
OnInit()
and may be used to initialize the parser with the command line options for this application.
More...
virtual int
OnRun
()
Virtual function executing the application's main event loop.
More...
wxString
GetAppDisplayName
() const
Returns the user-readable application name.
More...
wxString
GetAppName
() const
Returns the application name.
More...
wxString
GetClassName
() const
Gets the class name of the application.
More...
wxAppTraits
GetTraits
()
Returns a pointer to the
wxAppTraits
object for the application.
More...
const
wxString
GetVendorDisplayName
() const
Returns the user-readable vendor name.
More...
const
wxString
GetVendorName
() const
Returns the application's vendor name.
More...
void
SetAppDisplayName
(const
wxString
&name)
Set the application name to be used in the user-visible places such as window titles.
More...
void
SetAppName
(const
wxString
&name)
Sets the name of the application.
More...
void
SetClassName
(const
wxString
&name)
Sets the class name of the application.
More...
void
SetVendorDisplayName
(const
wxString
&name)
Set the vendor name to be used in the user-visible places.
More...
void
SetVendorName
(const
wxString
&name)
Sets the name of application's vendor.
More...
virtual bool
OnExceptionInMainLoop
()
This function is called if an unhandled exception occurs inside the main application event loop.
More...
virtual void
OnUnhandledException
()
This function is called when an unhandled C++ exception occurs in user code called by wxWidgets.
More...
virtual bool
StoreCurrentException
()
Method to store exceptions not handled by
OnExceptionInMainLoop()
More...
virtual void
RethrowStoredException
()
Method to rethrow exceptions stored by
StoreCurrentException()
More...
Public Member Functions inherited from
wxEvtHandler
wxEvtHandler
()
Constructor.
More...
virtual
~wxEvtHandler
()
Destructor.
More...
virtual void
QueueEvent
wxEvent
*event)
Queue event for a later processing.
More...
virtual void
AddPendingEvent
(const
wxEvent
&event)
Post an event to be processed later.
More...
template
void
CallAfter
(void(T::*method)(T1,...), T1 x1,...)
Asynchronously call the given method.
More...
template
void
CallAfter
(const T &functor)
Asynchronously call the given functor.
More...
virtual bool
ProcessEvent
wxEvent
&event)
Processes an event, searching event tables and calling zero or more suitable event handler function(s).
More...
bool
ProcessEventLocally
wxEvent
&event)
Try to process the event in this handler and all those chained to it.
More...
bool
SafelyProcessEvent
wxEvent
&event)
Processes an event by calling
ProcessEvent()
and handles any exceptions that occur in the process.
More...
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.
More...
void
DeletePendingEvents
()
Deletes all events queued on this event handler using
QueueEvent()
or
AddPendingEvent()
More...
void
Connect
(int id, int lastId,
wxEventType
eventType, wxObjectEventFunction function,
wxObject
*userData=nullptr,
wxEvtHandler
*eventSink=nullptr)
Connects the given function dynamically with the event handler, id and event type.
More...
void
Connect
(int id,
wxEventType
eventType, wxObjectEventFunction function,
wxObject
*userData=nullptr,
wxEvtHandler
*eventSink=nullptr)
See the
Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
overload for more info.
More...
void
Connect
wxEventType
eventType, wxObjectEventFunction function,
wxObject
*userData=nullptr,
wxEvtHandler
*eventSink=nullptr)
See the
Connect(int, int, wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
overload for more info.
More...
bool
Disconnect
wxEventType
eventType, wxObjectEventFunction function,
wxObject
*userData=nullptr,
wxEvtHandler
*eventSink=nullptr)
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.
More...
bool
Disconnect
(int id=
wxID_ANY
wxEventType
eventType=
wxEVT_NULL
, wxObjectEventFunction function=nullptr,
wxObject
*userData=nullptr,
wxEvtHandler
*eventSink=nullptr)
See the
Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
overload for more info.
More...
bool
Disconnect
(int id, int lastId,
wxEventType
eventType, wxObjectEventFunction function=nullptr,
wxObject
*userData=nullptr,
wxEvtHandler
*eventSink=nullptr)
See the
Disconnect(wxEventType, wxObjectEventFunction, wxObject*, wxEvtHandler*)
overload for more info.
More...
template
void
Bind
(const EventTag &eventType, Functor functor, int id=
wxID_ANY
, int lastId=
wxID_ANY
wxObject
*userData=nullptr)
Binds the given function, functor or method dynamically with the event.
More...
template
void
Bind
(const EventTag &eventType, void(Class::*method)(EventArg &), EventHandler *handler, int id=
wxID_ANY
, int lastId=
wxID_ANY
wxObject
*userData=nullptr)
See the
Bind<>(const EventTag&, Functor, int, int, wxObject*)
overload for more info.
More...
template
bool
Unbind
(const EventTag &eventType, Functor functor, int id=
wxID_ANY
, int lastId=
wxID_ANY
wxObject
*userData=nullptr)
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.
More...
template
bool
Unbind
(const EventTag &eventType, void(Class::*method)(EventArg &), EventHandler *handler, int id=
wxID_ANY
, int lastId=
wxID_ANY
wxObject
*userData=nullptr)
See the
Unbind<>(const EventTag&, Functor, int, int, wxObject*)
overload for more info.
More...
void *
GetClientData
() const
Returns user-supplied client data.
More...
wxClientData
GetClientObject
() const
Returns a pointer to the user-supplied client data object.
More...
void
SetClientData
(void *data)
Sets user-supplied client data.
More...
void
SetClientObject
wxClientData
*data)
Set the client data object.
More...
bool
GetEvtHandlerEnabled
() const
Returns
true
if the event handler is enabled,
false
otherwise.
More...
wxEvtHandler
GetNextHandler
() const
Returns the pointer to the next handler in the chain.
More...
wxEvtHandler
GetPreviousHandler
() const
Returns the pointer to the previous handler in the chain.
More...
void
SetEvtHandlerEnabled
(bool enabled)
Enables or disables the event handler.
More...
virtual void
SetNextHandler
wxEvtHandler
*handler)
Sets the pointer to the next handler.
More...
virtual void
SetPreviousHandler
wxEvtHandler
*handler)
Sets the pointer to the previous handler.
More...
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).
More...
bool
IsUnlinked
() const
Returns
true
if the next and the previous handler pointers of this event handler instance are
nullptr
More...
Public Member Functions inherited from
wxObject
wxObject
()
Default ctor; initializes to
nullptr
the internal reference data.
More...
wxObject
(const
wxObject
&other)
Copy ctor.
More...
virtual
~wxObject
()
Destructor.
More...
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).
More...
wxObjectRefData
GetRefData
() const
Returns the
wxObject::m_refData
pointer, i.e. the data referenced by this object.
More...
bool
IsKindOf
(const
wxClassInfo
*info) const
Determines whether this class is a subclass of (or the same class as) the given class.
More...
bool
IsSameAs
(const
wxObject
&obj) const
Returns
true
if this object has the same data pointer as
obj
More...
void
Ref
(const
wxObject
&clone)
Makes this object refer to the data in
clone
More...
void
SetRefData
wxObjectRefData
*data)
Sets the
wxObject::m_refData
pointer.
More...
void
UnRef
()
Decrements the reference count in the associated data, and if it is zero, deletes the data.
More...
void
UnShare
()
This is the same of
AllocExclusive()
but this method is public.
More...
void
operator delete
(void *buf)
The
delete
operator is defined for debugging versions of the library only, when the identifier
__WXDEBUG__
is defined.
More...
void *
operator new
(size_t size, const
wxString
&filename=nullptr, int lineNum=0)
The
new
operator is defined for debugging versions of the library only, when the identifier
__WXDEBUG__
is defined.
More...
Public Member Functions inherited from
wxEventFilter
wxEventFilter
()
Default constructor.
More...
virtual
~wxEventFilter
()
Destructor.
More...
Static Public Member Functions
static
wxAppConsole
GetGUIInstance
()
Returns the current GUI
wxApp
object if any or
nullptr
otherwise.
More...
static
wxWindow
GetMainTopWindow
()
Returns a pointer to the top application window if any.
More...
GTK-specific functions
static void
GTKSuppressDiagnostics
(int flags=-1)
Disables the printing of various GTK messages.
More...
static void
GTKAllowDiagnosticsControl
()
Allows wxWidgets to selectively suppress some GTK messages.
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.
More...
static
wxAppConsole
GetInstance
()
Returns the one and only global application object.
More...
static bool
IsMainLoopRunning
()
Returns
true
if the main event loop is currently running, i.e. if the application is inside
OnRun()
More...
static void
SetFatalErrorExitCode
(int code)
Allows to set a custom process exit code if a fatal error happens.
More...
static void
CallOnUnhandledException
()
Call
OnUnhandledException()
on the current wxTheApp object if it exists.
More...
Static Public Member Functions inherited from
wxEvtHandler
static void
AddFilter
wxEventFilter
*filter)
Add an event filter whose FilterEvent() method will be called for each and every event processed by wxWidgets.
More...
static void
RemoveFilter
wxEventFilter
*filter)
Remove a filter previously installed with
AddFilter()
More...
Additional Inherited Members
Public Attributes inherited from
wxAppConsole
int
argc
Number of command line arguments (after environment-specific processing).
More...
wxChar
**
argv
Command line arguments (after environment-specific processing).
More...
Protected Member Functions inherited from
wxAppConsole
virtual
wxAppTraits
CreateTraits
()
Creates the
wxAppTraits
object when
GetTraits()
needs it for the first time.
More...
Protected Member Functions inherited from
wxEvtHandler
virtual bool
TryBefore
wxEvent
&event)
Method called by
ProcessEvent()
before examining this object event tables.
More...
virtual bool
TryAfter
wxEvent
&event)
Method called by
ProcessEvent()
as last resort.
More...
Protected Member Functions inherited from
wxObject
void
AllocExclusive
()
Ensure that this object's data is not shared with any other object.
More...
virtual
wxObjectRefData
CreateRefData
() const
Creates a new instance of the wxObjectRefData-derived class specific to this object and returns it.
More...
virtual
wxObjectRefData
CloneRefData
(const
wxObjectRefData
*data) const
Creates a new instance of the wxObjectRefData-derived class specific to this object and initializes it copying
data
More...
Protected Attributes inherited from
wxObject
wxObjectRefData
m_refData
Pointer to an object which is the object's reference-counted data.
More...
Member Enumeration Documentation
Appearance
enum
wxApp::Appearance
strong
Possible parameters for
SetAppearance()
Since
3.3.0
Enumerator
System
Use system default appearance.
Light
Use light appearance.
Dark
Use dark appearance.
AppearanceResult
enum
wxApp::AppearanceResult
strong
Possible values returned by
SetAppearance()
Since
3.3.0
Enumerator
Failure
Changing the appearance failed.
Ok
Appearance was successfully changed.
CannotChange
Appearance can't be changed any more.
Constructor & Destructor Documentation
wxApp()
wxApp::wxApp
Constructor.
Called implicitly with a definition of a
wxApp
object.
~wxApp()
virtual wxApp::~wxApp
virtual
Destructor.
Will be called implicitly on program exit if the
wxApp
object is created on the stack.
Member Function Documentation
GetDisplayMode()
virtual
wxVideoMode
wxApp::GetDisplayMode
const
virtual
Get display mode that is used use.
This is only used in framebuffer wxWidgets ports such as wxDFB.
GetExitOnFrameDelete()
bool wxApp::GetExitOnFrameDelete
const
Returns
true
if the application will exit when the top-level frame is deleted.
See also
SetExitOnFrameDelete()
GetGUIInstance()
static
wxAppConsole
* wxApp::GetGUIInstance
static
Returns the current GUI
wxApp
object if any or
nullptr
otherwise.
This function should only be used in the rare cases when the same code needs to work in both console and GUI applications, but needs to use GUI-specific functionality if it is available, and so just calling
wxAppConsole::GetInstance()
is insufficient while using
wxTheApp
is incorrect, as the application object is not always a GUI
wxApp
For example:
WXWidget handle = 0;
if
wxApp
const
app =
wxApp::GetGUIInstance
() ) {
if
wxWindow
const
w = app->GetTopWindow() ) {
handle = w->GetHandle();
//else: no window to use
some_native_function_taking_a_window_handle(handle);
wxApp
The wxApp class represents the application itself when wxUSE_GUI=1.
Definition:
app.h:983
wxApp::GetGUIInstance
static wxAppConsole * GetGUIInstance()
Returns the current GUI wxApp object if any or nullptr otherwise.
wxWindow
wxWindow is the base class for all windows and represents any visible object on screen.
Definition:
window.h:353
Note that in this particular example, you could use
GetMainTopWindow()
which already does the same thing instead of doing it yourself.
Since
3.1.6
GetLayoutDirection()
virtual
wxLayoutDirection
wxApp::GetLayoutDirection
const
virtual
Return the layout direction for the current locale or
wxLayout_Default
if it's unknown.
GetMainTopWindow()
static
wxWindow
* wxApp::GetMainTopWindow
static
Returns a pointer to the top application window if any.
This function is safe to call even before creating, or after destroying, the application object, as it simply returns
nullptr
if it doesn't exist. Otherwise it's equivalent to calling
wxTheApp->
GetTopWindow()
Since
3.1.5
GetTopWindow()
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()
GetUseBestVisual()
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()
GTKAllowDiagnosticsControl()
static void wxApp::GTKAllowDiagnosticsControl
static
Allows wxWidgets to selectively suppress some GTK messages.
This function can be called to allow wxWidgets to control GTK message logging. You must
not
call it if your application calls the
g_log_set_writer_func()
function itself, as this function can be only called once.
It is recommended to call this function in your overridden version of
wxApp::OnInit()
to allow wxWidgets to suppress some spurious GTK error messages, e.g. the ones that happen whenever
wxNotebook
pages are removed with the current GTK versions.
Availability:
only available for the
wxGTK
port.
Since
3.2.1
GTKSuppressDiagnostics()
static void wxApp::GTKSuppressDiagnostics
int
flags
-1
static
Disables the printing of various GTK messages.
This function can be called to suppress GTK diagnostic messages that are output on the standard error stream by default.
If
WXSUPPRESS_GTK_DIAGNOSTICS
environment variable is set to a non-zero value, wxWidgets automatically calls this function on program startup with the value of this variable as
flags
if it's a number or with the default flags value otherwise.
The default value of the argument disables all messages, but you can pass in a mask flag to specifically disable only particular categories of messages.
Note that this function only works when using glib 2.50 (released in September 2016) or later and does nothing with the older versions of the library.
Parameters
flags
The mask for the types of messages to suppress. Refer to the glib documentation for the
GLogLevelFlags
enum, which defines the various message types.
Availability:
only available for the
wxGTK
port.
Since
3.1.6
IsActive()
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.
MacNewFile()
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/Cocoa
port.
MacOpenFile()
virtual void wxApp::MacOpenFile
const
wxString
fileName
virtual
Called in response of an "open-document" Apple event.
Deprecated:
This function is kept mostly for backwards compatibility. Please override
wxApp::MacOpenFiles
method instead in any new code.
Availability:
only available for the
wxOSX/Cocoa
port.
MacOpenFiles()
virtual void wxApp::MacOpenFiles
const
wxArrayString
fileNames
virtual
Called in response of an openFiles message.
You need to override this method in order to open one or more document files after the user double clicked on it or if the files and/or folders were dropped on either the application in the dock or the application icon in Finder.
By default this method calls MacOpenFile for each file/folder.
Availability:
only available for the
wxOSX/Cocoa
port.
Since
2.9.3
MacOpenURL()
virtual void wxApp::MacOpenURL
const
wxString
url
virtual
Called in response of a "get-url" Apple event.
Availability:
only available for the
wxOSX/Cocoa
port.
MacPrintFile()
virtual void wxApp::MacPrintFile
const
wxString
fileName
virtual
Called in response of a "print-document" Apple event.
Availability:
only available for the
wxOSX/Cocoa
port.
MacReopenApp()
virtual void wxApp::MacReopenApp
virtual
Called in response of a "reopen-application" Apple event.
Availability:
only available for the
wxOSX/Cocoa
port.
MSWEnableDarkMode()
bool wxApp::MSWEnableDarkMode
int
flags
wxDarkModeSettings
settings
nullptr
Enable experimental dark mode support for MSW applications.
This function uses
undocumented
, and unsupported by Microsoft, functions to enable dark mode support for the desktop applications under Windows 10 versions later than v1809 (which includes Windows 10 LTSC 2019) and all Windows 11 versions. Please note that dark mode testing under versions of Windows earlier than 20H1 (i.e. v2004) has been limited, make sure to test your application especially carefully if you target these versions and want to enable dark mode support.
Note that dark mode can also be enabled by setting the "msw.dark-mode"
system option
via an environment variable from outside the application or by calling
SetAppearance()
with either
System
or
Dark
parameter.
Known limitations of dark mode support include:
Anything based on
TaskDialog()
Win32 API doesn't support dark mode:
wxMessageBox()
wxMessageDialog
wxRichMessageDialog
wxProgressDialog
and simple (i.e., without hyperlink or licence)
wxAboutBox()
. Consider using generic versions (e.g. wxGenericMessageDialog or
wxGenericProgressDialog
) if dark mode support is more important than using the native dialog.
The following dialogs wrapping common windows dialogs don't support dark mode:
wxColourDialog
wxFindReplaceDialog
wxFontDialog
wxPageSetupDialog
wxPrintDialog
wxTimePickerCtrl
wxDatePickerCtrl
and
wxCalendarCtrl
don't support dark mode and use the same (light) background as by default in it.
Toolbar items for which
wxToolBar::SetDropdownMenu()
was called don't draw the menu drop-down correctly, making it almost invisible.
Parameters
flags
Can include
wxApp::DarkMode_Always
to force enabling dark mode for the application, even if the system doesn't use the dark mode by default. Otherwise dark mode is only used if it is the default mode for the applications on the current system.
settings
If specified, allows to customize dark mode appearance. Please see
wxDarkModeSettings
documentation for more information.
Returns
true
if dark mode support was enabled,
false
if it couldn't be done, most likely because the system doesn't support dark mode.
Availability:
only available for the
wxMSW
port.
Since
3.3.0
OSXEnableAutomaticTabbing()
void wxApp::OSXEnableAutomaticTabbing
bool
enable
Enable the automatic tabbing features of macOS.
This feature is native to the operating system. When it is enabled, macOS will automatically place windows inside tabs and show a tab bar in the application. Entries are also added to the View menu to show/hide the tab bar.
Availability:
only available for the
wxOSX/Cocoa
port.
Remarks
Requires macOS 10.12+, does nothing under earlier OS versions.
Since
3.1.4
OSXIsGUIApplication()
virtual bool wxApp::OSXIsGUIApplication
virtual
May be overridden to indicate that the application is not a foreground GUI application under macOS.
This method is called during the application startup and returns
true
by default. In this case, wxWidgets ensures that the application is ran as a foreground, GUI application so that the user can interact with it normally, even if it is not bundled. If this is undesired, i.e. if the application doesn't need to be brought to the foreground, this method can be overridden to return
false
Notice that overriding it doesn't make any difference for the bundled applications which are always foreground unless
LSBackgroundOnly
key is specified in the
Info.plist
file.
Availability:
only available for the
wxOSX/Cocoa
port.
Since
3.0.1
ProcessMessage()
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);
wxApp::ProcessMessage
bool ProcessMessage(WXMSG *msg)
Windows-only function for processing a message.
wxTheApp
wxApp * wxTheApp
The global pointer to the singleton wxApp object.
Definition:
app.h:1613
Availability:
only available for the
wxMSW
port.
SafeYield()
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
nullptr
, 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
SafeYieldFor()
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
wxEventLoopBase::YieldFor()
for more info.
SetAppearance()
AppearanceResult
wxApp::SetAppearance
Appearance
appearance
Request using either system default or explicitly light or dark theme for the application.
Under GTK and macOS applications use the system default appearance by default, and so it is only useful to call this function with either
Appearance::Light
or
Appearance::Dark
parameters if you need to override the default system appearance. The effect of calling this function is immediate, i.e. this function returns
AppearanceResult::Ok
, and affects all the existing windows as well as any windows created after this call.
Under MSW, the default appearance is always light and the applications that want to follow the system appearance need to explicitly call this function with
Appearance::System
parameter in order to do it. Please note using dark appearance under MSW requires using non-documented system functions and has several known limitations, please see
MSWEnableDarkMode()
for more details. Also, on this platform the appearance can be only set before any windows are created and calling this function too late will return
AppearanceResult::CannotChange
Note that to query the current appearance, you can use
wxSystemAppearance
, see
wxSystemSettings::GetAppearance()
Returns
AppearanceResult::Ok
if the appearance was successfully changed or had been already set to the requested value,
AppearanceResult::CannotChange
if the appearance can't be changed any more because it's too late to do it but could be changed if done immediately on next program launch (only returned by wxMSW currently) or
AppearanceResult::Failure
if changing the appearance failed for some other reason, e.g. because
GTK_THEME
is defined when using wxGTK of this function is not implemented at all for the current platform.
Since
3.3.0
SetDisplayMode()
virtual bool wxApp::SetDisplayMode
const
wxVideoMode
info
virtual
Set display mode to use.
This is only used in framebuffer wxWidgets ports such as wxDFB.
SetExitOnFrameDelete()
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
SetNativeTheme()
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
SetTopWindow()
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(nullptr)
Parameters
window
The new top window.
See also
GetTopWindow()
OnInit()
SetUseBestVisual()
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.
Generated on Sat Apr 18 2026 22:28:11 for wxWidgets by
Doxygen
1.9.1