Application initialization and termination

Application initialization and termination

The functions in this section are used on application startup/shutdown and also to control the behaviour of the main event loop of the GUI programs.

::wxEntry
::wxGetApp
::wxHandleFatalExceptions
::wxInitAllImageHandlers
::wxInitialize
::wxSafeYield
::wxUninitialize
::wxYield
::wxWakeUpIdle

::wxEntry

This 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 an Microsoft Foundation Classes application using this function.

void wxEntry(HANDLE hInstance, HANDLE hPrevInstance, const wxString& commandLine, int cmdShow, bool enterLoop = true)

wxWidgets initialization under Windows (non-DLL). If enterLoop is false, the function will return immediately after calling wxApp::OnInit. Otherwise, the wxWidgets message loop will be entered.

void wxEntry(HANDLE hInstance, HANDLE hPrevInstance, WORD wDataSegment, WORD wHeapSize, const wxString& commandLine)

wxWidgets initialization under Windows (for applications constructed as a DLL).

int wxEntry(int argc, const wxString& *argv)

wxWidgets initialization under Unix.

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();
}

Include files

::wxGetApp

wxAppDerivedClass& wxGetApp()

This function doesn't exist in wxWidgets but it is created by using the IMPLEMENT_APP macro. Thus, before using it anywhere but in the same module where this macro is used, you must make it available using DECLARE_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.

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

::wxInitAllImageHandlers

void wxInitAllImageHandlers()

Initializes all available image handlers. For a list of available handlers, see wxImage.

See also

wxImage, wxImageHandler

Include files

::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 files

::wxSafeYield

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

This function is similar to wxYield, except that it disables the user input to all program windows before calling wxYield 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 ::wxYield.

Include files

::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 files

::wxYield

bool wxYield()

Calls wxApp::Yield.

This function is kept only for backwards compatibility. Please use the wxApp::Yield method instead in any new code.

Include files

::wxWakeUpIdle

void wxWakeUpIdle()

This functions 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 files