Class

Summary

A pane with a sliding marker, which allows the user to control a numerical value within a specified range.

Package

capi

Superclasses

range-pane
titled-object
simple-pane

Initargs

:print-function

A function of two arguments, or a format string.

:show-value-p

A generalized boolean.

:start-point

A keyword.

:tick-frequency

An integer, a ratio or the keyword :default.

Accessors

slider-print-function

Readers

slider-show-value-p
slider-start-point
slider-tick-frequency

Description

The class slider allows the user to enter a number by moving a marker on a sliding scale to the desired value.

show-value-p determines whether the slider displays the current value, on Microsoft Windows and GTK+. The default value is t. show-value-p is ignored on Cocoa.

start-point specifies which end of the slider is the start point in the range. The values allowed depend on the orientation of the slider. For horizontal sliders, start-point can take these values:

:left

The start point is on the left.

:right

The start point is on the right.

:default

The start point is at the default side (the left).

For vertical sliders, start-point can take these values:

:top

The start point is at the top.

:bottom

The start point is at the bottom.

:default

The start point is at the default position, which is the top on Microsoft Windows and Motif, and the bottom on Cocoa.

tick-frequency specifies the spacing of tick marks drawn on the slider. If tick-frequency is :default, then the slider may or may not draw tick marks according the OS conventions. If tick-frequency is 0, then no tick marks are drawn. If tick-frequency is a ratio 1/N for integer N>1, then tick marks are drawn to divide the slider range into N sections. Otherwise tick-frequency should be an integer greater than 1 which specifies the spacing of tick marks in units between start and end . The default value of tick-frequency is :default.

print-function , when supplied, should be a function with signature

print-function pane value => result

where pane is the slider pane, value is its current value, and result is a string or nil. When the slider pane displays the current value, it calls print-function and displays the value as result , unless that is nil, in which case the value is printed normally.

As a special case, print-function can also be a string, which is used as the format string in a call to format with one additional argument, the value, that is

(format nil print-function value )

and the result of this call to format is displayed.

Notes

1. :print-function is not implemented on Motif.
2. :print-function has no effect on Cocoa because the slider pane never displays the value
3. Use of the print-function is determined when the slider pane is displayed. Setting the print-function in a slider that did not have a print-function when it was first displayed does not work until the slider is destroyed and displayed again. Therefore, if you want to display a slider without a print-function but set it later, initially you should supply a print-function that always returns nil, for example:

     (make-instance 'capi:slider

               :start 10 :end 34

               :print-function 'false)

4. print-function is useful for displaying fractional values or values that grow logarithmically (or any other non-linear function), because the actual values in a slider are always integers that increase linearly as the slider moves.
5. On Windows the slider's value is displayed (when show-value-p is true) in a tooltip that is visible only while the user moves the marker with a mouse.

Compatibility note

In LispWorks 6.0 and earlier versions, ticks are drawn as if tick-frequency is :default.

Example

Given the default start and end of 0 and 100, this gives ticks at 0, 25, 50, 75 and 100:

(make-instance 'slider :tick-frequency 25)

while this gives ticks at 0, 20, 40, 60, 80 and 100:

(make-instance 'slider :tick-frequency 1/5)

This example illustrates the use of print-function to display fractional and non-linear values ranges:

(example-edit-file "capi/elements/slider-print-function")

See also

Slider, Progress bar and Scroll bar