Package wx :: Module combo :: Class ComboCtrl

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

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.