Package: gtk

Class gtk-button

Superclasses

Documented Subclasses

Direct Slots

always-show-image
The always-show-image property of type :boolean (Read / Write / Construct)
If true, the button will ignore the gtk-button-images setting of type gtk-settings and always show the image, if available. Use this property if the button would be useless or hard to use without the image.
Default value: nil
Since 3.6
focus-on-click
The focus-on-click property of type :boolean (Read / Write)
Whether the button grabs focus when it is clicked with the mouse.
Default value: true
image
The image property of type gtk-widget (Read / Write)
The child widget to appear next to the button text.
image-position
The image-position property of type gtk-position-type (Read / Write)
The position of the image relative to the text inside the button.
Default value: :left
label
The label property of type :string (Read / Write / Construct)
Text of the label widget inside the button, if the button contains a label widget.
Default value: nil
relief
The relief property of type gtk-relief-style (Read / Write)
The border relief style.
Default value: :normal
use-stock
The use-stock property of type :boolean (Read / Write / Construct)
If set, the label is used to pick a stock item instead of being displayed.
Warning: The property use-stock has been deprecated since version 3.10 and should not be used in newly-written code.
Default value: nil
use-underline
The use-underline property of type :boolean (Read / Write / Construct)
If set, an underline in the text indicates the next character should be used for the mnemonic accelerator key.
Default value: nil
xalign
The xalign property of type :float (Read / Write)
If the child of the button is a gtk-misc or gtk-alignment, this property can be used to control its horizontal alignment. The value 0.0 is left aligned, 1.0 is right aligned.
Warning: xalign has been deprecated since version 3.14 and should not be used in newly-written code. Access the child widget directly if you need to control its alignment.
Allowed values: [0,1]
Default value: 0.5
yalign
The yalign property of type :float (Read / Write)
If the child of the button is a gtk-misc or gtk-alignment, this property can be used to control its vertical alignment. The value 0.0 is top aligned, 1.0 is bottom aligned.
Warning: yalign has been deprecated since version 3.14 and should not be used in newly-written code. Access the child widget directly if you need to control its alignment.
Allowed values: [0,1]
Default value: 0.5

Details

A widget that emits a signal when clicked on.



The gtk-button widget is generally used to trigger a callback function that is called when the button is pressed. The various signals and how to use them are outlined below.

The gtk-button widget can hold any valid child widget. That is, it can hold almost any other standard gtk-widget. The most commonly used child is the gtk-label.

CSS nodes

gtk-button 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.

Other style classes that are commonly used with gtk-button include .suggested-action and .destructive-action. In special cases, buttons can be made round by adding the .circular style class.

Button-like widgets like gtk-toggle-button, gtk-menu-button, gtk-volume-button, gtk-lock-button, gtk-color-button, gtk-font-button or gtk-file-chooser-button use style classes such as .toggle, .popup, .scale, .lock, .color, .font, .file to differentiate themselves from a plain gtk-button.

Style Property Details

child-displacement-x
The child-displacement-x style property of type :int (Read)
How far in the x direction to move the child when the button is depressed.
Warning: child-displacement-x has been deprecated since version 3.20 and should not be used in newly-written code. Use CSS margins and padding instead; the value of this style property is ignored.
Default value: 0
child-displacement-y
The child-displacement-y style property of type :int (Read)
How far in the y direction to move the child when the button is depressed.
Warning: child-displacement-x has been deprecated since version 3.20 and should not be used in newly-written code. Use CSS margins and padding instead; the value of this style property is ignored.
Default value: 0
default-border
The default-border style property of type gtk-border (Read)
The default-border style property defines the extra space to add around a button that can become the default widget of its window. For more information about default widgets, see the function gtk-widget-grab-default.
Warning: default-border has been deprecated since version 3.14 and should not be used in newly-written code. Use CSS margins and padding instead; the value of this style property is ignored.
default-outside-border
The default-outside-border style property of type gtk-border (Read)
The default-outside-border style property defines the extra outside space to add around a button that can become the default widget of its window. Extra outside space is always drawn outside the button border. For more information about default widgets, see the function gtk-widget-grab-default.
Warning: default-border has been deprecated since version 3.14 and should not be used in newly-written code. Use CSS margins and padding instead; the value of this style property is ignored.
displace-focus
The displace-focus style property of type :boolean (Read)
Whether the child-displacement-x or child-displacement-y properties should also affect the focus rectangle.
Warning: displace-focus has been deprecated since version 3.20 and should not be used in newly-written code. Use CSS margins and padding instead; the value of this style property is ignored.
Default value: nil
image-spacing
The image-spacing style property of type :int (Read)
Spacing in pixels between the image and label.
Allowed values: >= 0
Default value: 2
inner-border
The inner-border style property of type gtk-border (Read)
Sets the border between the button edges and child.
Warning: The inner-border style property has been deprecated since version 3.4 and should not be used in newly written code. Use the standard border and padding CSS properties; the value of this style property is ignored.

Signal Details

The "activate" signal
 lambda (button)    : Action      
The "activate" signal on gtk-button is an action signal and emitting it causes the button to animate press then release. Applications should never connect to this signal, but use the "clicked" signal.
button
The object which received the signal.
The "clicked" signal
 lambda (button)    : Action      
Emitted when the button has been activated (pressed and released).
button
The object that received the signal.
The "enter" signal
 lambda (button)    : Run First      
Warning: The "enter" signal has been deprecated since version 2.8 and should not be used in newly written code. Use the "enter-notify-event" signal.
Emitted when the pointer enters the button.
button
The object that received the signal.
The "leave" signal
 lambda (button)    : Run First      
Warning: The "leave" signal has been deprecated since version 2.8 and should not be used in newly written code. Use the "leave-notify-event" signal.
Emitted when the pointer leaves the button.
button
The object that received the signal.
The "pressed" signal
 lambda (button)    : Run First      
Warning: The "pressed" signal has been deprecated since version 2.8 and should not be used in newly-written code. Use the "button-press-event" signal.
Emitted when the button is pressed.
button
The object that received the signal.
The "released" signal
 lambda (button)    : Run First      
Warning: The "released" has been deprecated since version 2.8 and should not be used in newly written code. Use the "button-release-event" signal.
Emitted when the button is released.
button
The object that received the signal.
 

Slot Access Functions

Inherited Slot Access Functions

See also

2013-12-9