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