interface/wx/srchctrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        srchctrl.h
   3 // Purpose:     interface of wxSearchCtrl
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxSearchCtrl
  11
  12     A search control is a composite control with a search button, a text
  13     control, and a cancel button.
  14
  15     @beginStyleTable
  16     @style{wxTE_PROCESS_ENTER}
  17            The control will generate the event @c wxEVT_TEXT_ENTER
  18            (otherwise pressing Enter key is either processed internally by the
  19            control or used for navigation between dialog controls).
  20     @style{wxTE_PROCESS_TAB}
  21            The control will receive @c wxEVT_CHAR events for TAB pressed -
  22            normally, TAB is used for passing to the next control in a dialog
  23            instead. For the control created with this style, you can still use
  24            Ctrl-Enter to pass to the next control from the keyboard.
  25     @style{wxTE_NOHIDESEL}
  26            By default, the Windows text control doesn't show the selection
  27            when it doesn't have focus - use this style to force it to always
  28            show it. It doesn't do anything under other platforms.
  29     @style{wxTE_LEFT}
  30            The text in the control will be left-justified (default).
  31     @style{wxTE_CENTRE}
  32            The text in the control will be centered (currently wxMSW and
  33            wxGTK2 only).
  34     @style{wxTE_RIGHT}
  35            The text in the control will be right-justified (currently wxMSW
  36            and wxGTK2 only).
  37     @style{wxTE_CAPITALIZE}
  38            On PocketPC and Smartphone, causes the first letter to be
  39            capitalized.
  40     @endStyleTable
  41
  42     @beginEventEmissionTable{wxCommandEvent}
  43     To retrieve actual search queries, use EVT_TEXT and EVT_TEXT_ENTER events,
  44     just as you would with wxTextCtrl.
  45     @event{EVT_SEARCHCTRL_SEARCH_BTN(id, func)}
  46         Respond to a @c wxEVT_SEARCHCTRL_SEARCH_BTN event, generated when the
  47         search button is clicked. Note that this does not initiate a search on
  48         its own, you need to perform the appropriate action in your event
  49         handler. You may use @code event.GetString() @endcode to retrieve the
  50         string to search for in the event handler code.
  51     @event{EVT_SEARCHCTRL_CANCEL_BTN(id, func)}
  52         Respond to a @c wxEVT_SEARCHCTRL_CANCEL_BTN event, generated when the
  53         cancel button is clicked.
  54     @endEventTable
  55
  56     @library{wxcore}
  57     @category{ctrl}
  58     @appearance{searchctrl}
  59
  60     @see wxTextCtrl::Create, wxValidator
  61 */
  62 class wxSearchCtrl : public wxTextCtrl
  63 {
  64 public:
  65     /**
  66       Default constructor
  67     */
  68     wxSearchCtrl();
  69
  70     /**
  71         Constructor, creating and showing a text control.
  72
  73         @param parent
  74             Parent window. Should not be @NULL.
  75         @param id
  76             Control identifier. A value of -1 denotes a default value.
  77         @param value
  78             Default text value.
  79         @param pos
  80             Text control position.
  81         @param size
  82             Text control size.
  83         @param style
  84             Window style. See wxSearchCtrl.
  85         @param validator
  86             Window validator.
  87         @param name
  88             Window name.
  89
  90         @see wxTextCtrl::Create, wxValidator
  91     */
  92     wxSearchCtrl(wxWindow* parent, wxWindowID id,
  93                  const wxString& value = wxEmptyString,
  94                  const wxPoint& pos = wxDefaultPosition,
  95                  const wxSize& size = wxDefaultSize,
  96                  long style = 0,
  97                  const wxValidator& validator = wxDefaultValidator,
  98                  const wxString& name = wxSearchCtrlNameStr);
  99
 100     /**
 101         Destructor, destroying the search control.
 102     */
 103     virtual ~wxSearchCtrl();
 104
 105
 106     bool Create(wxWindow* parent, wxWindowID id,
 107                  const wxString& value = wxEmptyString,
 108                  const wxPoint& pos = wxDefaultPosition,
 109                  const wxSize& size = wxDefaultSize,
 110                  long style = 0,
 111                  const wxValidator& validator = wxDefaultValidator,
 112                  const wxString& name = wxSearchCtrlNameStr);
 113
 114     /**
 115         Returns a pointer to the search control's menu object or @NULL if there is no
 116         menu attached.
 117     */
 118     virtual wxMenu* GetMenu();
 119
 120     /**
 121         Returns the search button visibility value.
 122         If there is a menu attached, the search button will be visible regardless of
 123         the search button visibility value.
 124
 125         This always returns @false in Mac OS X v10.3
 126     */
 127     virtual bool IsSearchButtonVisible() const;
 128
 129     /**
 130        Returns the cancel button's visibility state.
 131     */
 132     virtual bool IsCancelButtonVisible() const;
 133
 134     /**
 135         Sets the search control's menu object.
 136         If there is already a menu associated with the search control it is deleted.
 137
 138         @param menu
 139             Menu to attach to the search control.
 140     */
 141     virtual void SetMenu(wxMenu* menu);
 142
 143     /**
 144         Shows or hides the cancel button.
 145     */
 146     virtual void ShowCancelButton(bool show);
 147
 148     /**
 149         Sets the search button visibility value on the search control.
 150         If there is a menu attached, the search button will be visible regardless of
 151         the search button visibility value.
 152
 153         This has no effect in Mac OS X v10.3
 154     */
 155     virtual void ShowSearchButton(bool show);
 156
 157     /**
 158        Set the text to be displayed in the search control when the user has
 159        not yet typed anything in it.
 160     */
 161     void        SetDescriptiveText(const wxString& text);
 162
 163     /**
 164        Return the text displayed when there is not yet any user input.
 165     */
 166     wxString    GetDescriptiveText() const;
 167 };
 168
 169
 170 wxEventType  wxEVT_SEARCHCTRL_CANCEL_BTN;
 171 wxEventType  wxEVT_SEARCHCTRL_SEARCH_BTN;