Class gtk-spin-button

Package: gtk

Superclasses

gtk-entry, gtk-widget, gtk-buildable, gtk-editable, gtk-cell-editable, gtk-orientable, g-object, common-lisp:standard-object, common-lisp:t

Documented Subclasses

None

Direct Slots

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

A 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.

The main properties of a gtk-spin-button widget are through an adjustment. See the gtk-adjustment class for more details about an adjustment's properties. Note that the spin button will by default make its entry large enough to accomodate the lower and upper bounds of the adjustment, which can lead to surprising results. Best practice is to set both the width-chars and max-width-chars poperties to the desired number of characters to display in the entry.

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 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 entry node. The orientation of the spin button is reflected in the .vertical or .horizontal style class on the main node.

Example

Code fragment for creating a spin button. The value from the spin button is retrieved with the function gtk-spin-button-value in a signal handler as a floating point number. Use the function gtk-spin-button-value-as-int 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)))))
                        ... ))

Style Property Details

shadow-type: The "shadow-type" style property of type gtk-shadow-type (Read)
Style of bevel around the spin button.
Warning: The shadow-type style property has been deprecated since version 3.20 and should not be used in newly written code. Use CSS to determine the style of the border. The value of this style property is ignored.
Default value: :in

Signal Details

The "change-value" signal

 lambda (spin-button scroll)    : Action

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

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

The "input" signal

 lambda (spin-button new-value)    : Run Last

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

spin-button: The gtk-spin-button widget on which the signal was emitted.
new-value: A 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 GTK_INPUT_ERROR if the conversion failed.

The "output" signal

 lambda (spin-button)    : Run Last

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 (spin-button)
      (let ((value (gtk-adjustment-value
                     (gtk-spin-button-adjustment spin-button)))
            (digits (truncate
                      (gtk-adjustment-value
                        (gtk-spin-button-adjustment spinner2)))))
        (setf (gtk-entry-text spin-button)
              (format nil "~@?" (format nil "~~,~d@f" digits) value)))))
  ... )

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