NAME
Prima::Sliders - sliding bars, spin buttons and input lines, dial
widget etc.
DESCRIPTION
The module is a set of widget classes, with one common property; - all
of these provide input and / or output of an integer value. This
property unites the following set of class hierarchies:
Prima::AbstractSpinButton
Prima::SpinButton
Prima::AltSpinButton
Prima::SpinEdit
Prima::Gauge
Prima::AbstractSlider
Prima::Slider
Prima::CircularSlider
Prima::AbstractSpinButton
Provides a generic interface to spin-button class functionality, which
includes range definition properties and events. Neither
"Prima::AbstractSpinButton", nor its descendants store the integer
value. These provide a mere possibility for the user to send
incrementing or decrementing commands.
The class is not usable directly.
Properties
state INTEGER
Internal state, reflects widget modal state, for example, is set to
non-zero when the user performs a mouse drag action. The exact
meaning of "state" is defined in the descendant classes.
Events
Increment DELTA
Called when the user presses a part of a widget that is responsible
for incrementing or decrementing commands. DELTA is an integer
value, indicating how the associated value must be modified.
TrackEnd
Called when the user finished the mouse transaction.
Prima::SpinButton
A rectangular spin button, consists of three parts, divided
horizontally. The upper and the lower parts are push-buttons
associated with singular increment and decrement commands. The middle
part, when dragged by mouse, fires "Increment" events with delta value,
based on a vertical position of the mouse pointer.
Prima::AltSpinButton
A rectangular spin button, consists of two push-buttons, associated
with singular increment and decrement command. Comparing to
"Prima::SpinButton", the class is less functional but has more stylish
look.
Prima::SpinEdit
The class is a numerical input line, paired with a spin button. The
input line value can be change three ways - either as a direct
traditional keyboard input, or as spin button actions, or as mouse
wheel response. The class provides value storage and range selection
properties.
Properties
circulate BOOLEAN
Selects the value modification rule when the increment or decrement
action hits the range. If 1, the value is changed to the opposite
limit value ( for example, if value is 100 in range 2-100, and the
user clicks on ’increment’ button, the value is changed to 2 ).
If 0, the value does not change.
Default value: 0
editClass STRING
Assigns an input line class.
Create-only property.
Default value: "Prima::InputLine"
editDelegations ARRAY
Assigns the input line list of delegated notifications.
Create-only property.
editProfile HASH
Assigns hash of properties, passed to the input line during the
creation.
Create-only property.
max INTEGER
Sets the upper limit for "value".
Default value: 100.
min INTEGER
Sets the lower limit for "value".
Default value: 0
pageStep INTEGER
Determines the multiplication factor for incrementing/decrementing
actions of the mouse wheel.
Default value: 10
spinClass STRING
Assigns a spin-button class.
Create-only property.
Default value: "Prima::AltSpinButton"
spinProfile ARRAY
Assigns the spin-button list of delegated notifications.
Create-only property.
spinDelegations HASH
Assigns hash of properties, passed to the spin-button during the
creation.
Create-only property.
step INTEGER
Determines the multiplication factor for incrementing/decrementing
actions of the spin-button.
Default value: 1
value INTEGER
Selects integer value in range from "min" to "max", reflected in
the input line.
Default value: 0.
Methods
set_bounds MIN, MAX
Simultaneously sets both "min" and "max" values.
Events
Change
Called when "value" is changed.
Prima::Gauge
An output-only widget class, displays a progress bar and an eventual
percentage string. Useful as a progress indicator.
Properties
indent INTEGER
Selects width of a border around the widget.
Default value: 1
max INTEGER
Sets the upper limit for "value".
Default value: 100.
min INTEGER
Sets the lower limit for "value".
Default value: 0
relief INTEGER
Selects the style of a border around the widget. Can be one of the
following "gr::XXX" constants:
gr::Sink - 3d sunken look
gr::Border - uniform black border
gr::Raise - 3d risen look
Default value: "gr::Sink".
threshold INTEGER
Selects the threshold value used to determine if the changes to
"value" are reflected immediately or deferred until the value is
changed more significantly. When 0, all calls to "value" result in
an immediate repaint request.
Default value: 0
value INTEGER
Selects integer value between "min" and "max", reflected in the
progress bar and eventual text.
Default value: 0.
vertical BOOLEAN
If 1, the widget is drawn vertically, and the progress bar moves
from bottom to top. If 0, the widget is drawn horizontally, and
the progress bar moves from left to right.
Default value: 0
Methods
set_bounds MIN, MAX
Simultaneously sets both "min" and "max" values.
Events
Stringify VALUE, REF
Converts integer VALUE into a string format and puts into REF
scalar reference. Default stringifying conversion is identical to
"sprintf("%2d%%")" one.
Prima::AbstractSlider
The class provides basic functionality of a sliding bar, equipped with
tick marks. Tick marks are supposed to be drawn alongside the main
sliding axis or circle and provide visual feedback for the user.
The class is not usable directly.
Properties
autoTrack BOOLEAN
A boolean flag, selects the way notifications execute when the user
mouse-drags the sliding bar. If 1, "Change" notification is
executed as soon as "value" is changed. If 0, "Change" is deferred
until the user finished the mouse drag; instead, "Track"
notification is executed when the bar is moved.
This property can be used when the action, called on "Change"
performs very slow, so the eventual fast mouse interactions would
not thrash down the program.
Default value: 1
increment INTEGER
A step range value, used in "scheme" for marking the key ticks.
See scheme for details.
Default value: 10
max INTEGER
Sets the upper limit for "value".
Default value: 100.
min INTEGER
Sets the lower limit for "value".
Default value: 0
readOnly BOOLEAN
If 1, the use cannot change the value by moving the bar or
otherwise.
Default value: 0
ticks ARRAY
Selects the tick marks representation along the sliding axis or
circle. ARRAY consists of hashes, each for one tick. The hash must
contain at least "value" key, with integer value. The two
additional keys, "height" and "text", select the height of a tick
mark in pixels and the text drawn near the mark, correspondingly.
If ARRAY is "undef", no ticks are drawn.
scheme INTEGER
"scheme" is a property, that creates a set of tick marks using one
of the predefined scale designs, selected by "ss::XXX" constants.
Each constant produces different scale; some make use of
"increment" integer property, which selects a step by which the
additional text marks are drawn. As an example, "ss::Thermometer"
design with default "min", "max", and "increment" values would look
like that:
0 10 20 100
| | | |
|||||||||||||||....|||
The module defines the following constants:
ss::Axis - 5 minor ticks per increment
ss::Gauge - 1 tick per increment
ss::StdMinMax - 2 ticks at the ends of the bar
ss::Thermometer - 10 minor ticks per increment, longer text ticks
When "tick" property is set, "scheme" is reset to "undef".
snap BOOLEAN
If 1, "value" cannot accept values that are not on the tick scale.
When set such a value, it is rounded to the closest tick mark. If
0, "value" can accept any integer value in range from "min" to
"max".
Default value: 0
step INTEGER
Integer delta for singular increment / decrement commands and a
threshold for "value" when "snap" value is 0.
Default value: 1
value INTEGER
Selects integer value between "min" and "max" and the corresponding
sliding bar position.
Default value: 0.
Events
Change
Called when "value" value is changed, with one exception: if the
user moves the sliding bar while "autoTrack" is 0, "Track"
notification is called instead.
Track
Called when the user moves the sliding bar while "autoTrack" value
is 0; this notification is a substitute to "Change".
Prima::Slider
Presents a linear sliding bar, movable along a linear shaft.
Properties
borderWidth INTEGER
In horizontal mode, sets extra margin space between the slider line
and the widget boundaries. Can be used for fine tuning of
displaying text labels from <ticks()>, where the default spacing
(0) or spacing procedure (drop overlapping labels) is not enough.
ribbonStrip BOOLEAN
If 1, the parts of shaft are painted with different colors, to
increase visual feedback. If 0, the shaft is painted with single
default background color.
Default value: 0
shaftBreadth INTEGER
Breadth of the shaft in pixels.
Default value: 6
tickAlign INTEGER
One of "tka::XXX" constants, that correspond to the situation of
tick marks:
tka::Normal - ticks are drawn on the left or on the top of the shaft
tka::Alternative - ticks are drawn on the right or at the bottom of the shaft
tka::Dual - ticks are drawn both ways
The ticks orientation ( left or top, right or bottom ) is dependant
on "vertical" property value.
Default value: "tka::Normal"
vertical BOOLEAN
If 1, the widget is drawn vertically, and the slider moves from
bottom to top. If 0, the widget is drawn horizontally, and the
slider moves from left to right.
Default value: 0
Methods
pos2info X, Y
Translates integer coordinates pair ( X, Y ) into the value
corresponding to the scale, and returns three scalars:
info INTEGER
If "undef", the user-driven positioning is not possible ( "min"
equals to "max" ).
If 1, the point is located on the slider.
If 0, the point is outside the slider.
value INTEGER
If "info" is 0 or 1, contains the corresponding "value".
aperture INTEGER
Offset in pixels along the shaft axis.
Prima::CircularSlider
Presents a slider widget with the dial and two increment / decrement
buttons. The tick marks are drawn around the perimeter of the dial;
current value is displayed in the center of the dial.
Properties
buttons BOOLEAN
If 1, the increment / decrement buttons are shown at the bottom of
the dial, and the user can change the value either by the dial or
by the buttons. If 0, the buttons are not shown.
Default values: 0
stdPointer BOOLEAN
Determines the style of a value indicator ( pointer ) on the dial.
If 1, it is drawn as a black triangular mark. If 0, it is drawn as
a small circular knob.
Default value: 0
Methods
offset2data VALUE
Converts integer value in range from "min" to "max" into the
corresponding angle, and return two real values: cosine and sine of
the angle.
offset2pt X, Y, VALUE, RADIUS
Converts integer value in range from "min" to "max" into the point
coordinates, with the RADIUS and dial center coordinates X and Y.
Return the calculated point coordinates as two integers in (X,Y)
format.
xy2val X, Y
Converts widget coordinates X and Y into value in range from "min"
to "max", and return two scalars: the value and the boolean flag,
which is set to 1 if the (X,Y) point is inside the dial circle, and
0 otherwise.
Events
Stringify VALUE, REF
Converts integer VALUE into a string format and puts into REF
scalar reference. The resulting string is displayed in the center
of the dial.
Default conversion routine simply copies VALUE to REF as is.
AUTHOR
Dmitry Karasik, <dmitry@karasik.eu.org>, Anton Berezin
<tobez@tobez.org>.
SEE ALSO
Prima, examples/fontdlg.pl