Package wx :: Module combo :: Class ComboCtrl

[frames | no frames]

## Type ComboCtrl

    object --+
             |
        Object --+
                 |
        EvtHandler --+
                     |
                Window --+
                         |
                   Control --+
                             |
                            ComboCtrl

Known Subclasses:
  `OwnerDrawnComboBox`

A combo control is a generic combobox that allows for a totally custom popup. In addition it has other customization features. For instance, position and size of the dropdown button can be changed.

To specify what to use for the popup control you need to derive a class from `wx.combo.ComboPopup` and pass it to the ComboCtrl with `SetPopupControl`. It doesn't derive from any widget class so it can be used either as a mixin class combined with some standard or custom widget, or you can use the derived ComboPopup to create and hold an independent reference to the widget to be used for the popup.

# Window Styles

> wx.CB_READONLY | Text will not be editable.
> wx.CB_SORT | Sorts the entries in the list alphabetically.
> wx.TE_PROCESS_ENTER | The control will generate the event EVT_TEXT_ENTER (otherwise pressing Enter key is either processed internally by the control or used for navigation between dialog controls).
> wx.CC_SPECIAL_DCLICK | Double-clicking triggers a call to popup's OnComboDoubleClick. Actual behaviour is defined by a derived class. For instance, OwnerDrawnComboBox will cycle an item. This style only applies if wx.CB_READONLY is used as well.
> wx.CC_STD_BUTTON | Drop button will behave more like a standard push button.

Method Summary
Control | ``__init__`(self, parent, id, pos, size, style, validator, name)` Create a Control.
bool | ``AnimateShow`(self, rect, flags)` Implement in derived class to create a drop-down animation.
| `Copy(self)`
| `Cut(self)`
| ``DoShowPopup`(self, rect, flags)` Shows and positions the popup.
| ``EnablePopupAnimation`(self, enable)` Enables or disables popup animation, if any, depending on the value of the argument.
Bitmap | `GetBitmapDisabled(self)`
Bitmap | `GetBitmapHover(self)`
Bitmap | `GetBitmapNormal(self)`
Bitmap | `GetBitmapPressed(self)`
Window | ``GetButton`(self)` Get the dropdown button which is part of the combobox.
Size | ``GetButtonSize`(self)` Returns current size of the dropdown button.
int | `GetCustomPaintWidth(self)`
int | ``GetFeatures`()` Returns a bit-list of flags indicating which features of the ComboCtrl functionality are implemented by this implemetation. (Static method)
long | `GetInsertionPoint(self)`
unsigned int | `GetInternalFlags(self)`
long | `GetLastPosition(self)`
Window | `GetMainWindowOfCompositeControl(self)`
ComboPopup | ``GetPopupControl`(self)` Returns the current popup interface that has been set with `SetPopupControl`.
Window | ``GetPopupWindow`(self)` Returns the popup window containing the popup control.
int | `GetPopupWindowState(self)`
wxTextCtrl | ``GetTextCtrl`(self)` Get the text control which is part of the combo control.
int | ``GetTextIndent`(self)` Returns actual indentation in pixels.
Rect | ``GetTextRect`(self)` Returns area covered by the text field (includes everything except borders and the dropdown button).
String | ``GetValue`(self)` Returns text representation of the current value.
| ``HidePopup`(self)` Dismisses the popup window.
bool | ``IsCreated`(self)` Return true if Create has finished
bool | ``IsKeyPopupToggle`(self, event)` Returns true if given key combination should toggle the popup.
bool | ``IsPopupShown`(self)` Returns true if the popup is currently shown.
bool | `IsPopupWindowState(self, state)`
| ``OnButtonClick`(self)` Implement in a derived class to define what happens on dropdown button click.
| ``OnPopupDismiss`(self)` Common code to be called on popup hide/dismiss
| `Paste(self)`
| ``PrepareBackground`(self, dc, rect, flags)` Prepare background of combo control or an item in a dropdown list in a way typical on platform.
| `Remove(self, from, to)`
| `Replace(self, from, to, value)`
| ``SetButtonBitmaps`(self, bmpNormal, pushButtonBg, bmpPressed, bmpHover, bmpDisabled)` Sets custom dropdown button graphics.
| ``SetButtonPosition`(self, width, height, side, spacingX)` Set the position of the dropdown button.
| `SetCtrlMainWnd(self, wnd)`
| ``SetCustomPaintWidth`(self, width)` Set width, in pixels, of custom painted area in control without wx.CB_READONLY style.
| `SetInsertionPoint(self, pos)`
| `SetInsertionPointEnd(self)`
| `SetMark(self, from, to)`
| ``SetPopupAnchor`(self, anchorSide)` Set side of the control to which the popup will align itself.
| ``SetPopupControl`(self, popup)` Set popup interface class derived from `wx.combo.ComboPopup`.
| ``SetPopupExtents`(self, extLeft, extRight)` Extends popup size horizontally, relative to the edges of the combo control.
| ``SetPopupMaxHeight`(self, height)` Sets preferred maximum height of the popup.
| ``SetPopupMinWidth`(self, width)` Sets minimum width of the popup.
| ``SetText`(self, value)` Sets the text for the text field without affecting the popup.
| ``SetTextIndent`(self, indent)` This will set the space in pixels between left edge of the control and the text, regardless whether control is read-only or not.
| ``SetValue`(self, value)` Sets the text for the combo control text field.
| ``SetValueWithEvent`(self, value, withEvent)` Same as `SetValue`, but also sends a EVT_TEXT event if withEvent is true.
bool | ``ShouldDrawFocus`(self)` Returns true if focus indicator should be drawn in the control.
| ``ShowPopup`(self)` Show the popup window.
| `Undo(self)`
| ``UseAltPopupWindow`(self, enable)` Enable or disable usage of an alternative popup window, which guarantees ability to focus the popup control, and allows common native controls to function normally.

Property Summary
| `BitmapDisabled`
| `BitmapHover`
| `BitmapNormal`
| `BitmapPressed`
| `Button`
| `ButtonSize`
| `CustomPaintWidth`
| `InsertionPoint`
| `PopupControl`
| `PopupWindow`
| `PopupWindowState`
| `TextCtrl`
| `TextIndent`
| `TextRect`
| `thisown`: The membership flag
| `Value`

Class Variable Summary
`int` | `Animating` = 2
`int` | `CanDeferShow` = 2
`int` | `Hidden` = 0
`int` | `ShowAbove` = 1
`int` | `ShowBelow` = 0
`int` | `Visible` = 3

Instance Method Details

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

Create a Control. Normally you should only call this from a subclass' __init__ as a plain old wx.Control is not very useful.

  Parameters:
    `parent`
    (type=Window)

    `id`
    (type=int)

    `pos`
    (type=Point)

    `size`
    (type=Size)

    `style`
    (type=long)

    `validator`
    (type=Validator)

    `name`
    (type=String)

  Returns:
    Control
  Overrides:
    `wx.Control.__init__` (inherited documentation)

### AnimateShow(self, rect, flags)

Implement in derived class to create a drop-down animation. Return `True` if finished immediately. Otherwise the popup is only shown when the derived class calls `DoShowPopup`. Flags are same as for `DoShowPopup`.

  Parameters:
    `rect`
    (type=Rect)

    `flags`
    (type=int)

  Returns:
    bool

### DoShowPopup(self, rect, flags)

Shows and positions the popup.

Flags:

  ShowBelow | Showing popup below the control
  ShowAbove | Showing popup above the control
  CanDeferShow | Can only return true from AnimateShow if this is set

  Parameters:
    `rect`
    (type=Rect)

    `flags`
    (type=int)

### EnablePopupAnimation(self, enable=True)

Enables or disables popup animation, if any, depending on the value of the argument.

  Parameters:
    `enable`
    (type=bool)

### GetButton(self)

Get the dropdown button which is part of the combobox. Note: it's not necessarily a wx.Button or wx.BitmapButton.

  Returns:
    Window

### GetButtonSize(self)

Returns current size of the dropdown button.

  Returns:
    Size

### GetPopupControl(self)

Returns the current popup interface that has been set with `SetPopupControl`.

  Returns:
    ComboPopup

### GetPopupWindow(self)

Returns the popup window containing the popup control.

  Returns:
    Window

### GetTextCtrl(self)

Get the text control which is part of the combo control.

  Returns:
    wxTextCtrl

### GetTextIndent(self)

Returns actual indentation in pixels.

  Returns:
    int

### GetTextRect(self)

Returns area covered by the text field (includes everything except borders and the dropdown button).

  Returns:
    Rect

### GetValue(self)

Returns text representation of the current value. For writable combo control it always returns the value in the text field.

  Returns:
    String

### HidePopup(self)

Dismisses the popup window.

### IsCreated(self)

Return true if Create has finished

  Returns:
    bool

### IsKeyPopupToggle(self, event)

Returns true if given key combination should toggle the popup.

  Parameters:
    `event`
    (type=KeyEvent)

  Returns:
    bool

### IsPopupShown(self)

Returns true if the popup is currently shown.

  Returns:
    bool

### OnButtonClick(self)

Implement in a derived class to define what happens on dropdown button click. Default action is to show the popup.

### OnPopupDismiss(self)

Common code to be called on popup hide/dismiss

### PrepareBackground(self, dc, rect, flags)

Prepare background of combo control or an item in a dropdown list in a way typical on platform. This includes painting the focus/disabled background and setting the clipping region. Unless you plan to paint your own focus indicator, you should always call this in your wxComboPopup::PaintComboControl implementation. In addition, it sets pen and text colour to what looks good and proper against the background.

flags are the same as wx.RendererNative flags:

> wx.CONTROL_ISSUBMENU | drawing a list item instead of combo control
> wx.CONTROL_SELECTED | list item is selected
> wx.CONTROL_DISABLED | control/item is disabled

  Parameters:
    `dc`
    (type=DC)

    `rect`
    (type=Rect)

    `flags`
    (type=int)

### SetButtonBitmaps(self, bmpNormal, pushButtonBg=False, bmpPressed=wxNullBitmap, bmpHover=wxNullBitmap, bmpDisabled=wxNullBitmap)

Sets custom dropdown button graphics.

  Parameters:
    `bmpNormal` - Default button image
    (type=Bitmap)

    `pushButtonBg` - If `True`, blank push button background is painted below the image.
    (type=bool)

    `bmpPressed` - Depressed butotn image.
    (type=Bitmap)

    `bmpHover` - Button imate to use when the mouse hovers over it.
    (type=Bitmap)

    `bmpDisabled` - Disabled button image.
    (type=Bitmap)

### SetButtonPosition(self, width=-1, height=-1, side=RIGHT, spacingX=0)

Set the position of the dropdown button.

  Parameters:
    `width`
    (type=int)

    `height`
    (type=int)

    `side`
    (type=int)

    `spacingX`
    (type=int)

### SetCustomPaintWidth(self, width)

Set width, in pixels, of custom painted area in control without wx.CB_READONLY style. In read-only OwnerDrawnComboBox, this is used to indicate the area that is not covered by the focus rectangle.

  Parameters:
    `width`
    (type=int)

### SetPopupAnchor(self, anchorSide)

Set side of the control to which the popup will align itself. Valid values are wx.LEFT, wx.RIGHT and 0. The default value 0 means that the most appropriate side is used (which, currently, is always wx.LEFT).

  Parameters:
    `anchorSide`
    (type=int)

### SetPopupControl(self, popup)

Set popup interface class derived from `wx.combo.ComboPopup`. This method should be called as soon as possible after the control has been created, unless `OnButtonClick` has been overridden.

  Parameters:
    `popup`
    (type=ComboPopup)

### SetPopupExtents(self, extLeft, extRight)

Extends popup size horizontally, relative to the edges of the combo control. Values are given in pixels, and the defaults are zero. It is up to the popup to fully take these values into account.

  Parameters:
    `extLeft`
    (type=int)

    `extRight`
    (type=int)

### SetPopupMaxHeight(self, height)

Sets preferred maximum height of the popup. A value of -1 indicates to use the default. The popup implementation may choose to ignore this.

  Parameters:
    `height`
    (type=int)

### SetPopupMinWidth(self, width)

Sets minimum width of the popup. If wider than combo control, it will extend to the left. A value of -1 indicates to use the default. The popup implementation may choose to ignore this.

  Parameters:
    `width`
    (type=int)

### SetText(self, value)

Sets the text for the text field without affecting the popup. Thus, unlike `SetValue`, it works equally well with combo control using wx.CB_READONLY style.

  Parameters:
    `value`
    (type=String)

### SetTextIndent(self, indent)

This will set the space in pixels between left edge of the control and the text, regardless whether control is read-only or not. A value of -1 can be given to indicate platform default.

  Parameters:
    `indent`
    (type=int)

### SetValue(self, value)

Sets the text for the combo control text field. For a combo control with wx.CB_READONLY style the string must be accepted by the popup (for instance, exist in the dropdown list), otherwise the call to SetValue is ignored.

  Parameters:
    `value`
    (type=String)

### SetValueWithEvent(self, value, withEvent=True)

Same as `SetValue`, but also sends a EVT_TEXT event if withEvent is true.

  Parameters:
    `value`
    (type=String)

    `withEvent`
    (type=bool)

### ShouldDrawFocus(self)

Returns true if focus indicator should be drawn in the control.

  Returns:
    bool

### ShowPopup(self)

Show the popup window.

### UseAltPopupWindow(self, enable=True)

Enable or disable usage of an alternative popup window, which guarantees ability to focus the popup control, and allows common native controls to function normally. This alternative popup window is usually a wxDialog, and as such, when it is shown, its parent top-level window will appear as if the focus has been lost from it.

  Parameters:
    `enable`
    (type=bool)

Static Method Details

### GetFeatures()

Returns a bit-list of flags indicating which features of the ComboCtrl functionality are implemented by this implemetation. See `wx.combo.ComboCtrlFeatures`.

  Returns:
    int

Property Details

### BitmapDisabled

  Get Method:
    `GetBitmapDisabled`(self)

### BitmapHover

  Get Method:
    `GetBitmapHover`(self)

### BitmapNormal

  Get Method:
    `GetBitmapNormal`(self)

### BitmapPressed

  Get Method:
    `GetBitmapPressed`(self)

### Button

  Get Method:
    `GetButton`(self)

### ButtonSize

  Get Method:
    `GetButtonSize`(self)

### CustomPaintWidth

  Get Method:
    `GetCustomPaintWidth`(self)
  Set Method:
    `SetCustomPaintWidth`(self, width)

### InsertionPoint

  Get Method:
    `GetInsertionPoint`(self)

### PopupControl

  Get Method:
    `GetPopupControl`(self)
  Set Method:
    `SetPopupControl`(self, popup)

### PopupWindow

  Get Method:
    `GetPopupWindow`(self)

### PopupWindowState

  Get Method:
    `GetPopupWindowState`(self)

### TextCtrl

  Get Method:
    `GetTextCtrl`(self)

### TextIndent

  Get Method:
    `GetTextIndent`(self)
  Set Method:
    `SetTextIndent`(self, indent)

### TextRect

  Get Method:
    `GetTextRect`(self)

### thisown

The membership flag

  Get Method:
    unknown--1217732284(...)
  Set Method:
    unknown--1217732228(...)

### Value

  Get Method:
    `GetValue`(self)
  Set Method:
    `SetValue`(self, value)

Class Variable Details

### Animating

  Type:
    `int`
  Value:

        2

### CanDeferShow

  Type:
    `int`
  Value:

        2

### Hidden

  Type:
    `int`
  Value:

        0

### ShowAbove

  Type:
    `int`
  Value:

        1

### ShowBelow

  Type:
    `int`
  Value:

        0

### Visible

  Type:
    `int`
  Value:

        3

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