// Purpose: interface of wxApp
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
@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);
/**
- Returns the main event loop instance, i.e. the event loop which is started
+ Returns the main event loop instance, i.e.\ the event loop which is started
by OnRun() and which dispatches all events sent from the native toolkit
to the application (except when new event loops are temporarily set-up).
The returned value maybe @NULL. Put initialization code which needs a
//@}
+ 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 wxAppConsole* GetInstance();
/**
- Returns @true if the main event loop is currently running, i.e. if the
+ Returns @true if the main event loop is currently running, i.e.\ if the
application is inside OnRun().
This can be useful to test whether events can be dispatched. For example,
*/
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 is called when an assert failure occurs, i.e. the condition
+ This function is called when an assert failure occurs, i.e.\ the condition
specified in wxASSERT() macro evaluated to @false.
It is only called in debug mode (when @c __WXDEBUG__ is defined) as
const wxChar *msg);
/**
- Called when command line parsing fails (i.e. an incorrect command line option
+ Called when command line parsing fails (i.e.\ an incorrect command line option
was specified by the user). The default behaviour is to show the program usage
text and abort the program.
/**
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;
virtual wxWindow* GetTopWindow() const;
/**
- Returns @true if the application is active, i.e. if one of its windows is
+ Returns @true if the application is active, i.e.\ if one of its windows is
currently in the foreground.
If this function returns @false and you need to attract users attention to
*/
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();
+
+ //@}
+
};
projects / wxWidgets.git / blobdiff