Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Simplified app initialisation in wxMSW and wxStubs

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@741 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Julian Smart
1998-09-17 09:58:52 +00:00
parent 7f555861b7
commit 589f0e3e60
7 changed files with 227 additions and 274 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
distrib/msw/stubs.rsp
View File

@@ -3,6 +3,9 @@ src/stubs/*.h
src/stubs/makefile*
src/stubs/*.inc
src/make.env
src/makeprog.env
include/wx/stubs/*.h
include/wx/stubs/*.rc

3
distrib/msw/zipdist.bat
View File

@@ -6,7 +6,7 @@ if "%src" == "" goto usage
if "%dest" == "" goto usage
echo About to archive an external wxWindows distribution:
echo From %src
echo To %dest\wx200gen.zip, %dest\wx200doc.zip, %dest\wx200msw.zip, %dest\wx200ps.zip, %dest\wx200hlp.zip, %dest\wx200htm.zip, %dest\wx200pdf.zip
echo To %dest
echo CTRL-C if this is not correct.
pause
@@ -18,6 +18,7 @@ zip32 -@ %dest\wx200gen.zip < %src\distrib\msw\generic.rsp
zip32 -@ %dest\wx200msw.zip < %src\distrib\msw\msw.rsp
zip32 -@ %dest\wx200gtk.zip < %src\distrib\msw\gtk.rsp
zip32 -@ %dest\wx200stubs.zip < %src\distrib\msw\stubs.rsp
zip32 -@ %dest\wx200mot.zip < %src\distrib\msw\motif.rsp
zip32 -@ %dest\wx200doc.zip < %src\distrib\msw\docsrc.rsp
zip32 -@ %dest\wx200hlp.zip < %src\distrib\msw\wx_hlp.rsp

10
include/wx/defs.h
View File

@@ -884,5 +884,15 @@ typedef int (__stdcall *WXFARPROC)();
#endif
#ifdef __WXMOTIF__
// Stand-ins for X/Xt/Motif types
typedef void* WXWindow;
typedef void* WXWidget;
typedef void* WXAppContext;
typedef void* WXMainColormap;
typedef void WXDisplay;
typedef void WXEvent;
#endif
#endif
// _WX_DEFS_H_

17
include/wx/msw/app.h
View File

@@ -30,10 +30,6 @@ class WXDLLEXPORT wxLog;
WXDLLEXPORT_DATA(extern wxApp*) wxTheApp;
void WXDLLEXPORT wxCleanUp();
void WXDLLEXPORT wxCommonCleanUp(); // Call this from the platform's wxCleanUp()
void WXDLLEXPORT wxCommonInit(); // Call this from the platform's initialization
// Force an exit from main loop
void WXDLLEXPORT wxExit();
@@ -46,7 +42,7 @@ class WXDLLEXPORT wxApp: public wxEvtHandler
{
DECLARE_DYNAMIC_CLASS(wxApp)
wxApp();
inline ~wxApp() {}
~wxApp();
static void SetInitializerFunction(wxAppInitializerFunction fn) { m_appInitFn = fn; }
static wxAppInitializerFunction GetInitializerFunction() { return m_appInitFn; }
@@ -131,11 +127,12 @@ protected:
public:
// Implementation
static bool Initialize(WXHINSTANCE instance);
static void CommonInit();
static bool RegisterWindowClasses();
static bool Initialize();
static void CleanUp();
static void CommonCleanUp();
static bool RegisterWindowClasses();
// Convert Windows to argc, argv style
void ConvertToStandardCommandArgs(char* p);
virtual bool DoMessage();
virtual bool ProcessMessage(WXMSG* pMsg);
void DeletePendingObjects();
@@ -148,8 +145,6 @@ public:
protected:
bool m_keepGoing ;
// bool m_resourceCollection;
// bool m_pendingCleanup; // TRUE if we need to check the GDI object lists for cleanup
DECLARE_EVENT_TABLE()
};

9
include/wx/stubs/app.h
View File

@@ -32,10 +32,6 @@ class WXDLLEXPORT wxLog;
WXDLLEXPORT_DATA(extern wxApp*) wxTheApp;
void WXDLLEXPORT wxCleanUp();
void WXDLLEXPORT wxCommonCleanUp(); // Call this from the platform's wxCleanUp()
void WXDLLEXPORT wxCommonInit(); // Call this from the platform's initialization
// Force an exit from main loop
void WXDLLEXPORT wxExit();
@@ -132,8 +128,9 @@ protected:
public:
// Implementation
static void CommonInit();
static void CommonCleanUp();
static bool Initialize();
static void CleanUp();
void DeletePendingObjects();
bool ProcessIdle();

421
src/msw/app.cpp
View File

@@ -100,11 +100,57 @@ long wxApp::sm_lastMessageTime = 0;
static HINSTANCE gs_hRichEdit = NULL;
#endif
bool wxApp::Initialize(WXHINSTANCE instance)
{
HINSTANCE hInstance = (HINSTANCE) instance;
//// Initialize
CommonInit();
bool wxApp::Initialize()
{
wxBuffer = new char[1500];
/* Doesn't work when using the makefiles, for some reason.
#if defined(__WXDEBUG__) && defined(_MSC_VER)
// do check for memory leaks on program exit
// (another useful flag is _CRTDBG_DELAY_FREE_MEM_DF which doesn't free
// deallocated memory which may be used to simulate low-memory condition)
_CrtSetDbgFlag(_CrtSetDbgFlag(_CRTDBG_REPORT_FLAG) | _CRTDBG_LEAK_CHECK_DF);
#endif // debug build under MS VC++
*/
#if (WXDEBUG && USE_MEMORY_TRACING) || USE_DEBUG_CONTEXT
#if !defined(_WINDLL)
streambuf* sBuf = new wxDebugStreamBuf;
#else
streambuf* sBuf = NULL;
#endif
ostream* oStr = new ostream(sBuf) ;
wxDebugContext::SetStream(oStr, sBuf);
#endif // USE_MEMORY_TRACING
wxClassInfo::InitializeClasses();
#if USE_RESOURCES
wxGetResource("wxWindows", "OsVersion", &wxOsVersion);
#endif
wxTheColourDatabase = new wxColourDatabase(wxKEY_STRING);
wxTheColourDatabase->Initialize();
wxInitializeStockLists();
wxInitializeStockObjects();
#if USE_WX_RESOURCES
wxInitializeResourceSystem();
#endif
// For PostScript printing
#if USE_POSTSCRIPT
wxInitializePrintSetupData();
wxThePrintPaperDatabase = new wxPrintPaperDatabase;
wxThePrintPaperDatabase->CreateDatabase();
#endif
wxBitmap::InitStandardHandlers();
#if defined(__WIN95__)
InitCommonControls();
@@ -123,19 +169,21 @@ bool wxApp::Initialize(WXHINSTANCE instance)
#endif
#if CTL3D
if (!Ctl3dRegister(hInstance))
if (!Ctl3dRegister(wxhInstance))
wxFatalError("Cannot register CTL3D");
Ctl3dAutoSubclass(hInstance);
Ctl3dAutoSubclass(wxhInstance);
#endif
wxSTD_FRAME_ICON = LoadIcon(hInstance, "wxSTD_FRAME");
wxSTD_MDIPARENTFRAME_ICON = LoadIcon(hInstance, "wxSTD_MDIPARENTFRAME");
wxSTD_MDICHILDFRAME_ICON = LoadIcon(hInstance, "wxSTD_MDICHILDFRAME");
g_globalCursor = new wxCursor;
wxDEFAULT_FRAME_ICON = LoadIcon(hInstance, "wxDEFAULT_FRAME");
wxDEFAULT_MDIPARENTFRAME_ICON = LoadIcon(hInstance, "wxDEFAULT_MDIPARENTFRAME");
wxDEFAULT_MDICHILDFRAME_ICON = LoadIcon(hInstance, "wxDEFAULT_MDICHILDFRAME");
wxSTD_FRAME_ICON = LoadIcon(wxhInstance, "wxSTD_FRAME");
wxSTD_MDIPARENTFRAME_ICON = LoadIcon(wxhInstance, "wxSTD_MDIPARENTFRAME");
wxSTD_MDICHILDFRAME_ICON = LoadIcon(wxhInstance, "wxSTD_MDICHILDFRAME");
wxDEFAULT_FRAME_ICON = LoadIcon(wxhInstance, "wxDEFAULT_FRAME");
wxDEFAULT_MDIPARENTFRAME_ICON = LoadIcon(wxhInstance, "wxDEFAULT_MDIPARENTFRAME");
wxDEFAULT_MDICHILDFRAME_ICON = LoadIcon(wxhInstance, "wxDEFAULT_MDICHILDFRAME");
RegisterWindowClasses();
@@ -143,7 +191,7 @@ bool wxApp::Initialize(WXHINSTANCE instance)
LOGBRUSH lb ;
lb.lbStyle = BS_PATTERN;
lb.lbHatch = (int)LoadBitmap( hInstance, "wxDISABLE_BUTTON_BITMAP" ) ;
lb.lbHatch = (int)LoadBitmap( wxhInstance, "wxDISABLE_BUTTON_BITMAP" ) ;
wxDisableButtonBrush = ::CreateBrushIndirect( & lb ) ;
::DeleteObject( (HGDIOBJ)lb.lbHatch ) ;
@@ -167,6 +215,8 @@ bool wxApp::Initialize(WXHINSTANCE instance)
return TRUE;
}
//// RegisterWindowClasses
bool wxApp::RegisterWindowClasses()
{
///////////////////////////////////////////////////////////////////////
@@ -184,7 +234,7 @@ bool wxApp::RegisterWindowClasses()
// wndclass.hbrBackground = GetStockObject( WHITE_BRUSH );
wndclass.lpszMenuName = NULL;
#ifdef _MULTIPLE_INSTANCES
sprintf( wxFrameClassName,"wxFrameClass%d", hInstance );
sprintf( wxFrameClassName,"wxFrameClass%d", wxhInstance );
#endif
wndclass.lpszClassName = wxFrameClassName;
@@ -291,12 +341,113 @@ bool wxApp::RegisterWindowClasses()
return TRUE;
}
// Cleans up any wxWindows internal structures left lying around
//// Convert Windows to argc, argv style
void wxApp::ConvertToStandardCommandArgs(char* lpCmdLine)
{
// Split command line into tokens, as in usual main(argc, argv)
char **command = new char*[50];
int count = 0;
char *buf = new char[strlen(lpCmdLine) + 1];
// Hangs around until end of app. in case
// user carries pointers to the tokens
/* Model independent strcpy */
int i;
for (i = 0; (buf[i] = lpCmdLine[i]) != 0; i++)
{
/* loop */;
}
// Get application name
char name[200];
::GetModuleFileName(wxhInstance, name, 199);
// Is it only 16-bit Borland that already copies the program name
// to the first argv index?
#if !defined(__GNUWIN32__)
// #if ! (defined(__BORLANDC__) && !defined(__WIN32__))
command[count++] = copystring(name);
// #endif
#endif
strcpy(name, wxFileNameFromPath(name));
wxStripExtension(name);
wxTheApp->SetAppName(name);
/* Break up string */
// Treat strings enclosed in double-quotes as single arguments
char* str = buf;
while (*str)
{
while (*str && *str <= ' ') str++; // skip whitespace
if (*str == '"')
{
str++;
command[count++] = str;
while (*str && *str != '"') str++;
}
else if (*str)
{
command[count++] = str;
while (*str && *str > ' ') str++;
}
if (*str) *str++ = '\0';
}
wxTheApp->argv = new char*[argc+1];
wxTheApp->argv[count] = NULL; /* argv[] is NULL terminated list! */
wxTheApp->argc = count;
for (i = 0; i < count; i++)
{
wxTheApp->argv[i] = copystring(command[i]);
}
delete[] buf;
}
//// Cleans up any wxWindows internal structures left lying around
void wxApp::CleanUp()
{
//// COMMON CLEANUP
wxModule::CleanUpModules();
CommonCleanUp();
#if USE_WX_RESOURCES
wxCleanUpResourceSystem();
// wxDefaultResourceTable->ClearTable();
#endif
// Indicate that the cursor can be freed,
// so that cursor won't be deleted by deleting
// the bitmap list before g_globalCursor goes out
// of scope (double deletion of the cursor).
wxSetCursor(wxNullCursor);
delete g_globalCursor;
wxDeleteStockObjects() ;
// Destroy all GDI lists, etc.
wxDeleteStockLists();
delete wxTheColourDatabase;
wxTheColourDatabase = NULL;
#if USE_POSTSCRIPT
wxInitializePrintSetupData(FALSE);
delete wxThePrintPaperDatabase;
wxThePrintPaperDatabase = NULL;
#endif
wxBitmap::CleanUpHandlers();
delete[] wxBuffer;
wxBuffer = NULL;
//// WINDOWS-SPECIFIC CLEANUP
wxSetKeyboardHook(FALSE);
@@ -344,108 +495,16 @@ void wxApp::CleanUp()
delete wxLog::SetActiveTarget(NULL);
}
void wxApp::CommonInit()
{
#ifdef __WXMSW__
wxBuffer = new char[1500];
#else
wxBuffer = new char[BUFSIZ + 512];
#endif
wxClassInfo::InitializeClasses();
#if USE_RESOURCES
wxGetResource("wxWindows", "OsVersion", &wxOsVersion);
#endif
wxTheColourDatabase = new wxColourDatabase(wxKEY_STRING);
wxTheColourDatabase->Initialize();
wxInitializeStockLists();
wxInitializeStockObjects();
#if USE_WX_RESOURCES
wxInitializeResourceSystem();
#endif
// For PostScript printing
#if USE_POSTSCRIPT
wxInitializePrintSetupData();
wxThePrintPaperDatabase = new wxPrintPaperDatabase;
wxThePrintPaperDatabase->CreateDatabase();
#endif
wxBitmap::InitStandardHandlers();
g_globalCursor = new wxCursor;
}
void wxApp::CommonCleanUp()
{
#if USE_WX_RESOURCES
wxCleanUpResourceSystem();
// wxDefaultResourceTable->ClearTable();
#endif
// Indicate that the cursor can be freed,
// so that cursor won't be deleted by deleting
// the bitmap list before g_globalCursor goes out
// of scope (double deletion of the cursor).
wxSetCursor(wxNullCursor);
delete g_globalCursor;
wxDeleteStockObjects() ;
// Destroy all GDI lists, etc.
wxDeleteStockLists();
delete wxTheColourDatabase;
wxTheColourDatabase = NULL;
#if USE_POSTSCRIPT
wxInitializePrintSetupData(FALSE);
delete wxThePrintPaperDatabase;
wxThePrintPaperDatabase = NULL;
#endif
wxBitmap::CleanUpHandlers();
delete[] wxBuffer;
wxBuffer = NULL;
}
#if !defined(_WINDLL) || (defined(_WINDLL) && defined(WXMAKINGDLL))
// Main wxWindows entry point
//// Main wxWindows entry point
int wxEntry(WXHINSTANCE hInstance, WXHINSTANCE WXUNUSED(hPrevInstance), char *m_lpCmdLine,
int wxEntry(WXHINSTANCE hInstance, WXHINSTANCE WXUNUSED(hPrevInstance), char *lpCmdLine,
int nCmdShow, bool enterLoop)
{
wxhInstance = (HINSTANCE) hInstance;
/* Doesn't work when using the makefiles, for some reason.
#if defined(__WXDEBUG__) && defined(_MSC_VER)
// do check for memory leaks on program exit
// (another useful flag is _CRTDBG_DELAY_FREE_MEM_DF which doesn't free
// deallocated memory which may be used to simulate low-memory condition)
_CrtSetDbgFlag(_CrtSetDbgFlag(_CRTDBG_REPORT_FLAG) | _CRTDBG_LEAK_CHECK_DF);
#endif // debug build under MS VC++
*/
#if (WXDEBUG && USE_MEMORY_TRACING) || USE_DEBUG_CONTEXT
#if !defined(_WINDLL)
streambuf* sBuf = new wxDebugStreamBuf;
#else
streambuf* sBuf = NULL;
#endif
ostream* oStr = new ostream(sBuf) ;
wxDebugContext::SetStream(oStr, sBuf);
#endif // USE_MEMORY_TRACING
if (!wxApp::Initialize((WXHINSTANCE) wxhInstance))
if (!wxApp::Initialize())
return 0;
// The app may have declared a global application object, but we recommend
@@ -467,61 +526,7 @@ int wxEntry(WXHINSTANCE hInstance, WXHINSTANCE WXUNUSED(hPrevInstance), char *m_
return 0;
}
// Split command line into tokens, as in usual main(argc, argv)
char **command = new char*[50];
int count = 0;
char *buf = new char[strlen(m_lpCmdLine) + 1];
// Hangs around until end of app. in case
// user carries pointers to the tokens
/* Model independent strcpy */
int i;
for (i = 0; (buf[i] = m_lpCmdLine[i]) != 0; i++)
{
/* loop */;
}
// Get application name
char name[200];
::GetModuleFileName(wxhInstance, name, 199);
// Is it only 16-bit Borland that already copies the program name
// to the first argv index?
#if !defined(__GNUWIN32__)
// #if ! (defined(__BORLANDC__) && !defined(__WIN32__))
command[count++] = copystring(name);
// #endif
#endif
strcpy(name, wxFileNameFromPath(name));
wxStripExtension(name);
wxTheApp->SetAppName(name);
/* Break up string */
// Treat strings enclosed in double-quotes as single arguments
char* str = buf;
while (*str)
{
while (*str && *str <= ' ') str++; // skip whitespace
if (*str == '"')
{
str++;
command[count++] = str;
while (*str && *str != '"') str++;
}
else if (*str)
{
command[count++] = str;
while (*str && *str > ' ') str++;
}
if (*str) *str++ = '\0';
}
command[count] = NULL; /* argv[] is NULL terminated list! */
wxTheApp->argc = count;
wxTheApp->argv = command;
wxTheApp->ConvertToStandardCommandArgs(lpCmdLine);
wxTheApp->m_nCmdShow = nCmdShow;
// GUI-specific initialisation. In fact on Windows we don't have any,
@@ -537,11 +542,6 @@ int wxEntry(WXHINSTANCE hInstance, WXHINSTANCE WXUNUSED(hPrevInstance), char *m_
delete wxTheApp;
wxTheApp = NULL;
delete [] buf ;
// TODO: This should really be cleaned up in ~wxApp
delete [] command[0] ;
delete [] command ;
return 0;
}
@@ -581,10 +581,6 @@ int wxEntry(WXHINSTANCE hInstance, WXHINSTANCE WXUNUSED(hPrevInstance), char *m_
delete wxTheApp;
wxTheApp = NULL;
delete [] buf ;
delete [] command[0] ;
delete [] command ;
#if (WXDEBUG && USE_MEMORY_TRACING) || USE_DEBUG_CONTEXT
// At this point we want to check if there are any memory
// blocks that aren't part of the wxDebugContext itself,
@@ -604,10 +600,12 @@ int wxEntry(WXHINSTANCE hInstance, WXHINSTANCE WXUNUSED(hPrevInstance), char *m_
#else /* _WINDLL */
//// Entry point for DLLs
int wxEntry(WXHINSTANCE hInstance)
{
wxhInstance = (HINSTANCE) hInstance;
wxApp::Initialize((WXHINSTANCE) wxhInstance);
wxApp::Initialize();
// The app may have declared a global application object, but we recommend
// the IMPLEMENT_APP macro is used instead, which sets an initializer function
@@ -644,17 +642,15 @@ int wxEntry(WXHINSTANCE hInstance)
}
#endif // _WINDLL
// Static member initialization
//// Static member initialization
wxAppInitializerFunction wxApp::m_appInitFn = (wxAppInitializerFunction) NULL;
wxApp::wxApp()
{
m_topWindow = NULL;
wxTheApp = this;
// work_proc = NULL ;
m_className = "";
// m_resourceCollection = TRUE;
// m_pendingCleanup = FALSE;
m_wantDebugOutput = TRUE ;
m_appName = "";
argc = 0;
@@ -668,6 +664,17 @@ wxApp::wxApp()
m_auto3D = TRUE;
}
wxApp::~wxApp()
{
// Delete command-line args
int i;
for (i = 0; i < argc; i++)
{
delete[] argv[i];
}
delete argv;
}
bool wxApp::Initialized()
{
#ifndef _WINDLL
@@ -879,60 +886,6 @@ void wxApp::DeletePendingObjects()
}
}
/*
// Free up font objects that are not being used at present.
bool wxApp::DoResourceCleanup()
{
// wxDebugMsg("ResourceCleanup\n");
if (wxTheFontList)
{
wxNode *node = wxTheFontList->First();
while (node)
{
wxGDIObject *obj = (wxGDIObject *)node->Data();
if ((obj->GetResourceHandle() != 0) && (obj->GetResourceUsage() == 0))
{
// wxDebugMsg("Freeing font %ld (GDI object %d)\n", (long)obj, (int)obj->GetResourceHandle());
obj->FreeResource();
}
node = node->Next();
}
}
if (wxThePenList)
{
wxNode *node = wxThePenList->First();
while (node)
{
wxGDIObject *obj = (wxGDIObject *)node->Data();
if ((obj->GetResourceHandle() != 0) && (obj->GetResourceUsage() == 0))
{
// wxDebugMsg("Freeing pen %ld (GDI object %d)\n", (long)obj, (int)obj->GetResourceHandle());
obj->FreeResource();
}
node = node->Next();
}
}
if (wxTheBrushList)
{
wxNode *node = wxTheBrushList->First();
while (node)
{
wxGDIObject *obj = (wxGDIObject *)node->Data();
if ((obj->GetResourceHandle() != 0) && (obj->GetResourceUsage() == 0))
{
// wxDebugMsg("Freeing brush %ld (GDI object %d)\n", (long)obj, (int)obj->GetResourceHandle());
obj->FreeResource();
}
node = node->Next();
}
}
SetPendingCleanup(FALSE);
return FALSE;
}
*/
wxLog* wxApp::CreateLogTarget()
{
return new wxLogGui;

38
src/stubs/app.cpp
View File

@@ -53,7 +53,7 @@ END_EVENT_TABLE()
long wxApp::sm_lastMessageTime = 0;
void wxApp::CommonInit()
bool wxApp::Initialize()
{
#ifdef __WXMSW__
wxBuffer = new char[1500];
@@ -61,6 +61,14 @@ void wxApp::CommonInit()
wxBuffer = new char[BUFSIZ + 512];
#endif
#if (WXDEBUG && USE_MEMORY_TRACING) || USE_DEBUG_CONTEXT
streambuf* sBuf = new wxDebugStreamBuf;
ostream* oStr = new ostream(sBuf) ;
wxDebugContext::SetStream(oStr, sBuf);
#endif
wxClassInfo::InitializeClasses();
wxTheColourDatabase = new wxColourDatabase(wxKEY_STRING);
@@ -82,9 +90,11 @@ void wxApp::CommonInit()
wxModule::RegisterModules();
wxASSERT( wxModule::InitializeModules() == TRUE );
return TRUE;
}
void wxApp::CommonCleanUp()
void wxApp::CleanUp()
{
wxModule::CleanUpModules();
@@ -132,20 +142,8 @@ void wxApp::CommonCleanUp()
int wxEntry( int argc, char *argv[] )
{
wxClassInfo::InitializeClasses();
#if (WXDEBUG && USE_MEMORY_TRACING) || USE_DEBUG_CONTEXT
#if !defined(_WINDLL)
streambuf* sBuf = new wxDebugStreamBuf;
#else
streambuf* sBuf = NULL;
#endif
ostream* oStr = new ostream(sBuf) ;
wxDebugContext::SetStream(oStr, sBuf);
#endif
if (!wxApp::Initialize())
return FALSE;
if (!wxTheApp)
{
if (!wxApp::GetInitializerFunction())
@@ -166,10 +164,6 @@ int wxEntry( int argc, char *argv[] )
wxTheApp->argc = argc;
wxTheApp->argv = argv;
// TODO: your platform-specific initialization.
wxApp::CommonInit();
// GUI-specific initialization, such as creating an app context.
wxTheApp->OnInitGui();
@@ -193,7 +187,7 @@ int wxEntry( int argc, char *argv[] )
wxTheApp->OnExit();
wxApp::CommonCleanUp();
wxApp::CleanUp();
delete wxTheApp;
wxTheApp = NULL;
@@ -393,7 +387,7 @@ wxWindow* wxApp::GetTopWindow() const
void wxExit()
{
wxApp::CommonCleanUp();
wxApp::CleanUp();
/*
* TODO: Exit in some platform-specific way. Not recommended that the app calls this:
* only for emergencies.