Updated layout test

[wxWidgets.git] / wxPython / src / _app.i

diff --git a/wxPython/src/_app.i b/wxPython/src/_app.i
index 8831abcb90f56df6d5a9b06fb2aed15cc76356d5..b5f9b7fbe171d2cd294a8993d222f9aea0ccc31f 100644 (file)
--- 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:
 
 
 class wxPyApp : public wxEvtHandler {
 public:
 

-    %addtofunc wxPyApp
+    %pythonAppend wxPyApp

        "self._setCallbackInfo(self, PyApp)
         self._setOORInfo(self)";
 
        "self._setCallbackInfo(self, PyApp)
         self._setOORInfo(self)";
 

+    DocStr(wxPyApp,
+           "Create a new application object, starting the bootstrap process.");

     %extend {
         wxPyApp() {
             wxPythonApp = new wxPyApp();
     %extend {
         wxPyApp() {
             wxPythonApp = new wxPyApp();


@@ -59,99 +64,144 @@ public:
 
     void _setCallbackInfo(PyObject* self, PyObject* _class);
 
 
     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 
 
 #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;
     
     // wxWin ports (such as wxMGL).
     virtual wxVideoMode GetDisplayMode() const;
     


@@ -161,9 +211,16 @@ public:
     virtual bool SetDisplayMode(const wxVideoMode& info);
 #endif
     
     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.
     //
 
     // set/get printing mode: see wxPRINT_XXX constants.
     //


@@ -172,14 +229,25 @@ public:
     virtual void SetPrintMode(int mode);
     int GetPrintMode() const;
 
     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 bool GetMacSupportPCMenuShortcuts();


@@ -194,17 +262,20 @@ public:
     static void SetMacExitMenuItemId(long val);
     static void SetMacHelpMenuTitleName(const wxString& val);
 
     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__
 #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()
     static int GetComCtl32Version();
 #else
     %extend {
         static int GetComCtl32Version()

-            { PyErr_SetNone(PyExc_NotImplementedError); return 0; }
+            { wxPyRaiseNotImplemented(); return 0; }

     }
 #endif
 };
     }
 #endif
 };


@@ -214,28 +285,56 @@ public:
 //---------------------------------------------------------------------------
 %newgroup;
 
 //---------------------------------------------------------------------------
 %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();
     }
 %} 
 
 %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;
 %inline %{
     wxPyApp* wxGetApp() {
         return (wxPyApp*)wxTheApp;