Package wx :: Class SearchCtrl

[frames | no frames]

## Type SearchCtrl

    object --+
             |
        Object --+
                 |
        EvtHandler --+
                     |
                Window --+
                         |
                   Control --+
                             |
                      TextCtrl --+
                                 |
                                SearchCtrl

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`, 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.

# Events

> EVT_SEARCHCTRL_SEARCH_BTN | Sent when the search icon is clicked
> EVT_SEARCHCTRL_CANCEL_BTN | Sent when the cancel icon is clicked
> EVT_TEXT | Sent when the text changes
> EVT_TEXT_ENTER | Sent when the RETURN/ENTER key is pressed in the search control and the control has the wx.TE_PROCESS_ENTER style flag set.

Method Summary
SearchCtrl | ``__init__`(self, parent, id, value, pos, size, style, validator, name)` A search control is a composite of a `wx.TextCtrl` with optional bitmap buttons and a drop-down menu.
bool | ``Create`(self, parent, id, pos, size, style, validator, name)` Do the 2nd phase and create the GUI control.
String | ``GetDescriptiveText`(self)` Get the text to be displayed when the user has not yet typed anything in the control.
Menu | ``GetMenu`(self)` Returns a pointer to the search control's menu object or None if there is no menu attached.
bool | ``IsCancelButtonVisible`(self)` Indicates whether the cancel button is visible.
bool | ``IsSearchButtonVisible`(self)` Returns the search button visibility value.
| ``SetCancelBitmap`(self, bitmap)` Sets the bitmap to use for the cancel button.
| ``SetDescriptiveText`(self, text)` Set the text to be displayed when the user has not yet typed anything in the control.
| ``SetMenu`(self, menu)` Sets the search control's menu object.
| ``SetSearchBitmap`(self, bitmap)` Sets the bitmap to use for the search button.
| ``SetSearchMenuBitmap`(self, bitmap)` Sets the bitmap to use for the search button when there is a drop-down menu associated with the search control.
| ``ShowCancelButton`(self, show)` Shows or hides the cancel button.
| ``ShowSearchButton`(self, show)` Sets the search button visibility value on the search control.

Property Summary
| `CancelButtonVisible`
| `DescriptiveText`
| `Menu`
| `SearchButtonVisible`
| `thisown`: The membership flag

Instance Method Details

### __init__(self, parent, id=-1, value=wxEmptyString, pos=DefaultPosition, size=DefaultSize, style=0, validator=DefaultValidator, name=SearchCtrlNameStr)
(Constructor)

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`, 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.

# Events

> EVT_SEARCHCTRL_SEARCH_BTN | Sent when the search icon is clicked
> EVT_SEARCHCTRL_CANCEL_BTN | Sent when the cancel icon is clicked
> EVT_TEXT | Sent when the text changes
> EVT_TEXT_ENTER | Sent when the RETURN/ENTER key is pressed in the search control and the control has the wx.TE_PROCESS_ENTER style flag set.

  Parameters:
    `parent`
    (type=Window)

    `id`
    (type=int)

    `value`
    (type=String)

    `pos`
    (type=Point)

    `size`
    (type=Size)

    `style`
    (type=long)

    `validator`
    (type=Validator)

    `name`
    (type=String)

  Returns:
    SearchCtrl
  Overrides:
    `wx.TextCtrl.__init__`

### Create(self, parent, id=-1, value=wxEmptyString, pos=DefaultPosition, size=DefaultSize, style=0, validator=DefaultValidator, name=SearchCtrlNameStr)

Do the 2nd phase and create the GUI control.

  Parameters:
    `parent`
    (type=Window)

    `id`
    (type=int)

    `pos`
    (type=Point)

    `size`
    (type=Size)

    `style`
    (type=long)

    `validator`
    (type=Validator)

    `name`
    (type=String)

  Returns:
    bool
  Overrides:
    `wx.TextCtrl.Create` (inherited documentation)

### GetDescriptiveText(self)

Get the text to be displayed when the user has not yet typed anything in the control.

  Returns:
    String

### GetMenu(self)

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

  Returns:
    Menu

### IsCancelButtonVisible(self)

Indicates whether the cancel button is visible.

  Returns:
    bool

### 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

  Returns:
    bool

### SetCancelBitmap(self, bitmap)

Sets the bitmap to use for the cancel button. This currently does not work on the Mac.

  Parameters:
    `bitmap`
    (type=Bitmap)

### SetDescriptiveText(self, text)

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

  Parameters:
    `text`
    (type=String)

### SetMenu(self, menu)

Sets the search control's menu object. If there is already a menu associated with the search control it is deleted.

  Parameters:
    `menu`
    (type=Menu)

### SetSearchBitmap(self, bitmap)

Sets the bitmap to use for the search button. This currently does not work on the Mac.

  Parameters:
    `bitmap`
    (type=Bitmap)

### SetSearchMenuBitmap(self, bitmap)

Sets the bitmap to use for the search button when there is a drop-down menu associated with the search control. This currently does not work on the Mac.

  Parameters:
    `bitmap`
    (type=Bitmap)

### ShowCancelButton(self, show)

Shows or hides the cancel button.

  Parameters:
    `show`
    (type=bool)

### 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

  Parameters:
    `show`
    (type=bool)

Property Details

### CancelButtonVisible

  Get Method:
    `IsCancelButtonVisible`(self)
  Set Method:
    `ShowCancelButton`(self, show)

### DescriptiveText

  Get Method:
    `GetDescriptiveText`(self)
  Set Method:
    `SetDescriptiveText`(self, text)

### Menu

  Get Method:
    `GetMenu`(self)
  Set Method:
    `SetMenu`(self, menu)

### SearchButtonVisible

  Get Method:
    `IsSearchButtonVisible`(self)
  Set Method:
    `ShowSearchButton`(self, show)

### thisown

The membership flag

Generated by Epydoc 2.1.20050511.rpd on Thu Mar 22 12:14:15 2007 | http://epydoc.sf.net