+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();
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;
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.
//
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();
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
};
//---------------------------------------------------------------------------
%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;
projects / wxWidgets.git / blobdiff