Add docstrings and a dummy class to be used in builds that don't have wxSearchCtrl.

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

wxPython/src/_srchctrl.i

@@ -18,7 +18,91 @@
 MAKE_CONST_WXSTRING(SearchCtrlNameStr);
 
 
+%{
+#if !defined(wxUSE_SEARCHCTRL) || !wxUSE_SEARCHCTRL
+// define a dummy class for builds that don't have wxSearchCtrl
+
+enum {
+    wxEVT_COMMAND_SEARCHCTRL_CANCEL,
+    wxEVT_COMMAND_SEARCHCTRL_SEARCH
+};
+
+class wxSearchCtrl : public wxTextCtrl
+{
+public:
+    wxSearchCtrl() { wxPyRaiseNotImplemented(); }
+    wxSearchCtrl(wxWindow*, wxWindowID,
+                 const wxString&,
+                 const wxPoint&,
+                 const wxSize&,
+                 long style,
+                 const wxValidator&,
+                 const wxString& name)
+    { wxPyRaiseNotImplemented(); }
+
+    bool Create( wxWindow*, wxWindowID,
+                 const wxString&,
+                 const wxPoint&,
+                 const wxSize&,
+                 long style,
+                 const wxValidator&,
+                 const wxString& name) {}
+        
+    virtual void SetMenu( wxMenu* ) {}
+    virtual wxMenu* GetMenu() { return NULL; }
+    
+    // get/set search options
+    // ----------------------
+    virtual void ShowSearchButton( bool ) {}
+    virtual bool IsSearchButtonVisible() const { return false; }
+
+    virtual void ShowCancelButton( bool ) {}
+    virtual bool IsCancelButtonVisible() const { return false; }
+};    
+#endif
+%}
+
+
+
+// Now define the class for SWIG
+
 MustHaveApp(wxSearchCtrl);
+DocStr(wxSearchCtrl,
+"A search control is a composite of a `wx.TextCtrl` with optional
+bitmap buttons and a drop-down menu.  Controls like this can typically
+be found on a toolbar of applications that support some form of search
+functionality.  On the Mac this control is implemneted using the
+native HISearchField control, on the other platforms a generic control
+is used, although that may change in the future as more platforms
+introduce native search widgets.
+
+If you wish to use a drop-down menu with your wx.SearchCtrl then you
+will need to manage its content and handle the menu events yourself,
+but this is an easy thing to do.  Simply build the menu, pass it to
+`SetMenu`, and also bind a handler for a range of EVT_MENU events.
+This gives you the flexibility to use the drop-down menu however you
+wish, such as for a history of searches, or as a way to select
+different kinds of searches.  The ToolBar.py sample in the demo shows
+one way to do this.
+
+Since the control derives from `wx.TextCtrl` it is convenient to use
+the styles and events designed for `wx.TextCtrl`.  For example you can
+use the ``wx.TE_PROCESS_ENTER`` style and catch the
+``wx.EVT_TEXT_ENTER`` event to know when the user has pressed the
+Enter key in the control and wishes to start a search.
+", "
+
+Events
+-------
+    ======================    =========================================
+    EVT_SEARCHCTRL_SEARCH     Sent when the search icon is clicked
+    EVT_SEARCHCTRL_CANCEL     Sent when the cancel icon is clicked
+    EVT_TEXT                  Sent when the text changes
+    EVT_TEXT_ENTER            Sent when the RETURN/ENTER key is pressed 
+                              in the search control and the control has
+                              the wx.TE_PROCESS_ENTER style flag set.
+    ======================    =========================================
+");
 
 
 class wxSearchCtrl : public wxTextCtrl
@@ -49,18 +133,51 @@ public:
                 const wxString& name = wxPySearchCtrlNameStr);
 
 
-    // get/set search button menu
+    DocDeclStr(
-    // --------------------------
+        virtual void , SetMenu( wxMenu* menu ),
-    virtual void SetMenu( wxMenu* menu );
+        "Sets the search control's menu object. If there is already a menu
-    virtual wxMenu* GetMenu();
+associated with the search control it is deleted.", "");
     
-    // get/set search options
+    DocDeclStr(
-    // ----------------------
+        virtual wxMenu* , GetMenu(),
-    virtual void ShowSearchButton( bool show );
+        "Returns a pointer to the search control's menu object or None if there
-    virtual bool IsSearchButtonVisible() const;
+is no menu attached.", "");
 
-    virtual void ShowCancelButton( bool show );
+    
-    virtual bool IsCancelButtonVisible() const;
+    
+    DocDeclStr(
+        virtual void , ShowSearchButton( bool show ),
+        "Sets the search button visibility value on the search control. If
+there is a menu attached, the search button will be visible regardless
+of the search button visibility value.  This has no effect in Mac OS X
+v10.3", "");
+    
+    DocDeclStr(
+        virtual bool , IsSearchButtonVisible() const,
+        "Returns the search button visibility value. If there is a menu
+attached, the search button will be visible regardless of the search
+button visibility value.  This always returns false in Mac OS X v10.3", "");
+    
+
+    DocDeclStr(
+        virtual void , ShowCancelButton( bool show ),
+        "Shows or hides the cancel button.", "");
+    
+    DocDeclStr(
+        virtual bool , IsCancelButtonVisible() const,
+        "Indicates whether the cancel button is visible. ", "");
+    
+
+    DocStr(SetSearchBitmap,
+           "Sets the bitmap to use for the search button.  This currently does not
+work on the Mac.", "");
+    DocStr(SetSearchMenuBitmap,
+           "Sets the bitmap to use for the search button when there is a drop-down
+menu associated with the search control.  This currently does not work
+on the Mac.", "");
+    DocStr(SetCancelBitmap,
+           "Sets the bitmap to use for the cancel button.  This currently does not
+work on the Mac.", "");
     
 #ifdef __WXMAC__
     %extend {