.. include:: headings.inc



.. _SearchCtrl:

==========================================================================================================================================
|phoenix_title|  **SearchCtrl**
==========================================================================================================================================

A search control is a composite control with a search button, a text control, and a cancel button.          





.. _SearchCtrl-styles:

|styles| Window Styles
================================

This class supports the following styles: 

- ``TE_PROCESS_ENTER``: The control will generate the event  ``wxEVT_COMMAND_TEXT_ENTER``   (otherwise pressing Enter key is either processed internally by the control or used for navigation between dialog controls).   
- ``TE_PROCESS_TAB``: The control will receive  ``wxEVT_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.   
- ``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.  
- ``TE_LEFT``: The text in the control will be left-justified (default).  
- ``TE_CENTRE``: The text in the control will be centered (currently wxMSW and wxGTK2 only).  
- ``TE_RIGHT``: The text in the control will be right-justified (currently wxMSW and wxGTK2 only).  
- ``TE_CAPITALIZE``: On PocketPC and Smartphone, causes the first letter to be capitalized.  






.. _SearchCtrl-events:

|events| Events Emitted by this Class
=====================================

Handlers bound for the following event types will receive one of the :ref:`CommandEvent`:ref:`TextCtrl`. parameters.

- EVT_SEARCHCTRL_SEARCH_BTN: Respond to a  ``wxEVT_SEARCHCTRL_SEARCH_BTN``   event, generated when the search button is clicked. Note that this does not initiate a search on its own, you need to perform the appropriate action in your event handler. You may use  ::

           event.GetString()

to retrieve the string to search for in the event handler code.  
- EVT_SEARCHCTRL_CANCEL_BTN: Respond to a  ``wxEVT_SEARCHCTRL_CANCEL_BTN``   event, generated when the cancel button is clicked.   








         



.. seealso:: :meth:`TextCtrl.Create` , :ref:`Validator`    







|

|class_hierarchy| Inheritance Diagram
=====================================

Inheritance diagram for class **SearchCtrl**

.. raw:: html

   <p class="graphviz">
   <img src="_static/images/inheritance/SearchCtrl_inheritance.png" alt="Inheritance diagram of SearchCtrl" usemap="#dummy" class="inheritance"/>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="Control.html" title="This is the base class for a control or 'widget'." alt="" coords="435,58,509,89"/> <area shape="rect" id="node7" href="TextCtrl.html" title="A text control allows text to be displayed and edited." alt="" coords="567,31,641,62"/> <area shape="rect" id="node2" href="Window.html" title="Window  is the base class for all windows and represents any visible object on screen." alt="" coords="297,58,377,89"/> <area shape="rect" id="node4" href="Object.html" title="This is the root class of many of the wxWidgets classes." alt="" coords="16,31,88,62"/> <area shape="rect" id="node5" href="EvtHandler.html" title="A class that can handle events from the windowing system." alt="" coords="148,58,247,89"/> <area shape="rect" id="node14" href="SearchCtrl.html" title="A search control is a composite control with a search button, a text control, and a cancel button." alt="" coords="692,31,791,62"/> <area shape="rect" id="node9" href="TextEntry.html" title="Common base class for single line text entry fields." alt="" coords="427,5,517,35"/> <area shape="rect" id="node12" href="Trackable.html" title="Add-on base class for a trackable object." alt="" coords="5,85,99,115"/> </map> 
   </p>

|


|appearance| Control Appearance
===============================

|

.. figure:: _static/images/widgets/fullsize/wxmsw/searchctrl.png
   :alt: wxMSW
   :figclass: floatleft
   
   **wxMSW**


.. figure:: _static/images/widgets/fullsize/wxmac/searchctrl.png
   :alt: wxMAC
   :figclass: floatright
   
   **wxMAC**


.. figure:: _static/images/widgets/fullsize/wxgtk/searchctrl.png
   :alt: wxGTK
   :figclass: floatcenter
   
   **wxGTK**


|


|method_summary| Methods Summary
================================

================================================================================ ================================================================================
:meth:`~SearchCtrl.__init__`                                                     Default constructor.
:meth:`~SearchCtrl.Create`                                                       Creates the text control for two-step construction.
:meth:`~SearchCtrl.GetDescriptiveText`                                           Return the text displayed when there is not yet any user input.
:meth:`~SearchCtrl.GetMenu`                                                      Returns a pointer to the search control's menu object or ``None`` if there is no menu attached.
:meth:`~SearchCtrl.IsCancelButtonVisible`                                        Returns the cancel button's visibility state.
:meth:`~SearchCtrl.IsSearchButtonVisible`                                        Returns the search button visibility value.
:meth:`~SearchCtrl.SetCancelBitmap`                                              
:meth:`~SearchCtrl.SetDescriptiveText`                                           Set the text to be displayed in the search control when the user has not yet typed anything in it.
:meth:`~SearchCtrl.SetMenu`                                                      Sets the search control's menu object.
:meth:`~SearchCtrl.SetSearchBitmap`                                              
:meth:`~SearchCtrl.SetSearchMenuBitmap`                                          
:meth:`~SearchCtrl.ShowCancelButton`                                             Shows or hides the cancel button.
:meth:`~SearchCtrl.ShowSearchButton`                                             Sets the search button visibility value on the search control.
================================================================================ ================================================================================


|


|property_summary| Properties Summary
=====================================

================================================================================ ================================================================================
:attr:`~SearchCtrl.CancelButtonVisible`                                          See :meth:`~SearchCtrl.IsCancelButtonVisible` and :meth:`~SearchCtrl.ShowCancelButton`
:attr:`~SearchCtrl.DescriptiveText`                                              See :meth:`~SearchCtrl.GetDescriptiveText` and :meth:`~SearchCtrl.SetDescriptiveText`
:attr:`~SearchCtrl.Menu`                                                         See :meth:`~SearchCtrl.GetMenu` and :meth:`~SearchCtrl.SetMenu`
:attr:`~SearchCtrl.SearchButtonVisible`                                          See :meth:`~SearchCtrl.IsSearchButtonVisible` and :meth:`~SearchCtrl.ShowSearchButton`
================================================================================ ================================================================================


|


|api| Class API
===============
   

.. class:: SearchCtrl(TextCtrl)

   A search control is a composite control with a search button, a text control, and a cancel button.
   
   **Possible constructors**::

       SearchCtrl()
       
       SearchCtrl(parent, id=ID_ANY, value='', pos=DefaultPosition,
                  size=DefaultSize, style=0, validator=DefaultValidator,
                  name=SearchCtrlNameStr)
       



   .. method:: __init__(self, *args, **kw)



      |overload| **Overloaded Implementations**:

      **~~~**

      
      **__init__** `(self)`
      
      Default constructor.                   
      
      
      
      
      **~~~**

      
      **__init__** `(self, parent, id=ID_ANY, value='', pos=DefaultPosition, size=DefaultSize, style=0, validator=DefaultValidator, name=SearchCtrlNameStr)`
      
      Constructor, creating and showing a text control.                  
      
      
      
      
      :param `parent`: Parent window. Should not be ``None``.   
      :type `parent`: Window
      :param `id`: Control identifier. A value of -1 denotes a default value.   
      :type `id`: int
      :param `value`: Default text value.   
      :type `value`: string
      :param `pos`: Text control position.   
      :type `pos`: Point
      :param `size`: Text control size.   
      :type `size`: Size
      :param `style`: Window style. See :ref:`SearchCtrl`.   
      :type `style`: long
      :param `validator`: Window validator.   
      :type `validator`: Validator
      :param `name`: Window name.  
      :type `name`: string
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
                        
      
      
      
      .. seealso:: :meth:`TextCtrl.Create` , :ref:`Validator`    
      
      
      
      
      
      
      
      **~~~**






   .. method:: Create(self, parent, id=ID_ANY, value='', pos=DefaultPosition, size=DefaultSize, style=0, validator=DefaultValidator, name=SearchCtrlNameStr)

      Creates the text control for two-step construction.                  

      This method should be called if the default constructor was used for the control creation. Its parameters have the same meaning as for the non-default constructor.                  


      :param `parent`: 
      :type `parent`: Window
      :param `id`: 
      :type `id`: int
      :param `value`: 
      :type `value`: string
      :param `pos`: 
      :type `pos`: Point
      :param `size`: 
      :type `size`: Size
      :param `style`: 
      :type `style`: long
      :param `validator`: 
      :type `validator`: Validator
      :param `name`: 
      :type `name`: string




      :rtype: `bool`








   .. method:: GetDescriptiveText(self)

      Return the text displayed when there is not yet any user input.                  

      :rtype: `string`








   .. method:: GetMenu(self)

      Returns a pointer to the search control's menu object or ``None`` if there is no menu attached.                  

      :rtype: :ref:`Menu`








   .. method:: IsCancelButtonVisible(self)

      Returns the cancel button's visibility state.                  

      :rtype: `bool`








   .. method:: IsSearchButtonVisible(self)

      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. 

      This always returns ``False`` in Mac OS X v10.3                  

      :rtype: `bool`








   .. method:: SetCancelBitmap(self, bmp)






   .. method:: SetDescriptiveText(self, text)

      Set the text to be displayed in the search control when the user has not yet typed anything in it.                  


      :param `text`: 
      :type `text`: string







   .. method:: SetMenu(self, menu)

      Sets the search control's menu object.                  

      If there is already a menu associated with the search control it is deleted. 




      :param `menu`: Menu to attach to the search control.   
      :type `menu`: Menu




                  





   .. method:: SetSearchBitmap(self, bmp)






   .. method:: SetSearchMenuBitmap(self, bmp)






   .. method:: ShowCancelButton(self, show)

      Shows or hides the cancel button.                  


      :param `show`: 
      :type `show`: bool







   .. method:: ShowSearchButton(self, 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. 

      This has no effect in Mac OS X v10.3                  


      :param `show`: 
      :type `show`: bool







   .. attribute:: CancelButtonVisible

      See :meth:`~SearchCtrl.IsCancelButtonVisible` and :meth:`~SearchCtrl.ShowCancelButton`


   .. attribute:: DescriptiveText

      See :meth:`~SearchCtrl.GetDescriptiveText` and :meth:`~SearchCtrl.SetDescriptiveText`


   .. attribute:: Menu

      See :meth:`~SearchCtrl.GetMenu` and :meth:`~SearchCtrl.SetMenu`


   .. attribute:: SearchButtonVisible

      See :meth:`~SearchCtrl.IsSearchButtonVisible` and :meth:`~SearchCtrl.ShowSearchButton`