:right-sidebar: True Button =================================================================== .. currentmodule:: gi.repository.Gtk .. class:: Button(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object` Subclasses: :class:`~gi.repository.Gtk.LinkButton`, :class:`~gi.repository.Gtk.LockButton`, :class:`~gi.repository.Gtk.ToggleButton` Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.Actionable`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget` The ``GtkButton`` widget is generally used to trigger a callback function that is called when the button is pressed. .. image:: https://docs.gtk.org/gtk4/button.png The ``GtkButton`` widget can hold any valid child widget. That is, it can hold almost any other standard ``GtkWidget``. The most commonly used child is the ``GtkLabel``. CSS nodes --------- ``GtkButton`` has a single CSS node with name button. The node will get the style classes .image-button or .text-button, if the content is just an image or label, respectively. It may also receive the .flat style class. When activating a button via the keyboard, the button will temporarily gain the .keyboard-activating style class. Other style classes that are commonly used with ``GtkButton`` include .suggested-action and .destructive-action. In special cases, buttons can be made round by adding the .circular style class. Button-like widgets like :obj:`~gi.repository.Gtk.ToggleButton`, :obj:`~gi.repository.Gtk.MenuButton`, :obj:`~gi.repository.Gtk.VolumeButton`, :obj:`~gi.repository.Gtk.LockButton`, :obj:`~gi.repository.Gtk.ColorButton` or :obj:`~gi.repository.Gtk.FontButton` use style classes such as .toggle, .popup, .scale, .lock, .color on the button node to differentiate themselves from a plain ``GtkButton``. Accessibility ------------- ``GtkButton`` uses the :const:`~gi.repository.Gtk.AccessibleRole.BUTTON` role. Constructors ------------ .. rst-class:: interim-class .. class:: Button :no-index: .. classmethod:: new() -> ~gi.repository.Gtk.Widget Creates a new ``GtkButton`` widget. To add a child widget to the button, use :obj:`~gi.repository.Gtk.Button.set_child`. .. classmethod:: new_from_icon_name(icon_name: str) -> ~gi.repository.Gtk.Widget Creates a new button containing an icon from the current icon theme. If the icon name isn’t known, a “broken image” icon will be displayed instead. If the current icon theme is changed, the icon will be updated appropriately. :param icon_name: an icon name .. classmethod:: new_with_label(label: str) -> ~gi.repository.Gtk.Widget Creates a ``GtkButton`` widget with a ``GtkLabel`` child. :param label: The text you want the ``GtkLabel`` to hold .. classmethod:: new_with_mnemonic(label: str) -> ~gi.repository.Gtk.Widget Creates a new ``GtkButton`` containing a label. If characters in ``label`` are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use “``__``” (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing :kbd:`Alt` and that key activates the button. :param label: The text of the button, with an underscore in front of the mnemonic character Methods ------- .. rst-class:: interim-class .. class:: Button :no-index: .. method:: get_can_shrink() -> bool Retrieves whether the button can be smaller than the natural size of its contents. .. versionadded:: 4.12 .. method:: get_child() -> ~gi.repository.Gtk.Widget | None Gets the child widget of ``button``. .. method:: get_has_frame() -> bool Returns whether the button has a frame. .. method:: get_icon_name() -> str | None Returns the icon name of the button. If the icon name has not been set with :obj:`~gi.repository.Gtk.Button.set_icon_name` the return value will be :const:`None`. This will be the case if you create an empty button with :obj:`~gi.repository.Gtk.Button.new` to use as a container. .. method:: get_label() -> str | None Fetches the text from the label of the button. If the label text has not been set with :obj:`~gi.repository.Gtk.Button.set_label` the return value will be :const:`None`. This will be the case if you create an empty button with :obj:`~gi.repository.Gtk.Button.new` to use as a container. .. method:: get_use_underline() -> bool gets whether underlines are interpreted as mnemonics. See :obj:`~gi.repository.Gtk.Button.set_use_underline`. .. method:: set_can_shrink(can_shrink: bool) -> None Sets whether the button size can be smaller than the natural size of its contents. For text buttons, setting ``can_shrink`` to true will ellipsize the label. For icons and custom children, this function has no effect. .. versionadded:: 4.12 :param can_shrink: whether the button can shrink .. method:: set_child(child: ~gi.repository.Gtk.Widget | None = None) -> None Sets the child widget of ``button``. Note that by using this API, you take full responsibility for setting up the proper accessibility label and description information for ``button``. Most likely, you'll either set the accessibility label or description for ``button`` explicitly, or you'll set a labelled-by or described-by relations from ``child`` to ``button``. :param child: the child widget .. method:: set_has_frame(has_frame: bool) -> None Sets the style of the button. Buttons can have a flat appearance or have a frame drawn around them. :param has_frame: whether the button should have a visible frame .. method:: set_icon_name(icon_name: str) -> None Adds a ``GtkImage`` with the given icon name as a child. If ``button`` already contains a child widget, that child widget will be removed and replaced with the image. :param icon_name: An icon name .. method:: set_label(label: str) -> None Sets the text of the label of the button to ``label``. This will also clear any previously set labels. :param label: a string .. method:: set_use_underline(use_underline: bool) -> None Sets whether to use underlines as mnemonics. If true, an underline in the text of the button label indicates the next character should be used for the mnemonic accelerator key. :param use_underline: :const:`True` if underlines in the text indicate mnemonics Properties ---------- .. rst-class:: interim-class .. class:: Button :no-index: .. attribute:: props.can_shrink :type: bool Whether the size of the button can be made smaller than the natural size of its contents. For text buttons, setting this property will allow ellipsizing the label. If the contents of a button are an icon or a custom widget, setting this property has no effect. .. versionadded:: 4.12 .. attribute:: props.child :type: ~gi.repository.Gtk.Widget The child widget. .. attribute:: props.has_frame :type: bool Whether the button has a frame. .. attribute:: props.icon_name :type: str The name of the icon used to automatically populate the button. .. attribute:: props.label :type: str Text of the label inside the button, if the button contains a label widget. .. attribute:: props.use_underline :type: bool If set, an underline in the text indicates that the following character is to be used as mnemonic. Signals ------- .. rst-class:: interim-class .. class:: Button.signals :no-index: .. method:: activate() -> None Emitted to animate press then release. This is an action signal. Applications should never connect to this signal, but use the :obj:`~gi.repository.Gtk.Button.signals.clicked` signal. The default bindings for this signal are all forms of the ␣ and :kbd:`Enter` keys. .. method:: clicked() -> None Emitted when the button has been activated (pressed and released). Virtual Methods --------------- .. rst-class:: interim-class .. class:: Button :no-index: .. method:: do_activate() -> None Signal that causes the button to animate press then release. Applications should never connect to this signal, but use the ``clicked`` signal. .. method:: do_clicked() -> None Signal emitted when the button has been activated (pressed and released). Fields ------ .. rst-class:: interim-class .. class:: Button :no-index: .. attribute:: parent_instance