Added docstrings

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

wxPython/src/_cshelp.i

@@ -37,74 +37,223 @@ EVT_DETAILED_HELP_RANGE = wx.PyEventBinder( wxEVT_DETAILED_HELP, 2)
 
 //----------------------------------------------------------------------
 
-// A help event is sent when the user clicks on a window in context-help mode.
+DocStr(wxHelpEvent,
+"A help event is sent when the user has requested
+context-sensitive help. This can either be caused by the
+application requesting context-sensitive help mode via
+wx.ContextHelp, or (on MS Windows) by the system generating a
+WM_HELP message when the user pressed F1 or clicked on the query
+button in a dialog caption.
+
+A help event is sent to the window that the user clicked on, and
+is propagated up the window hierarchy until the event is
+processed or there are no more event handlers. The application
+should call event.GetId to check the identity of the clicked-on
+window, and then either show some suitable help or call
+event.Skip if the identifier is unrecognised. Calling Skip is
+important because it allows wxWindows to generate further events
+for ancestors of the clicked-on window. Otherwise it would be
+impossible to show help for container windows, since processing
+would stop after the first window found.
+
+ Events
+    EVT_HELP            Sent when the user has requested context-
+                        sensitive help.
+    EVT_HELP_RANGE      Allows to catch EVT_HELP for a range of IDs
+");
+
 
 class wxHelpEvent : public wxCommandEvent
 {
 public:
+    DocCtorStr(
         wxHelpEvent(wxEventType type = wxEVT_NULL,
                     wxWindowID winid = 0,
-                const wxPoint& pt = wxDefaultPosition);
+                    const wxPoint& pt = wxDefaultPosition),
+        "");
     
-    // Position of event (in screen coordinates)
-    const wxPoint& GetPosition() const;
-    void SetPosition(const wxPoint& pos);
 
-    // Optional link to further help
+    DocDeclStr(
-    const wxString& GetLink() const;
+        const wxPoint , GetPosition() const,
-    void SetLink(const wxString& link);
+        "Returns the left-click position of the mouse, in screen\n"
+        "coordinates. This allows the application to position the help\n"
+        "appropriately.");
+    
+    DocDeclStr(
+        void , SetPosition(const wxPoint& pos),
+        "Sets the left-click position of the mouse, in screen coordinates.");
+    
+
+    DocDeclStr(
+        const wxString& , GetLink() const,
+        "Get an optional link to further help");
+    
+    DocDeclStr(
+        void , SetLink(const wxString& link),
+        "Set an optional link to further help");
+    
+
+    DocDeclStr(
+        const wxString& , GetTarget() const,
+        "Get an optional target to display help in. E.g. a window specification");
+    
+    DocDeclStr(
+        void , SetTarget(const wxString& target),
+        "Set an optional target to display help in. E.g. a window specification");
     
-    // Optional target to display help in. E.g. a window specification
-    const wxString& GetTarget() const;
-    void SetTarget(const wxString& target);
 };
 
 //---------------------------------------------------------------------------
 
+
+DocStr(wxContextHelp,
+"This class changes the cursor to a query and puts the application
+into a 'context-sensitive help mode'. When the user left-clicks
+on a window within the specified window, a EVT_HELP event is sent
+to that control, and the application may respond to it by popping
+up some help.
+
+There are a couple of ways to invoke this behaviour implicitly:
+
+    * Use the wx.DIALOG_EX_CONTEXTHELP extended style for a
+      dialog (Windows only). This will put a question mark in the
+      titlebar, and Windows will put the application into
+      context-sensitive help mode automatically, with further
+      programming.
+
+    * Create a wx.ContextHelpButton, whose predefined behaviour
+      is to create a context help object. Normally you will write
+      your application so that this button is only added to a
+      dialog for non-Windows platforms (use
+      wx.DIALOG_EX_CONTEXTHELP on Windows).
+");       
+
 class wxContextHelp : public wxObject {
 public:
-    wxContextHelp(wxWindow* window = NULL, bool doNow = True);
+    DocCtorStr(
+        wxContextHelp(wxWindow* window = NULL, bool doNow = True),
+        "Constructs a context help object, calling BeginContextHelp if\n"
+        "doNow is true (the default).\n"
+        "\n"
+        "If window is None, the top window is used.");
+    
     ~wxContextHelp();
 
-    bool BeginContextHelp(wxWindow* window = NULL);
+    DocDeclStr(
-    bool EndContextHelp();
+        bool , BeginContextHelp(wxWindow* window = NULL),
+        "Puts the application into context-sensitive help mode. window is\n"
+        "the window which will be used to catch events; if NULL, the top\n"
+        "window will be used.\n"
+        "\n"
+        "Returns true if the application was successfully put into\n"
+        "context-sensitive help mode. This function only returns when the\n"
+        "event loop has finished.");
+    
+    DocDeclStr(
+        bool , EndContextHelp(),
+        "Ends context-sensitive help mode. Not normally called by the\n"
+        "application.");
+    
 };
 
 
 //----------------------------------------------------------------------
 
+DocStr(wxContextHelpButton,
+"Instances of this class may be used to add a question mark button
+that when pressed, puts the application into context-help
+mode. It does this by creating a wx.ContextHelp object which
+itself generates a EVT_HELP event when the user clicks on a
+window.
+
+On Windows, you may add a question-mark icon to a dialog by use
+of the wx.DIALOG_EX_CONTEXTHELP extra style, but on other
+platforms you will have to add a button explicitly, usually next
+to OK, Cancel or similar buttons.
+");
+
 class wxContextHelpButton : public wxBitmapButton {
 public:
     %pythonAppend wxContextHelpButton "self._setOORInfo(self)"
 
+    DocCtorStr(
         wxContextHelpButton(wxWindow* parent, wxWindowID id = wxID_CONTEXT_HELP,
                             const wxPoint& pos = wxDefaultPosition,
                             const wxSize& size = wxDefaultSize,
-                        long style = wxBU_AUTODRAW);
+                            long style = wxBU_AUTODRAW),
+        "Constructor, creating and showing a context help button.");
 };
 
 
 //----------------------------------------------------------------------
 
+DocStr(wxHelpProvider,
+"wx.HelpProvider is an abstract class used by a program
+implementing context-sensitive help to show the help text for the
+given window.
+
+The current help provider must be explicitly set by the
+application using wx.HelpProvider.Set().");
+
 class wxHelpProvider 
 {
 public:
-    static wxHelpProvider *Set(wxHelpProvider *helpProvider);
+    DocDeclStr(
-    static wxHelpProvider *Get();
+        static wxHelpProvider *, Set(wxHelpProvider *helpProvider),
+        "Sset the current, application-wide help provider. Returns the\n"
+        "previous one.  Unlike some other classes, the help provider is\n"
+        "not created on demand. This must be explicitly done by the\n"
+        "application.");
+    
+    DocDeclStr(
+        static wxHelpProvider *, Get(),
+        "Return the current application-wide help provider.");
+    
+
+    DocDeclStr(
+        wxString , GetHelp(const wxWindow *window),
+        "Gets the help string for this window. Its interpretation is\n"
+        "dependent on the help provider except that empty string always\n"
+        "means that no help is associated with the window.");
+    
+    DocDeclStr(
+        bool , ShowHelp(wxWindow *window),
+        "Shows help for the given window. Uses GetHelp internally if\n"
+        "applicable.\n"
+        "\n"
+        "Returns true if it was done, or false if no help was available\n"
+        "for this window.");
+    
+    DocDeclStr(
+        void , AddHelp(wxWindow *window, const wxString& text),
+        "Associates the text with the given window.");
+
+    DocDeclStrName(
+        void , AddHelp(wxWindowID id, const wxString& text),
+        "This version associates the given text with all windows with this\n"
+        "id. May be used to set the same help string for all Cancel\n"
+        "buttons in the application, for example.",
+        AddHelpById);
+
+    DocDeclStr(
+        void , RemoveHelp(wxWindow* window),
+        "Removes the association between the window pointer and the help\n"
+        "text. This is called by the wx.Window destructor. Without this,\n"
+        "the table of help strings will fill up and when window pointers\n"
+        "are reused, the wrong help string will be found.");
     
-    // Virtuals...
-    wxString GetHelp(const wxWindow *window);
-    bool ShowHelp(wxWindow *window);
-    void AddHelp(wxWindow *window, const wxString& text);
-    %name(AddHelpById)void AddHelp(wxWindowID id, const wxString& text);
     
     %extend { void Destroy() { delete self; } }
-
 };
 
  
 //----------------------------------------------------------------------
 
+DocStr(wxSimpleHelpProvider,
+"wx.SimpleHelpProvider is an implementation of wx.HelpProvider
+which supports only plain text help strings, and shows the string
+associated with the control (if any) in a tooltip.");
+
 class wxSimpleHelpProvider : public wxHelpProvider
 {
 public:

wxPython/src/_cursor.i

@@ -15,58 +15,167 @@
 
 //---------------------------------------------------------------------------
 
+
+DocStr(wxCursor,
+"A cursor is a small bitmap usually used for denoting where the
+mouse pointer is, with a picture that might indicate the
+interpretation of a mouse click.
+
+A single cursor object may be used in many windows (any subwindow
+type). The wxWindows convention is to set the cursor for a
+window, as in X, rather than to set it globally as in MS Windows,
+although a global wx.SetCursor function is also available for use
+on MS Windows.");
+
+
+RefDoc(wxCursor::wxCursor(int id),
+"
+  Stock Cursor IDs
+
+    wx.CURSOR_ARROW             A standard arrow cursor.
+    wx.CURSOR_RIGHT_ARROW       A standard arrow cursor pointing to the right.
+    wx.CURSOR_BLANK             Transparent cursor.
+    wx.CURSOR_BULLSEYE          Bullseye cursor.
+    wx.CURSOR_CHAR              Rectangular character cursor.
+    wx.CURSOR_CROSS             A cross cursor.
+    wx.CURSOR_HAND              A hand cursor.
+    wx.CURSOR_IBEAM             An I-beam cursor (vertical line).
+    wx.CURSOR_LEFT_BUTTON       Represents a mouse with the left button depressed.
+    wx.CURSOR_MAGNIFIER         A magnifier icon.
+    wx.CURSOR_MIDDLE_BUTTON     Represents a mouse with the middle button depressed.
+    wx.CURSOR_NO_ENTRY          A no-entry sign cursor.
+    wx.CURSOR_PAINT_BRUSH       A paintbrush cursor.
+    wx.CURSOR_PENCIL            A pencil cursor.
+    wx.CURSOR_POINT_LEFT        A cursor that points left.
+    wx.CURSOR_POINT_RIGHT       A cursor that points right.
+    wx.CURSOR_QUESTION_ARROW    An arrow and question mark.
+    wx.CURSOR_RIGHT_BUTTON      Represents a mouse with the right button depressed.
+    wx.CURSOR_SIZENESW          A sizing cursor pointing NE-SW.
+    wx.CURSOR_SIZENS            A sizing cursor pointing N-S.
+    wx.CURSOR_SIZENWSE          A sizing cursor pointing NW-SE.
+    wx.CURSOR_SIZEWE            A sizing cursor pointing W-E.
+    wx.CURSOR_SIZING            A general sizing cursor.
+    wx.CURSOR_SPRAYCAN          A spraycan cursor.
+    wx.CURSOR_WAIT              A wait cursor.
+    wx.CURSOR_WATCH             A watch cursor.
+    wx.CURSOR_ARROWWAIT         A cursor with both an arrow and an hourglass, (windows.)
+
+");
+
 class wxCursor : public wxGDIObject
 {
 public:
+    
     %extend {
-        wxCursor(const wxString* cursorName, long flags, int hotSpotX=0, int hotSpotY=0) {
+        DocStr(wxCursor,
-#ifdef __WXGTK__
+               "Construct a Cursor from a file.  Specify the type of file using\n"
+               "wx.BITAMP_TYPE* constants, and specify the hotspot if not using a\n"
+               ".cur file.\n"
+               "\n"
+               "This cursor is not available on wxGTK, use wx.StockCursor,\n"
+               "wx.CursorFromImage, or wx.CursorFromBits instead.");
+        wxCursor(const wxString* cursorName, long type, int hotSpotX=0, int hotSpotY=0) {
+%#ifdef __WXGTK__
             wxCHECK_MSG(False, NULL,
-                        wxT("wxCursor constructor not implemented for wxGTK, use wxStockCursor, wxCursorFromImage, or wxCursorFromBits instead."));
+                        wxT("wx.Cursor constructor not implemented for wxGTK, use wx.StockCursor, wx.CursorFromImage, or wx.CursorFromBits instead."));
-#else
+%#else
             return new wxCursor(*cursorName, flags, hotSpotX, hotSpotY);
-#endif
+%#endif
         }
     }
 
     ~wxCursor();
 
-    // alternate constructors
+    DocCtorStrName(
-    %name(StockCursor) wxCursor(int id);
+        wxCursor(int id),
-    %name(CursorFromImage) wxCursor(const wxImage& image);
+        "Create a cursor using one of the stock cursors.  Note that not\n"
-    %extend {
+        "all cursors are available on all platforms.",
-        %name(CursorFromBits) wxCursor(PyObject* bits, int width, int  height,
+        StockCursor);
-                                         int hotSpotX=-1, int hotSpotY=-1,
+
-                                         PyObject* maskBits=0) {
+    
-            char* bitsbuf;
+    DocCtorStrName(
-            char* maskbuf = NULL;
+        wxCursor(const wxImage& image),
-            int   length;
+        "Constructs a cursor from a wxImage. The cursor is monochrome,\n"
-            PyString_AsStringAndSize(bits, &bitsbuf, &length);
+        "colors with the RGB elements all greater than 127 will be\n"
-            if (maskBits)
+        "foreground, colors less than this background. The mask (if any)\n"
-                PyString_AsStringAndSize(maskBits, &maskbuf, &length);
+        "will be used as transparent.\n"
-            return new wxCursor(bitsbuf, width, height, hotSpotX, hotSpotY, maskbuf);
+        "\n"
-        }
+        "In MSW the foreground will be white and the background black. The\n"
-    }
+        "cursor is resized to 32x32 In GTK, the two most frequent colors\n"
+        "will be used for foreground and background. The cursor will be\n"
+        "displayed at the size of the image. On MacOS the cursor is\n"
+        "resized to 16x16 and currently only shown as black/white (mask\n"
+        "respected).",
+        CursorFromImage);
+    
+    
+//     %extend {
+//         DocStr(wxCursor,
+//                "");
+//         %name(CursorFromBits) wxCursor(PyObject* bits, int width, int  height,
+//                                          int hotSpotX=-1, int hotSpotY=-1,
+//                                          PyObject* maskBits=NULL) {
+//             char* bitsbuf;
+//             char* maskbuf = NULL;
+//             int   length;
+//             PyString_AsStringAndSize(bits, &bitsbuf, &length);
+//             if (maskBits)
+//                 PyString_AsStringAndSize(maskBits, &maskbuf, &length);
+//             return new wxCursor(bitsbuf, width, height, hotSpotX, hotSpotY, maskbuf);
+//         }
+//     }
 
-    // wxGDIImage methods
-#ifdef __WXMSW__
-    long GetHandle();
-    void SetHandle(long handle);
-#endif
     
-    bool Ok();
     
 #ifdef __WXMSW__
-    int GetWidth();
+    DocDeclStr(
-    int GetHeight();
+        long , GetHandle(),
-    int GetDepth();
+        "Get the MS Windows handle for the cursor");
-    void SetWidth(int w);
+    
-    void SetHeight(int h);
+    DocDeclStr(
-    void SetDepth(int d);
+        void , SetHandle(long handle),
-    void SetSize(const wxSize& size);
+        "Set the MS WIndows handle for the cursor");
+    
 #endif
     
+    DocDeclStr(
+        bool , Ok(),
+        "");
+
     %pythoncode { def __nonzero__(self): return self.Ok() }
+
+    
+#ifdef __WXMSW__
+    DocDeclStr(
+        int , GetWidth(),
+        "");
+    
+    DocDeclStr(
+        int , GetHeight(),
+        "");
+    
+    DocDeclStr(
+        int , GetDepth(),
+        "");
+    
+    DocDeclStr(
+        void , SetWidth(int w),
+        "");
+    
+    DocDeclStr(
+        void , SetHeight(int h),
+        "");
+    
+    DocDeclStr(
+        void , SetDepth(int d),
+        "");
+    
+    DocDeclStr(
+        void , SetSize(const wxSize& size),
+        "");
+    
+#endif
+    
 };