wxWidgets: interface/wx/app.h File Reference

| Version: 3.1.5

Classes | Macros | Functions | Variables
app.h File Reference

## Classes
class | wxAppConsole
| This class is essential for writing console-only or hybrid apps without having to define `wxUSE_GUI=0`. More...
class | wxApp
| The wxApp class represents the application itself when `wxUSE_GUI=1`. More...

## Macros
#define | wxDECLARE_APP(className)
| This is used in headers to create a forward declaration of the wxGetApp() function implemented by wxIMPLEMENT_APP(). More...
#define | wxIMPLEMENT_APP(className)
| This is used in the application class implementation file to make the application class known to wxWidgets for dynamic construction. More...
#define | wxDISABLE_DEBUG_SUPPORT()
| Use this macro to disable all debugging code in release build when not using wxIMPLEMENT_APP(). More...

## Functions
wxAppDerivedClass & | wxGetApp ()
| This function doesn't exist in wxWidgets but it is created by using the wxIMPLEMENT_APP() macro. More...
bool | wxHandleFatalExceptions (bool doIt=true)
| If doIt is true, the fatal exceptions (also known as general protection faults under Windows or segmentation violations in the Unix world) will be caught and passed to wxApp::OnFatalException. More...
bool | wxInitialize ()
| This function is used in wxBase only and only if you don't create wxApp object at all. More...
void | wxUninitialize ()
| This function is for use in console (wxBase) programs only. More...
void | wxWakeUpIdle ()
| This function wakes up the (internal and platform dependent) idle system, i.e. More...
bool | wxYield ()
| Calls wxAppConsole::Yield if there is an existing application object. More...
bool | wxSafeYield (wxWindow *win=NULL, bool onlyIfNeeded=false)
| Calls wxApp::SafeYield. More...
int | wxEntry (int &argc, wxChar **argv)
| This function initializes wxWidgets in a platform-dependent way. More...
int | wxEntry (HINSTANCE hInstance, HINSTANCE hPrevInstance=NULL, char *pCmdLine=NULL, int nCmdShow=SW_SHOWNORMAL)
| See wxEntry(int&,wxChar**) for more info about this function. More...
void | wxExit ()
| Exits application after calling wxApp::OnExit. More...

## Variables
wxApp * | wxTheApp
| The global pointer to the singleton wxApp object. More...

## Macro Definition Documentation

## ◆ wxDECLARE_APP

#define wxDECLARE_APP | ( |  | className | ) |

This is used in headers to create a forward declaration of the wxGetApp() function implemented by wxIMPLEMENT_APP().

It creates the declaration `className& wxGetApp()` (requires a final semicolon).

Include file:

    #include <wx/app.h>

Example:

wxDECLARE_APP(MyApp);
wxDECLARE_APP
#define wxDECLARE_APP(className)
This is used in headers to create a forward declaration of the wxGetApp() function implemented by wxI...
Definition: app.h:1132

## ◆ wxDISABLE_DEBUG_SUPPORT

#define wxDISABLE_DEBUG_SUPPORT | ( |  | ) |

Value:
wxDISABLE_ASSERTS_IN_RELEASE_BUILD(); \
wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD()
wxDISABLE_ASSERTS_IN_RELEASE_BUILD
#define wxDISABLE_ASSERTS_IN_RELEASE_BUILD()
Use this macro to disable asserts in release build when not using wxIMPLEMENT_APP().
Definition: debug.h:295

Use this macro to disable all debugging code in release build when not using wxIMPLEMENT_APP().

Currently this macro disables assert checking and debug and trace level logging messages in release build (i.e. when `NDEBUG` is defined). It is used by wxIMPLEMENT_APP() macro so you only need to use it explicitly if you don't use this macro but initialize wxWidgets directly (e.g. calls wxEntry() or wxEntryStart() itself).

If you do not want to disable debugging code even in release build of your application, you can use wxSetDefaultAssertHandler() and wxLog::SetLogLevel() with `wxLOG_Max` parameter to enable assertions and debug logging respectively.

See also
  wxDISABLE_ASSERTS_IN_RELEASE_BUILD(), wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD(), Debugging

Since
  2.9.1

Include file:

    #include <wx/app.h>

## ◆ wxIMPLEMENT_APP

#define wxIMPLEMENT_APP | ( |  | className | ) |

This is used in the application class implementation file to make the application class known to wxWidgets for dynamic construction.

Note that this macro requires a final semicolon.

Include file:

    #include <wx/app.h>

Example:

wxIMPLEMENT_APP(MyApp);
wxIMPLEMENT_APP
#define wxIMPLEMENT_APP(className)
This is used in the application class implementation file to make the application class known to wxWi...
Definition: app.h:1149

See also
  wxDECLARE_APP()

## Function Documentation

## ◆ wxEntry() [1/2]

int wxEntry | ( | HINSTANCE | hInstance,
|  | HINSTANCE | hPrevInstance = `NULL`,
|  | char * | pCmdLine = `NULL`,
|  | int | nCmdShow = `SW_SHOWNORMAL`
| ) |  |

See wxEntry(int&,wxChar**) for more info about this function.

Notice that the type of pCmdLine is `char` *, even in Unicode build.

Remarks
  To clean up wxWidgets, call wxApp::OnExit followed by the static function wxApp::CleanUp. For example, if exiting from an MFC application that also uses wxWidgets:
  int CTheApp::ExitInstance()
  {
  // OnExit isn't called by CleanUp so must be called explicitly.
  wxTheApp->OnExit();
  wxApp::CleanUp();
  return CWinApp::ExitInstance();
  }
  wxAppConsole::OnExit
  virtual int OnExit()
  Override this member function for any processing which needs to be done as the application is about t...
  wxTheApp
  wxApp * wxTheApp
  The global pointer to the singleton wxApp object.
  Definition: app.h:1160

Include file:

    #include <wx/app.h>

## ◆ wxEntry() [2/2]

int wxEntry | ( | int & | argc,
|  | wxChar ** | argv
| ) |  |

This function initializes wxWidgets in a platform-dependent way.

Use this if you are not using the default wxWidgets entry code (e.g. main or WinMain).

For example, you can initialize wxWidgets from a Microsoft Foundation Classes (MFC) application using this function.

Note
  This overload of wxEntry is available under all platforms.

See also
  wxEntryStart()

Include file:

    #include <wx/app.h>

## ◆ wxExit()

void wxExit | ( |  | ) |

Exits application after calling wxApp::OnExit.

Should only be used in an emergency: normally the top-level frame should be deleted (after deleting all other frames) to terminate the application. See wxCloseEvent and wxApp.

Include file:

    #include <wx/app.h>

## ◆ wxGetApp()

wxAppDerivedClass & wxGetApp | ( |  | ) |

This function doesn't exist in wxWidgets but it is created by using the wxIMPLEMENT_APP() macro.

Thus, before using it anywhere but in the same module where this macro is used, you must make it available using wxDECLARE_APP().

The advantage of using this function compared to directly using the global wxTheApp pointer is that the latter is of type wxApp* and so wouldn't allow you to access the functions specific to your application class but not present in wxApp while wxGetApp() returns the object of the right type.

Include file:

    #include <wx/app.h>

## ◆ wxHandleFatalExceptions()

bool wxHandleFatalExceptions | ( | bool | doIt = `true` | ) |

If doIt is true, the fatal exceptions (also known as general protection faults under Windows or segmentation violations in the Unix world) will be caught and passed to wxApp::OnFatalException.

By default, i.e. before this function is called, they will be handled in the normal way which usually just means that the application will be terminated. Calling wxHandleFatalExceptions() with doIt equal to false will restore this default behaviour.

Notice that this function is only available if `wxUSE_ON_FATAL_EXCEPTION` is 1 and under Windows platform this requires a compiler with support for SEH (structured exception handling) which currently means only Microsoft Visual C++.

Include file:

    #include <wx/app.h>

## ◆ wxInitialize()

bool wxInitialize | ( |  | ) |

This function is used in wxBase only and only if you don't create wxApp object at all.

In this case you must call it from your `main()` function before calling any other wxWidgets functions.

If the function returns false the initialization could not be performed, in this case the library cannot be used and wxUninitialize() shouldn't be called neither.

This function may be called several times but wxUninitialize() must be called for each successful call to this function.

Include file:

    #include <wx/app.h>

## ◆ wxSafeYield()

bool wxSafeYield | ( | wxWindow * | win = `NULL`,
|  | bool | onlyIfNeeded = `false`
| ) |  |

Calls wxApp::SafeYield.

Include file:

    #include <wx/app.h>

## ◆ wxUninitialize()

void wxUninitialize | ( |  | ) |

This function is for use in console (wxBase) programs only.

It must be called once for each previous successful call to wxInitialize().

Include file:

    #include <wx/app.h>

## ◆ wxWakeUpIdle()

void wxWakeUpIdle | ( |  | ) |

This function wakes up the (internal and platform dependent) idle system, i.e.

it will force the system to send an idle event even if the system currently is idle and thus would not send any idle event until after some other event would get sent. This is also useful for sending events between two threads and is used by the corresponding functions wxPostEvent() and wxEvtHandler::AddPendingEvent().

Include file:

    #include <wx/app.h>

## ◆ wxYield()

bool wxYield | ( |  | ) |

Calls wxAppConsole::Yield if there is an existing application object.

Does nothing if there is no application (which typically only happens early during the program startup or late during its shutdown).

See also
  wxEvtLoopBase::Yield()

Include file:

    #include <wx/app.h>

## Variable Documentation

## ◆ wxTheApp

wxApp* wxTheApp

The global pointer to the singleton wxApp object.

See also
  wxApp::GetInstance()