// 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.
@see @ref overview_app, wxApp, wxAppTraits, wxEventLoopBase
*/
-class wxAppConsole : public wxEvtHandler
+class wxAppConsole : public wxEvtHandler,
+ public wxEventFilter
{
protected:
/**
virtual void ExitMainLoop();
/**
+ Overridden wxEventFilter method.
+
This function is called before processing any event and allows the application
- to preempt the processing of some events.
+ to preempt the processing of some events, see wxEventFilter
+ documentation for more information.
- If this method returns -1 the event is processed normally, otherwise either
- @true or @false should be returned and the event processing stops immediately
- considering that the event had been already processed (for the former return
- value) or that it is not going to be processed at all (for the latter one).
+ wxApp implementation of this method always return -1 indicating that
+ the event should be processed normally.
*/
virtual int FilterEvent(wxEvent& event);
//@}
+ bool Yield(bool onlyIfNeeded = false);
+
/**
Allows external code to modify global ::wxTheApp, but you should really
know what you're doing if you call it.
*/
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();
//@}
+ /**
+ Sets the C locale to the default locale for the current environment.
+
+ It is advised to call this to ensure that the underlying toolkit uses
+ the locale in which the numbers and monetary amounts are shown in the
+ format expected by user and so on.
+
+ Calling this function is roughly equivalent to calling
+ @code
+ setlocale(LC_ALL, "");
+ @endcode
+ but performs additional toolkit-specific tasks under some platforms and
+ so should be used instead of @c setlocale() itself. Alternatively, you
+ can use wxLocale to change the locale with more control.
+
+ Notice that this does @em not change the global C++ locale, you need to
+ do it explicitly if you want, e.g.
+ @code
+ std::locale::global(std::locale(""));
+ @endcode
+ but be warned that locale support in C++ standard library can be poor
+ or worse under some platforms, e.g. the above line results in an
+ immediate crash under OS X up to the version 10.8.2.
+
+ @since 2.9.5
+ */
+ void SetCLocale();
/**
Number of command line arguments (after environment-specific processing).
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.
/**
Get display mode that is used use. This is only used in framebuffer
- wxWidgets ports (such as wxMGL or wxDFB).
+ wxWidgets ports such as wxDFB.
*/
virtual wxVideoMode GetDisplayMode() const;
*/
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).
+ ports such as wxDFB.
*/
virtual bool SetDisplayMode(const wxVideoMode& info);
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}
+ */
+ 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();
+
+ //@}
+
};
/**
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