X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/dd9f7fea29e3f8bb61861f52984b7943512346ac..3e3b7e75561ddcad61f12b914ecbc9ad06938789:/wxPython/src/_app.i diff --git a/wxPython/src/_app.i b/wxPython/src/_app.i index 8831abcb90..b5f9b7fbe1 100644 --- a/wxPython/src/_app.i +++ b/wxPython/src/_app.i @@ -40,14 +40,19 @@ enum +DocStr(wxPyApp, +"The ``wx.PyApp`` class is an *implementation detail*, please use the +`wx.App` class (or some other derived class) instead."); class wxPyApp : public wxEvtHandler { public: - %addtofunc wxPyApp + %pythonAppend wxPyApp "self._setCallbackInfo(self, PyApp) self._setOORInfo(self)"; + DocStr(wxPyApp, + "Create a new application object, starting the bootstrap process."); %extend { wxPyApp() { wxPythonApp = new wxPyApp(); @@ -59,99 +64,144 @@ public: void _setCallbackInfo(PyObject* self, PyObject* _class); - // set/get the application name - wxString GetAppName() const; - void SetAppName(const wxString& name); - // set/get the app class name - wxString GetClassName() const; - void SetClassName(const wxString& name); + DocDeclStr( + wxString, GetAppName() const, + "Get the application name."); + DocDeclStr( + void, SetAppName(const wxString& name), + "Set the application name. This value may be used automatically by +`wx.Config` and such."); - // set/get the vendor name - const wxString& GetVendorName() const; - void SetVendorName(const wxString& name); + DocDeclStr( + wxString, GetClassName() const, + "Get the application's class name."); + DocDeclStr( + void, SetClassName(const wxString& name), + "Set the application's class name. This value may be used for +X-resources if applicable for the platform"); - // create the app traits object to which we delegate for everything which - // either should be configurable by the user (then he can change the - // default behaviour simply by overriding CreateTraits() and returning his - // own traits object) or which is GUI/console dependent as then wxAppTraits - // allows us to abstract the differences behind the common façade - wxAppTraits *GetTraits(); + DocDeclStr( + const wxString&, GetVendorName() const, + "Get the application's vendor name."); + DocDeclStr( + void, SetVendorName(const wxString& name), + "Set the application's vendor name. This value may be used +automatically by `wx.Config` and such."); - // process all events in the wxPendingEvents list -- it is necessary to - // call this function to process posted events. This happens during each - // event loop iteration. - virtual void ProcessPendingEvents(); - // process all currently pending events right now - // - // it is an error to call Yield() recursively unless the value of - // onlyIfNeeded is True - // - // WARNING: this function is dangerous as it can lead to unexpected - // reentrancies (i.e. when called from an event handler it - // may result in calling the same event handler again), use - // with _extreme_ care or, better, don't use at all! - virtual bool Yield(bool onlyIfNeeded = False); + DocDeclStr( + wxAppTraits*, GetTraits(), + "Return (and create if necessary) the app traits object to which we +delegate for everything which either should be configurable by the +user (then he can change the default behaviour simply by overriding +CreateTraits() and returning his own traits object) or which is +GUI/console dependent as then wx.AppTraits allows us to abstract the +differences behind the common facade. - // make sure that idle events are sent again - virtual void WakeUpIdle(); +:todo: Add support for overriding CreateAppTraits in wxPython."); - // execute the main GUI loop, the function returns when the loop ends - virtual int MainLoop(); + DocDeclStr( + virtual void, ProcessPendingEvents(), + "Process all events in the Pending Events list -- it is necessary to +call this function to process posted events. This normally happens +during each event loop iteration."); - // exit the main loop thus terminating the application - virtual void Exit(); - // exit the main GUI loop during the next iteration (i.e. it does not - // stop the program immediately!) - virtual void ExitMainLoop(); + DocDeclStr( + virtual bool, Yield(bool onlyIfNeeded = False), + "Process all currently pending events right now, instead of waiting +until return to the event loop. It is an error to call ``Yield`` +recursively unless the value of ``onlyIfNeeded`` is True. - // returns True if there are unprocessed events in the event queue - virtual bool Pending(); +:warning: This function is dangerous as it can lead to unexpected + reentrancies (i.e. when called from an event handler it may + result in calling the same event handler again), use with + _extreme_ care or, better, don't use at all! - // process the first event in the event queue (blocks until an event - // apperas if there are none currently) - virtual bool Dispatch(); +:see: `wx.Yield`, `wx.YieldIfNeeded`, `wx.SafeYield`"); + + DocDeclStr( + virtual void, WakeUpIdle(), + "Make sure that idle events are sent again. +:see: `wx.WakeUpIdle`"); - // this virtual function is called in the GUI mode when the application - // becomes idle and normally just sends wxIdleEvent to all interested - // parties - // - // it should return True if more idle events are needed, False if not - virtual bool ProcessIdle() ; - // Send idle event to window and all subwindows - // Returns True if more idle time is requested. - virtual bool SendIdleEvents(wxWindow* win, wxIdleEvent& event); + DocDeclStr( + virtual int, MainLoop(), + "Execute the main GUI loop, the function doesn't normally return until +all top level windows have been closed and destroyed."); + + + DocDeclStr( + virtual void, Exit(), + "Exit the main loop thus terminating the application. +:see: `wx.Exit`"); - // Perform standard OnIdle behaviour: call from port's OnIdle - void OnIdle(wxIdleEvent& event); + + DocDeclStr( + virtual void, ExitMainLoop(), + "Exit the main GUI loop during the next iteration of the main +loop, (i.e. it does not stop the program immediately!)"); + + DocDeclStr( + virtual bool, Pending(), + "Returns True if there are unprocessed events in the event queue."); - // return True if our app has focus - virtual bool IsActive() const; + + DocDeclStr( + virtual bool, Dispatch(), + "Process the first event in the event queue (blocks until an event +appears if there are none currently)"); - // set the "main" top level window - void SetTopWindow(wxWindow *win); - // return the "main" top level window (if it hadn't been set previously - // with SetTopWindow(), will return just some top level window and, if - // there are none, will return NULL) - virtual wxWindow *GetTopWindow() const; + DocDeclStr( + virtual bool, ProcessIdle(), + "Called from the MainLoop when the application becomes idle (there are +no pending events) and sends a `wx.IdleEvent` to all interested +parties. Returns True if more idle events are needed, False if not."); - // control the exit behaviour: by default, the program will exit the - // main loop (and so, usually, terminate) when the last top-level - // program window is deleted. Beware that if you disable this behaviour - // (with SetExitOnFrameDelete(False)), you'll have to call - // ExitMainLoop() explicitly from somewhere. - void SetExitOnFrameDelete(bool flag); - bool GetExitOnFrameDelete() const; + + DocDeclStr( + virtual bool, SendIdleEvents(wxWindow* win, wxIdleEvent& event), + "Send idle event to window and all subwindows. Returns True if more +idle time is requested."); + + + DocDeclStr( + virtual bool, IsActive() const, + "Return True if our app has focus."); + + + DocDeclStr( + void, SetTopWindow(wxWindow *win), + "Set the *main* top level window"); + + DocDeclStr( + virtual wxWindow*, GetTopWindow() const, + "Return the *main* top level window (if it hadn't been set previously +with SetTopWindow(), will return just some top level window and, if +there not any, will return None)"); + + + DocDeclStr( + void, SetExitOnFrameDelete(bool flag), + "Control the exit behaviour: by default, the program will exit the main +loop (and so, usually, terminate) when the last top-level program +window is deleted. Beware that if you disable this behaviour (with +SetExitOnFrameDelete(False)), you'll have to call ExitMainLoop() +explicitly from somewhere."); + + + DocDeclStr( + bool, GetExitOnFrameDelete() const, + "Get the current exit behaviour setting."); #if 0 - // Get display mode that is used use. This is only used in framebuffer + // Get display mode that is in use. This is only used in framebuffer // wxWin ports (such as wxMGL). virtual wxVideoMode GetDisplayMode() const; @@ -161,9 +211,16 @@ public: virtual bool SetDisplayMode(const wxVideoMode& info); #endif - // set use of best visual flag (see below) - void SetUseBestVisual( bool flag ); - bool GetUseBestVisual() const; + + DocDeclStr( + void, SetUseBestVisual( bool flag ), + "Set whether the app should try to use the best available visual on +systems where more than one is available, (Sun, SGI, XFree86 4, etc.)"); + + DocDeclStr( + bool, GetUseBestVisual() const, + "Get current UseBestVisual setting."); + // set/get printing mode: see wxPRINT_XXX constants. // @@ -172,14 +229,25 @@ public: virtual void SetPrintMode(int mode); int GetPrintMode() const; - // Get/Set OnAssert behaviour. The following flags may be or'd together: - // - // wxPYAPP_ASSERT_SUPPRESS Don't do anything - // wxPYAPP_ASSERT_EXCEPTION Turn it into a Python exception if possible - // wxPYAPP_ASSERT_DIALOG Display a message dialog - // wxPYAPP_ASSERT_LOG Write the assertion info to the wxLog - int GetAssertMode(); - void SetAssertMode(int mode); + + DocDeclStr( + void, SetAssertMode(int mode), + "Set the OnAssert behaviour for debug and hybrid builds. The following +flags may be or'd together: + + ========================= ======================================= + wx.PYAPP_ASSERT_SUPPRESS Don't do anything + wx.PYAPP_ASSERT_EXCEPTION Turn it into a Python exception if possible + (default) + wx.PYAPP_ASSERT_DIALOG Display a message dialog + wx.PYAPP_ASSERT_LOG Write the assertion info to the wx.Log + ========================= ======================================= + +"); + + DocDeclStr( + int, GetAssertMode(), + "Get the current OnAssert behaviour setting."); static bool GetMacSupportPCMenuShortcuts(); @@ -194,17 +262,20 @@ public: static void SetMacExitMenuItemId(long val); static void SetMacHelpMenuTitleName(const wxString& val); - // For internal use only - void _BootstrapApp(); + DocDeclStr( + void, _BootstrapApp(), + "For internal use only"); + + DocStr(GetComCtl32Version, + "Returns 400, 470, 471, etc. for comctl32.dll 4.00, 4.70, 4.71 or 0 if +it wasn't found at all. Raises an exception on non-Windows platforms."); #ifdef __WXMSW__ - // returns 400, 470, 471 for comctl32.dll 4.00, 4.70, 4.71 or 0 if it - // wasn't found at all static int GetComCtl32Version(); #else %extend { static int GetComCtl32Version() - { PyErr_SetNone(PyExc_NotImplementedError); return 0; } + { wxPyRaiseNotImplemented(); return 0; } } #endif }; @@ -214,28 +285,56 @@ public: //--------------------------------------------------------------------------- %newgroup; -// Force an exit from main loop -void wxExit(); -// Yield to other apps/messages -bool wxYield(); -bool wxYieldIfNeeded(); -bool wxSafeYield(wxWindow* win=NULL, bool onlyIfNeeded=False); +DocDeclStr( + void, wxExit(), + "Force an exit of the application. Convenience for wx.GetApp().Exit()"); + -// Cause the message queue to become empty again -void wxWakeUpIdle(); +DocDeclStr( + bool, wxYield(), + "Yield to other apps/messages. Convenience for wx.GetApp().Yield()"); -// Send an event to be processed later -void wxPostEvent(wxEvtHandler *dest, wxEvent& event); +DocDeclStr( + bool, wxYieldIfNeeded(), + "Yield to other apps/messages. Convenience for wx.GetApp().Yield(True)"); -// This is used to cleanup after wxWindows when Python shuts down. + +DocDeclStr( + bool, wxSafeYield(wxWindow* win=NULL, bool onlyIfNeeded=False), + "This function is similar to `wx.Yield`, except that it disables the +user input to all program windows before calling `wx.Yield` and +re-enables it again afterwards. If ``win`` is not None, this window +will remain enabled, allowing the implementation of some limited user +interaction. + +:Returns: the result of the call to `wx.Yield`."); + + +DocDeclStr( + void, wxWakeUpIdle(), + "Cause the message queue to become empty again, so idle events will be +sent."); + + +DocDeclStr( + void, wxPostEvent(wxEvtHandler *dest, wxEvent& event), + "Send an event to a window or other wx.EvtHandler to be processed +later."); + + +DocStr(wxApp_CleanUp, + "For internal use only, it is used to cleanup after wxWindows when +Python shuts down."); %inline %{ void wxApp_CleanUp() { __wxPyCleanup(); } %} -// Return a reference to the current wxApp object. + +DocStr(wxGetApp, + "Return a reference to the current wx.App object."); %inline %{ wxPyApp* wxGetApp() { return (wxPyApp*)wxTheApp;