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 license
   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 wxEVT_COMMAND_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 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 wxEVT_SEARCHCTRL_SEARCH_BTN event, generated when the
  47         search button is clicked. Note that this does not initiate a search.
  48     @event{EVT_SEARCHCTRL_CANCEL_BTN(id, func)}
  49         Respond to a wxEVT_SEARCHCTRL_CANCEL_BTN event, generated when the
  50         cancel button is clicked.
  51     @endEventTable
  52
  53     @library{wxcore}
  54     @category{ctrl}
  55     @appearance{searchctrl.png}
  56
  57     @see wxTextCtrl::Create, wxValidator
  58 */
  59 class wxSearchCtrl : public wxTextCtrl
  60 {
  61 public:
  62     /**
  63       Default constructor
  64     */
  65     wxSearchCtrl();
  66
  67     /**
  68         Constructor, creating and showing a text control.
  69
  70         @param parent
  71             Parent window. Should not be @NULL.
  72         @param id
  73             Control identifier. A value of -1 denotes a default value.
  74         @param value
  75             Default text value.
  76         @param pos
  77             Text control position.
  78         @param size
  79             Text control size.
  80         @param style
  81             Window style. See wxSearchCtrl.
  82         @param validator
  83             Window validator.
  84         @param name
  85             Window name.
  86
  87         @see wxTextCtrl::Create, wxValidator
  88     */
  89     wxSearchCtrl(wxWindow* parent, wxWindowID id,
  90                  const wxString& value = wxEmptyString,
  91                  const wxPoint& pos = wxDefaultPosition,
  92                  const wxSize& size = wxDefaultSize,
  93                  long style = 0,
  94                  const wxValidator& validator = wxDefaultValidator,
  95                  const wxString& name = wxSearchCtrlNameStr);
  96
  97     /**
  98         Destructor, destroying the search control.
  99     */
 100     virtual ~wxSearchCtrl();
 101
 102     /**
 103         Returns a pointer to the search control's menu object or @NULL if there is no
 104         menu attached.
 105     */
 106     virtual wxMenu* GetMenu();
 107
 108     /**
 109         Returns the search button visibility value.
 110         If there is a menu attached, the search button will be visible regardless of
 111         the search button visibility value.
 112
 113         This always returns @false in Mac OS X v10.3
 114     */
 115     virtual bool IsSearchButtonVisible() const;
 116
 117     /**
 118         Sets the search control's menu object.
 119         If there is already a menu associated with the search control it is deleted.
 120
 121         @param menu
 122             Menu to attach to the search control.
 123     */
 124     virtual void SetMenu(wxMenu* menu);
 125
 126     /**
 127         Shows or hides the cancel button.
 128     */
 129     virtual void ShowCancelButton(bool show);
 130
 131     /**
 132         Sets the search button visibility value on the search control.
 133         If there is a menu attached, the search button will be visible regardless of
 134         the search button visibility value.
 135
 136         This has no effect in Mac OS X v10.3
 137     */
 138     virtual void ShowSearchButton(bool show);
 139 };
 140