Application Initialization and Termination

Detailed Description

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.

Related macros/global-functions group: Application and Process Management.

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	wxInitAllImageHandlers ()
	Initializes all available image handlers. More...
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. More...
bool	wxEntryStart (HINSTANCE hInstance, HINSTANCE hPrevInstance=NULL, char *pCmdLine=NULL, int nCmdShow=SW_SHOWNORMAL)
	See wxEntryStart(int&,wxChar**) for more info about this function. More...
void	wxEntryCleanup ()
	Free resources allocated by a successful call to wxEntryStart(). More...
bool	wxInitialize (int argc=0, wxChar **argv=NULL)
	Initialize the library (may be called as many times as needed, but each call to wxInitialize() must be matched by wxUninitialize()). More...

Function Documentation

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

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

Include file:

#include <wx/app.h> 

void wxEntryCleanup

(

)

Free resources allocated by a successful call to wxEntryStart().

Include file:

#include <wx/init.h> 

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

#include <wx/init.h> 

bool wxEntryStart	(	HINSTANCE	hInstance,
		HINSTANCE	hPrevInstance = NULL,
		char *	pCmdLine = NULL,
		int	nCmdShow = SW_SHOWNORMAL
	)

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

This is an additional overload of wxEntryStart() provided under MSW only. It is meant to be called with the parameters passed to WinMain().

Note

The type of pCmdLine is char *, even in Unicode build.

Availability:  only available for the wxMSW port.

Include file:

#include <wx/init.h> 

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> 

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++ or a recent Borland C++ version.

Include file:

#include <wx/app.h> 

void wxInitAllImageHandlers

(

)

Initializes all available image handlers.

This function calls wxImage::AddHandler() for all the available image handlers (see Available image handlers for the full list). Calling it is the simplest way to initialize wxImage but it creates and registers even the handlers your program may not use. If you want to avoid the overhead of doing this you need to call wxImage::AddHandler() manually just for the handlers that you do want to use.

See also

wxImage, wxImageHandler

Include file:

#include <wx/image.h> 

bool wxInitialize	(	int	argc = 0,
		wxChar **	argv = NULL
	)

Initialize the library (may be called as many times as needed, but each call to wxInitialize() must be matched by wxUninitialize()).

With this function you may avoid wxDECLARE_APP() and wxIMPLEMENT_APP() macros and use wxInitialize() and wxUninitialize() dynamically in the program startup and termination.

Include file:

#include <wx/init.h> 

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> 

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

Calls wxApp::SafeYield.

Include file:

#include <wx/app.h> 

void wxUninitialize

(

)

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

Clean up; the library can't be used any more after the last call to wxUninitialize().

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

Include file:

#include <wx/app.h> 

See wxInitialize() for more info.

Include file:

#include <wx/init.h> 

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> 

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>