interface/wx/srchctrl.h

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