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: GetBitmapDisabled(self) -> Bitmap
  BitmapHover: GetBitmapHover(self) -> Bitmap
  BitmapNormal: GetBitmapNormal(self) -> Bitmap
  BitmapPressed: GetBitmapPressed(self) -> Bitmap
  Button: GetButton(self) -> Window
  ButtonSize: GetButtonSize(self) -> Size
  CustomPaintWidth: GetCustomPaintWidth(self) -> int
  InsertionPoint: GetInsertionPoint(self) -> long
  PopupControl: GetPopupControl(self) -> ComboPopup
  PopupWindow: GetPopupWindow(self) -> Window
  PopupWindowState: GetPopupWindowState(self) -> int
  TextCtrl: GetTextCtrl(self) -> wxTextCtrl
  TextIndent: GetTextIndent(self) -> int
  TextRect: GetTextRect(self) -> Rect
  thisown: The membership flag
  Value: GetValue(self) -> String

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

GetBitmapDisabled(self) -> Bitmap

Get Method:
GetBitmapDisabled(self)

BitmapHover

GetBitmapHover(self) -> Bitmap

Get Method:
GetBitmapHover(self)

BitmapNormal

GetBitmapNormal(self) -> Bitmap

Get Method:
GetBitmapNormal(self)

BitmapPressed

GetBitmapPressed(self) -> Bitmap

Get Method:
GetBitmapPressed(self)

Button

GetButton(self) -> Window

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

Get Method:
GetButton(self)

ButtonSize

GetButtonSize(self) -> Size

Returns current size of the dropdown button.

Get Method:
GetButtonSize(self)

CustomPaintWidth

GetCustomPaintWidth(self) -> int

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

InsertionPoint

GetInsertionPoint(self) -> long

Get Method:
GetInsertionPoint(self)

PopupControl

GetPopupControl(self) -> ComboPopup

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

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

PopupWindow

GetPopupWindow(self) -> Window

Returns the popup window containing the popup control.

Get Method:
GetPopupWindow(self)

PopupWindowState

GetPopupWindowState(self) -> int

Get Method:
GetPopupWindowState(self)

TextCtrl

GetTextCtrl(self) -> wxTextCtrl

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

Get Method:
GetTextCtrl(self)

TextIndent

GetTextIndent(self) -> int

Returns actual indentation in pixels.

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

TextRect

GetTextRect(self) -> Rect

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

Get Method:
GetTextRect(self)

thisown

The membership flag

Get Method:
unknown-16214688(...)
Set Method:
unknown-16214808(...)

Value

GetValue(self) -> String

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

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 Mon Feb 16 12:52:24 2009 http://epydoc.sf.net