wx.Control¶

This is the base class for a control or “widget”.

A control is generally a small window which processes user input and/or displays one or more item of data.

^^

Events Emitted by this Class¶

Handlers bound for the following event types will receive a wx.ClipboardTextEvent parameter.

EVT_TEXT_COPY: Some or all of the controls content was copied to the clipboard.
EVT_TEXT_CUT: Some or all of the controls content was cut (i.e. copied and deleted).
EVT_TEXT_PASTE: Clipboard content was pasted into the control. ^^

Class Hierarchy¶

Inheritance diagram for class Control:

Known Subclasses¶

ActiveXContainer , wx.ActivityIndicator, wx.adv.AnimationCtrl, wx.AnyButton, wx.aui.AuiToolBar, wx.BookCtrlBase, wx.adv.CalendarCtrl, wx.CheckBox, wx.Choice, wx.CollapsibleHeaderCtrl, wx.CollapsiblePane, wx.ComboBox, wx.ComboCtrl, wx.ControlWithItems, wx.dataview.DataViewCtrl, wx.adv.DatePickerCtrl, wx.FileCtrl, wx.Gauge, wx.GenericDirCtrl, wx.HeaderCtrl, wx.adv.HyperlinkCtrl, wx.InfoBar, wx.ListBox, wx.ListCtrl, wx.media.MediaCtrl, wx.PickerBase, wx.RadioBox, wx.RadioButton, wx.ribbon.RibbonControl, wx.richtext.RichTextCtrl, wx.richtext.RichTextStyleListCtrl, wx.ScrollBar, wx.Scrolled, wx.SearchCtrl, wx.Slider, wx.SpinButton, wx.SpinCtrl, wx.SpinCtrlDouble, wx.StaticBitmap, wx.StaticBox, wx.StaticLine, wx.StaticText, wx.StatusBar, wx.stc.StyledTextCtrl, wx.TextCtrl, wx.adv.TimePickerCtrl, wx.ToolBar, wx.TreeCtrl, wx.html2.WebView

Methods Summary¶

`__init__`	Constructs a control.
`Command`	Simulates the effect of the user issuing a command to the item.
`Create`
`Ellipsize`	Replaces parts of the label string with ellipsis, if needed, so that it fits into maxWidth pixels if possible.
`EscapeMnemonics`	Escapes the special mnemonics characters (“&”) in the given string.
`GetClassDefaultAttributes`
`GetLabel`	Returns the control’s label, as it was passed to `SetLabel` .
`GetLabelText`	Returns the control’s label without mnemonics.
`GetSizeFromText`	Determine the minimum size needed by the control to display the given text.
`GetSizeFromTextSize`	Determine the size needed by the control to leave the given area for its text.
`RemoveMnemonics`	Returns the given str string without mnemonics (“&” characters).
`SetLabel`	Sets the control’s label.
`SetLabelMarkup`	Sets the controls label to a string using markup.
`SetLabelText`	Sets the control’s label to exactly the given string.

Properties Summary¶

`Label`	See `GetLabel` and `SetLabel`
`LabelText`	See `GetLabelText` and `SetLabelText`

Class API¶

class wx.Control(Window)¶

Possible constructors:

Control(parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize,
        style=0, validator=DefaultValidator, name=ControlNameStr)

Control()

This is the base class for a control or “widget”.

Methods¶

__init__(self, *args, **kw)¶

Overloaded Implementations:

__init__ (self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=0, validator=DefaultValidator, name=ControlNameStr)

Constructs a control.

Parameters

parent (wx.Window) – Pointer to a parent window.
id (wx.WindowID) – Control identifier. If wx.ID_ANY, will automatically create an identifier.
pos (wx.Point) – Control position. DefaultPosition indicates that wxWidgets should generate a default position for the control.
size (wx.Size) – Control size. DefaultSize indicates that wxWidgets should generate a default size for the window. If no suitable size can be found, the window will be sized to 20x20 pixels so that the window is visible but obviously not correctly sized.
style (long) – Control style. For generic window styles, please see wx.Window.
validator (wx.Validator) – Control validator.
name (string) – Control name.

__init__ (self)

Default constructor to allow 2-phase creation.

Command(self, event)¶

Simulates the effect of the user issuing a command to the item.

Parameters: event (wx.CommandEvent) –

See also

wx.CommandEvent

Create(self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=0, validator=DefaultValidator, name=ControlNameStr)¶

Parameters

parent (wx.Window) –
id (wx.WindowID) –
pos (wx.Point) –
size (wx.Size) –
style (long) –
validator (wx.Validator) –
name (string) –

Return type

bool

static Ellipsize(label, dc, mode, maxWidth, flags=ELLIPSIZE_FLAGS_DEFAULT)¶

Replaces parts of the label string with ellipsis, if needed, so that it fits into maxWidth pixels if possible.

Note that this function does not guarantee that the returned string will always be shorter than maxWidth; if maxWidth is extremely small, ellipsized text may be larger.

Parameters

label (string) – The string to ellipsize
dc (wx.DC) – The DC used to retrieve the character widths through the wx.DC.GetPartialTextExtents function.
mode (EllipsizeMode) – The ellipsization mode. This is the setting which determines which part of the string should be replaced by the ellipsis (unless it is ELLIPSIZE_NONE in which case nothing is done). See wx.EllipsizeMode enumeration values for more info.
maxWidth (int) – The maximum width of the returned string in pixels. This argument determines how much characters of the string need to be removed (and replaced by ellipsis).
flags (int) – One or more of the wx.EllipsizeFlags enumeration values combined.

Return type

string

static EscapeMnemonics(text)¶

Escapes the special mnemonics characters (“&”) in the given string.

This function can be helpful if you need to set the controls label to a user-provided string. If the string contains ampersands, they wouldn’t appear on the display but be used instead to indicate that the character following the first of them can be used as a control mnemonic. While this can sometimes be desirable (e.g. to allow the user to configure mnemonics of the controls), more often you will want to use this function before passing a user-defined string to SetLabel . Alternatively, if the label is entirely user-defined, you can just call SetLabelText directly – but this function must be used if the label is a combination of a part defined by program containing the control mnemonics and a user-defined part.

Parameters: text (string) – The string such as it should appear on the display.
Return type: string
Returns: The same string with the ampersands in it doubled.

static GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)¶

Parameters: variant (WindowVariant) –
Return type: wx.VisualAttributes

GetLabel(self)¶

Returns the control’s label, as it was passed to SetLabel .

Note that the returned string may contains mnemonics (“&” characters) if they were passed to the SetLabel function; use GetLabelText if they are undesired.

Also note that the returned string is always the string which was passed to SetLabel but may be different from the string passed to SetLabelText (since this last one escapes mnemonic characters).

Return type: string

GetLabelText(self, *args, **kw)¶

Overloaded Implementations:

GetLabelText (self)

Returns the control’s label without mnemonics.

Note that because of the stripping of the mnemonics the returned string may differ from the string which was passed to SetLabel but should always be the same which was passed to SetLabelText .

Return type: string

GetLabelText (label)

Returns the given label string without mnemonics (“&” characters).

Parameters: label (string) –
Return type: string

GetSizeFromText(self, text)¶

Determine the minimum size needed by the control to display the given text.

The helper function that uses combination of GetSizeFromTextSize and GetTextExtent which used together pretty often:

# GetSizeFromText is a simpler way to do this:
size = self.GetSizeFromTextSize(self.GetTextExtent(text).GetWidth())

Parameters: text (string) – The given text.
Return type: wx.Size
Returns: The size that the control should have to leave the area of the specified text. May return DefaultSize if this method is not implemented for this particular control under the current platform.

New in version 4.1/wxWidgets-3.1.3.

GetSizeFromTextSize(self, *args, **kw)¶

Overloaded Implementations:

GetSizeFromTextSize (self, xlen, ylen=-1)

Determine the size needed by the control to leave the given area for its text.

This function is mostly useful with control displaying short amounts of text that can be edited by the user, e.g. wx.TextCtrl, wx.ComboBox, wx.SearchCtrl etc. Typically it is used to size these controls for the maximal amount of input they are supposed to contain, for example:

# Create a control for post code entry.
postcode = wx.TextCtrl(self, -1, "")

# And set its initial and minimal size to be big enough for
# entering 5 digits.
postcode.SetInitialSize(
    postcode.GetSizeFromTextSize(
        postcode.GetTextExtent("99999")))

Currently this method is only implemented for wx.TextCtrl, wx.ComboBox and wx.Choice in wxMSW and wxGTK.

Parameters

xlen (int) – The horizontal extent of the area to leave for text, in pixels.
ylen (int) – The vertical extent of the area to leave for text, in pixels. By default -1 meaning that the vertical component of the returned size should be the default height of this control.

Return type

wx.Size

Returns

The size that the control should have to leave the area of the specified size for its text. May return DefaultSize if this method is not implemented for this particular control under the current platform.

New in version 2.9.5.

GetSizeFromTextSize (self, tsize)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters: tsize (wx.Size) –
Return type: wx.Size

static RemoveMnemonics(str)¶

Returns the given str string without mnemonics (“&” characters).

Parameters: str (string) –
Return type: string

Note

This function is identical to GetLabelText and is provided mostly for symmetry with EscapeMnemonics .

SetLabel(self, label)¶

Sets the control’s label.

All “&” characters in the label are special and indicate that the following character is a mnemonic for this control and can be used to activate it from the keyboard (typically by using Alt key in combination with it). To insert a literal ampersand character, you need to float it, i.e. use “&&”. If this behaviour is undesirable, use SetLabelText instead.

Parameters: label (string) –

SetLabelMarkup(self, markup)¶

Sets the controls label to a string using markup.

Simple markup supported by this function can be used to apply different fonts or colours to different parts of the control label when supported. If markup is not supported by the control or platform, it is simply stripped and SetLabel is used with the resulting string.

For example,

text = wx.StaticText(self, -1, 'Hello world!')

# Some more code...
text.SetLabelMarkup("<b>&ampBed</b> &ampmp "
                     "<span foreground='red'>breakfast</span> "
                     "available <big>HERE</big>")

would show the string using bold, red and big for the corresponding words under wxGTK but will simply show the string “Bed & breakfast available HERE” on the other platforms. In any case, the “B” of “Bed” will be underlined to indicate that it can be used as a mnemonic for this control.

The supported tags are:

Tag	Description
<b>	bold text
<big>	bigger text
<i>	italic text
<s>	strike-through text
<small>	smaller text
<tt>	monospaced text
<u>	underlined text
<span>	generic formatter tag, see the table below for supported attributes.

Supported <span> attributes:

Name	Description
foreground, fgcolor, color	Foreground text colour, can be a name or `RGB` value.
background, bgcolor	Background text colour, can be a name or `RGB` value.
font_family, face	Font face name.
font_weight, weight	Numeric value in 0..900 range or one of “ultralight”, “light”, “normal” (all meaning non-bold), “bold”, “ultrabold” and “heavy” (all meaning bold).
font_style, style	Either “oblique” or “italic” (both with the same meaning) or “normal”.
size	The font size can be specified either as “smaller” or “larger” relatively to the current font, as a CSS font size name (“xx-small”, “x-small”, “small”, “medium”, “large”, “x-large” or “xx-large”) or as a number giving font size in 1024th parts of a point, i.e. 10240 for a 10pt font.

This markup language is a strict subset of Pango markup (described at http://library.gnome.org/devel/pango/unstable/PangoMarkupFormat.html) and any tags and span attributes not documented above can’t be used under non-GTK platforms.

Also note that you need to escape the following special characters:

Special character	Escape as
`&`	`&amp` ; or as `&&`
`'`	`&apos` ;
`"`	`&quot` ;
`<`	`&lt` ;
`>`	`&gt` ;

The non-escaped ampersand & characters are interpreted as mnemonics as with wx.Control.SetLabel .

Parameters: markup (string) – String containing markup for the label. It may contain markup tags described above and newline characters but currently only wxGTK and wxOSX support multiline labels with markup, the generic implementation (also used in wxMSW) only handles single line markup labels. Notice that the string must be well-formed (e.g. all tags must be correctly closed) and won’t be shown at all otherwise.
Return type: bool

Currently wx.Button supports markup in all major ports (wxMSW, wxGTK and OSX/Cocoa) while wx.StaticText supports it in wxGTK and wxOSX and its generic version (which can be used under MSW if markup support is required). Extending support to more controls is planned in the future.

Returns: True if the new label was set (even if markup in it was ignored) or False if we failed to parse the markup. In this case the label remains unchanged.

New in version 2.9.2.

SetLabelText(self, text)¶

Sets the control’s label to exactly the given string.

Unlike SetLabel , this function shows exactly the text passed to it in the control, without interpreting ampersands in it in any way. Notice that it means that the control can’t have any mnemonic defined for it using this function.

Parameters: text (string) –

Properties¶

Label¶: See GetLabel and SetLabel

LabelText¶: See GetLabelText and SetLabelText

Navigation

wx.Control¶

Events Emitted by this Class¶

Class Hierarchy¶

Known Subclasses¶

Methods Summary¶

Properties Summary¶

Class API¶

Methods¶

Properties¶