Package: gtk

Class gtk-spin-button

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.
The "value-changed" signal
 lambda (spin-button)    : Run Last      
Is emitted when the value represented by spin-button changes. Also see the "output" signal.
spin-button
The gtk-spin-button widget on which the signal was emitted.
The "wrapped" signal
 lambda (spin-button)    : Run Last      
Is emitted right after the spin button wraps from its maximum to minimum value or vice versa.
spin-button
The gtk-spin-button widget which received the signal.
 

Slot Access Functions

Inherited Slot Access Functions

gtk-cell-editable-editing-canceled
gtk-orientable-orientation
gtk-entry-activates-default
gtk-entry-attributes
gtk-entry-buffer
gtk-entry-caps-lock-warning
gtk-entry-completion
gtk-entry-cursor-position
gtk-entry-editable
gtk-entry-has-frame
gtk-entry-im-module
gtk-entry-inner-border
gtk-entry-input-hints
gtk-entry-input-purpose
gtk-entry-invisible-char
gtk-entry-invisible-char-set
gtk-entry-max-length
gtk-entry-overwrite-mode
gtk-entry-placeholder-text
gtk-entry-populate-all
gtk-entry-primary-icon-activatable
gtk-entry-primary-icon-gicon
gtk-entry-primary-icon-name
gtk-entry-primary-icon-pixbuf
gtk-entry-primary-icon-sensitive
gtk-entry-primary-icon-stock
gtk-entry-primary-icon-storage-type
gtk-entry-primary-icon-tooltip-markup
gtk-entry-primary-icon-tooltip-text
gtk-entry-progress-fraction
gtk-entry-progress-pulse-step
gtk-entry-scroll-offset
gtk-entry-secondary-icon-activatable
gtk-entry-secondary-icon-gicon
gtk-entry-secondary-icon-name
gtk-entry-secondary-icon-pixbuf
gtk-entry-secondary-icon-sensitive
gtk-entry-secondary-icon-stock
gtk-entry-secondary-icon-storage-type
gtk-entry-secondary-icon-tooltip-markup
gtk-entry-secondary-icon-tooltip-text
gtk-entry-selection-bound
gtk-entry-shadow-type
gtk-entry-tabs
gtk-entry-text
gtk-entry-text-length
gtk-entry-truncate-multiline
gtk-entry-visibility
gtk-entry-width-chars
gtk-entry-xalign
gtk-widget-app-paintable
gtk-widget-can-default
gtk-widget-can-focus
gtk-widget-composite-child
gtk-widget-double-buffered
gtk-widget-events
gtk-widget-expand
gtk-widget-focus-on-click
gtk-widget-halign
gtk-widget-has-default
gtk-widget-has-focus
gtk-widget-has-tooltip
gtk-widget-height-request
gtk-widget-hexpand
gtk-widget-hexpand-set
gtk-widget-is-focus
gtk-widget-margin
gtk-widget-margin-bottom
gtk-widget-margin-end
gtk-widget-margin-left
gtk-widget-margin-right
gtk-widget-margin-start
gtk-widget-margin-top
gtk-widget-name
gtk-widget-no-show-all
gtk-widget-opacity
gtk-widget-parent
gtk-widget-receives-default
gtk-widget-scale-factor
gtk-widget-sensitive
gtk-widget-style
gtk-widget-tooltip-markup
gtk-widget-tooltip-text
gtk-widget-valign
gtk-widget-vexpand
gtk-widget-vexpand-set
gtk-widget-visible
gtk-widget-width-request
gtk-widget-window
g-object-has-reference
g-object-pointer
g-object-signal-handlers

See also

2021-2-10