Class spin-button - cl-cffi-gtk4 API documentation

Package: gtk

Class gtk:spin-button

Superclasses

gtk:widget, gobject:initially-unowned, gtk:accessible, gtk:buildable, gtk:constraint-target, gtk:orientable, gtk:editable, gtk:cell-editable, gobject:object, common-lisp:standard-object, common-lisp:t

Documented Subclasses

None

Direct Slots

activates-default

The activates-default property of type gboolean (Read / Write)
Whether to activate the default widget when the spin button is activated. Since 4.16
Default value: false

adjustment

The adjustment property of type gtk:adjustment (Read / Write)
The adjustment that holds the value of the spin button.

climb-rate

The climb-rate property of type :double (Read / Write)
The acceleration rate when you hold down a button.
Allowed values: >= 0
Default value: 0

digits

The digits property of type :uint (Read / Write)
The number of decimal places to display.
Allowed values: <= 20
Default value: 0

numeric

The numeric property of type :boolean (Read / Write)
Whether non numeric characters should be ignored.
Default value: false

snap-to-ticks

The snap-to-ticks property of type :boolean (Read / Write)
Whether erroneous values are automatically changed to a spin button's nearest step increment.
Default value: false

update-policy

The update-policy property of type gtk:spin-button-update-policy (Read / Write)
Whether the spin button should update always, or only when the value is legal.
Default value: :always

value

The value property of type :double (Read / Write)
Reads the current value, or sets a new value.
Default value: 0.0

wrap

The wrap property of type :boolean (Read / Write)
Whether a spin button should wrap upon reaching its limits.
Default value: false

Details

The gtk:spin-button widget is an ideal way to allow the user to set the value of some attribute. Rather than having to directly type a number into a gtk:entry widget, the spin button allows the user to click on one of two arrows to increment or decrement the displayed value. A value can still be typed in, with the bonus that it can be checked to ensure it is in a given range.

Figure: GtkSpinButton

The main properties of a gtk:spin-button widget are through an adjustment. See the gtk:adjustment class for more details about the properties of an adjustment.

Note that the gtk:spin-button widget will by default make its entry large enough to accommodate the lower and upper bounds of the adjustment. If this is not desired, the automatic sizing can be turned off by explicitly setting the width-chars property to a value not equal to -1.

CSS nodes

spinbutton.horizontal
├── undershoot.left
├── undershoot.right
├── entry
│   ╰── ...
├── button.down
╰── button.up


spinbutton.vertical
├── undershoot.left
├── undershoot.right
├── button.up
├── entry
│   ╰── ...
╰── button.down

The gtk:spin-button implementation main CSS node has the name spinbutton. It creates subnodes for the text entry and the two buttons, with these names. The button nodes have the .up and .down style classes. The gtk:entry subnodes, if present, are put below the text entry node. The orientation of the spin button is reflected in the .vertical or .horizontal style class on the main node.

Examples

Code fragment for creating a spin button. The value from the spin button is retrieved with the gtk:spin-button-value function in a signal handler as a floating point number. Use the gtk:spin-button-value-as-int function to retrieve the value as an integer.

(let (...
      (spinner (make-instance 'gtk:spin-button
                              :adjustment
                              (make-instance 'gtk:adjustment
                                             :value 50.0
                                             :lower 0.0
                                             :upper 100.0
                                             :step-increment 1.0
                                             :page-increment 5.0
                                             :page-size 0.0)
                              :climb-rate 0
                              :digits 0
                              :wrap t)))


  (g:signal-connect spinner "value-changed"
                    (lambda (widget)
                      (let ((value (gtk:spin-button-value widget)))))
                        ... ))

Accessibility

The gtk:spin-button implementation uses the :spin-button role of the gtk:accessible-role enumeration.

Signal Details

The "change-value" signal

lambda (button scroll)    :action

button: The gtk:spin-button widget on which the signal was emitted.
scroll: The value of the gtk:scroll-type enumeration to specify the speed and amount of change.

Keybinding signal which gets emitted when the user initiates a value change. Applications should not connect to it, but may emit it with the g:signal-emit function if they need to control the cursor programmatically. The default bindings for this signal are Up/Down and PageUp and PageDown.

The "input" signal

lambda (button value)    :run-last

button: The gtk:spin-button widget on which the signal was emitted.
value: The pointer to a double float with the return location for the new value.
Returns: True for a successful conversion, false if the input was not handled, and -1 if the conversion failed.

Can be used to influence the conversion of the users input into a double float value. The signal handler is expected to use the gtk:editable-text function to retrieve the text of the text entry and set value to the new value. The default conversion uses the g_strtod() function.

The "output" signal

lambda (button)    :run-last

button: The gtk:spin-button widget which received the signal.
Returns: True if the value has been displayed.

Can be used to change the formatting of the value that is displayed in the spin buttons entry.

(let (...
      ;; A spin button for a number
      (spinner1 (make-instance 'gtk:spin-button
                               :adjustment
                               (make-instance 'gtk:adjustment
                                              :value 1.0
                                              :lower -10000.0
                                              :upper  10000.0
                                              :step-increment 0.5
                                              :page-increment 100.0
                                              :page-size 0.0)
                               :climb-rate 1.0
                               :digits 2
                               :wrap t))
      ;; A spin button for the digits to display
      (spinner2 (make-instance 'gtk:spin-button
                               :adjustment
                               (make-instance 'gtk:adjustment
                                              :value 2
                                              :lower 1
                                              :upper 5
                                              :step-increment 1
                                              :page-increment 1
                                              :page-size 0)
                                :climb-rate 0.0
                                :digits 0
                                :wrap t)))
  ;; Customize the appearance of the number
  (g:signal-connect spinner1 "output"
    (lambda (spinbutton)
      (let ((value (gtk:adjustment-value
                     (gtk:spin-button-adjustment spinbutton)))
            (digits (truncate
                      (gtk:adjustment-value
                        (gtk:spin-button-adjustment spinner2)))))
        (setf (gtk:entry-text spinbutton)
              (format nil "~@?" (format nil "~~,~d@f" digits) value)))))
  ... )

The "value-changed" signal

lambda (button)    :run-last

button: The gtk:spin-button widget on which the signal was emitted.

Is emitted when the value represented by button changes. Also see the "output" signal.

The "wrapped" signal

lambda (button)    :run-last

button: The gtk:spin-button widget which received the signal.

Is emitted right after the spin button wraps from its maximum to minimum value or vice versa.