************* wx.SearchCtrl ************* Inheritance diagram for `wx.SearchCtrl`: | .. inheritance-diagram:: wx.SearchCtrl | Description =========== A search control is a composite control with a search button, a text control, and a cancel button. Derived From ^^^^^^^^^^^^^ * `wx.TextCtrl `_ * `wx.Control `_ * `wx.Window `_ * `wx.EvtHandler `_ * `wx.Object `_ Window Styles ^^^^^^^^^^^^^ ================================================== ================================================== Window Style Description ================================================== ================================================== ``wx.TE_PROCESS_ENTER`` The control will generate the event ``wx.wxEVT_COMMAND_TEXT_ENTER`` (otherwise pressing ``Enter`` key is either processed internally by the control or used for navigation between dialog controls). ``wx.TE_PROCESS_TAB`` The control will receive ``wx.EVT_CHAR`` events for ``TAB`` pressed - normally, ``TAB`` is used for passing to the next control in a dialog instead. For the control created with this style, you can still use ``Ctrl-Enter`` to pass to the next control from the keyboard. ``wx.TE_NOHIDESEL`` By default, the Windows text control doesn't show the selection when it doesn't have focus - use this style to force it to always show it. It doesn't do anything under other platforms. ``wx.TE_LEFT`` The text in the control will be left-justified (default). ``wx.TE_CENTRE`` The text in the control will be centered (currently wxMSW and wxGTK2 only). ``wx.TE_RIGHT`` The text in the control will be right-justified (currently wxMSW and wxGTK2 only). ``wx.TE_CAPITALIZE`` On PocketPC and Smartphone, causes the first letter to be capitalized. ================================================== ================================================== Event Handling ^^^^^^^^^^^^^^ To process input from a search control, use these event handler macros to direct input to member functions that take a `wx.CommandEvent <../Events/wx.CommandEvent.html>`_ argument. To retrieve actual search queries, use ``wx.EVT_TEXT`` and ``wx.EVT_TEXT_ENTER`` events, just as you would with `wx.TextCtrl `_. ================================================== ================================================== Event Name Description ================================================== ================================================== wx.EVT_SEARCHCTRL_SEARCH_BTN(id, func) Respond to a ``wx.wxEVT_SEARCHCTRL_SEARCH_BTN`` event, generated when the search button is clicked. Note that this does not initiate a search. wx.EVT_SEARCHCTRL_CANCEL_BTN(id, func) Respond to a ``wx.wxEVT_SEARCHCTRL_CANCEL_BTN`` event, generated when the cancel button is clicked. ================================================== ================================================== | Control Appearance ^^^^^^^^^^^^^^^^^^ | .. figure:: ../images/wxWidgets/wxmsw/searchctrl.png :alt: wxMSW :figclass: floatleft **wxMSW** .. figure:: ../images/wxWidgets/wxmac/searchctrl.png :alt: wxMAC :figclass: floatright **wxMAC** .. figure:: ../images/wxWidgets/wxgtk/searchctrl.png :alt: wxGTK :figclass: floatcenter **wxGTK** | Methods Summary ^^^^^^^^^^^^^^^ * `__init__ <#__init__>`_ * `GetDescriptiveText <#GetDescriptiveText>`_ * `GetMenu <#GetMenu>`_ * `IsCancelButtonVisible <#IsCancelButtonVisible>`_ * `IsSearchButtonVisible <#IsSearchButtonVisible>`_ * `SetCancelBitmap <#SetCancelBitmap>`_ * `SetDescriptiveText <#SetDescriptiveText>`_ * `SetMenu <#SetMenu>`_ * `SetSearchBitmap <#SetSearchBitmap>`_ * `SetSearchMenuBitmap <#SetSearchMenuBitmap>`_ * `ShowCancelButton <#ShowCancelButton>`_ * `ShowSearchButton <#ShowSearchButton>`_ Properties Summary ^^^^^^^^^^^^^^^^^^ * `CancelButtonVisible <#CancelButtonVisible>`_ * `DescriptiveText <#DescriptiveText>`_ * `Menu <#Menu>`_ * `SearchButtonVisible <#SearchButtonVisible>`_ Class API ========= Methods ^^^^^^^ .. method:: __init__(parent, id=-1, value="", pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, validator=wx.DefaultValidator, name=wx.SearchCtrlNameStr) 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 implemented 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 <#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. **Parameters:** * `parent` (`wx.Window `_) * `id` (int) * `value` (string) * `pos` (`wx.Point `_) * `size` (`wx.Size `_) * `style` (long) * `validator` (`wx.Validator `_) * `name` (string) | **Returns:** `wx.SearchCtrl `_ -------- .. method:: GetDescriptiveText() Get the text to be displayed when the user has not yet typed anything in the control. | **Returns:** `string` -------- .. method:: GetMenu() Returns a pointer to the search control's menu object or ``None`` if there is no menu attached. | **Returns:** `wx.Menu `_ -------- .. method:: IsCancelButtonVisible() Indicates whether the cancel button is visible. | **Returns:** `bool` -------- .. method:: IsSearchButtonVisible() 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. | **Returns:** `bool` .. note:: This always returns ``False`` in Mac OS X v10.3 -------- .. method:: SetCancelBitmap(bitmap) Sets the bitmap to use for the cancel button. **Parameters:** * `bitmap` (`wx.Bitmap `_) .. note:: This currently does not work on the Mac. -------- .. method:: SetDescriptiveText(text) Set the text to be displayed when the user has not yet typed anything in the control. **Parameters:** * `text` (string) -------- .. method:: SetMenu(menu) Sets the search control's menu object. If there is already a menu associated with the search control it is deleted. **Parameters:** * `menu` (`wx.Menu `_): Menu to attach to the search control. -------- .. method:: SetSearchBitmap(bitmap) Sets the bitmap to use for the search button. **Parameters:** * `bitmap` (`wx.Bitmap `_) .. note:: This currently does not work on the Mac. -------- .. method:: SetSearchMenuBitmap(bitmap) Sets the bitmap to use for the search button when there is a drop-down menu associated with the search control. **Parameters:** * `bitmap` (`wx.Bitmap `_) .. note:: This currently does not work on the Mac. -------- .. method:: ShowCancelButton(show) Shows or hides the cancel button. **Parameters:** * `show` (bool) -------- .. method:: ShowSearchButton(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. **Parameters:** * `show` (bool) .. note:: This has no effect in Mac OS X v10.3 -------- Properties ^^^^^^^^^^ .. attribute:: CancelButtonVisible Indicates whether the cancel button is visible. .. attribute:: DescriptiveText Get the text to be displayed when the user has not yet typed anything in the control. .. attribute:: Menu Returns a pointer to the search control's menu object or ``None`` if there is no menu attached. .. attribute:: SearchButtonVisible 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. .. note:: This always returns false in Mac OS X v10.3