X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e4431849b4f2097edf0e01c5d50bf0ed947befa9..5eeccdd52c8a7140bfa220d412aa9dc181f7a4d8:/interface/wx/app.h diff --git a/interface/wx/app.h b/interface/wx/app.h index 4e8be1de06..3261fd74aa 100644 --- a/interface/wx/app.h +++ b/interface/wx/app.h @@ -3,7 +3,7 @@ // Purpose: interface of wxApp // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -37,7 +37,8 @@ @see @ref overview_app, wxApp, wxAppTraits, wxEventLoopBase */ -class wxAppConsole : public wxEvtHandler +class wxAppConsole : public wxEvtHandler, + public wxEventFilter { protected: /** @@ -81,13 +82,14 @@ public: 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); @@ -221,6 +223,8 @@ public: //@} + 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. @@ -250,55 +254,6 @@ public: */ 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" */ @@ -420,7 +375,7 @@ public: /** 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. @@ -439,7 +394,7 @@ public: 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(). @@ -468,15 +423,21 @@ public: 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(); @@ -611,7 +572,7 @@ public: 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. @@ -674,7 +635,7 @@ public: /** 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; @@ -764,22 +725,9 @@ public: */ 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); @@ -842,6 +790,72 @@ public: 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(); + + //@} + };