Class button - cl-cffi-gtk3 API documentation

Package: gtk

Class gtk:button

Superclasses

gtk:bin, gtk:container, gtk:widget, gtk:buildable, gtk:actionable, gtk:activatable, gobject:object, common-lisp:standard-object, common-lisp:t

Documented Subclasses

gtk:color-button, gtk:font-button, gtk:link-button, gtk:lock-button, gtk:model-button, gtk:scale-button, gtk:toggle-button

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 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: false

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)
The text of the label inside the button, if the button contains a label.
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 use-stock property has been deprecated since version 3.10 and should not be used in newly written code.
Default value: false

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: false

xalign

The xalign property of type :float (Read / Write)
If the child of the button is a gtk:misc or gtk:alignment widget, this property can be used to control its horizontal alignment. The value 0.0 is left aligned, 1.0 is right aligned.
Warning: The xalign property 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 widget, this property can be used to control its vertical alignment. The value 0.0 is top aligned, 1.0 is bottom aligned.
Warning: The yalign property 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

The gtk:button widget emits a signal when clicked on.

Figure: GtkButton

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 object. The most commonly used child is the gtk:label widget.

CSS nodes

The gtk:button implementation has a single CSS node with name button. The node will get the .image-button or .text-button style classes, 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 the gtk:button widget 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 widget.

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: The child-displacement-x style property 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: The child-displacement-x style property 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)
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 gtk:widget-grab-default function.
Warning: The default-border style property 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)
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 gtk:widget-grab-default function.
Warning: The default-outside-border style property 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: The displace-focus style property 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: false

image-spacing

The image-spacing style property of type :int (Read)
The 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

button: The gtk:button widget that received the signal.

The signal on the gtk:button widget 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.

The "clicked" signal

lambda (button)    :action

button: The gtk:button widget that received the signal.

Emitted when the button has been activated (pressed and released).

The "enter" signal

lambda (button)    :run-first

button: The gtk:button widget that received the signal.

Emitted when the pointer enters the button.
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 of the gtk:widget class.

The "leave" signal

lambda (button)    :run-first

button: The gtk:button widget that received the signal.

Emitted when the pointer leaves the button.
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 of the gtk:widget class.

The "pressed" signal

lambda (button)    :run-first

button: The gtk:button widget that received the signal.

Emitted when the button is pressed.
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 of the gtk:widget class.

The "released" signal

lambda (button)    :run-first

button: The gtk:button widget that received the signal.

Emitted when the button is released.
Warning: The "released" signal has been deprecated since version 2.8 and should not be used in newly written code. Use the "button-release-event" signal of the gtk:widget class.