.. include:: headings.inc .. _Control: ========================================================================================================================================== |phoenix_title| **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. .. _Control-events: |events| Events Emitted by this Class ===================================== Handlers bound for the following event types will receive a :ref:`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. .. seealso:: :ref:`Validator` | |class_hierarchy| Inheritance Diagram ===================================== Inheritance diagram for class **Control** .. raw:: html
| |sub_classes| Known Subclasses ============================== `ActiveXContainer`, :ref:`adv.AnimationCtrl`, :ref:`AnyButton`, `AuiToolBar`, :ref:`BookCtrlBase`, :ref:`adv.CalendarCtrl`, :ref:`CheckBox`, :ref:`CollapsiblePane`, :ref:`ComboBox`, `ComboCtrl`, :ref:`ControlWithItems`, :ref:`dataview.DataViewCtrl`, :ref:`adv.DatePickerCtrl`, :ref:`FileCtrl`, :ref:`Gauge`, :ref:`GenericDirCtrl`, `HeaderCtrl`, :ref:`adv.HyperlinkCtrl`, :ref:`InfoBar`, :ref:`ListCtrl`, `MediaCtrl`, :ref:`PickerBase`, `PropertyGrid`, :ref:`RadioBox`, :ref:`RadioButton`, `RibbonControl`, `RichTextCtrl`, `RichTextStyleListCtrl`, :ref:`ScrollBar`, :ref:`Slider`, :ref:`SpinButton`, :ref:`SpinCtrl`, :ref:`SpinCtrlDouble`, :ref:`StaticBitmap`, :ref:`StaticBox`, :ref:`StaticLine`, :ref:`StaticText`, :ref:`StatusBar`, `StyledTextCtrl`, :ref:`TextCtrl`, `TimePickerCtrl`, :ref:`ToolBar`, :ref:`TreeCtrl`, `WebView` | |method_summary| Methods Summary ================================ ================================================================================ ================================================================================ :meth:`~Control.__init__` Constructs a control. :meth:`~Control.Command` Simulates the effect of the user issuing a command to the item. :meth:`~Control.Create` :meth:`~Control.Ellipsize` Replaces parts of the `label` string with ellipsis, if needed, so that it fits into `maxWidth` pixels if possible. :meth:`~Control.EscapeMnemonics` Escapes the special mnemonics characters ("") in the given string. :meth:`~Control.GetLabel` Returns the control's label, as it was passed to :meth:`SetLabel` . :meth:`~Control.GetLabelText` Returns the control's label without mnemonics. :meth:`~Control.RemoveMnemonics` Returns the given `str` string without mnemonics ("" characters). :meth:`~Control.SetLabel` Sets the control's label. :meth:`~Control.SetLabelMarkup` Sets the controls label to a string using markup. :meth:`~Control.SetLabelText` Sets the control's label to exactly the given string. ================================================================================ ================================================================================ | |property_summary| Properties Summary ===================================== ================================================================================ ================================================================================ :attr:`~Control.Label` See :meth:`~Control.GetLabel` and :meth:`~Control.SetLabel` :attr:`~Control.LabelText` See :meth:`~Control.GetLabelText` and :meth:`~Control.SetLabelText` ================================================================================ ================================================================================ | |api| Class API =============== .. class:: Control(Window) This is the base class for a control or "widget". **Possible constructors**:: Control(parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=0, validator=DefaultValidator, name=ControlNameStr) Control() .. method:: __init__(self, *args, **kw) |overload| **Overloaded Implementations**: **~~~** **__init__** `(self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=0, validator=DefaultValidator, name=ControlNameStr)` Constructs a control. :param `parent`: Pointer to a parent window. :type `parent`: Window :param `id`: Control identifier. If ``ID_ANY``, will automatically create an identifier. :type `id`: int :param `pos`: Control position. DefaultPosition indicates that wxWidgets should generate a default position for the control. :type `pos`: Point :param `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. :type `size`: Size :param `style`: Control style. For generic window styles, please see :ref:`Window`. :type `style`: long :param `validator`: :type `validator`: Validator :param `name`: Control name. :type `name`: string **~~~** **__init__** `(self)` Default constructor to allow 2-phase creation. **~~~** .. method:: Command(self, event) Simulates the effect of the user issuing a command to the item. :param `event`: :type `event`: CommandEvent .. seealso:: :ref:`CommandEvent` .. method:: Create(self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=0, validator=DefaultValidator, name=ControlNameStr) :param `parent`: :type `parent`: Window :param `id`: :type `id`: int :param `pos`: :type `pos`: Point :param `size`: :type `size`: Size :param `style`: :type `style`: long :param `validator`: :type `validator`: Validator :param `name`: :type `name`: string :rtype: `bool` .. staticmethod:: 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. :param `label`: The string to ellipsize :type `label`: string :param `dc`: The DC used to retrieve the character widths through the :meth:`DC.GetPartialTextExtents` function. :type `dc`: DC :param `mode`: The ellipsization mode. This is the setting which determines which part of the string should be replaced by the ellipsis. See :ref:`EllipsizeMode` enumeration values for more info. :type `mode`: EllipsizeMode :param `maxWidth`: 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). :type `maxWidth`: int :param `flags`: One or more of the :ref:`EllipsizeFlags` enumeration values combined. :type `flags`: int :rtype: `string` .. staticmethod:: 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 :meth:`SetLabel` . Alternatively, if the label is entirely user-defined, you can just call :meth:`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. :param `text`: The string such as it should appear on the display. :type `text`: string :rtype: `string` :returns: The same string with the ampersands in it doubled. .. method:: GetLabel(self) Returns the control's label, as it was passed to :meth:`SetLabel` . Note that the returned string may contains mnemonics ("" characters) if they were passed to the :meth:`SetLabel` function; use :meth:`GetLabelText` if they are undesired. Also note that the returned string is always the string which was passed to :meth:`SetLabel` but may be different from the string passed to :meth:`SetLabelText` (since this last one escapes mnemonic characters). :rtype: `string` .. method:: GetLabelText(self, *args, **kw) |overload| **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 :meth:`SetLabel` but should always be the same which was passed to :meth:`SetLabelText` . :rtype: `string` **~~~** **GetLabelText** `(label)` Returns the given `label` string without mnemonics ("" characters). :param `label`: :type `label`: string :rtype: `string` **~~~** .. staticmethod:: RemoveMnemonics(str) Returns the given `str` string without mnemonics ("" characters). :param `str`: :type `str`: string :rtype: `string` .. note:: This function is identical to :meth:`GetLabelText` and is provided mostly for symmetry with :meth:`EscapeMnemonics` . .. method:: 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 :meth:`SetLabelText` instead. :param `label`: :type `label`: string .. method:: 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 :meth:`SetLabel` is used with the resulting string. For example, :: text = wx.StaticText(self, -1, 'Hello world!') # Some more code... text.SetLabelMarkup("&Bed &mp " "breakfast " "available HERE") would show the string using bold, red and big for the corresponding words under wxGTK but will simply show the string "Bed amp; 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** =========== ========================================================================= bold text bigger text italic text