Docstring updates and tweaks for epydoc

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@27016 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/wxPython/src/_accel.i b/wxPython/src/_accel.i
index 28e6c5bad234c558b2939264c24810d468b75076..40eade94d61673a6e06d423dea95b9774559dd4d 100644 (file)
--- a/wxPython/src/_accel.i
+++ b/wxPython/src/_accel.i
@@ -30,35 +30,97 @@
 //---------------------------------------------------------------------------
 %newgroup;
 
 //---------------------------------------------------------------------------
 %newgroup;
 

+DocStr(wxAcceleratorEntry,
+"A class used to define items in an `wx.AcceleratorTable`.  wxPython
+programs can choose to use wx.AcceleratorEntry objects, but using a
+list of 3-tuple of integers (flags, keyCode, cmdID) usually works just
+as well.  See `__init__` for details of the tuple values.
+
+:see: `wx.AcceleratorTable`");

 
 class wxAcceleratorEntry {
 public:
 
 class wxAcceleratorEntry {
 public:

-    wxAcceleratorEntry(int flags = 0, int keyCode = 0, int cmd = 0, wxMenuItem *item = NULL);
+    DocCtorStr(
+        wxAcceleratorEntry(int flags = 0, int keyCode = 0, int cmdID = 0/*, wxMenuItem *menuitem = NULL*/),
+        "Construct a wx.AcceleratorEntry.
+
+  :param flags: A bitmask of wx.ACCEL_ALT, wx.ACCEL_SHIFT,
+                wx.ACCEL_CTRL or wx.ACCEL_NORMAL used to specify
+                which modifier keys are held down.
+  :param keyCode: The keycode to be detected
+  :param cmdID: The menu or control command ID to use for the
+                accellerator event.
+");

     ~wxAcceleratorEntry();
 
     ~wxAcceleratorEntry();
 

-    void Set(int flags, int keyCode, int cmd, wxMenuItem *item = NULL);
+    DocDeclStr(
+        void , Set(int flags, int keyCode, int cmd/*, wxMenuItem *menuItem = NULL*/),
+        "(Re)set the attributes of a wx.AcceleratorEntry.
+:see `__init__`");
+    
+
+//     void SetMenuItem(wxMenuItem *item);
+//     wxMenuItem *GetMenuItem() const;
+
+    DocDeclStr(
+        int , GetFlags(),
+        "Get the AcceleratorEntry's flags.");
+    
+    DocDeclStr(
+        int , GetKeyCode(),
+        "Get the AcceleratorEntry's keycode.");
+    
+    DocDeclStr(
+        int , GetCommand(),
+        "Get the AcceleratorEntry's command ID.");
+};
+

 
 

-    void SetMenuItem(wxMenuItem *item);
-    wxMenuItem *GetMenuItem() const;

 
 

-    int GetFlags();
-    int GetKeyCode();
-    int GetCommand();
-};

 
 
 
 

+DocStr(wxAcceleratorTable,
+"An accelerator table allows the application to specify a table of
+keyboard shortcuts for menus or other commands. On Windows, menu or
+button commands are supported; on GTK, only menu commands are
+supported.
+
+The object ``wx.NullAcceleratorTable`` is defined to be a table with
+no data, and is the initial accelerator table for a window.
+
+An accelerator takes precedence over normal processing and can be a
+convenient way to program some event handling. For example, you can
+use an accelerator table to make a hotkey generate an event no matter
+which window within a frame has the focus.
+
+Foe example::
+
+    aTable = wx.AcceleratorTable([(wx.ACCEL_ALT,  ord('X'), exitID),
+                                  (wx.ACCEL_CTRL, ord('H'), helpID),
+                                  (wx.ACCEL_CTRL, ord('F'), findID),
+                                  (wx.ACCEL_NORMAL, wx.WXK_F3, findnextID)
+                                  ])
+    self.SetAcceleratorTable(aTable)
+
+
+:see: `wx.AcceleratorEntry`, `wx.Window.SetAcceleratorTable`
+");
+

 class wxAcceleratorTable : public wxObject {
 public:
     DocAStr(wxAcceleratorTable,
             "__init__(entries) -> AcceleratorTable",
 class wxAcceleratorTable : public wxObject {
 public:
     DocAStr(wxAcceleratorTable,
             "__init__(entries) -> AcceleratorTable",

-            "Construct an AcceleratorTable from a list of AcceleratorEntry items or\n"
-            "3-tuples (flags, keyCode, cmdID)");
+            "Construct an AcceleratorTable from a list of `wx.AcceleratorEntry`
+items or or of 3-tuples (flags, keyCode, cmdID)
+
+:see: `wx.AcceleratorEntry`");

     wxAcceleratorTable(int n, const wxAcceleratorEntry* entries);
     ~wxAcceleratorTable();
 
     bool Ok() const;
 };
 
     wxAcceleratorTable(int n, const wxAcceleratorEntry* entries);
     ~wxAcceleratorTable();
 
     bool Ok() const;
 };
 

+

  
 %immutable;
 // See also wxPy_ReinitStockObjects in helpers.cpp
  
 %immutable;
 // See also wxPy_ReinitStockObjects in helpers.cpp

diff --git a/wxPython/src/_app.i b/wxPython/src/_app.i
index ce26488679f37d5e870a03dc3a6d775f5ee3eb62..b5f9b7fbe171d2cd294a8993d222f9aea0ccc31f 100644 (file)
--- a/wxPython/src/_app.i
+++ b/wxPython/src/_app.i
@@ -40,6 +40,9 @@ 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:


@@ -67,73 +70,81 @@ public:
         "Get the application name.");
     DocDeclStr(
         void, SetAppName(const wxString& name),
         "Get the application name.");
     DocDeclStr(
         void, SetAppName(const wxString& name),

-        "Set the application name. This value may be used automatically\n"
-        "by wx.Config and such.");
+        "Set the application name. This value may be used automatically by
+`wx.Config` and such.");

 
     DocDeclStr(
         wxString, GetClassName() const,
         "Get the application's class name.");
     DocDeclStr(
         void, SetClassName(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\n"
-        "applicable for the platform");
+        "Set the application's class name. This value may be used for
+X-resources if applicable for the platform");

 
     DocDeclStr(
         const wxString&, GetVendorName() const,
         "Get the application's vendor name.");
     DocDeclStr(
         void, SetVendorName(const wxString& name),
 
     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\n"
-        "by wx.Config and such.");
+        "Set the application's vendor name. This value may be used
+automatically by `wx.Config` and such.");

 
 
     DocDeclStr(
         wxAppTraits*, GetTraits(),
 
 
     DocDeclStr(
         wxAppTraits*, GetTraits(),

-        "Create the app traits object to which we delegate for everything which either\n"
-        "should be configurable by the user (then he can change the default behaviour\n"
-        "simply by overriding CreateTraits() and returning his own traits object) or\n"
-        "which is GUI/console dependent as then wx.AppTraits allows us to abstract the\n"
-        "differences behind the common facade");
+        "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.
+
+:todo: Add support for overriding CreateAppTraits in wxPython.");

 
 
     DocDeclStr(
         virtual void, ProcessPendingEvents(),
 
 
     DocDeclStr(
         virtual void, ProcessPendingEvents(),

-        "Process all events in the Pending Events list -- it is necessary to call this\n"
-        "function to process posted events. This happens during each event loop\n"
-        "iteration.");
+        "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.");

 
 
     DocDeclStr(
         virtual bool, Yield(bool onlyIfNeeded = False),
 
 
     DocDeclStr(
         virtual bool, Yield(bool onlyIfNeeded = False),

-        "Process all currently pending events right now, instead of waiting until\n"
-        "return to the event loop.  It is an error to call Yield() recursively unless\n"
-        "the value of onlyIfNeeded is True.\n"
-        "\n"
-        "WARNING: This function is dangerous as it can lead to unexpected\n"
-        "         reentrancies (i.e. when called from an event handler it\n"
-        "         may result in calling the same event handler again), use\n"
-        "         with _extreme_ care or, better, don't use at all!\n");
+        "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.
+
+: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!
+
+:see: `wx.Yield`, `wx.YieldIfNeeded`, `wx.SafeYield`");

 
     
     DocDeclStr(
         virtual void, WakeUpIdle(),
 
     
     DocDeclStr(
         virtual void, WakeUpIdle(),

-        "Make sure that idle events are sent again");
+        "Make sure that idle events are sent again.
+:see: `wx.WakeUpIdle`");

 
 
     DocDeclStr(
         virtual int, MainLoop(),
 
 
     DocDeclStr(
         virtual int, MainLoop(),

-        "Execute the main GUI loop, the function returns when the loop ends.");
+        "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(),
 
     
     DocDeclStr(
         virtual void, Exit(),

-        "Exit the main loop thus terminating the application.");
+        "Exit the main loop thus terminating the application.
+:see: `wx.Exit`");

 
     
     DocDeclStr(
         virtual void, ExitMainLoop(),
 
     
     DocDeclStr(
         virtual void, ExitMainLoop(),

-        "Exit the main GUI loop during the next iteration (i.e. it does not\n"
-        "stop the program immediately!)");
+        "Exit the main GUI loop during the next iteration of the main
+loop, (i.e. it does not stop the program immediately!)");

 
     
     DocDeclStr(
 
     
     DocDeclStr(


@@ -143,21 +154,21 @@ public:
     
     DocDeclStr(
         virtual bool, Dispatch(),
     
     DocDeclStr(
         virtual bool, Dispatch(),

-        "Process the first event in the event queue (blocks until an event\n"
-        "appears if there are none currently)");
+        "Process the first event in the event queue (blocks until an event
+appears if there are none currently)");

 
 
     DocDeclStr(
         virtual bool, ProcessIdle(),
 
 
     DocDeclStr(
         virtual bool, ProcessIdle(),

-        "Called from the MainLoop when the application becomes idle and sends an\n"
-        "IdleEvent to all interested parties.  Returns True is more idle events are\n"
-        "needed, False if not.");
+        "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.");

 
     
     DocDeclStr(
         virtual bool, SendIdleEvents(wxWindow* win, wxIdleEvent& event),
 
     
     DocDeclStr(
         virtual bool, SendIdleEvents(wxWindow* win, wxIdleEvent& event),

-        "Send idle event to window and all subwindows.  Returns True if more idle time\n"
-        "is requested.");
+        "Send idle event to window and all subwindows.  Returns True if more
+idle time is requested.");

 
 
     DocDeclStr(
 
 
     DocDeclStr(


@@ -167,22 +178,22 @@ public:
     
     DocDeclStr(
         void, SetTopWindow(wxWindow *win),
     
     DocDeclStr(
         void, SetTopWindow(wxWindow *win),

-        "Set the \"main\" top level window");
+        "Set the *main* top level window");

 
     DocDeclStr(
         virtual wxWindow*, GetTopWindow() const,
 
     DocDeclStr(
         virtual wxWindow*, GetTopWindow() const,

-        "Return the \"main\" top level window (if it hadn't been set previously with\n"
-        "SetTopWindow(), will return just some top level window and, if there not any,\n"
-        "will return None)");        
+        "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),
 
 
     DocDeclStr(
         void, SetExitOnFrameDelete(bool flag),

-        "Control the exit behaviour: by default, the program will exit the main loop\n"
-        "(and so, usually, terminate) when the last top-level program window is\n"
-        "deleted.  Beware that if you disable this behaviour (with\n"
-        "SetExitOnFrameDelete(False)), you'll have to call ExitMainLoop() explicitly\n"
-        "from somewhere.\n");
+        "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(
 
     
     DocDeclStr(


@@ -203,8 +214,8 @@ public:
     
     DocDeclStr(
         void, SetUseBestVisual( bool flag ),
     
     DocDeclStr(
         void, SetUseBestVisual( bool flag ),

-        "Set whether the app should try to use the best available visual on systems\n"
-        "where more than one is available, (Sun, SGI, XFree86 4, etc.)");
+        "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,
     
     DocDeclStr(
         bool, GetUseBestVisual() const,


@@ -221,13 +232,18 @@ public:
 
     DocDeclStr(
         void, SetAssertMode(int mode),
 
     DocDeclStr(
         void, SetAssertMode(int mode),

-        "Set the OnAssert behaviour for debug and hybrid builds.  The following flags\n"
-        "may be or'd together:\n"
-        "\n"
-        " wx.PYAPP_ASSERT_SUPPRESS         Don't do anything\n"
-        " wx.PYAPP_ASSERT_EXCEPTION        Turn it into a Python exception if possible (default)\n"
-        " wx.PYAPP_ASSERT_DIALOG           Display a message dialog\n"
-        " wx.PYAPP_ASSERT_LOG              Write the assertion info to the wx.Log\n");
+        "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(),
     
     DocDeclStr(
         int,  GetAssertMode(),


@@ -252,9 +268,8 @@ public:
         "For internal use only");
 
     DocStr(GetComCtl32Version,
         "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.");
+           "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__
     static int GetComCtl32Version();
 #else
 #ifdef __WXMSW__
     static int GetComCtl32Version();
 #else


@@ -287,26 +302,30 @@ DocDeclStr(
 
 DocDeclStr(
     bool, wxSafeYield(wxWindow* win=NULL, bool onlyIfNeeded=False),
 
 DocDeclStr(
     bool, wxSafeYield(wxWindow* win=NULL, bool onlyIfNeeded=False),

-    "This function is similar to wx.Yield, except that it disables the user input\n"
-    "to all program windows before calling wx.Yield and re-enables it again\n"
-    "afterwards. If win is not None, this window will remain enabled, allowing the\n"
-    "implementation of some limited user interaction.\n"
-    "\n"
-    "Returns the result of the call to wx.Yield.");
+    "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(),
 
 
 DocDeclStr(
     void,  wxWakeUpIdle(),

-    "Cause the message queue to become empty again, so idle events will be sent.");
+    "Cause the message queue to become empty again, so idle events will be
+sent.");

 
 
 DocDeclStr(
     void, wxPostEvent(wxEvtHandler *dest, wxEvent& event),
 
 
 DocDeclStr(
     void, wxPostEvent(wxEvtHandler *dest, wxEvent& event),

-    "Send an event to a window or other wx.EvtHandler to be processed later.");
+    "Send an event to a window or other wx.EvtHandler to be processed
+later.");

 
 
 DocStr(wxApp_CleanUp,
 
 
 DocStr(wxApp_CleanUp,

-       "For internal use only, it is used to cleanup after wxWindows when Python shuts down.");
+       "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();

diff --git a/wxPython/src/_app_ex.py b/wxPython/src/_app_ex.py
index 15778e811a5947378b76ea2090e577acea0fcb8f..808743dd33f5421fe6f107ee09f9be6d2b57150b 100644 (file)
--- a/wxPython/src/_app_ex.py
+++ b/wxPython/src/_app_ex.py
@@ -67,12 +67,56 @@ _defRedirect = (wx.Platform == '__WXMSW__' or wx.Platform == '__WXMAC__')
 
 class App(wx.PyApp):
     """
 
 class App(wx.PyApp):
     """

-    The main application class.  Derive from this and implement an OnInit
-    method that creates a frame and then calls self.SetTopWindow(frame)
+    The ``wx.App`` class represents the application and is used to:
+
+      * bootstrap the wxPython system and initialize the underlying
+        gui toolkit
+      * set and get application-wide properties
+      * implement the windowing system main message or event loop,
+        and to dispatch events to window instances
+      * etc.
+
+    Every application must have a ``wx.App`` instance, and all
+    creation of UI objects should be delayed until after the
+    ``wx.App`` object has been created in order to ensure that the
+    gui platform and wxWidgets have been fully initialized.
+
+    Normally you would derive from this class and implement an
+    ``OnInit`` method that creates a frame and then calls
+    ``self.SetTopWindow(frame)``.
+
+    :see: `wx.PySimpleApp` for a simpler app class that can be used directly.

     """
     """

+    

     outputWindowClass = PyOnDemandOutputWindow
 
     def __init__(self, redirect=_defRedirect, filename=None, useBestVisual=False):
     outputWindowClass = PyOnDemandOutputWindow
 
     def __init__(self, redirect=_defRedirect, filename=None, useBestVisual=False):

+        """
+        Construct a ``wx.App`` object.  
+
+        :param redirect: Should ``sys.stdout`` and ``sys.stderr``
+            be redirected?  Defaults to True on Windows and Mac,
+            False otherwise.  If `filename` is None then output
+            will be redirected to a window that pops up as
+            needed.  (You can control what kind of window is
+            created for the output by resetting the class
+            variable ``outputWindowClass`` to a class of your
+            choosing.)
+
+        :param filename: The name of a file to redirect output
+            to, if redirect is True.
+
+        :param useBestVisual: Should the app try to use the best
+            available visual provided by the system (only
+            relevant on systems that have more than one visual.)
+            This parameter must be used instead of calling
+            `SetUseBestVisual` later on because it must be set
+            before the underlying GUI toolkit is initialized.
+
+        :note: You should override OnInit to do applicaition
+            initialization to ensure that the system, toolkit and
+            wxWidgets are fully initialized.
+        """

         wx.PyApp.__init__(self)
 
         if wx.Platform == "__WXMAC__":
         wx.PyApp.__init__(self)
 
         if wx.Platform == "__WXMAC__":


@@ -147,7 +191,7 @@ your Mac."""
 
 
 
 
 
 

-# change from wxPyApp_ to wxApp_
+# change from wx.PyApp_XX to wx.App_XX

 App_GetMacSupportPCMenuShortcuts = _core_.PyApp_GetMacSupportPCMenuShortcuts
 App_GetMacAboutMenuItemId        = _core_.PyApp_GetMacAboutMenuItemId
 App_GetMacPreferencesMenuItemId  = _core_.PyApp_GetMacPreferencesMenuItemId
 App_GetMacSupportPCMenuShortcuts = _core_.PyApp_GetMacSupportPCMenuShortcuts
 App_GetMacAboutMenuItemId        = _core_.PyApp_GetMacAboutMenuItemId
 App_GetMacPreferencesMenuItemId  = _core_.PyApp_GetMacPreferencesMenuItemId


@@ -166,9 +210,20 @@ class PySimpleApp(wx.App):
     """
     A simple application class.  You can just create one of these and
     then then make your top level windows later, and not have to worry
     """
     A simple application class.  You can just create one of these and
     then then make your top level windows later, and not have to worry

-    about OnInit."""
+    about OnInit.  For example::
+
+        app = wx.PySimpleApp()
+        frame = wx.Frame(None, title='Hello World')
+        frame.Show()
+        app.MainLoop()
+
+    :see: `wx.App` 
+    """

 
     def __init__(self, redirect=False, filename=None, useBestVisual=False):
 
     def __init__(self, redirect=False, filename=None, useBestVisual=False):

+        """
+        :see: `wx.App.__init__`
+        """

         wx.App.__init__(self, redirect, filename, useBestVisual)
         
     def OnInit(self):
         wx.App.__init__(self, redirect, filename, useBestVisual)
         
     def OnInit(self):


@@ -176,6 +231,7 @@ class PySimpleApp(wx.App):
         return True
 
 
         return True
 
 

+

 # Is anybody using this one?
 class PyWidgetTester(wx.App):
     def __init__(self, size = (250, 100)):
 # Is anybody using this one?
 class PyWidgetTester(wx.App):
     def __init__(self, size = (250, 100)):


@@ -187,15 +243,15 @@ class PyWidgetTester(wx.App):
         self.SetTopWindow(self.frame)
         return True
 
         self.SetTopWindow(self.frame)
         return True
 

-    def SetWidget(self, widgetClass, *args):
-        w = widgetClass(self.frame, *args)
+    def SetWidget(self, widgetClass, *args, **kwargs):
+        w = widgetClass(self.frame, *args, **kwargs)

         self.frame.Show(True)
 
 #----------------------------------------------------------------------------
 # DO NOT hold any other references to this object.  This is how we
         self.frame.Show(True)
 
 #----------------------------------------------------------------------------
 # DO NOT hold any other references to this object.  This is how we

-# know when to cleanup system resources that wxWin is holding.  When
+# know when to cleanup system resources that wxWidgets is holding.  When

 # the sys module is unloaded, the refcount on sys.__wxPythonCleanup
 # the sys module is unloaded, the refcount on sys.__wxPythonCleanup

-# goes to zero and it calls the wxApp_CleanUp function.
+# goes to zero and it calls the wx.App_CleanUp function.

 
 class __wxPyCleanup:
     def __init__(self):
 
 class __wxPyCleanup:
     def __init__(self):


@@ -206,11 +262,8 @@ class __wxPyCleanup:
 _sys.__wxPythonCleanup = __wxPyCleanup()
 
 ## # another possible solution, but it gets called too early...
 _sys.__wxPythonCleanup = __wxPyCleanup()
 
 ## # another possible solution, but it gets called too early...

-## if sys.version[0] == '2':
-##     import atexit
-##     atexit.register(_core_.wxApp_CleanUp)
-## else:
-##     sys.exitfunc = _core_.wxApp_CleanUp
+## import atexit
+## atexit.register(_core_.wxApp_CleanUp)

 
 
 #----------------------------------------------------------------------------
 
 
 #----------------------------------------------------------------------------

diff --git a/wxPython/src/_artprov.i b/wxPython/src/_artprov.i
index 1f6fe34cf32e2a04fa0eb91fe5df89cae9da28ea..e8f19c9eb6d23bfbffd0fd07b6a58b048e8f4e52 100644 (file)
--- a/wxPython/src/_artprov.i
+++ b/wxPython/src/_artprov.i
@@ -102,6 +102,90 @@ public:
 %}
 
 // The one for SWIG to see
 %}
 
 // The one for SWIG to see

+
+
+
+DocStr(wxPyArtProvider,
+"The wx.ArtProvider class is used to customize the look of wxWidgets
+application. When wxWidgets needs to display an icon or a bitmap (e.g.
+in the standard file dialog), it does not use hard-coded resource but
+asks wx.ArtProvider for it instead. This way the users can plug in
+their own wx.ArtProvider class and easily replace standard art with
+his/her own version. It is easy thing to do: all that is needed is
+to derive a class from wx.ArtProvider, override it's CreateBitmap
+method and register the provider with wx.ArtProvider.PushProvider::
+
+    class MyArtProvider(wx.ArtProvider):
+        def __init__(self):
+            wx.ArtProvider.__init__(self)
+
+        def CreateBitmap(self, artid, client, size):
+            ...
+            return bmp
+
+
+Identifying art resources
+-------------------------
+
+Every bitmap is known to wx.ArtProvider under an unique ID that is
+used when requesting a resource from it. The IDs can have one of these
+predefined values:
+
+    * wx.ART_ADD_BOOKMARK
+    * wx.ART_DEL_BOOKMARK
+    * wx.ART_HELP_SIDE_PANEL
+    * wx.ART_HELP_SETTINGS
+    * wx.ART_HELP_BOOK
+    * wx.ART_HELP_FOLDER
+    * wx.ART_HELP_PAGE
+    * wx.ART_GO_BACK
+    * wx.ART_GO_FORWARD
+    * wx.ART_GO_UP
+    * wx.ART_GO_DOWN
+    * wx.ART_GO_TO_PARENT
+    * wx.ART_GO_HOME
+    * wx.ART_FILE_OPEN
+    * wx.ART_PRINT
+    * wx.ART_HELP
+    * wx.ART_TIP
+    * wx.ART_REPORT_VIEW
+    * wx.ART_LIST_VIEW
+    * wx.ART_NEW_DIR
+    * wx.ART_FOLDER
+    * wx.ART_GO_DIR_UP
+    * wx.ART_EXECUTABLE_FILE
+    * wx.ART_NORMAL_FILE
+    * wx.ART_TICK_MARK
+    * wx.ART_CROSS_MARK
+    * wx.ART_ERROR
+    * wx.ART_QUESTION
+    * wx.ART_WARNING
+    * wx.ART_INFORMATION
+    * wx.ART_MISSING_IMAGE 
+
+
+Clients
+-------
+
+The Client is the entity that calls wx.ArtProvider's `GetBitmap` or
+`GetIcon` function.  Client IDs server as a hint to wx.ArtProvider
+that is supposed to help it to choose the best looking bitmap. For
+example it is often desirable to use slightly different icons in menus
+and toolbars even though they represent the same action (e.g.
+wx.ART_FILE_OPEN). Remember that this is really only a hint for
+wx.ArtProvider -- it is common that `wx.ArtProvider.GetBitmap` returns
+identical bitmap for different client values!
+
+    * wx.ART_TOOLBAR
+    * wx.ART_MENU
+    * wx.ART_FRAME_ICON
+    * wx.ART_CMN_DIALOG
+    * wx.ART_HELP_BROWSER
+    * wx.ART_MESSAGE_BOX
+    * wx.ART_OTHER (used for all requests that don't fit into any
+      of the categories above)
+");
+

 %name(ArtProvider) class wxPyArtProvider /*: public wxObject*/
 {
 public:
 %name(ArtProvider) class wxPyArtProvider /*: public wxObject*/
 {
 public:


@@ -111,30 +195,37 @@ public:
     
     void _setCallbackInfo(PyObject* self, PyObject* _class);
 
     
     void _setCallbackInfo(PyObject* self, PyObject* _class);
 

-    DocStr(PushProvider, "Add new provider to the top of providers stack.");
-    static void PushProvider(wxPyArtProvider *provider);
+    DocDeclStr(
+        static void , PushProvider(wxPyArtProvider *provider),
+        "Add new provider to the top of providers stack.");
+    

 
 

-    DocStr(PopProvider, "Remove latest added provider and delete it.");
-    static bool PopProvider();
+    DocDeclStr(
+        static bool , PopProvider(),
+        "Remove latest added provider and delete it.");
+    

 
 

-    DocStr(RemoveProvider,
-           "Remove provider. The provider must have been added previously!\n"
-           "The provider is _not_ deleted.");
-    static bool RemoveProvider(wxPyArtProvider *provider);
+    DocDeclStr(
+        static bool , RemoveProvider(wxPyArtProvider *provider),
+        "Remove provider. The provider must have been added previously!  The
+provider is _not_ deleted.");
+    

 
 

-    DocStr(GetBitmap,
-           "Query the providers for bitmap with given ID and return it. Return\n"
-           "wx.NullBitmap if no provider provides it.");
-    static wxBitmap GetBitmap(const wxString& id,
-                              const wxString& client = wxPyART_OTHER,
-                              const wxSize& size = wxDefaultSize);
+    DocDeclStr(
+        static wxBitmap , GetBitmap(const wxString& id,
+                                    const wxString& client = wxPyART_OTHER,
+                                    const wxSize& size = wxDefaultSize),
+        "Query the providers for bitmap with given ID and return it. Return
+wx.NullBitmap if no provider provides it.");
+    

 
 

-    DocStr(GetIcon,
-           "Query the providers for icon with given ID and return it. Return\n"
-           "wx.NullIcon if no provider provides it.");
-    static wxIcon GetIcon(const wxString& id,
+    DocDeclStr(
+        static wxIcon , GetIcon(const wxString& id,

                           const wxString& client = wxPyART_OTHER,
                           const wxString& client = wxPyART_OTHER,

-                          const wxSize& size = wxDefaultSize);
+                                const wxSize& size = wxDefaultSize),
+        "Query the providers for icon with given ID and return it.  Return
+wx.NullIcon if no provider provides it.");
+    

 
     %extend { void Destroy() { delete self; }}
 };
 
     %extend { void Destroy() { delete self; }}
 };

diff --git a/wxPython/src/_bitmap.i b/wxPython/src/_bitmap.i
index 44f39290e6aa9a9f457d6b9be5269f58b6f12d9e..2b4aaca596eb04abd721179144e119957a188579 100644 (file)
--- a/wxPython/src/_bitmap.i
+++ b/wxPython/src/_bitmap.i
@@ -43,34 +43,83 @@
 // TODO:  When the API stabalizes and is available on other platforms, add
 // wrappers for the new wxBitmap, wxRawBitmap, wxDIB stuff...
 
 // TODO:  When the API stabalizes and is available on other platforms, add
 // wrappers for the new wxBitmap, wxRawBitmap, wxDIB stuff...
 

+DocStr(wxBitmap,
+"The wx.Bitmap class encapsulates the concept of a platform-dependent
+bitmap.  It can be either monochrome or colour, and either loaded from
+a file or created dynamically.  A bitmap can be selected into a memory
+device context (instance of `wx.MemoryDC`). This enables the bitmap to
+be copied to a window or memory device context using `wx.DC.Blit`, or
+to be used as a drawing surface.
+
+The BMP and XMP image file formats are supported on all platforms by
+wx.Bitmap.  Other formats are automatically loaded by `wx.Image` and
+converted to a wx.Bitmap, so any image file format supported by
+`wx.Image` can be used.
+
+:todo: Add wrappers and support for raw bitmap data access.  Can this
+       be be put into Python without losing the speed benefits of the
+       teplates and iterators in rawbmp.h?
+
+:todo: Find a way to do very efficient PIL Image <--> wx.Bitmap
+       converstions.
+");
+

 
 class wxBitmap : public wxGDIObject
 {
 public:
     DocCtorStr(
         wxBitmap(const wxString& name, wxBitmapType type=wxBITMAP_TYPE_ANY),
 
 class wxBitmap : public wxGDIObject
 {
 public:
     DocCtorStr(
         wxBitmap(const wxString& name, wxBitmapType type=wxBITMAP_TYPE_ANY),

-        "Loads a bitmap from a file.");
+        "Loads a bitmap from a file.
+
+:param name:  Name of the file to load the bitmap from.
+:param type: The type of image to expect.  Can be one of the following
+    constants (assuming that the neccessary `wx.Image` handlers are
+    loaded):
+
+        * wx.BITMAP_TYPE_ANY
+        * wx.BITMAP_TYPE_BMP
+        * wx.BITMAP_TYPE_ICO
+        * wx.BITMAP_TYPE_CUR
+        * wx.BITMAP_TYPE_XBM
+        * wx.BITMAP_TYPE_XPM
+        * wx.BITMAP_TYPE_TIF
+        * wx.BITMAP_TYPE_GIF
+        * wx.BITMAP_TYPE_PNG
+        * wx.BITMAP_TYPE_JPEG
+        * wx.BITMAP_TYPE_PNM
+        * wx.BITMAP_TYPE_PCX
+        * wx.BITMAP_TYPE_PICT
+        * wx.BITMAP_TYPE_ICON
+        * wx.BITMAP_TYPE_ANI
+        * wx.BITMAP_TYPE_IFF
+
+:see: Alternate constructors `wx.EmptyBitmap`, `wx.BitmapFromIcon`,
+      `wx.BitmapFromImage`, `wx.BitmapFromXPMData`,
+      `wx.BitmapFromBits`
+");

         
     ~wxBitmap();
 
         
     ~wxBitmap();
 

-//     DocCtorStrName(
-//         wxBitmap(int width, int height, int depth=-1),
-//         "Creates a new bitmap of the given size.  A depth of -1 indicates the depth of\n"
-//         "the current screen or visual. Some platforms only support 1 for monochrome and\n"
-//         "-1 for the current colour setting.",
-//         EmptyBitmap);
+    DocCtorStrName(
+        wxBitmap(int width, int height, int depth=-1),
+        "Creates a new bitmap of the given size.  A depth of -1 indicates the
+depth of the current screen or visual. Some platforms only support 1
+for monochrome and -1 for the current colour setting.",
+        EmptyBitmap);

 
     DocCtorStrName(
         wxBitmap(const wxIcon& icon),
 
     DocCtorStrName(
         wxBitmap(const wxIcon& icon),

-        "Create a new bitmap from an Icon object.",
+        "Create a new bitmap from a `wx.Icon` object.",

         BitmapFromIcon);
 
     DocCtorStrName(
         wxBitmap(const wxImage& image, int depth=-1),
         BitmapFromIcon);
 
     DocCtorStrName(
         wxBitmap(const wxImage& image, int depth=-1),

-        "Creates bitmap object from the image. This has to be done to actually display\n"
-        "an image as you cannot draw an image directly on a window. The resulting\n"
-        "bitmap will use the provided colour depth (or that of the current system if\n"
-        "depth is -1) which entails that a colour reduction has to take place.",
+        "Creates bitmap object from a `wx.Image`. This has to be done to
+actually display a `wx.Image` as you cannot draw an image directly on
+a window. The resulting bitmap will use the provided colour depth (or
+that of the current screen colour depth if depth is -1) which entails
+that a colour reduction may have to take place.",

         BitmapFromImage);
 
     
         BitmapFromImage);
 
     


@@ -90,31 +139,16 @@ public:
         }
 
         DocStr(wxBitmap(PyObject* bits, int width, int height, int depth=1 ),
         }
 
         DocStr(wxBitmap(PyObject* bits, int width, int height, int depth=1 ),

-               "Creates a bitmap from an array of bits.  You should only use this function for\n"
-               "monochrome bitmaps (depth 1) in portable programs: in this case the bits\n"
-               "parameter should contain an XBM image.  For other bit depths, the behaviour is\n"
-               "platform dependent.");
+               "Creates a bitmap from an array of bits.  You should only use this
+function for monochrome bitmaps (depth 1) in portable programs: in
+this case the bits parameter should contain an XBM image.  For other
+bit depths, the behaviour is platform dependent.");

         %name(BitmapFromBits) wxBitmap(PyObject* bits, int width, int height, int depth=1 ) {
             char* buf;
             int   length;
             PyString_AsStringAndSize(bits, &buf, &length);
             return new wxBitmap(buf, width, height, depth);
         }
         %name(BitmapFromBits) wxBitmap(PyObject* bits, int width, int height, int depth=1 ) {
             char* buf;
             int   length;
             PyString_AsStringAndSize(bits, &buf, &length);
             return new wxBitmap(buf, width, height, depth);
         }

-
-
-        DocStr(wxBitmap(const wxSize& size, int depth=-1), 
-               "Creates a new bitmap of the given size.  A depth of -1 indicates
-the depth of the current screen or visual. Some platforms only
-support 1 for monochrome and -1 for the current colour setting.");
-
-        %nokwargs wxBitmap(int width, int height, int depth=-1);
-        %nokwargs wxBitmap(const wxSize& size, int depth=-1);
-        %name(EmptyBitmap)wxBitmap(int width, int height, int depth=-1) {
-            return new wxBitmap(width, height, depth);
-        }
-        %name(EmptyBitmap)wxBitmap(const wxSize& size, int depth=-1) {
-            return new wxBitmap(size.x, size.y, depth);
-        }

     }    
 
     
     }    
 
     


@@ -132,16 +166,21 @@ support 1 for monochrome and -1 for the current colour setting.");
 
     bool Ok();
     
 
     bool Ok();
     

-    DocStr(GetWidth, "Gets the width of the bitmap in pixels.");
-    int GetWidth();
+    DocDeclStr(
+        int , GetWidth(),
+        "Gets the width of the bitmap in pixels.");
+    

 
 

-    DocStr(GetHeight, "Gets the height of the bitmap in pixels.");
-    int GetHeight();
+    DocDeclStr(
+        int , GetHeight(),
+        "Gets the height of the bitmap in pixels.");
+    

 
 

-    DocStr(GetDepth,
-           "Gets the colour depth of the bitmap. A value of 1 indicates a\n"
-           "monochrome bitmap.");
-    int GetDepth();
+    DocDeclStr(
+        int , GetDepth(),
+        "Gets the colour depth of the bitmap. A value of 1 indicates a
+monochrome bitmap.");
+    

 
 
     %extend {
 
 
     %extend {


@@ -153,20 +192,29 @@ support 1 for monochrome and -1 for the current colour setting.");
     }
 
     
     }
 
     

-    DocStr(ConvertToImage,
-           "Creates a platform-independent image from a platform-dependent bitmap. This\n"
-           "preserves mask information so that bitmaps and images can be converted back\n"
-           "and forth without loss in that respect.");
-    virtual wxImage ConvertToImage() const;
-
-    DocStr(GetMask,
-           "Gets the associated mask (if any) which may have been loaded from a file\n"
-           "or explpicitly set for the bitmap.");
-    virtual wxMask* GetMask() const;
-
-    DocStr(SetMask,
-           "Sets the mask for this bitmap.");
-    virtual void SetMask(wxMask* mask);
+    DocDeclStr(
+        virtual wxImage , ConvertToImage() const,
+        "Creates a platform-independent image from a platform-dependent
+bitmap. This preserves mask information so that bitmaps and images can
+be converted back and forth without loss in that respect.");
+    
+
+    DocDeclStr(
+        virtual wxMask* , GetMask() const,
+        "Gets the associated mask (if any) which may have been loaded from a
+file or explpicitly set for the bitmap.
+
+:see: `SetMask`, `wx.Mask`
+");
+    
+
+    DocDeclStr(
+        virtual void , SetMask(wxMask* mask),
+        "Sets the mask for this bitmap.
+
+:see: `GetMask`, `wx.Mask`
+");
+    

     
     %extend {
         DocStr(SetMaskColour,
     
     %extend {
         DocStr(SetMaskColour,


@@ -177,17 +225,26 @@ support 1 for monochrome and -1 for the current colour setting.");
         }
     }
 
         }
     }
 

-    DocStr(GetSubBitmap,
-           "Returns a sub bitmap of the current one as long as the rect belongs entirely\n"
-           "to the bitmap. This function preserves bit depth and mask information.");
-    virtual wxBitmap GetSubBitmap(const wxRect& rect) const;

 
 

-    DocStr(SaveFile, "Saves a bitmap in the named file.");
-    virtual bool SaveFile(const wxString &name, wxBitmapType type,
-                          wxPalette *palette = (wxPalette *)NULL);
+    DocDeclStr(
+        virtual wxBitmap , GetSubBitmap(const wxRect& rect) const,
+        "Returns a sub-bitmap of the current one as long as the rect belongs
+entirely to the bitmap. This function preserves bit depth and mask
+information.");
+    
+
+    DocDeclStr(
+        virtual bool , SaveFile(const wxString &name, wxBitmapType type,
+                                wxPalette *palette = NULL),
+        "Saves a bitmap in the named file.  See `__init__` for a description of
+the ``type`` parameter.");
+    

 
 

-    DocStr(LoadFile, "Loads a bitmap from a file");
-    virtual bool LoadFile(const wxString &name, wxBitmapType type);
+    DocDeclStr(
+        virtual bool , LoadFile(const wxString &name, wxBitmapType type),
+        "Loads a bitmap from a file.  See `__init__` for a description of the
+``type`` parameter.");
+    

 
     
 #if wxUSE_PALETTE
 
     
 #if wxUSE_PALETTE


@@ -198,17 +255,23 @@ support 1 for monochrome and -1 for the current colour setting.");
     
     virtual bool CopyFromIcon(const wxIcon& icon);
 
     
     virtual bool CopyFromIcon(const wxIcon& icon);
 

-    DocStr(SetHeight, "Set the height property (does not affect the bitmap data).")
-    virtual void SetHeight(int height);
+    DocDeclStr(
+        virtual void , SetHeight(int height),
+        "Set the height property (does not affect the existing bitmap data).");
+    
+    
+    DocDeclStr(
+        virtual void , SetWidth(int width),
+        "Set the width property (does not affect the existing bitmap data).");

     
     

-    DocStr(SetWidth, "Set the width property (does not affect the bitmap data).")
-    virtual void SetWidth(int width);

 
 

-    DocStr(SetDepth, "Set the depth property (does not affect the bitmap data).")
-    virtual void SetDepth(int depth);
+    DocDeclStr(
+        virtual void , SetDepth(int depth),
+        "Set the depth property (does not affect the existing bitmap data).");
+    

 
     %extend {
 
     %extend {

-        DocStr(SetSize, "Set the bitmap size");
+        DocStr(SetSize, "Set the bitmap size (does not affect the existing bitmap data).");

         void SetSize(const wxSize& size) {
             self->SetWidth(size.x);
             self->SetHeight(size.y);
         void SetSize(const wxSize& size) {
             self->SetWidth(size.x);
             self->SetHeight(size.y);


@@ -233,22 +296,28 @@ support 1 for monochrome and -1 for the current colour setting.");
 //---------------------------------------------------------------------------
 
 DocStr(wxMask,
 //---------------------------------------------------------------------------
 
 DocStr(wxMask,

-       "This class encapsulates a monochrome mask bitmap, where the masked area is\n"
-       "black and the unmasked area is white. When associated with a bitmap and drawn\n"
-       "in a device context, the unmasked area of the bitmap will be drawn, and the\n"
-       "masked area will not be drawn.");
+"This class encapsulates a monochrome mask bitmap, where the masked
+area is black and the unmasked area is white. When associated with a
+bitmap and drawn in a device context, the unmasked area of the bitmap
+will be drawn, and the masked area will not be drawn.
+
+A mask may be associated with a `wx.Bitmap`. It is used in
+`wx.DC.DrawBitmap` or `wx.DC.Blit` when the source device context is a
+`wx.MemoryDC` with a `wx.Bitmap` selected into it that contains a
+mask.
+");

 
 class wxMask : public wxObject {
 public:
 
 class wxMask : public wxObject {
 public:

-#if 0
-    DocCtorStr(
-        wxMask(const wxBitmap& bitmap),
-        "Constructs a mask from a monochrome bitmap.");
-#endif

 
     DocStr(wxMask,
 
     DocStr(wxMask,

-           "Constructs a mask from a bitmap and a colour in that bitmap that indicates\n"
-           "the transparent portions of the mask, by default BLACK is used.");
+           "Constructs a mask from a `wx.Bitmap` and a `wx.Colour` in that bitmap
+that indicates the transparent portions of the mask.  In other words,
+the pixels in ``bitmap`` that match ``colour`` will be the transparent
+portions of the mask.  If no ``colour`` or an invalid ``colour`` is
+passed then BLACK is used.
+
+:see: `wx.Bitmap`, `wx.Colour`");

     
     %extend {
         wxMask(const wxBitmap& bitmap, const wxColour& colour = wxNullColour) {
     
     %extend {
         wxMask(const wxBitmap& bitmap, const wxColour& colour = wxNullColour) {


@@ -262,7 +331,7 @@ public:
     //~wxMask();
 };
 
     //~wxMask();
 };
 

-%pythoncode { MaskColour = Mask }
+%pythoncode { MaskColour = wx._deprecated(Mask, "wx.MaskColour is deprecated, use `wx.Mask` instead.") }

 
 //---------------------------------------------------------------------------
 //---------------------------------------------------------------------------
 
 //---------------------------------------------------------------------------
 //---------------------------------------------------------------------------

diff --git a/wxPython/src/_brush.i b/wxPython/src/_brush.i
index c3e27280d503b3556d95b3020fe200adc75020a5..45503e817f750967ca8a282f39902e8b5321d5b4 100644 (file)
--- a/wxPython/src/_brush.i
+++ b/wxPython/src/_brush.i
@@ -17,25 +17,81 @@
 %newgroup
 
 DocStr(wxBrush,
 %newgroup
 
 DocStr(wxBrush,

-       "A brush is a drawing tool for filling in areas. It is used for painting the\n"
-       "background of rectangles, ellipses, etc. It has a colour and a style.");
+"A brush is a drawing tool for filling in areas. It is used for
+painting the background of rectangles, ellipses, etc. when drawing on
+a `wx.DC`.  It has a colour and a style.
+
+:warning: Do not create instances of wx.Brush before the `wx.App`
+    object has been created because, depending on the platform,
+    required internal data structures may not have been initialized
+    yet.  Instead create your brushes in the app's OnInit or as they
+    are needed for drawing.
+
+:note: On monochrome displays all brushes are white, unless the colour
+    really is black.
+
+:see: `wx.BrushList`, `wx.DC`, `wx.DC.SetBrush`
+");

 
 class wxBrush : public wxGDIObject {
 public:
 
 class wxBrush : public wxGDIObject {
 public:

-    DocStr(wxBrush, "Constructs a brush from a colour object and style.");
-    wxBrush(const wxColour& colour, int style=wxSOLID);
+    DocCtorStr(
+        wxBrush(const wxColour& colour, int style=wxSOLID),
+        "Constructs a brush from a `wx.Colour` object and a style.  The style
+parameter may be one of the following:
+
+    ===================   =============================
+    Style                 Meaning
+    ===================   =============================
+    wx.TRANSPARENT        Transparent (no fill).
+    wx.SOLID              Solid.
+    wx.STIPPLE            Uses a bitmap as a stipple.
+    wx.BDIAGONAL_HATCH    Backward diagonal hatch.
+    wx.CROSSDIAG_HATCH    Cross-diagonal hatch.
+    wx.FDIAGONAL_HATCH    Forward diagonal hatch.
+    wx.CROSS_HATCH        Cross hatch.
+    wx.HORIZONTAL_HATCH   Horizontal hatch.
+    wx.VERTICAL_HATCH     Vertical hatch.
+    ===================   =============================
+
+");
+

     ~wxBrush();
     ~wxBrush();

-    
-    
-    virtual void SetColour(const wxColour& col);
-    virtual void SetStyle(int style);
-    virtual void SetStipple(const wxBitmap& stipple);

 
 

-    wxColour GetColour() const;
-    int GetStyle() const;
-    wxBitmap *GetStipple() const;

 
 

-    bool Ok();
+    DocDeclStr(
+        virtual void , SetColour(const wxColour& col),
+        "Set the brush's `wx.Colour`.");
+
+    DocDeclStr(
+        virtual void , SetStyle(int style),
+        "Sets the style of the brush. See `__init__` for a listing of styles.");
+
+    DocDeclStr(
+        virtual void , SetStipple(const wxBitmap& stipple),
+        "Sets the stipple `wx.Bitmap`.");
+
+
+    DocDeclStr(
+        wxColour , GetColour() const,
+        "Returns the `wx.Colour` of the brush.");
+
+    DocDeclStr(
+        int , GetStyle() const,
+        "Returns the style of the brush.  See `__init__` for a listing of
+styles.");
+
+    DocDeclStr(
+        wxBitmap *, GetStipple() const,
+        "Returns the stiple `wx.Bitmap` of the brush.  If the brush does not
+have a wx.STIPPLE style, then the return value may be non-None but an
+uninitialised bitmap (`wx.Bitmap.Ok` returns False).");
+
+
+    DocDeclStr(
+        bool , Ok(),
+        "Returns True if the brush is initialised and valid.");
+

 
 #ifdef __WXMAC__
     short MacGetTheme();
 
 #ifdef __WXMAC__
     short MacGetTheme();

diff --git a/wxPython/src/_button.i b/wxPython/src/_button.i
index 320f480990712ac145949ebff74912a1c1366135..be6ec069cc9187d989bc502d2d3fd162b24097a2 100644 (file)
--- a/wxPython/src/_button.i
+++ b/wxPython/src/_button.i
@@ -31,21 +31,31 @@ enum {
 //---------------------------------------------------------------------------
 
 DocStr(wxButton,
 //---------------------------------------------------------------------------
 
 DocStr(wxButton,

-       "A button is a control that contains a text string, and is one of the most\n"
-       "common elements of a GUI.  It may be placed on a dialog box or panel, or\n"
-       "indeed almost any other window.");
-
-RefDoc(wxButton,  "
- Styles
-    wx.BU_LEFT:     Left-justifies the label. WIN32 only.
-    wx.BU_TOP:      Aligns the label to the top of the button. WIN32 only.
-    wx.BU_RIGHT:    Right-justifies the bitmap label. WIN32 only.
-    wx.BU_BOTTOM:   Aligns the label to the bottom of the button. WIN32 only.
-    wx.BU_EXACTFIT: Creates the button as small as possible instead of making
-                    it of the standard size (which is the default behaviour.)
-
- Events
-     EVT_BUTTON:    Sent when the button is clicked.
+"A button is a control that contains a text string, and is one of the most
+common elements of a GUI.  It may be placed on a dialog box or panel, or
+indeed almost any other window.
+
+Window Styles
+-------------
+    ==============   ==========================================
+    wx.BU_LEFT       Left-justifies the label. WIN32 only.
+    wx.BU_TOP        Aligns the label to the top of the button.
+                     WIN32 only.
+    wx.BU_RIGHT      Right-justifies the bitmap label. WIN32 only.
+    wx.BU_BOTTOM     Aligns the label to the bottom of the button.
+                     WIN32 only.
+    wx.BU_EXACTFIT   Creates the button as small as possible
+                     instead of making it of the standard size
+                     (which is the default behaviour.)
+    ==============   ==========================================
+
+Events
+------
+    ============     ==========================================
+    EVT_BUTTON       Sent when the button is clicked.
+    ============     ==========================================
+
+:see: `wx.BitmapButton`

 ");
 
 class wxButton : public wxControl
 ");
 
 class wxButton : public wxControl


@@ -55,41 +65,40 @@ public:
     %pythonAppend wxButton()       ""
 
 
     %pythonAppend wxButton()       ""
 
 

-    DocStr(wxButton, "Create and show a button.");

     RefDoc(wxButton, "");
     RefDoc(wxButton, "");

-    wxButton(wxWindow* parent, wxWindowID id, const wxString& label,
-             const wxPoint& pos = wxDefaultPosition,
-             const wxSize& size = wxDefaultSize,
-             long style = 0,
-             const wxValidator& validator = wxDefaultValidator,
-             const wxString& name = wxPyButtonNameStr);
-
-    DocStr(wxButton(), "Precreate a Button for 2-phase creation.");
-    %name(PreButton)wxButton();
-
-    DocStr(Create, "Acutally create the GUI Button for 2-phase creation.");
-    bool Create(wxWindow* parent, wxWindowID id, const wxString& label,
-             const wxPoint& pos = wxDefaultPosition,
-             const wxSize& size = wxDefaultSize,
-             long style = 0,
-             const wxValidator& validator = wxDefaultValidator,
-             const wxString& name = wxPyButtonNameStr);
-
-
-    DocStr(SetDefault, "This sets the button to be the default item for the panel or dialog box.");
-    void SetDefault();
-
+    DocCtorStr(
+        wxButton(wxWindow* parent, wxWindowID id, const wxString& label,
+                 const wxPoint& pos = wxDefaultPosition,
+                 const wxSize& size = wxDefaultSize,
+                 long style = 0,
+                 const wxValidator& validator = wxDefaultValidator,
+                 const wxString& name = wxPyButtonNameStr),
+        "Create and show a button.");
+
+    DocCtorStrName(
+        wxButton(),
+        "Precreate a Button for 2-phase creation.",
+        PreButton);
+
+    DocDeclStr(
+        bool , Create(wxWindow* parent, wxWindowID id, const wxString& label,
+                      const wxPoint& pos = wxDefaultPosition,
+                      const wxSize& size = wxDefaultSize,
+                      long style = 0,
+                      const wxValidator& validator = wxDefaultValidator,
+                      const wxString& name = wxPyButtonNameStr),
+        "Acutally create the GUI Button for 2-phase creation.");
+    

 
 

-// #ifdef __WXMSW__
-//     // show the image in the button in addition to the label
-//     void SetImageLabel(const wxBitmap& bitmap);

 
 

-//     // set the margins around the image
-//     void SetImageMargins(wxCoord x, wxCoord y);
-// #endif
+    DocDeclStr(
+        void , SetDefault(),
+        "This sets the button to be the default item for the panel or dialog box.");
+    

 
 

-    DocStr(GetDefaultButtonSize, "Returns the default button size for this platform.");
-    static wxSize GetDefaultSize();
+    DocDeclStr(
+        static wxSize , GetDefaultSize(),
+        "Returns the default button size for this platform.");   

 };
 
 
 };
 
 


@@ -99,27 +108,37 @@ public:
 
 DocStr(wxBitmapButton,
 "A Button that contains a bitmap.  A bitmap button can be supplied with a
 
 DocStr(wxBitmapButton,
 "A Button that contains a bitmap.  A bitmap button can be supplied with a

-single bitmap, and wxWindows will draw all button states using this bitmap. If
+single bitmap, and wxWidgets will draw all button states using this bitmap. If

 the application needs more control, additional bitmaps for the selected state,
 unpressed focused state, and greyed-out state may be supplied.
 the application needs more control, additional bitmaps for the selected state,
 unpressed focused state, and greyed-out state may be supplied.

-");

 
 

-RefDoc(wxBitmapButton,  "
- Styles
-    wx.BU_AUTODRAW: If this is specified, the button will be drawn
-                    automatically using the label bitmap only, providing a
-                    3D-look border. If this style is not specified, the button
-                    will be drawn without borders and using all provided
+Window Styles
+-------------
+    ==============  =============================================
+    wx.BU_AUTODRAW  If this is specified, the button will be drawn
+                    automatically using the label bitmap only,
+                    providing a 3D-look border. If this style is
+                    not specified, the button will be drawn
+                    without borders and using all provided

                     bitmaps. WIN32 only.
                     bitmaps. WIN32 only.

-    wx.BU_LEFT:     Left-justifies the label. WIN32 only.
-    wx.BU_TOP:      Aligns the label to the top of the button. WIN32 only.
-    wx.BU_RIGHT:    Right-justifies the bitmap label. WIN32 only.
-    wx.BU_BOTTOM:   Aligns the label to the bottom of the button. WIN32 only.
-    wx.BU_EXACTFIT: Creates the button as small as possible instead of making
-                    it of the standard size (which is the default behaviour.)
-
- Events
-     EVT_BUTTON:    Sent when the button is clicked.
+    wx.BU_LEFT      Left-justifies the label. WIN32 only.
+    wx.BU_TOP       Aligns the label to the top of the button. WIN32
+                    only.
+    wx.BU_RIGHT     Right-justifies the bitmap label. WIN32 only.
+    wx.BU_BOTTOM    Aligns the label to the bottom of the
+                    button. WIN32 only.
+    wx.BU_EXACTFIT  Creates the button as small as possible
+                    instead of making it of the standard size
+                    (which is the default behaviour.)
+    ==============  =============================================
+
+Events
+------
+     ===========   ==================================
+     EVT_BUTTON    Sent when the button is clicked.
+     ===========   ==================================
+
+:see: `wx.Button`, `wx.Bitmap`

 ");
 
 class wxBitmapButton : public wxButton
 ");
 
 class wxBitmapButton : public wxButton


@@ -128,52 +147,70 @@ public:
     %pythonAppend wxBitmapButton         "self._setOORInfo(self)"
     %pythonAppend wxBitmapButton()       ""
 
     %pythonAppend wxBitmapButton         "self._setOORInfo(self)"
     %pythonAppend wxBitmapButton()       ""
 

-    DocStr(wxBitmapButton, "Create and show a button with a bitmap for the label.")

     RefDoc(wxBitmapButton, ""); // turn it off for the ctors
     RefDoc(wxBitmapButton, ""); // turn it off for the ctors

-    
-    wxBitmapButton(wxWindow* parent, wxWindowID id, const wxBitmap& bitmap,
-                   const wxPoint& pos = wxDefaultPosition,
-                   const wxSize& size = wxDefaultSize,
-                   long style = wxBU_AUTODRAW,
-                   const wxValidator& validator = wxDefaultValidator,
-                   const wxString& name = wxPyButtonNameStr);
-
-    DocStr(wxBitmapButton(), "Precreate a BitmapButton for 2-phase creation.");
-    %name(PreBitmapButton)wxBitmapButton();
-
-    DocStr(Create, "Acutally create the GUI BitmapButton for 2-phase creation.");
-    bool Create(wxWindow* parent, wxWindowID id, const wxBitmap& bitmap,
+
+    DocCtorStr(
+        wxBitmapButton(wxWindow* parent, wxWindowID id, const wxBitmap& bitmap,
+                       const wxPoint& pos = wxDefaultPosition,
+                       const wxSize& size = wxDefaultSize,
+                       long style = wxBU_AUTODRAW,
+                       const wxValidator& validator = wxDefaultValidator,
+                       const wxString& name = wxPyButtonNameStr),
+        "Create and show a button with a bitmap for the label.");
+
+    DocCtorStrName(
+        wxBitmapButton(),
+        "Precreate a BitmapButton for 2-phase creation.",
+        PreBitmapButton);
+
+    DocDeclStr(
+        bool , Create(wxWindow* parent, wxWindowID id, const wxBitmap& bitmap,

                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,
                 long style = wxBU_AUTODRAW,
                 const wxValidator& validator = wxDefaultValidator,
                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,
                 long style = wxBU_AUTODRAW,
                 const wxValidator& validator = wxDefaultValidator,

-                const wxString& name = wxPyButtonNameStr);
-
-    DocStr(GetBitmapLabel, "Returns the label bitmap (the one passed to the constructor).");
-    wxBitmap GetBitmapLabel();
-
-    DocStr(GetBitmapDisabled, "Returns the bitmap for the disabled state.");
-    wxBitmap GetBitmapDisabled();
+                      const wxString& name = wxPyButtonNameStr),
+        "Acutally create the GUI BitmapButton for 2-phase creation.");
+    

 
 

-    DocStr(GetBitmapFocus, "Returns the bitmap for the focused state.");
-    wxBitmap GetBitmapFocus();
+    DocDeclStr(
+        wxBitmap , GetBitmapLabel(),
+        "Returns the label bitmap (the one passed to the constructor).");
+    
+    DocDeclStr(
+        wxBitmap , GetBitmapDisabled(),
+        "Returns the bitmap for the disabled state.");
+    
+    DocDeclStr(
+        wxBitmap , GetBitmapFocus(),
+        "Returns the bitmap for the focused state.");
+    

 
 

-    DocStr(GetBitmapSelected, "Returns the bitmap for the selected state.");
-    wxBitmap GetBitmapSelected();
+    DocDeclStr(
+        wxBitmap , GetBitmapSelected(),
+        "Returns the bitmap for the selected state.");
+    

 
 

-    DocStr(SetBitmapDisabled, "Sets the bitmap for the disabled button appearance.");
-    void SetBitmapDisabled(const wxBitmap& bitmap);
+    DocDeclStr(
+        void , SetBitmapDisabled(const wxBitmap& bitmap),
+        "Sets the bitmap for the disabled button appearance.");
+    

 
 

-    DocStr(SetBitmapFocus, "Sets the bitmap for the button appearance when it has the keyboard focus.");
-    void SetBitmapFocus(const wxBitmap& bitmap);
+    DocDeclStr(
+        void , SetBitmapFocus(const wxBitmap& bitmap),
+        "Sets the bitmap for the button appearance when it has the keyboard focus.");
+    

 
 

-    DocStr(SetBitmapSelected, "Sets the bitmap for the selected (depressed) button appearance.");
-    void SetBitmapSelected(const wxBitmap& bitmap);
+    DocDeclStr(
+        void , SetBitmapSelected(const wxBitmap& bitmap),
+        "Sets the bitmap for the selected (depressed) button appearance.");
+    

 
 

-    DocStr(SetBitmapLabel,
-           "Sets the bitmap label for the button.  This is the bitmap used for the\n"
-           "unselected state, and for all other states if no other bitmaps are provided.");
-    void SetBitmapLabel(const wxBitmap& bitmap);
+    DocDeclStr(
+        void , SetBitmapLabel(const wxBitmap& bitmap),
+        "Sets the bitmap label for the button.  This is the bitmap used for the
+unselected state, and for all other states if no other bitmaps are provided.");
+    

 
     void SetMargins(int x, int y);
     int GetMarginX() const;
 
     void SetMargins(int x, int y);
     int GetMarginX() const;

diff --git a/wxPython/src/_checkbox.i b/wxPython/src/_checkbox.i
index 74b6bbc3e42b80d9d2b4fd404df53f2b2517b063..ae785bad9961e756b91e976b1645bb8be2f81077 100644 (file)
--- a/wxPython/src/_checkbox.i
+++ b/wxPython/src/_checkbox.i
@@ -45,24 +45,35 @@ enum wxCheckBoxState
 //---------------------------------------------------------------------------
 
 DocStr(wxCheckBox,
 //---------------------------------------------------------------------------
 
 DocStr(wxCheckBox,

-"A checkbox is a labelled box which by default is either on (checkmark is
-visible) or off (no checkmark). Optionally (When the wxCHK_3STATE style flag
-is set) it can have a third state, called the mixed or undetermined
-state. Often this is used as a \"Does Not Apply\" state.");
-
-RefDoc(wxCheckBox, "
- Styles
-    wx.CHK_2STATE:     Create a 2-state checkbox. This is the default.
-    wx.CHK_3STATE:     Create a 3-state checkbox.
-    wx.CHK_ALLOW_3RD_STATE_FOR_USER: By default a user can't set a 3-state
-                                     checkbox to the third state. It can only
-                                     be done from code. Using this flags
-                                     allows the user to set the checkbox to
-                                     the third state by clicking.
-    wx.ALIGN_RIGHT:    Makes the text appear on the left of the checkbox.
-
- Events
-    EVT_CHECKBOX:       Sent when checkbox is clicked.
+"A checkbox is a labelled box which by default is either on (the
+checkmark is visible) or off (no checkmark). Optionally (When the
+wx.CHK_3STATE style flag is set) it can have a third state, called the
+mixed or undetermined state. Often this is used as a \"Does Not
+Apply\" state.
+
+Window Styles
+-------------
+    =================================  ===============================
+    wx.CHK_2STATE                      Create a 2-state checkbox. 
+                                       This is the default.
+    wx.CHK_3STATE                      Create a 3-state checkbox.
+    wx.CHK_ALLOW_3RD_STATE_FOR_USER    By default a user can't set a
+                                       3-state checkbox to the
+                                       third state. It can only be
+                                       done from code. Using this
+                                       flags allows the user to set
+                                       the checkbox to the third
+                                       state by clicking.
+                                       wx.ALIGN_RIGHT Makes the
+                                       text appear on the left of
+                                       the checkbox.
+    =================================  ===============================
+
+Events
+------
+    ===============================  ===============================
+    EVT_CHECKBOX                     Sent when checkbox is clicked.
+    ===============================  ===============================

 ");
 
 
 ");
 
 


@@ -102,31 +113,33 @@ public:
     
     DocDeclStr(
         bool, GetValue(),
     
     DocDeclStr(
         bool, GetValue(),

-        "Gets the state of a 2-state CheckBox.  Returns True if it is checked,\n"
-        "False otherwise.");
+        "Gets the state of a 2-state CheckBox.  Returns True if it is checked,
+False otherwise.");

     
     DocDeclStr(
         bool, IsChecked(),
     
     DocDeclStr(
         bool, IsChecked(),

-        "Similar to GetValue, but raises an exception if it is not a 2-state CheckBox.");
+        "Similar to GetValue, but raises an exception if it is not a 2-state
+CheckBox.");

     
     DocDeclStr(
         void, SetValue(const bool state),
     
     DocDeclStr(
         void, SetValue(const bool state),

-        "Set the state of a 2-state CheckBox.  Pass True for checked,\n"
-        "False for unchecked.");
+        "Set the state of a 2-state CheckBox.  Pass True for checked, False for
+unchecked.");

     
     DocDeclStr(
         wxCheckBoxState, Get3StateValue() const,
     
     DocDeclStr(
         wxCheckBoxState, Get3StateValue() const,

-        "Returns wx.CHK_UNCHECKED when the CheckBox is unchecked, wx.CHK_CHECKED when\n"
-        "it is checked and wx.CHK_UNDETERMINED when it's in the undetermined state.\n"
-        "Raises an exceptiion when the function is used with a 2-state CheckBox.");
+        "Returns wx.CHK_UNCHECKED when the CheckBox is unchecked,
+wx.CHK_CHECKED when it is checked and wx.CHK_UNDETERMINED when it's in
+the undetermined state.  Raises an exceptiion when the function is
+used with a 2-state CheckBox.");

     
     DocDeclStr(
         void, Set3StateValue(wxCheckBoxState state),
     
     DocDeclStr(
         void, Set3StateValue(wxCheckBoxState state),

-        "Sets the CheckBox to the given state.  The state parameter can be\n"
-        "one of the following: wx.CHK_UNCHECKED (Check is off), wx.CHK_CHECKED\n"
-        "(Check is on) or wx.CHK_UNDETERMINED (Check is mixed). Raises an\n"
-        "exception  when the CheckBox is a 2-state checkbox and setting the state\n"
-        "to wx.CHK_UNDETERMINED.");
+        "Sets the CheckBox to the given state.  The state parameter can be one
+of the following: wx.CHK_UNCHECKED (Check is off), wx.CHK_CHECKED (the
+Check is on) or wx.CHK_UNDETERMINED (Check is mixed). Raises an
+exception when the CheckBox is a 2-state checkbox and setting the
+state to wx.CHK_UNDETERMINED.");

     
     DocDeclStr(
         bool, Is3State() const,
     
     DocDeclStr(
         bool, Is3State() const,


@@ -134,7 +147,8 @@ public:
     
     DocDeclStr(
         bool, Is3rdStateAllowedForUser() const,
     
     DocDeclStr(
         bool, Is3rdStateAllowedForUser() const,

-        "Returns whether or not the user can set the CheckBox to the third state.");
+        "Returns whether or not the user can set the CheckBox to the third
+state.");

     
 };
 
     
 };
 

diff --git a/wxPython/src/_choice.i b/wxPython/src/_choice.i
index a4b46b980e299841b5a79e806963a7ef404cc005..fa5deae4cac57288ed0dc3de3cd0c2800dbcc214 100644 (file)
--- a/wxPython/src/_choice.i
+++ b/wxPython/src/_choice.i
@@ -22,12 +22,15 @@ MAKE_CONST_WXSTRING(ChoiceNameStr);
 
 
 DocStr(wxChoice,       
 
 
 DocStr(wxChoice,       

-"A Choice control is used to select one of a list of strings. Unlike a ListBox,
-only the selection is visible until the user pulls down the menu of choices.");
-
-RefDoc(wxChoice, "
- Events
-    EVT_CHOICE:         Sent when an item in the list is selected.
+"A Choice control is used to select one of a list of strings.
+Unlike a `wx.ListBox`, only the selection is visible until the
+user pulls down the menu of choices.
+
+Events
+------
+    ================    ==========================================
+    EVT_CHOICE          Sent when an item in the list is selected.
+    ================    ==========================================

 ");
        
 
 ");
        
 


@@ -47,9 +50,9 @@ public:
                  long style = 0,
                  const wxValidator& validator = wxDefaultValidator,
                  const wxString& name = wxPyChoiceNameStr),
                  long style = 0,
                  const wxValidator& validator = wxDefaultValidator,
                  const wxString& name = wxPyChoiceNameStr),

-        "__init__(Window parent, int id, Point pos=DefaultPosition, Size size=DefaultSize,\n" 
-        "    List choices=[], long style=0, Validator validator=DefaultValidator,\n"
-        "    String name=ChoiceNameStr) -> Choice",
+        "__init__(Window parent, int id, Point pos=DefaultPosition, Size size=DefaultSize,
+    List choices=[], long style=0, Validator validator=DefaultValidator,
+    String name=ChoiceNameStr) -> Choice",

         "Create and show a Choice control");
 
     DocCtorStrName(
         "Create and show a Choice control");
 
     DocCtorStrName(


@@ -66,9 +69,9 @@ public:
                      long style = 0,
                      const wxValidator& validator = wxDefaultValidator,
                      const wxString& name = wxPyChoiceNameStr),
                      long style = 0,
                      const wxValidator& validator = wxDefaultValidator,
                      const wxString& name = wxPyChoiceNameStr),

-        "Create(Window parent, int id, Point pos=DefaultPosition, Size size=DefaultSize,\n" 
-        "    List choices=[], long style=0, Validator validator=DefaultValidator,\n"
-        "    String name=ChoiceNameStr) -> bool",
+        "Create(Window parent, int id, Point pos=DefaultPosition, Size size=DefaultSize,
+    List choices=[], long style=0, Validator validator=DefaultValidator,
+    String name=ChoiceNameStr) -> bool",

         "Actually create the GUI Choice control for 2-phase creation");
     
 
         "Actually create the GUI Choice control for 2-phase creation");
     
 

diff --git a/wxPython/src/_clipbrd.i b/wxPython/src/_clipbrd.i
index f0a2dde60ec8643ea13ee88df280c74eaa3ec446..7fd9be453453cedbe48854eac984b727c6b0c814 100644 (file)
--- a/wxPython/src/_clipbrd.i
+++ b/wxPython/src/_clipbrd.i
@@ -20,33 +20,38 @@
 %}
 
 DocStr(wxClipboard,
 %}
 
 DocStr(wxClipboard,

-       
-"wx.Clipboard represents the system clipboard and provides methods to copy data
-to or paste data from it.  Normally, you should only use wx.TheClipboard which
-is a reference to a global wx.Clipboard instance.
-
-Call wx.TheClipboard.Open to get ownership of the clipboard. If this operation
-returns True, you now own the clipboard. Call wx.TheClipboard.SetData to put
-data on the clipboard, or wx.TheClipboard.GetData to retrieve data from the
-clipboard.  Call wx.TheClipboard.Close to close the clipboard and relinquish
-ownership. You should keep the clipboard open only momentarily.
+"wx.Clipboard represents the system clipboard and provides methods to
+copy data to it or paste data from it.  Normally, you should only use
+``wx.TheClipboard`` which is a reference to a global wx.Clipboard
+instance.
+
+Call ``wx.TheClipboard``'s `Open` method to get ownership of the
+clipboard. If this operation returns True, you now own the
+clipboard. Call `SetData` to put data on the clipboard, or `GetData`
+to retrieve data from the clipboard.  Call `Close` to close the
+clipboard and relinquish ownership. You should keep the clipboard open
+only momentarily.
+
+:see: `wx.DataObject`

 ");
 
 
 
 class wxClipboard : public wxObject {
 public:
 ");
 
 
 
 class wxClipboard : public wxObject {
 public:

-    DocCtorStr( wxClipboard(), "" );
+    DocCtorStr(
+        wxClipboard(),
+        "");

     
     ~wxClipboard();
 
 
     DocDeclStr(
         virtual bool , Open(),
     
     ~wxClipboard();
 
 
     DocDeclStr(
         virtual bool , Open(),

-        "Call this function to open the clipboard before calling SetData\n"
-        "and GetData.  Call Close when you have finished with the clipboard.\n"
-        "You should keep the clipboard open for only a very short time.\n"
-        "Returns true on success. ");
+        "Call this function to open the clipboard before calling SetData and
+GetData.  Call Close when you have finished with the clipboard.  You
+should keep the clipboard open for only a very short time.  Returns
+True on success.");

     
 
     DocDeclStr(
     
 
     DocDeclStr(


@@ -64,50 +69,54 @@ public:
     
     DocDeclStr(
         virtual bool , AddData( wxDataObject *data ),
     
     DocDeclStr(
         virtual bool , AddData( wxDataObject *data ),

-        "Call this function to add the data object to the clipboard. You\n"
-        "may call this function repeatedly after having cleared the clipboard.\n"
-        "After this function has been called, the clipboard owns the data, so\n"
-        "do not delete the data explicitly.");
+        "Call this function to add the data object to the clipboard. You may
+call this function repeatedly after having cleared the clipboard.
+After this function has been called, the clipboard owns the data, so
+do not delete the data explicitly.
+
+:see: `wx.DataObject`");

     
 
     DocDeclStr(
         virtual bool , SetData( wxDataObject *data ),
     
 
     DocDeclStr(
         virtual bool , SetData( wxDataObject *data ),

-        "Set the clipboard data, this is the same as Clear followed by AddData.");
+        "Set the clipboard data, this is the same as `Clear` followed by
+`AddData`.
+
+:see: `wx.DataObject`");

     
 
     %clear wxDataObject *data;
     
     
 
     %clear wxDataObject *data;
     

-

     DocDeclStr(
         virtual bool , IsSupported( const wxDataFormat& format ),
     DocDeclStr(
         virtual bool , IsSupported( const wxDataFormat& format ),

-        "Returns True if the given format is available in the data object(s) on\n"
-        "the clipboard.");
+        "Returns True if the given format is available in the data object(s) on
+the clipboard.");

 
     DocDeclStr(
         virtual bool , GetData( wxDataObject& data ),
 
     DocDeclStr(
         virtual bool , GetData( wxDataObject& data ),

-        "Call this function to fill data with data on the clipboard, if available\n"
-        "in the required format. Returns true on success.");
+        "Call this function to fill data with data on the clipboard, if
+available in the required format. Returns true on success.");

     
     
     DocDeclStr(
         virtual void , Clear(),
     
     
     DocDeclStr(
         virtual void , Clear(),

-        "Clears data from the clipboard object and also  the system's clipboard\n"
-        "if possible.");
+        "Clears data from the clipboard object and also the system's clipboard
+if possible.");

     
 
     DocDeclStr(
         virtual bool , Flush(),
     
 
     DocDeclStr(
         virtual bool , Flush(),

-        "Flushes the clipboard: this means that the data which is currently on\n"
-        "clipboard will stay available even after the application exits (possibly\n"
-        "eating memory), otherwise the clipboard will be emptied on exit.\n"
-        "Returns False if the operation is unsuccesful for any reason.");
+        "Flushes the clipboard: this means that the data which is currently on
+clipboard will stay available even after the application exits,
+possibly eating memory, otherwise the clipboard will be emptied on
+exit.  Returns False if the operation is unsuccesful for any reason.");

     
 
     DocDeclStr(
         virtual void , UsePrimarySelection( bool primary = True ),
     
 
     DocDeclStr(
         virtual void , UsePrimarySelection( bool primary = True ),

-        "On platforms supporting it (the X11 based platforms), selects the so\n"
-        "called PRIMARY SELECTION as the clipboard as opposed to the normal\n"
-        "clipboard, if primary is True.");
+        "On platforms supporting it (the X11 based platforms), selects the
+so called PRIMARY SELECTION as the clipboard as opposed to the
+normal clipboard, if primary is True.");

 };
 
 
 };
 
 


@@ -121,8 +130,8 @@ wxClipboard* const wxTheClipboard;
 
 
 DocStr(wxClipboardLocker,
 
 
 DocStr(wxClipboardLocker,

-"A helpful class for opening the clipboard and automatically closing it when
-the locker is destroyed.");
+"A helpful class for opening the clipboard and automatically
+closing it when the locker is destroyed.");

 
 class wxClipboardLocker
 {
 
 class wxClipboardLocker
 {


@@ -131,8 +140,8 @@ public:
     ~wxClipboardLocker();
 
     DocStr(__nonzero__,
     ~wxClipboardLocker();
 
     DocStr(__nonzero__,

-           "A ClipboardLocker instance evaluates to True if the clipboard was\n"
-           "successfully opened.")
+           "A ClipboardLocker instance evaluates to True if the clipboard was
+successfully opened.")

     %extend {
         bool __nonzero__()   { return !!(*self); }
     }
     %extend {
         bool __nonzero__()   { return !!(*self); }
     }

diff --git a/wxPython/src/_cmndlgs.i b/wxPython/src/_cmndlgs.i
index 8cf834ec39a6858e6308d57cd87a14eeb9f32498..e898f3fabe1ede034d810dbbcf56837d27589fee 100644 (file)
--- a/wxPython/src/_cmndlgs.i
+++ b/wxPython/src/_cmndlgs.i
@@ -27,7 +27,9 @@ MAKE_CONST_WXSTRING(MessageBoxCaptionStr);
 
 
 DocStr(wxColourData,
 
 
 DocStr(wxColourData,

-       "This class holds a variety of information related to colour dialogs.");
+"This class holds a variety of information related to the colour
+chooser dialog, used to transfer settings and results to and from the
+`wx.ColourDialog`.");

     
 class wxColourData : public wxObject {
 public:
     
 class wxColourData : public wxObject {
 public:


@@ -40,9 +42,9 @@ public:
     
     DocDeclStr(
         bool , GetChooseFull(),
     
     DocDeclStr(
         bool , GetChooseFull(),

-        "Under Windows, determines whether the Windows colour dialog will display\n"
-        "the full dialog with custom colour selection controls. Has no meaning\n"
-        "under other platforms.  The default value is true.");
+        "Under Windows, determines whether the Windows colour dialog will
+display the full dialog with custom colour selection controls. Has no
+meaning under other platforms.  The default value is true.");

     
     DocDeclStr(
         wxColour , GetColour(),
     
     DocDeclStr(
         wxColour , GetColour(),


@@ -50,27 +52,31 @@ public:
     
     DocDeclStr(
         wxColour , GetCustomColour(int i),
     
     DocDeclStr(
         wxColour , GetCustomColour(int i),

-        "Gets the i'th custom colour associated with the colour dialog. i should\n"
-        "be an integer between 0 and 15. The default custom colours are all white.");
+        "Gets the i'th custom colour associated with the colour dialog. i
+should be an integer between 0 and 15. The default custom colours are
+all white.");

     
     DocDeclStr(
         void , SetChooseFull(int flag),
     
     DocDeclStr(
         void , SetChooseFull(int flag),

-        "Under Windows, tells the Windows colour dialog to display the full dialog\n"
-        "with custom colour selection controls. Under other platforms, has no effect.\n"
-        "The default value is true.");
+        "Under Windows, tells the Windows colour dialog to display the full
+dialog with custom colour selection controls. Under other platforms,
+has no effect.  The default value is true.");

     
     DocDeclStr(
         void , SetColour(const wxColour& colour),
     
     DocDeclStr(
         void , SetColour(const wxColour& colour),

-        "Sets the default colour for the colour dialog.  The default colour is black.");
+        "Sets the default colour for the colour dialog.  The default colour is
+black.");

     
     DocDeclStr(
         void , SetCustomColour(int i, const wxColour& colour),
     
     DocDeclStr(
         void , SetCustomColour(int i, const wxColour& colour),

-        "Sets the i'th custom colour for the colour dialog. i should be an integer\n"
-        "between 0 and 15. The default custom colours are all white.");
+        "Sets the i'th custom colour for the colour dialog. i should be an
+integer between 0 and 15. The default custom colours are all white.");

     
 };
 
 
     
 };
 
 

+
+

 DocStr(wxColourDialog,
        "This class represents the colour chooser dialog.");
 
 DocStr(wxColourDialog,
        "This class represents the colour chooser dialog.");
 


@@ -80,12 +86,13 @@ public:
 
    DocCtorStr(
        wxColourDialog(wxWindow* parent, wxColourData* data = NULL),
 
    DocCtorStr(
        wxColourDialog(wxWindow* parent, wxColourData* data = NULL),

-       "Constructor. Pass a parent window, and optionally a ColourData, which\n"
-       "will be copied to the colour dialog's internal ColourData instance.");
+       "Constructor. Pass a parent window, and optionally a `wx.ColourData`,
+which will be copied to the colour dialog's internal ColourData
+instance.");

 
     DocDeclStr(
         wxColourData& , GetColourData(),
 
     DocDeclStr(
         wxColourData& , GetColourData(),

-        "Returns a reference to the ColourData used by the dialog.");
+        "Returns a reference to the `wx.ColourData` used by the dialog.");

 };
 
 
 };
 
 


@@ -93,14 +100,19 @@ public:
 
 
 DocStr(wxDirDialog,
 
 
 DocStr(wxDirDialog,

-       "This class represents the directory chooser dialog.");
-
-RefDoc(wxDirDialog, "
- Styles
-    wxDD_NEW_DIR_BUTTON     Add \"Create new directory\" button and allow
-                            directory names to be editable. On Windows the new
-                            directory button is only available with recent
-                            versions of the common dialogs.");
+       "wx.DirDialog allows the user to select a directory by browising the
+file system.
+
+
+Window  Styles
+--------------
+    ====================  ==========================================
+    wx.DD_NEW_DIR_BUTTON  Add 'Create new directory' button and allow
+                          directory names to be editable. On Windows
+                          the new directory button is only available
+                          with recent versions of the common dialogs.
+    ====================  ==========================================
+");

 
 class wxDirDialog : public wxDialog {
 public:
 
 class wxDirDialog : public wxDialog {
 public:


@@ -145,40 +157,46 @@ public:
 //---------------------------------------------------------------------------
 
 DocStr(wxFileDialog,
 //---------------------------------------------------------------------------
 
 DocStr(wxFileDialog,

-       "This class represents the file chooser dialog.");
-
-RefDoc(wxFileDialog, "
-In Windows, this is the common file selector dialog. In X, this is a file
-selector box with somewhat less functionality. The path and filename are
-distinct elements of a full file pathname. If path is \"\", the current
-directory will be used. If filename is \"\", no default filename will be
-supplied. The wildcard determines what files are displayed in the file
-selector, and file extension supplies a type extension for the required
-filename.
-
-Both the X and Windows versions implement a wildcard filter. Typing a filename
-containing wildcards (*, ?) in the filename text item, and clicking on Ok,
-will result in only those files matching the pattern being displayed. The
-wildcard may be a specification for multiple types of file with a description
-for each, such as:
+"wx.FileDialog allows the user to select one or more files from the
+filesystem.
+
+In Windows, this is the common file selector dialog. On X based
+platforms a generic alternative is used.  The path and filename are
+distinct elements of a full file pathname. If path is \"\", the
+current directory will be used. If filename is \"\", no default
+filename will be supplied. The wildcard determines what files are
+displayed in the file selector, and file extension supplies a type
+extension for the required filename.
+
+Both the X and Windows versions implement a wildcard filter. Typing a
+filename containing wildcards (*, ?) in the filename text item, and
+clicking on Ok, will result in only those files matching the pattern
+being displayed. The wildcard may be a specification for multiple
+types of file with a description for each, such as::

 
    \"BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif\"
 
 
    \"BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif\"
 

- Styles
+
+Window  Styles
+--------------
+    ==================   ==========================================

     wx.OPEN              This is an open dialog.
 
     wx.SAVE              This is a save dialog.
 
     wx.OPEN              This is an open dialog.
 
     wx.SAVE              This is a save dialog.
 

-    wx.HIDE_READONLY     For open dialog only: hide the checkbox allowing to
-                         open the file in read-only mode.
+    wx.HIDE_READONLY     For open dialog only: hide the checkbox
+                         allowing to open the file in read-only mode.

 
 

-    wx.OVERWRITE_PROMPT  For save dialog only: prompt for a confirmation if a
-                         file will be overwritten.
+    wx.OVERWRITE_PROMPT  For save dialog only: prompt for a confirmation
+                         if a file will be overwritten.

 
 

-    wx.MULTIPLE          For open dialog only: allows selecting multiple files.
+    wx.MULTIPLE          For open dialog only: allows selecting multiple
+                         files.

 
 

-    wx.CHANGE_DIR        Change the current working directory to the directory
-                         where the file(s) chosen by the user are.
+    wx.CHANGE_DIR        Change the current working directory to the
+                         directory  where the file(s) chosen by the user
+                         are.
+    ==================   ==========================================

 ");
 
 
 ");
 
 


@@ -206,8 +224,8 @@ public:
     
     DocDeclStr(
         void , SetPath(const wxString& path),
     
     DocDeclStr(
         void , SetPath(const wxString& path),

-        "Sets the path (the combined directory and filename that will\n"
-        "be returned when the dialog is dismissed).");
+        "Sets the path (the combined directory and filename that will be
+returned when the dialog is dismissed).");

     
     DocDeclStr(
         void , SetDirectory(const wxString& dir),
     
     DocDeclStr(
         void , SetDirectory(const wxString& dir),


@@ -219,8 +237,11 @@ public:
     
     DocDeclStr(
         void , SetWildcard(const wxString& wildCard),
     
     DocDeclStr(
         void , SetWildcard(const wxString& wildCard),

-        "Sets the wildcard, which can contain multiple file types, for example:\n"
-        "    \"BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif\"");
+        "Sets the wildcard, which can contain multiple file types, for
+example::
+
+    \"BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif\"
+");

     
     DocDeclStr(
         void , SetStyle(long style),
     
     DocDeclStr(
         void , SetStyle(long style),


@@ -257,21 +278,21 @@ public:
     
     DocDeclStr(
         int , GetFilterIndex() const,
     
     DocDeclStr(
         int , GetFilterIndex() const,

-        "Returns the index into the list of filters supplied, optionally, in\n"
-        "the wildcard parameter. Before the dialog is shown, this is the index\n"
-        "which will be used when the dialog is first displayed. After the dialog\n"
-        "is shown, this is the index selected by the user.");
+        "Returns the index into the list of filters supplied, optionally, in
+the wildcard parameter. Before the dialog is shown, this is the index
+which will be used when the dialog is first displayed. After the
+dialog is shown, this is the index selected by the user.");

 
 
     DocStr(GetFilenames,
 
 
     DocStr(GetFilenames,

-        "Returns a list of filenames chosen in the dialog.  This function should\n"
-        "only be used with the dialogs which have wx.MULTIPLE style, use\n"
-        "GetFilename for the others.");
+        "Returns a list of filenames chosen in the dialog.  This function
+should only be used with the dialogs which have wx.MULTIPLE style, use
+GetFilename for the others.");

 
     DocStr(GetPaths,
 
     DocStr(GetPaths,

-        "Fills the array paths with the full paths of the files chosen. This\n"
-        "function should only be used with the dialogs which have wx.MULTIPLE style,\n"
-        "use GetPath for the others.");   
+        "Fills the array paths with the full paths of the files chosen. This
+function should only be used with the dialogs which have wx.MULTIPLE
+style, use GetPath for the others.");   

     
     %extend {
         PyObject* GetFilenames() {
     
     %extend {
         PyObject* GetFilenames() {


@@ -330,16 +351,17 @@ public:
                             int choices=0, wxString* choices_array,
                             long style = wxCHOICEDLG_STYLE,
                             const wxPoint& pos = wxDefaultPosition),
                             int choices=0, wxString* choices_array,
                             long style = wxCHOICEDLG_STYLE,
                             const wxPoint& pos = wxDefaultPosition),

-        "__init__(Window parent, String message, String caption,\n"
-        "    List choices=[], long style=CHOICEDLG_STYLE,\n"
-        "    Point pos=DefaultPosition) -> MultiChoiceDialog",
+        "__init__(Window parent, String message, String caption,
+    List choices=[], long style=CHOICEDLG_STYLE,
+    Point pos=DefaultPosition) -> MultiChoiceDialog",

         "Constructor.  Use ShowModal method to show the dialog.");
 
     
     DocDeclAStr(
         void, SetSelections(const wxArrayInt& selections),
         "SetSelections(List selections)",
         "Constructor.  Use ShowModal method to show the dialog.");
 
     
     DocDeclAStr(
         void, SetSelections(const wxArrayInt& selections),
         "SetSelections(List selections)",

-        "Specify the items in the list that shoudl be selected, using a list of integers.");
+        "Specify the items in the list that should be selected, using a list of
+integers.");

 
     DocAStr(GetSelections,
             "GetSelections() -> [selections]",
 
     DocAStr(GetSelections,
             "GetSelections() -> [selections]",


@@ -362,9 +384,9 @@ public:
     %pythonAppend wxSingleChoiceDialog   "self._setOORInfo(self)"
 
     DocAStr(wxSingleChoiceDialog,
     %pythonAppend wxSingleChoiceDialog   "self._setOORInfo(self)"
 
     DocAStr(wxSingleChoiceDialog,

-            "__init__(Window parent, String message, String caption,\n"
-            "    List choices=[], long style=CHOICEDLG_STYLE,\n"
-            "    Point pos=DefaultPosition) -> SingleChoiceDialog",
+            "__init__(Window parent, String message, String caption,
+    List choices=[], long style=CHOICEDLG_STYLE,
+    Point pos=DefaultPosition) -> SingleChoiceDialog",

             "Constructor.  Use ShowModal method to show the dialog.");
 
     %extend {
             "Constructor.  Use ShowModal method to show the dialog.");
 
     %extend {


@@ -416,8 +438,8 @@ public:
 
     DocDeclStr(
         wxString , GetValue(),
 
     DocDeclStr(
         wxString , GetValue(),

-        "Returns the text that the user has entered if the user has pressed OK,\n"
-        "or the original value if the user has pressed Cancel.");
+        "Returns the text that the user has entered if the user has pressed OK,
+or the original value if the user has pressed Cancel.");

     
     DocDeclStr(
         void , SetValue(const wxString& value),
     
     DocDeclStr(
         void , SetValue(const wxString& value),


@@ -428,7 +450,8 @@ public:
 
 
 DocStr(wxFontData,
 
 
 DocStr(wxFontData,

-       "This class holds a variety of information related to font dialogs.");
+       "This class holds a variety of information related to font dialogs and
+is used to transfer settings to and results from a `wx.FontDialog`.");

 
 
 class wxFontData : public wxObject {
 
 
 class wxFontData : public wxObject {


@@ -438,18 +461,20 @@ public:
 
     DocDeclStr(
         void , EnableEffects(bool enable),
 
     DocDeclStr(
         void , EnableEffects(bool enable),

-        "Enables or disables 'effects' under MS Windows only. This refers\n"
-        "to the controls for manipulating colour, strikeout and underline\n"
-        "properties.  The default value is true.");
+        "Enables or disables 'effects' under MS Windows only. This refers to
+the controls for manipulating colour, strikeout and underline
+properties.  The default value is true.");

     
     DocDeclStr(
         bool , GetAllowSymbols(),
     
     DocDeclStr(
         bool , GetAllowSymbols(),

-        "Under MS Windows, returns a flag determining whether symbol fonts can be\n"
-        "selected. Has no effect on other platforms. The default value is true.");
+        "Under MS Windows, returns a flag determining whether symbol fonts can
+be selected. Has no effect on other platforms. The default value is
+true.");

     
     DocDeclStr(
         wxColour , GetColour(),
     
     DocDeclStr(
         wxColour , GetColour(),

-        "Gets the colour associated with the font dialog. The default value is black.");
+        "Gets the colour associated with the font dialog. The default value is
+black.");

     
     DocDeclStr(
         wxFont , GetChosenFont(),
     
     DocDeclStr(
         wxFont , GetChosenFont(),


@@ -461,27 +486,28 @@ public:
     
     DocDeclStr(
         wxFont , GetInitialFont(),
     
     DocDeclStr(
         wxFont , GetInitialFont(),

-        "Gets the font that will be initially used by the font dialog. This should have\n"
-        "previously been set by the application.");
+        "Gets the font that will be initially used by the font dialog. This
+should have previously been set by the application.");

     
     DocDeclStr(
         bool , GetShowHelp(),
     
     DocDeclStr(
         bool , GetShowHelp(),

-        "Returns true if the Help button will be shown (Windows only).  The default\n"
-        "value is false.");
+        "Returns true if the Help button will be shown (Windows only).  The
+default value is false.");

     
     DocDeclStr(
         void , SetAllowSymbols(bool allowSymbols),
     
     DocDeclStr(
         void , SetAllowSymbols(bool allowSymbols),

-        "Under MS Windows, determines whether symbol fonts can be selected. Has no\n"
-        "effect on other platforms.  The default value is true.");
+        "Under MS Windows, determines whether symbol fonts can be selected. Has
+no effect on other platforms.  The default value is true.");

     
     DocDeclStr(
         void , SetChosenFont(const wxFont& font),
     
     DocDeclStr(
         void , SetChosenFont(const wxFont& font),

-        "Sets the font that will be returned to the user (for internal use only).");
+        "Sets the font that will be returned to the user (normally for internal
+use only).");

     
     DocDeclStr(
         void , SetColour(const wxColour& colour),
     
     DocDeclStr(
         void , SetColour(const wxColour& colour),

-        "Sets the colour that will be used for the font foreground colour.  The default\n"
-        "colour is black.");
+        "Sets the colour that will be used for the font foreground colour.  The
+default colour is black.");

     
     DocDeclStr(
         void , SetInitialFont(const wxFont& font),
     
     DocDeclStr(
         void , SetInitialFont(const wxFont& font),


@@ -489,34 +515,40 @@ public:
     
     DocDeclStr(
         void , SetRange(int min, int max),
     
     DocDeclStr(
         void , SetRange(int min, int max),

-        "Sets the valid range for the font point size (Windows only).  The default is\n"
-        "0, 0 (unrestricted range).");
+        "Sets the valid range for the font point size (Windows only).  The
+default is 0, 0 (unrestricted range).");

     
     DocDeclStr(
         void , SetShowHelp(bool showHelp),
     
     DocDeclStr(
         void , SetShowHelp(bool showHelp),

-        "Determines whether the Help button will be displayed in the font dialog\n"
-        "(Windows only).  The default value is false.");
+        "Determines whether the Help button will be displayed in the font
+dialog (Windows only).  The default value is false.");

 };
 
 
 
 
 DocStr(wxFontDialog,
 };
 
 
 
 
 DocStr(wxFontDialog,

-       "This class represents the font chooser dialog.");
+       "wx.FontDialog allows the user to select a system font and its attributes.
+
+:see: `wx.FontData`
+");

 
 class wxFontDialog : public wxDialog {
 public:
     %pythonAppend wxFontDialog   "self._setOORInfo(self)"
 
     DocStr(wxFontDialog,
 
 class wxFontDialog : public wxDialog {
 public:
     %pythonAppend wxFontDialog   "self._setOORInfo(self)"
 
     DocStr(wxFontDialog,

-           "Constructor. Pass a parent window and the FontData object to be\n"
-           "used to initialize the dialog controls.");
+           "Constructor. Pass a parent window and the `wx.FontData` object to be
+used to initialize the dialog controls.  Call `ShowModal` to display
+the dialog.  If ShowModal returns ``wx.ID_OK`` then you can fetch the
+results with via the `wx.FontData` returned by `GetFontData`.");

     wxFontDialog(wxWindow* parent, const wxFontData& data);
 
     
     DocDeclStr(
         wxFontData& , GetFontData(),
     wxFontDialog(wxWindow* parent, const wxFontData& data);
 
     
     DocDeclStr(
         wxFontData& , GetFontData(),

-        "Returns a reference to the internal FontData used by the FontDialog.");    
+        "Returns a reference to the internal `wx.FontData` used by the
+wx.FontDialog.");    

 };
 
 
 };
 
 


@@ -524,32 +556,28 @@ public:
 
 
 DocStr(wxMessageDialog,
 
 
 DocStr(wxMessageDialog,

-       "This class provides a dialog that shows a single or multi-line message, with\n"
-       "a choice of OK, Yes, No and Cancel buttons.");
-
-RefDoc(wxMessageDialog, "
-  Styles
-    wx.OK:                Show an OK button.
-
-    wx.CANCEL:            Show a Cancel button.
-
-    wx.YES_NO:            Show Yes and No buttons.
-
-    wx.YES_DEFAULT:       Used with wxYES_NO, makes Yes button the default - which is the default behaviour.
-
-    wx.NO_DEFAULT:        Used with wxYES_NO, makes No button the default.
-
-    wx.ICON_EXCLAMATION:  Shows an exclamation mark icon.
-
-    wx.ICON_HAND:         Shows an error icon.
-
-    wx.ICON_ERROR:        Shows an error icon - the same as wxICON_HAND.
-
-    wx.ICON_QUESTION:     Shows a question mark icon.
-
-    wx.ICON_INFORMATION:  Shows an information (i) icon.
-
-    wx.STAY_ON_TOP:       The message box stays on top of all other window, even those of the other applications (Windows only).
+"This class provides a simple dialog that shows a single or multi-line
+message, with a choice of OK, Yes, No and/or Cancel buttons.
+
+
+Window Styles
+--------------
+    =================    =============================================
+    wx.OK                Show an OK button.
+    wx.CANCEL            Show a Cancel button.
+    wx.YES_NO            Show Yes and No buttons.
+    wx.YES_DEFAULT       Used with wxYES_NO, makes Yes button the
+                         default - which is the default behaviour.
+    wx.NO_DEFAULT        Used with wxYES_NO, makes No button the default.
+    wx.ICON_EXCLAMATION  Shows an exclamation mark icon.
+    wx.ICON_HAND         Shows an error icon.
+    wx.ICON_ERROR        Shows an error icon - the same as wxICON_HAND.
+    wx.ICON_QUESTION     Shows a question mark icon.
+    wx.ICON_INFORMATION  Shows an information (i) icon.
+    wx.STAY_ON_TOP       The message box stays on top of all other
+                         window, even those of the other applications
+                         (Windows only).
+    =================    =============================================

 ");
 
 
 ");
 
 


@@ -558,12 +586,14 @@ public:
     %pythonAppend wxMessageDialog   "self._setOORInfo(self)"
     
     RefDoc(wxMessageDialog, ""); // turn it off for the ctors
     %pythonAppend wxMessageDialog   "self._setOORInfo(self)"
     
     RefDoc(wxMessageDialog, ""); // turn it off for the ctors

-    
-    wxMessageDialog(wxWindow* parent,
-                    const wxString& message,
-                    const wxString& caption = wxPyMessageBoxCaptionStr,
-                    long style = wxOK | wxCANCEL | wxCENTRE,
-                    const wxPoint& pos = wxDefaultPosition);
+
+    DocCtorStr(
+        wxMessageDialog(wxWindow* parent,
+                        const wxString& message,
+                        const wxString& caption = wxPyMessageBoxCaptionStr,
+                        long style = wxOK | wxCANCEL | wxCENTRE,
+                        const wxPoint& pos = wxDefaultPosition),
+        "Constructor, use `ShowModal` to display the dialog.");

 
 };
 
 
 };
 


@@ -571,34 +601,35 @@ public:
 
 
 DocStr(wxProgressDialog,
 
 
 DocStr(wxProgressDialog,

-       "A dialog that shows a short message and a progress bar. Optionally, it can\n"
-       "display an ABORT button.");
-
-RefDoc(wxProgressDialog, "
-  Styles
-
-    wx.PD_APP_MODAL:            Make the progress dialog modal. If this flag is
-                                not given, it is only \"locally\" modal - that is
-                                the input to the parent window is disabled,
-                                but not to the other ones.
-
-    wx.PD_AUTO_HIDE:            Causes the progress dialog to disappear from screen 
-                                as soon as the maximum value of the progress
-                                meter has been reached.
-
-    wx.PD_CAN_ABORT:            This flag tells the dialog that it should have
-                                a \"Cancel\" button which the user may press. If
-                                this happens, the next call to Update() will
-                                return false.
-
-    wx.PD_ELAPSED_TIME:         This flag tells the dialog that it should show
-                                elapsed time (since creating the dialog).
-
-    wx.PD_ESTIMATED_TIME:      This flag tells the dialog that it should show
-                                estimated time.
-
-    wx.PD_REMAINING_TIME:      This flag tells the dialog that it should show
-                                remaining time.
+"A dialog that shows a short message and a progress bar. Optionally, it
+can display an ABORT button.
+
+Window Styles
+--------------
+    =================     =============================================
+    wx.PD_APP_MODAL       Make the progress dialog modal. If this flag is
+                          not given, it is only \"locally\" modal -
+                          that is the input to the parent window is
+                          disabled, but not to the other ones.
+
+    wx.PD_AUTO_HIDE       Causes the progress dialog to disappear from
+                          screen as soon as the maximum value of the
+                          progress meter has been reached.
+
+    wx.PD_CAN_ABORT       This flag tells the dialog that it should have
+                          a \"Cancel\" button which the user may press. If
+                          this happens, the next call to Update() will
+                          return false.
+
+    wx.PD_ELAPSED_TIME    This flag tells the dialog that it should show
+                          elapsed time (since creating the dialog).
+
+    wx.PD_ESTIMATED_TIME  This flag tells the dialog that it should show
+                          estimated time.
+
+    wx.PD_REMAINING_TIME  This flag tells the dialog that it should show
+                          remaining time.
+    =================     =============================================

 ");
 
 
 ");
 
 


@@ -614,21 +645,24 @@ public:
                          int maximum = 100,
                          wxWindow* parent = NULL,
                          int style = wxPD_AUTO_HIDE | wxPD_APP_MODAL ),
                          int maximum = 100,
                          wxWindow* parent = NULL,
                          int style = wxPD_AUTO_HIDE | wxPD_APP_MODAL ),

-        "Constructor. Creates the dialog, displays it and disables user input for other\n"
-        "windows, or, if wxPD_APP_MODAL flag is not given, for its parent window only.");
+        "Constructor. Creates the dialog, displays it and disables user input
+for other windows, or, if wx.PD_APP_MODAL flag is not given, for its
+parent window only.");

 
     DocDeclStr(
         virtual bool , Update(int value, const wxString& newmsg = wxPyEmptyString),
 
     DocDeclStr(
         virtual bool , Update(int value, const wxString& newmsg = wxPyEmptyString),

-        "Updates the dialog, setting the progress bar to the new value and, if given\n"
-        "changes the message above it. Returns true unless the Cancel button has been\n"
-        "pressed.\n\n"
-        "If false is returned, the application can either immediately destroy the\n"
-        "dialog or ask the user for the confirmation and if the abort is not confirmed\n"
-        "the dialog may be resumed with Resume function.");
+        "Updates the dialog, setting the progress bar to the new value and, if
+given changes the message above it. Returns true unless the Cancel
+button has been pressed.
+
+If false is returned, the application can either immediately destroy
+the dialog or ask the user for the confirmation and if the abort is
+not confirmed the dialog may be resumed with Resume function.");

     
     DocDeclStr(
         void , Resume(),
     
     DocDeclStr(
         void , Resume(),

-        "Can be used to continue with the dialog, after the user had chosen to abort.");
+        "Can be used to continue with the dialog, after the user had chosen to
+abort.");

     
 };
 
     
 };
 


@@ -697,8 +731,8 @@ public:
     
     DocDeclStr(
         int , GetFlags(),
     
     DocDeclStr(
         int , GetFlags(),

-        "Get the currently selected flags: this is the combination of\n"
-        "wx.FR_DOWN, wx.FR_WHOLEWORD and wx.FR_MATCHCASE flags.");
+        "Get the currently selected flags: this is the combination of
+wx.FR_DOWN, wx.FR_WHOLEWORD and wx.FR_MATCHCASE flags.");

     
     DocDeclStr(
         const wxString& , GetFindString(),
     
     DocDeclStr(
         const wxString& , GetFindString(),


@@ -706,8 +740,8 @@ public:
     
     DocDeclStr(
         const wxString& , GetReplaceString(),
     
     DocDeclStr(
         const wxString& , GetReplaceString(),

-        "Return the string to replace the search string with (only\n"
-        "for replace and replace all events).");
+        "Return the string to replace the search string with (only for replace
+and replace all events).");

     
     DocDeclStr(
         wxFindReplaceDialog *, GetDialog(),
     
     DocDeclStr(
         wxFindReplaceDialog *, GetDialog(),


@@ -729,22 +763,26 @@ public:
 
 
 DocStr(wxFindReplaceData, 
 
 
 DocStr(wxFindReplaceData, 

-"FindReplaceData holds the data for FindReplaceDialog. It is used to initialize
-the dialog with the default values and will keep the last values from the
-dialog when it is closed. It is also updated each time a wxFindDialogEvent is
-generated so instead of using the wxFindDialogEvent methods you can also
-directly query this object.
-
-Note that all SetXXX() methods may only be called before showing the dialog
-and calling them has no effect later.
-
- Flags
-    wxFR_DOWN:          downward search/replace selected (otherwise, upwards)
-
-    wxFR_WHOLEWORD:     whole word search/replace selected
-
-    wxFR_MATCHCASE:     case sensitive search/replace selected (otherwise,
-                        case insensitive)
+"wx.FindReplaceData holds the data for wx.FindReplaceDialog. It is used
+to initialize the dialog with the default values and will keep the
+last values from the dialog when it is closed. It is also updated each
+time a `wx.FindDialogEvent` is generated so instead of using the
+`wx.FindDialogEvent` methods you can also directly query this object.
+
+Note that all SetXXX() methods may only be called before showing the
+dialog and calling them has no effect later.
+
+Flags
+-----
+    ================   ===============================================  
+    wx.FR_DOWN         Downward search/replace selected (otherwise,
+                       upwards)
+
+    wx.FR_WHOLEWORD    Whole word search/replace selected
+
+    wx.FR_MATCHCASE    Case sensitive search/replace selected
+                       (otherwise, case insensitive)
+    ================   ===============================================  

 ");
 
 
 ");
 
 


@@ -790,23 +828,27 @@ public:
 
 
 DocStr(wxFindReplaceDialog,
 
 
 DocStr(wxFindReplaceDialog,

-"FindReplaceDialog is a standard modeless dialog which is used to allow the
-user to search for some text (and possibly replace it with something
-else). The actual searching is supposed to be done in the owner window which
-is the parent of this dialog. Note that it means that unlike for the other
-standard dialogs this one must have a parent window. Also note that there is
-no way to use this dialog in a modal way; it is always, by design and
-implementation, modeless.");
+"wx.FindReplaceDialog is a standard modeless dialog which is used to
+allow the user to search for some text (and possibly replace it with
+something else). The actual searching is supposed to be done in the
+owner window which is the parent of this dialog. Note that it means
+that unlike for the other standard dialogs this one must have a parent
+window. Also note that there is no way to use this dialog in a modal
+way; it is always, by design and implementation, modeless.
+
+
+Window Styles
+-------------

 
 

-RefDoc(wxFindReplaceDialog, "
- Styles
-    wx.FR_REPLACEDIALOG:        replace dialog (otherwise find dialog)
+    =====================  =========================================
+    wx.FR_REPLACEDIALOG    replace dialog (otherwise find dialog)

 
 

-    wx.FR_NOUPDOWN:             don't allow changing the search direction
+    wx.FR_NOUPDOWN         don't allow changing the search direction

 
 

-    wx.FR_NOMATCHCASE:          don't allow case sensitive searching
+    wx.FR_NOMATCHCASE      don't allow case sensitive searching

 
 

-    wx.FR_NOWHOLEWORD:          don't allow whole word searching
+    wx.FR_NOWHOLEWORD      don't allow whole word searching
+    =====================  =========================================

 ");
 
 class wxFindReplaceDialog : public wxDialog {
 ");
 
 class wxFindReplaceDialog : public wxDialog {


@@ -821,8 +863,8 @@ public:
                             wxFindReplaceData *data,
                             const wxString &title,
                             int style = 0),
                             wxFindReplaceData *data,
                             const wxString &title,
                             int style = 0),

-        "Create a FindReplaceDialog.  The parent and data parameters must be\n"
-        "non-None.  Use Show to display the dialog.");
+        "Create a FindReplaceDialog.  The parent and data parameters must be
+non-None.  Use Show to display the dialog.");

 
     DocCtorStrName(
         wxFindReplaceDialog(),
 
     DocCtorStrName(
         wxFindReplaceDialog(),


@@ -831,10 +873,8 @@ public:
 
     
     DocDeclStr(
 
     
     DocDeclStr(

-        bool , Create(wxWindow *parent,
-                      wxFindReplaceData *data,
-                      const wxString &title,
-                      int style = 0),
+        bool , Create(wxWindow *parent, wxFindReplaceData *data,
+                      const wxString &title, int style = 0),

         "Create the dialog, for 2-phase create.");
     
 
         "Create the dialog, for 2-phase create.");
     
 

diff --git a/wxPython/src/_config.i b/wxPython/src/_config.i
index 7d15765a19fcae92cdbaaee93535e0a0eae16a14..ec06be39c702a4398763708365c2c82b76654d0e 100644 (file)
--- a/wxPython/src/_config.i
+++ b/wxPython/src/_config.i
@@ -313,7 +313,7 @@ public:
     DocDeclStr(
         virtual bool , DeleteAll(),
         "Delete the whole underlying object (disk file, registry key, ...)\n"
     DocDeclStr(
         virtual bool , DeleteAll(),
         "Delete the whole underlying object (disk file, registry key, ...)\n"

-        "primarly intended for use by desinstallation routine.");
+        "primarly intended for use by deinstallation routine.");

     
 
 
     
 
 

diff --git a/wxPython/src/_dc.i b/wxPython/src/_dc.i
index 55e415d87ca18ab2b804b879816af2ec925c1623..d48f2466651abbb2f1cd196b982244a12fe5fcb0 100644 (file)
--- a/wxPython/src/_dc.i
+++ b/wxPython/src/_dc.i
@@ -56,6 +56,8 @@ public:
 #if defined(wxUSE_DC_OLD_METHODS)
 
     bool FloodFill(wxCoord x, wxCoord y, const wxColour& col, int style = wxFLOOD_SURFACE);
 #if defined(wxUSE_DC_OLD_METHODS)
 
     bool FloodFill(wxCoord x, wxCoord y, const wxColour& col, int style = wxFLOOD_SURFACE);

+    %name(FloodFillPoint) bool FloodFill(const wxPoint& pt, const wxColour& col, int style = wxFLOOD_SURFACE);
+

     //bool GetPixel(wxCoord x, wxCoord y, wxColour *col) const;
     %extend {
         wxColour GetPixel(wxCoord x, wxCoord y) {
     //bool GetPixel(wxCoord x, wxCoord y, wxColour *col) const;
     %extend {
         wxColour GetPixel(wxCoord x, wxCoord y) {


@@ -63,26 +65,66 @@ public:
             self->GetPixel(x, y, &col);
             return col;
         }
             self->GetPixel(x, y, &col);
             return col;
         }

+        wxColour GetPixelPoint(const wxPoint& pt) {
+            wxColour col;
+            self->GetPixel(pt, &col);
+            return col;
+        }

     }
     }

+    

     void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2);
     void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2);

+    %name(DrawLinePoint) void DrawLine(const wxPoint& pt1, const wxPoint& pt2);
+

     void CrossHair(wxCoord x, wxCoord y);
     void CrossHair(wxCoord x, wxCoord y);

+    %name(CrossHairPoint) void CrossHair(const wxPoint& pt);
+

     void DrawArc(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, wxCoord xc, wxCoord yc);
     void DrawArc(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, wxCoord xc, wxCoord yc);

+    %name(DrawArcPoint) void DrawArc(const wxPoint& pt1, const wxPoint& pt2, const wxPoint& centre);
+

     void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
     void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, wxCoord height);

+    %name(DrawCheckMarkRect) void DrawCheckMark(const wxRect& rect);
+

     void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord w, wxCoord h, double sa, double ea);
     void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord w, wxCoord h, double sa, double ea);

+    %name(DrawEllipticArcPtSz) void DrawEllipticArc(const wxPoint& pt, const wxSize& sz, double sa, double ea);
+

     void DrawPoint(wxCoord x, wxCoord y);
     void DrawPoint(wxCoord x, wxCoord y);

+    %name(DrawPointPoint) void DrawPoint(const wxPoint& pt);
+

     void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
     %name(DrawRectangleRect)void DrawRectangle(const wxRect& rect);
     void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
     %name(DrawRectangleRect)void DrawRectangle(const wxRect& rect);

+    %name(DrawRectanglePtSz) void DrawRectangle(const wxPoint& pt, const wxSize& sz);
+

     void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height, double radius);
     void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height, double radius);

+    %name(DrawRoundedRectangleRect) void DrawRoundedRectangle(const wxRect& r, double radius);
+    %name(DrawRoundedRectanglePtSz) void DrawRoundedRectangle(const wxPoint& pt, const wxSize& sz, double radius);
+

     void DrawCircle(wxCoord x, wxCoord y, wxCoord radius);
     void DrawCircle(wxCoord x, wxCoord y, wxCoord radius);

+    %name(DrawCirclePoint) void DrawCircle(const wxPoint& pt, wxCoord radius);
+

     void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
     void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, wxCoord height);

+    %name(DrawEllipseRect) void DrawEllipse(const wxRect& rect);
+    %name(DrawEllipsePtSz) void DrawEllipse(const wxPoint& pt, const wxSize& sz);
+

     void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y);
     void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y);

+    %name(DrawIconPoint) void DrawIcon(const wxIcon& icon, const wxPoint& pt);
+

     void DrawBitmap(const wxBitmap &bmp, wxCoord x, wxCoord y, bool useMask = False);
     void DrawBitmap(const wxBitmap &bmp, wxCoord x, wxCoord y, bool useMask = False);

+    %name(DrawBitmapPoint) void DrawBitmap(const wxBitmap &bmp, const wxPoint& pt, bool useMask = False);
+

     void DrawText(const wxString& text, wxCoord x, wxCoord y);
     void DrawText(const wxString& text, wxCoord x, wxCoord y);

+    %name(DrawTextPoint) void DrawText(const wxString& text, const wxPoint& pt);
+

     void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y, double angle);
     void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y, double angle);

+    %name(DrawRotatedTextPoint) void DrawRotatedText(const wxString& text, const wxPoint& pt, double angle);
+

     bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width, wxCoord height,
               wxDC *source, wxCoord xsrc, wxCoord ysrc,
               int rop = wxCOPY, bool useMask = False,
               wxCoord xsrcMask = -1, wxCoord ysrcMask = -1);
     bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width, wxCoord height,
               wxDC *source, wxCoord xsrc, wxCoord ysrc,
               int rop = wxCOPY, bool useMask = False,
               wxCoord xsrcMask = -1, wxCoord ysrcMask = -1);

+    %name(BlitPtSz) bool Blit(const wxPoint& destPt, const wxSize& sz,
+                      wxDC *source, const wxPoint& srcPt,
+                      int rop = wxCOPY, bool useMask = False,
+                      const wxPoint& srcPtMask = wxDefaultPosition);

 
 
 
 
 
 


@@ -105,6 +147,7 @@ public:
             return col;
         }
     }
             return col;
         }
     }

+    

     %name(DrawLineXY) void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2);
     void DrawLine(const wxPoint& pt1, const wxPoint& pt2);
 
     %name(DrawLineXY) void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2);
     void DrawLine(const wxPoint& pt1, const wxPoint& pt2);
 

diff --git a/wxPython/src/_event_ex.py b/wxPython/src/_event_ex.py
index 03663716d2d2a68a342510f4de97a8a9a5cc1cc9..622bed6de91f65c4d10e207acd973ef875ff07a6 100644 (file)
--- a/wxPython/src/_event_ex.py
+++ b/wxPython/src/_event_ex.py
@@ -23,12 +23,14 @@ class PyEventBinder(object):
         for et in self.evtType:
             target.Connect(id1, id2, et, function)
 
         for et in self.evtType:
             target.Connect(id1, id2, et, function)
 

+

     def Unbind(self, target, id1, id2):
         """Remove an event binding."""
         success = 0
         for et in self.evtType:
             success += target.Disconnect(id1, id2, et)
         return success != 0
     def Unbind(self, target, id1, id2):
         """Remove an event binding."""
         success = 0
         for et in self.evtType:
             success += target.Disconnect(id1, id2, et)
         return success != 0

+

     
     def __call__(self, *args):
         """
     
     def __call__(self, *args):
         """

diff --git a/wxPython/src/_evthandler.i b/wxPython/src/_evthandler.i
index 5a12a452d844fc069ea4e07122eb7d14b683cc8d..2fed5cab97515c1a902c6e3ff1df36153730635e 100644 (file)
--- a/wxPython/src/_evthandler.i
+++ b/wxPython/src/_evthandler.i
@@ -113,7 +113,7 @@ public:
             """
             if source is not None:
                 id  = source.GetId()
             """
             if source is not None:
                 id  = source.GetId()

-            event.Unbind(self, id, id2)              
+            return event.Unbind(self, id, id2)              

     }
 
     
     }
 
     

diff --git a/wxPython/src/_gdicmn.i b/wxPython/src/_gdicmn.i
index 96355a11ea674beef9340168802d77abc249d5b1..5b86c9a6e0dafbb4e14d42d8fe6bd734dbf3b28e 100644 (file)
--- a/wxPython/src/_gdicmn.i
+++ b/wxPython/src/_gdicmn.i
@@ -130,6 +130,7 @@ public:
 
     ~wxSize();
 
 
     ~wxSize();
 

+// None/NULL is now handled properly by the typemap, so these are not needed.

 //     %extend {
 //         bool __eq__(const wxSize* other) { return other ? (*self == *other) : False; }
 //         bool __ne__(const wxSize* other) { return other ? (*self != *other) : True;  }
 //     %extend {
 //         bool __eq__(const wxSize* other) { return other ? (*self == *other) : False; }
 //         bool __ne__(const wxSize* other) { return other ? (*self != *other) : True;  }

diff --git a/wxPython/src/_image.i b/wxPython/src/_image.i
index f5d4b36bd3f6069505eae1cee85f2b587bc75933..08d530f0eb539bf92b0931aeb0db98d5c74ec491 100644 (file)
--- a/wxPython/src/_image.i
+++ b/wxPython/src/_image.i
@@ -83,24 +83,14 @@ public:
     %name(ImageFromMime) wxImage(const wxString& name, const wxString& mimetype, int index = -1);
     %name(ImageFromStream) wxImage(wxInputStream& stream, long type = wxBITMAP_TYPE_ANY, int index = -1);
     %name(ImageFromStreamMime) wxImage(wxInputStream& stream, const wxString& mimetype, int index = -1 );
     %name(ImageFromMime) wxImage(const wxString& name, const wxString& mimetype, int index = -1);
     %name(ImageFromStream) wxImage(wxInputStream& stream, long type = wxBITMAP_TYPE_ANY, int index = -1);
     %name(ImageFromStreamMime) wxImage(wxInputStream& stream, const wxString& mimetype, int index = -1 );

-
-
-    

     %extend {
     %extend {

-
-        %nokwargs wxImage(int width=0, int height=0, bool clear = True);
-        %nokwargs wxImage(const wxSize& size, bool clear = True);

         %name(EmptyImage) wxImage(int width=0, int height=0, bool clear = True) {
             if (width > 0 && height > 0)
                 return new wxImage(width, height, clear);
             else
                 return new wxImage;
         }   
         %name(EmptyImage) wxImage(int width=0, int height=0, bool clear = True) {
             if (width > 0 && height > 0)
                 return new wxImage(width, height, clear);
             else
                 return new wxImage;
         }   

-        %name(EmptyImage) wxImage(const wxSize& size, bool clear = True) {
-            return new wxImage(size.x, size.y, clear);
-        }   
-
-        
+           

         %name(ImageFromBitmap) wxImage(const wxBitmap &bitmap) {
             return new wxImage(bitmap.ConvertToImage());
         }
         %name(ImageFromBitmap) wxImage(const wxBitmap &bitmap) {
             return new wxImage(bitmap.ConvertToImage());
         }

diff --git a/wxPython/src/_sizers.i b/wxPython/src/_sizers.i
index f6c73d0b76921913a91a5ec5a73be0e5e642d89b..bf9aeaeaebec0e440ae660866b646dca4f490ed6 100644 (file)
--- a/wxPython/src/_sizers.i
+++ b/wxPython/src/_sizers.i
@@ -271,16 +271,30 @@ public:
 
     %pythoncode {
     def AddMany(self, widgets):
 
     %pythoncode {
     def AddMany(self, widgets):

+        """
+        AddMany is a convenience method for adding several items
+        to a sizer at one time.  Simply pass it a list of tuples,
+        where each tuple consists of the parameters that you
+        would normally pass to the `Add` method.
+        """

         for childinfo in widgets:
             if type(childinfo) != type(()) or (len(childinfo) == 2 and type(childinfo[0]) == type(1)):
                 childinfo = (childinfo, )
             self.Add(*childinfo)
 
     %# for backwards compatibility only, please do not use in new code
         for childinfo in widgets:
             if type(childinfo) != type(()) or (len(childinfo) == 2 and type(childinfo[0]) == type(1)):
                 childinfo = (childinfo, )
             self.Add(*childinfo)
 
     %# for backwards compatibility only, please do not use in new code

-    AddWindow = AddSizer = AddSpacer = Add
-    PrependWindow = PrependSizer = PrependSpacer = Prepend
-    InsertWindow = InsertSizer = InsertSpacer = Insert
-    RemoveWindow = RemoveSizer = RemovePos = Remove
+    AddWindow     = wx._deprecated(Add, "AddWindow is deprecated, use `Add` instead.")
+    AddSizer      = wx._deprecated(Add, "AddSizer is deprecated, use `Add` instead.")
+    AddSpacer     = wx._deprecated(Add, "AddSpacer is deprecated, use `Add` instead.")
+    PrependWindow = wx._deprecated(Prepend, "PrependWindow is deprecated, use `Prepend` instead.")
+    PrependSizer  = wx._deprecated(Prepend, "PrependSizer is deprecated, use `Prepend` instead.")
+    PrependSpacer = wx._deprecated(Prepend, "PrependSpacer is deprecated, use `Prepend` instead.")
+    InsertWindow  = wx._deprecated(Insert, "InsertWindow is deprecated, use `Insert` instead.")
+    InsertSizer   = wx._deprecated(Insert, "InsertSizer is deprecated, use `Insert` instead.")
+    InsertSpacer  = wx._deprecated(Insert, "InsertSpacer is deprecated, use `Insert` instead.")
+    RemoveWindow  = wx._deprecated(Remove, "RemoveWindow is deprecated, use `Remove` instead.")
+    RemoveSizer   = wx._deprecated(Remove, "RemoveSizer is deprecated, use `Remove` instead.")
+    RemovePos     = wx._deprecated(Remove, "RemovePos is deprecated, use `Remove` instead.")

 
 
     def SetItemMinSize(self, item, *args):
 
 
     def SetItemMinSize(self, item, *args):

diff --git a/wxPython/src/calendar.i b/wxPython/src/calendar.i
index b0466c88e171787a87039c11e818ee6d2008c8b3..262170001e0d1b6dce7b35dfb3659b01f7c3bc6d 100644 (file)
--- a/wxPython/src/calendar.i
+++ b/wxPython/src/calendar.i
@@ -62,8 +62,8 @@ enum wxCalendarDateBorder
 //---------------------------------------------------------------------------
 
 DocStr(wxCalendarDateAttr,
 //---------------------------------------------------------------------------
 
 DocStr(wxCalendarDateAttr,

-"A set of customization attributes for a calendar date, which can be used to
-control the look of the Calendar object.");
+"A set of customization attributes for a calendar date, which can be
+used to control the look of the Calendar object.");

 
 class wxCalendarDateAttr
 {
 
 class wxCalendarDateAttr
 {


@@ -142,54 +142,66 @@ MAKE_CONST_WXSTRING(CalendarNameStr);
 
 
 DocStr(wxCalendarCtrl,
 
 
 DocStr(wxCalendarCtrl,

-       "The calendar control allows the user to pick a date interactively.");
-
-RefDoc(wxCalendarCtrl,
-
-"The CalendarCtrl displays a window containing several parts: the control to
-pick the month and the year at the top (either or both of them may be
-disabled) and a month area below them which shows all the days in the
-month. The user can move the current selection using the keyboard and select
-the date (generating EVT_CALENDAR event) by pressing <Return> or double
-clicking it.
-
-It has advanced possibilities for the customization of its display. All global
-settings (such as colours and fonts used) can, of course, be changed. But
-also, the display style for each day in the month can be set independently
-using CalendarDateAttr class.
-
-An item without custom attributes is drawn with the default colours and font
-and without border, but setting custom attributes with SetAttr allows to
-modify its appearance. Just create a custom attribute object and set it for
-the day you want to be displayed specially A day may be marked as being a
-holiday, (even if it is not recognized as one by wx.DateTime) by using the
-SetHoliday method.
-
-As the attributes are specified for each day, they may change when the month
-is changed, so you will often want to update them in an EVT_CALENDAR_MONTH
-event handler.
-
- Styles
-    CAL_SUNDAY_FIRST:          Show Sunday as the first day in the week
-    CAL_MONDAY_FIRST:          Show Monday as the first day in the week
-    CAL_SHOW_HOLIDAYS:         Highlight holidays in the calendar
-    CAL_NO_YEAR_CHANGE:                Disable the year changing
-    CAL_NO_MONTH_CHANGE:       Disable the month (and, implicitly, the year) changing
-    CAL_SHOW_SURROUNDING_WEEKS:        Show the neighbouring weeks in the previous and next months
-    CAL_SEQUENTIAL_MONTH_SELECTION:    Use alternative, more compact, style for the month and year selection controls.
-
-The default calendar style is wxCAL_SHOW_HOLIDAYS.
-
- Events
-    EVT_CALENDAR:              A day was double clicked in the calendar.
-    EVT_CALENDAR_SEL_CHANGED:  The selected date changed.
-    EVT_CALENDAR_DAY:          The selected day changed.
-    EVT_CALENDAR_MONTH:        The selected month changed.
-    EVT_CALENDAR_YEAR:         The selected year changed.
-    EVT_CALENDAR_WEEKDAY_CLICKED:      User clicked on the week day header
-
-Note that changing the selected date will result in either of
-EVT_CALENDAR_DAY, MONTH or YEAR events and an EVT_CALENDAR_SEL_CHANGED event.
+"The calendar control allows the user to pick a date interactively.
+
+The CalendarCtrl displays a window containing several parts: the
+control to pick the month and the year at the top (either or both of
+them may be disabled) and a month area below them which shows all the
+days in the month. The user can move the current selection using the
+keyboard and select the date (generating EVT_CALENDAR event) by
+pressing <Return> or double clicking it.
+
+It has advanced possibilities for the customization of its
+display. All global settings (such as colours and fonts used) can, of
+course, be changed. But also, the display style for each day in the
+month can be set independently using CalendarDateAttr class.
+
+An item without custom attributes is drawn with the default colours
+and font and without border, but setting custom attributes with
+SetAttr allows to modify its appearance. Just create a custom
+attribute object and set it for the day you want to be displayed
+specially A day may be marked as being a holiday, (even if it is not
+recognized as one by wx.DateTime) by using the SetHoliday method.
+
+As the attributes are specified for each day, they may change when the
+month is changed, so you will often want to update them in an
+EVT_CALENDAR_MONTH event handler.
+
+Window Styles
+-------------
+    ==============================   ============================
+    CAL_SUNDAY_FIRST                 Show Sunday as the first day
+                                     in the week
+    CAL_MONDAY_FIRST                 Show Monday as the first day
+                                     in the week
+    CAL_SHOW_HOLIDAYS                Highlight holidays in the
+                                     calendar
+    CAL_NO_YEAR_CHANGE               Disable the year changing
+    CAL_NO_MONTH_CHANGE              Disable the month (and,
+                                     implicitly, the year) changing
+    CAL_SHOW_SURROUNDING_WEEKS       Show the neighbouring weeks in
+                                     the previous and next months
+    CAL_SEQUENTIAL_MONTH_SELECTION   Use alternative, more compact,
+                                     style for the month and year
+                                     selection controls.
+
+The default calendar style is CAL_SHOW_HOLIDAYS.
+
+Events
+-------
+    ===========================    ==============================
+    EVT_CALENDAR                   A day was double clicked in the
+                                   calendar.
+    EVT_CALENDAR_SEL_CHANGED       The selected date changed.
+    EVT_CALENDAR_DAY               The selected day changed.
+    EVT_CALENDAR_MONTH             The selected month changed.
+    EVT_CALENDAR_YEAR              The selected year changed.
+    EVT_CALENDAR_WEEKDAY_CLICKED   User clicked on the week day
+                                   header
+
+Note that changing the selected date will result in one of
+EVT_CALENDAR_DAY, MONTH or YEAR events and an EVT_CALENDAR_SEL_CHANGED
+event.

     
 ");       
 
     
 ");       
 


@@ -200,29 +212,34 @@ public:
     %pythonAppend wxCalendarCtrl      "self._setOORInfo(self)"
     %pythonAppend wxCalendarCtrl()    ""
 
     %pythonAppend wxCalendarCtrl      "self._setOORInfo(self)"
     %pythonAppend wxCalendarCtrl()    ""
 

-    DocStr(wxCalendarCtrl, "Create and show a calendar control.");

     RefDoc(wxCalendarCtrl, ""); // turn it off for the ctors
     RefDoc(wxCalendarCtrl, ""); // turn it off for the ctors

-    
-    wxCalendarCtrl(wxWindow *parent,
-                   wxWindowID id=-1,
-                   const wxDateTime& date = wxDefaultDateTime,
-                   const wxPoint& pos = wxDefaultPosition,
-                   const wxSize& size = wxDefaultSize,
-                   long style = wxCAL_SHOW_HOLIDAYS | wxWANTS_CHARS,
-                   const wxString& name = wxPyCalendarNameStr);
-

 
 

-    DocStr(wxCalendarCtrl(), "Precreate a CalendarCtrl for 2-phase creation.");
-    %name(PreCalendarCtrl)wxCalendarCtrl();
+    DocCtorStr(
+        wxCalendarCtrl(wxWindow *parent,
+                       wxWindowID id=-1,
+                       const wxDateTime& date = wxDefaultDateTime,
+                       const wxPoint& pos = wxDefaultPosition,
+                       const wxSize& size = wxDefaultSize,
+                       long style = wxCAL_SHOW_HOLIDAYS | wxWANTS_CHARS,
+                       const wxString& name = wxPyCalendarNameStr),
+        "Create and show a calendar control.");
+
+    DocCtorStrName(
+        wxCalendarCtrl(),
+        "Precreate a CalendarCtrl for 2-phase creation.",
+        PreCalendarCtrl);

 
 

-    DocStr(Create, "Acutally create the GUI portion of the CalendarCtrl for 2-phase creation.");
-    bool Create(wxWindow *parent,
-                wxWindowID id,
-                const wxDateTime& date = wxDefaultDateTime,
-                const wxPoint& pos = wxDefaultPosition,
-                const wxSize& size = wxDefaultSize,
-                long style = wxCAL_SHOW_HOLIDAYS | wxWANTS_CHARS,
-                const wxString& name = wxPyCalendarNameStr);
+    DocDeclStr(
+        bool , Create(wxWindow *parent,
+                      wxWindowID id,
+                      const wxDateTime& date = wxDefaultDateTime,
+                      const wxPoint& pos = wxDefaultPosition,
+                      const wxSize& size = wxDefaultSize,
+                      long style = wxCAL_SHOW_HOLIDAYS | wxWANTS_CHARS,
+                      const wxString& name = wxPyCalendarNameStr),
+        "Acutally create the GUI portion of the CalendarCtrl for 2-phase
+creation.");
+    

 
 
     DocDeclStr(
 
 
     DocDeclStr(


@@ -261,74 +278,80 @@ public:
 
     DocDeclStr(
         void, EnableYearChange(bool enable = True),
 
     DocDeclStr(
         void, EnableYearChange(bool enable = True),

-        "This function should be used instead of changing CAL_NO_YEAR_CHANGE\n"
-        "style bit directly. It allows or disallows the user to change the year\n"
-        "interactively.");
+        "This function should be used instead of changing CAL_NO_YEAR_CHANGE
+style bit directly. It allows or disallows the user to change the year
+interactively.");

     
     DocDeclStr(
         void, EnableMonthChange(bool enable = True),
     
     DocDeclStr(
         void, EnableMonthChange(bool enable = True),

-        "This function should be used instead of changing CAL_NO_MONTH_CHANGE style\n"
-        "bit. It allows or disallows the user to change the month interactively. Note\n"
-        "that if the month can not be changed, the year can not be changed either.");
+        "This function should be used instead of changing CAL_NO_MONTH_CHANGE
+style bit. It allows or disallows the user to change the month
+interactively. Note that if the month can not be changed, the year can
+not be changed either.");

 
     DocDeclStr(
         void, EnableHolidayDisplay(bool display = True),
 
     DocDeclStr(
         void, EnableHolidayDisplay(bool display = True),

-        "This function should be used instead of changing CAL_SHOW_HOLIDAYS style\n"
-        "bit directly. It enables or disables the special highlighting of the holidays.");
+        "This function should be used instead of changing CAL_SHOW_HOLIDAYS
+style bit directly. It enables or disables the special highlighting of
+the holidays.");

 
 
     
     DocDeclStr(
         void, SetHeaderColours(const wxColour& colFg, const wxColour& colBg),
 
 
     
     DocDeclStr(
         void, SetHeaderColours(const wxColour& colFg, const wxColour& colBg),

-        "header colours are used for painting the weekdays at the top");
+        "Header colours are used for painting the weekdays at the top.");

 
     DocDeclStr(
         wxColour, GetHeaderColourFg() const,
 
     DocDeclStr(
         wxColour, GetHeaderColourFg() const,

-        "header colours are used for painting the weekdays at the top");
+        "Header colours are used for painting the weekdays at the top.");

     
     DocDeclStr(
         wxColour, GetHeaderColourBg() const,
     
     DocDeclStr(
         wxColour, GetHeaderColourBg() const,

-        "header colours are used for painting the weekdays at the top");
+        "Header colours are used for painting the weekdays at the top.");

 
 
     
     DocDeclStr(
         void, SetHighlightColours(const wxColour& colFg, const wxColour& colBg),
 
 
     
     DocDeclStr(
         void, SetHighlightColours(const wxColour& colFg, const wxColour& colBg),

-        "highlight colour is used for the currently selected date");
+        "Highlight colour is used for the currently selected date.");

     
     DocDeclStr(
         wxColour, GetHighlightColourFg() const,
     
     DocDeclStr(
         wxColour, GetHighlightColourFg() const,

-        "highlight colour is used for the currently selected date");
+        "Highlight colour is used for the currently selected date.");

     
     DocDeclStr(
         wxColour, GetHighlightColourBg() const,
     
     DocDeclStr(
         wxColour, GetHighlightColourBg() const,

-        "highlight colour is used for the currently selected date");
+        "Highlight colour is used for the currently selected date.");

 
     
      
     DocDeclStr(
         void, SetHolidayColours(const wxColour& colFg, const wxColour& colBg),
 
     
      
     DocDeclStr(
         void, SetHolidayColours(const wxColour& colFg, const wxColour& colBg),

-        "holiday colour is used for the holidays (if CAL_SHOW_HOLIDAYS style is used)");
+        "Holiday colour is used for the holidays (if CAL_SHOW_HOLIDAYS style is
+used).");

     
     DocDeclStr(
         wxColour, GetHolidayColourFg() const,
     
     DocDeclStr(
         wxColour, GetHolidayColourFg() const,

-        "holiday colour is used for the holidays (if CAL_SHOW_HOLIDAYS style is used)");
+        "Holiday colour is used for the holidays (if CAL_SHOW_HOLIDAYS style is
+used).");

     
     DocDeclStr(
         wxColour, GetHolidayColourBg() const,
     
     DocDeclStr(
         wxColour, GetHolidayColourBg() const,

-        "holiday colour is used for the holidays (if CAL_SHOW_HOLIDAYS style is used)");
+        "Holiday colour is used for the holidays (if CAL_SHOW_HOLIDAYS style is
+used).");

 
 
     
     DocDeclStr(
         wxCalendarDateAttr*, GetAttr(size_t day) const,
 
 
     
     DocDeclStr(
         wxCalendarDateAttr*, GetAttr(size_t day) const,

-        "Returns the attribute for the given date (should be in the range 1...31).\n"
-        "The returned value may be None");
+        "Returns the attribute for the given date (should be in the range
+1...31).  The returned value may be None");

     
     DocDeclStr(
         void, SetAttr(size_t day, wxCalendarDateAttr *attr),
     
     DocDeclStr(
         void, SetAttr(size_t day, wxCalendarDateAttr *attr),

-        "Associates the attribute with the specified date (in the range 1...31).\n"
-        "If the attribute passed is None, the items attribute is cleared.");
+        "Associates the attribute with the specified date (in the range
+1...31).  If the attribute passed is None, the items attribute is
+cleared.");

 
     DocDeclStr(
         void, SetHoliday(size_t day),
 
     DocDeclStr(
         void, SetHoliday(size_t day),


@@ -336,19 +359,23 @@ public:
 
     DocDeclStr(
         void, ResetAttr(size_t day),
 
     DocDeclStr(
         void, ResetAttr(size_t day),

-        "Clears any attributes associated with the given day (in the range 1...31).");
+        "Clears any attributes associated with the given day (in the range
+1...31).");

     
 
 
     DocAStr(HitTest,
             "HitTest(Point pos) -> (result, date, weekday)",
     
 
 
     DocAStr(HitTest,
             "HitTest(Point pos) -> (result, date, weekday)",

-"Returns 3-tuple with information about the given position on the calendar
-control.  The first value of the tuple is a result code and determines the
-validity of the remaining two values.  The result codes are:
-
-    CAL_HITTEST_NOWHERE:    hit outside of anything
-    CAL_HITTEST_HEADER:     hit on the header, weekday is valid
-    CAL_HITTEST_DAY:        hit on a day in the calendar, date is set.
+"Returns 3-tuple with information about the given position on the
+calendar control.  The first value of the tuple is a result code and
+determines the validity of the remaining two values.  The result codes
+are:
+
+    ===================    ============================================
+    CAL_HITTEST_NOWHERE    hit outside of anything
+    CAL_HITTEST_HEADER     hit on the header, weekday is valid
+    CAL_HITTEST_DAY        hit on a day in the calendar, date is set.
+    ===================    ============================================

 ");           
     %extend {
         PyObject* HitTest(const wxPoint& pos) {
 ");           
     %extend {
         PyObject* HitTest(const wxPoint& pos) {


@@ -367,11 +394,11 @@ validity of the remaining two values.  The result codes are:
 
     DocDeclStr(
         wxControl*, GetMonthControl() const,
 
     DocDeclStr(
         wxControl*, GetMonthControl() const,

-        "get the currently shown control for month");
+        "Get the currently shown control for month.");

     
     DocDeclStr(
         wxControl*, GetYearControl() const,
     
     DocDeclStr(
         wxControl*, GetYearControl() const,

-        "get the currently shown control for year");
+        "Get the currently shown control for year.");

 };
 
 
 };
 
 

diff --git a/wxPython/src/core.i b/wxPython/src/core.i
index 5dd883fdc1e8be30223a737703360ecc166c22fb..b10d9d60dfdc5c3d348deceaf4ace82c19fe089e 100644 (file)
--- a/wxPython/src/core.i
+++ b/wxPython/src/core.i
@@ -39,11 +39,32 @@ _core_._wxPySetDictionary(vars())
 %#// be used here.
 import sys as _sys
 wx = _sys.modules[__name__]
 %#// be used here.
 import sys as _sys
 wx = _sys.modules[__name__]

-}

 
 

+}

 #endif
 
 
 #endif
 
 

+%pythoncode {
+%#----------------------------------------------------------------------------
+
+def _deprecated(callable, msg=None):
+    """
+    Create a wrapper function that will raise a DeprecationWarning
+    before calling the callable.
+    """
+    if msg is None:
+        msg = "%s is deprecated" % callable
+    def deprecatedWrapper(*args, **kwargs):
+        import warnings
+        warnings.warn(msg, DeprecationWarning, stacklevel=2)
+        return callable(*args, **kwargs)
+    deprecatedWrapper.__doc__ = msg
+    return deprecatedWrapper
+    
+                   
+%#----------------------------------------------------------------------------
+}
+

 
 //---------------------------------------------------------------------------
 // Include all the files that make up the core module
 
 //---------------------------------------------------------------------------
 // Include all the files that make up the core module

diff --git a/wxPython/wx/lib/rightalign.py b/wxPython/wx/lib/rightalign.py
index 69723c37a6547ebc44bf881a6b5eaad7aedbbf3a..b0969b9a0e69f1fc82211d0aa3a3d8a68c0a6bd4 100644 (file)
--- a/wxPython/wx/lib/rightalign.py
+++ b/wxPython/wx/lib/rightalign.py
@@ -37,7 +37,7 @@ left-aligned if it has focus.
 Hope this can help someone, as much as this list helps me.
 
 Josu Oyanguren
 Hope this can help someone, as much as this list helps me.
 
 Josu Oyanguren

-Ubera Servicios Informáticos.
+Ubera Servicios Informaticos.

 
 
 P.S.  This only works well on wxMSW.
 
 
 P.S.  This only works well on wxMSW.