// Purpose: interface of wxApp
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
objects in the application (see wxAppConsole::FilterEvent)
@li implement Apple-specific event handlers (see wxAppConsole::MacXXX functions)
- You should use the macro IMPLEMENT_APP(appClass) in your application
+ You should use the macro wxIMPLEMENT_APP(appClass) in your application
implementation file to tell wxWidgets how to create an instance of your
application class.
- Use DECLARE_APP(appClass) in a header file if you want the ::wxGetApp() function
+ Use wxDECLARE_APP(appClass) in a header file if you want the ::wxGetApp() function
(which returns a reference to your application object) to be visible to other
files.
static bool IsMainLoopRunning();
- /**
- @name Mac-specific functions
- */
- //@{
-
- /**
- Called in response of an "open-application" Apple event.
- Override this to create a new document in your app.
-
- @onlyfor{wxosx}
- */
- virtual void MacNewFile();
-
- /**
- Called in response of an "open-document" Apple event.
-
- You need to override this method in order to open a document file after the
- user double clicked on it or if the document file was dropped on either the
- running application or the application icon in Finder.
-
- @onlyfor{wxosx}
- */
- virtual void MacOpenFile(const wxString& fileName);
-
- /**
- Called in response of a "get-url" Apple event.
-
- @onlyfor{wxosx}
- */
- virtual void MacOpenURL(const wxString& url);
-
- /**
- Called in response of a "print-document" Apple event.
-
- @onlyfor{wxosx}
- */
- virtual void MacPrintFile(const wxString& fileName);
-
- /**
- Called in response of a "reopen-application" Apple event.
-
- @onlyfor{wxosx}
- */
- virtual void MacReopenApp();
-
- //@}
-
-
/**
@name Callbacks for application-wide "events"
*/
/**
This function may be called if something fatal happens: an unhandled
- exception under Win32 or a a fatal signal under Unix, for example. However,
+ exception under Win32 or a fatal signal under Unix, for example. However,
this will not happen by default: you have to explicitly call
wxHandleFatalExceptions() to enable this.
You may use OnExit() to clean up anything initialized here, provided
that the function returns @true.
- Notice that if you want to to use the command line processing provided by
+ Notice that if you want to use the command line processing provided by
wxWidgets you have to call the base class version in the derived class
OnInit().
virtual int OnRun();
/**
- This function is called when an unhandled C++ exception occurs inside
- OnRun() (the exceptions which occur during the program startup and shutdown
- might not be caught at all). Notice that by now the main event loop has been
- terminated and the program will exit, if you want to prevent this from happening
- (i.e. continue running after catching an exception) you need to override
- OnExceptionInMainLoop().
+ This function is called when an unhandled C++ exception occurs in user
+ code called by wxWidgets.
+
+ Any unhandled exceptions thrown from (overridden versions of) OnInit()
+ and OnExit() methods as well as any exceptions thrown from inside the
+ main loop and re-thrown by OnUnhandledException() will result in a call
+ to this function.
- The default implementation shows information about the exception in debug build
- but does nothing in the release build.
+ By the time this function is called, the program is already about to
+ exit and the exception can't be handled nor ignored any more, override
+ OnUnhandledException() or use explicit @c try/catch blocks around
+ OnInit() body to be able to handle the exception earlier.
+
+ The default implementation dumps information about the exception using
+ wxMessageOutputBest.
*/
virtual void OnUnhandledException();
Under Windows and Linux/Unix, you should parse the command line
arguments and check for files to be opened when starting your
- application. Under OS X, you need to override MacOpenFile()
+ application. Under OS X, you need to override MacOpenFiles()
since command line arguments are used differently there.
You may use the wxCmdLineParser to parse command line arguments.
*/
bool ProcessMessage(WXMSG* msg);
- /**
- Sends idle events to a window and its children.
- Please note that this function is internal to wxWidgets and shouldn't be used
- by user code.
-
- @remarks These functions poll the top-level windows, and their children,
- for idle event processing. If @true is returned, more OnIdle
- processing is requested by one or more window.
-
- @see wxIdleEvent
- */
- virtual bool SendIdleEvents(wxWindow* win, wxIdleEvent& event);
-
/**
Set display mode to use. This is only used in framebuffer wxWidgets
ports (such as wxMGL or wxDFB).
visual and abort the app if none is found.
*/
void SetUseBestVisual(bool flag, bool forceTrueColour = false);
+
+
+ /**
+ @name Mac-specific functions
+ */
+ //@{
+
+ /**
+ Called in response of an "open-application" Apple event.
+ Override this to create a new document in your app.
+
+ @onlyfor{wxosx}
+ */
+ virtual void MacNewFile();
+
+ /**
+ Called in response of an openFiles message with Cocoa, or an
+ "open-document" Apple event with Carbon.
+
+ You need to override this method in order to open one or more document
+ files after the user double clicked on it or if the files and/or
+ folders were dropped on either the application in the dock or the
+ application icon in Finder.
+
+ By default this method calls MacOpenFile for each file/folder.
+
+ @onlyfor{wxosx}
+
+ @since 2.9.3
+ */
+ virtual void MacOpenFiles(const wxArrayString& fileNames);
+
+ /**
+ Called in response of an "open-document" Apple event.
+
+ @deprecated
+ This function is kept mostly for backwards compatibility. Please
+ override wxApp::MacOpenFiles method instead in any new code.
+
+ @onlyfor{wxosx}
+ */
+ wxDEPRECATED_BUT_USED_INTERNALLY(
+ virtual void MacOpenFile(const wxString& fileName)
+ );
+
+ /**
+ Called in response of a "get-url" Apple event.
+
+ @onlyfor{wxosx}
+ */
+ virtual void MacOpenURL(const wxString& url);
+
+ /**
+ Called in response of a "print-document" Apple event.
+
+ @onlyfor{wxosx}
+ */
+ virtual void MacPrintFile(const wxString& fileName);
+
+ /**
+ Called in response of a "reopen-application" Apple event.
+
+ @onlyfor{wxosx}
+ */
+ virtual void MacReopenApp();
+
+
+ static long GetMacAboutMenuItemId();
+ static long GetMacPreferencesMenuItemId();
+ static long GetMacExitMenuItemId();
+ static wxString GetMacHelpMenuTitleName();
+
+ static void SetMacAboutMenuItemId(long val);
+ static void SetMacPreferencesMenuItemId(long val);
+ static void SetMacExitMenuItemId(long val);
+ static void SetMacHelpMenuTitleName(const wxString& val);
+
+ //@}
+
};
/**
This is used in headers to create a forward declaration of the ::wxGetApp()
- function implemented by IMPLEMENT_APP().
+ function implemented by wxIMPLEMENT_APP().
- It creates the declaration <tt>className& wxGetApp()</tt>.
+ It creates the declaration <tt>className& wxGetApp()</tt>
+ (requires a final semicolon).
@header{wx/app.h}
Example:
@code
- DECLARE_APP(MyApp)
+ wxDECLARE_APP(MyApp);
@endcode
*/
-#define DECLARE_APP( className )
+#define wxDECLARE_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.
@header{wx/app.h}
Example:
@code
- IMPLEMENT_APP(MyApp)
+ wxIMPLEMENT_APP(MyApp);
@endcode
- @see DECLARE_APP().
+ @see wxDECLARE_APP()
*/
-#define IMPLEMENT_APP( className )
+#define wxIMPLEMENT_APP( className )
//@}
/**
This function doesn't exist in wxWidgets but it is created by using the
- IMPLEMENT_APP() macro.
+ wxIMPLEMENT_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().
+ 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
@def wxDISABLE_DEBUG_SUPPORT()
Use this macro to disable all debugging code in release build when not
- using IMPLEMENT_APP().
+ using wxIMPLEMENT_APP().
Currently this macro disables assert checking and debug and trace level
logging messages in release build (i.e. when @c NDEBUG is defined). It is
- used by IMPLEMENT_APP() macro so you only need to use it explicitly if you
+ 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).
projects / wxWidgets.git / blobdiff