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

the following overload of wxentry is available under all platforms:

int wxentry(int& argc, wxchar **argv)

under ms windows, an additional overload suitable for calling from winmain is available:

int wxentry(hinstance hinstance, hinstance hprevinstance = null, char *pcmdline = null, int ncmdshow = sw_shownormal)

(notice that under windows ce platform, and only there, the type of pcmdline is wchar_t *, otherwise it is char *, even in unicode build).

see also

wxentrystart

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

<wx/app.h>

::wxentrycleanup

void wxentrycleanup()

free resources allocated by a successful call to wxentrystart.

include files

<wx/init.h>

::wxentrystart

bool wxentrystart(int& argc, wxchar **argv)

this function can be used to perform the initialization of wxwidgets if you can't use the default initialization code for any reason.

if the function returns true, the initialization was successful and the global wxapp object wxtheapp has been created. moreover, wxentrycleanup must be called afterwards. if the function returns false, a catastrophic initialization error occured and (at least the gui part of) the library can't be used at all.

notice that parameters argc and argv may be modified by this function.

include files

<wx/init.h>

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

<wx/image.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 files

<wx/app.h>

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

<wx/utils.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 files

<wx/app.h>

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

<wx/app.h> or <wx/utils.h>

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

<wx/app.h>