Prima::Sliders(3) | User Contributed Perl Documentation | Prima::Sliders(3) |
NAME¶
Prima::Sliders - sliding bars, spin buttons, dial widgets, etc
DESCRIPTION¶
The module contains a set of unrelated widget classes that provide input and/or output of an integer value. That is the only thing common in these classes, which are:
Prima::AbstractSpinButton Prima::SpinButton Prima::AltSpinButton Prima::SpinEdit Prima::Gauge Prima::PrigressBar Prima::AbstractSlider Prima::Slider Prima::CircularSlider
Prima::AbstractSpinButton¶
Provides a generic interface to the spin-button class functionality that includes events and range definition properties. Neither "Prima::AbstractSpinButton" nor its descendants store the integer value. These provide a mere possibility for the user to send the incrementing and decrementing commands.
The class is not usable directly.
Properties¶
- state INTEGER
- The property manages a common internal state that doesn't have an exact meaning, as it is only defined in the descendant classes. For example, the state can be set to non-zero when the user performs a mouse drag action.
Events¶
- Increment DELTA
- Called when the user presses a part of the widget that is responsible for incrementing or decrementing commands. DELTA is an integer value that indicates how the associated value must be modified.
- TrackEnd
- Called when the user finished the mouse transaction.
Prima::SpinButton¶
A rectangular spin button that 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 the mouse, fires the "Increment" events with delta value, based on the vertical position of the mouse pointer.
Prima::AltSpinButton¶
A rectangular spin button that consists of two push-buttons, associated with singular increment and decrement commands. Compared to "Prima::SpinButton", the class is a bit less functional but has a more stylish look.
Prima::SpinEdit¶
The widget contains a numerical input line and a spin button. The input line value can be changed in three ways - either as a direct traditional keyboard input, as a result of the spin button actions, or as the mouse wheel response. The class provides properties for value storage and range selection.
Properties¶
- allowEmpty BOOLEAN
- If set, allows an empty string as a valid value
Default value: false
- circulate BOOLEAN
- Selects the value modification rule when the increment or decrement action
hits a range limit. If 1, the value is changed to the opposite limit value
( for example, if the value is 100 in the range 2-100, and the user clicks
on the 'increment' button, the value is changed to 2 ).
If 0, the value does not change.
Default value: 0
- editClass STRING
- Assigns the input line class.
A create-only property.
Default value: "Prima::InputLine"
- editDelegations ARRAY
- Assigns the input line list of the notifications.
A create-only property.
- editProfile HASH
- Assigns a hash of properties passed to the input line during the creation.
A 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 and decrementing
actions of the mouse wheel.
Default value: 10
- spinClass STRING
- Assigns the spin-button class.
A create-only property.
Default value: "Prima::AltSpinButton"
- spinProfile ARRAY
- Assigns the spin-button list of the delegated notifications.
A create-only property.
- spinDelegations HASH
- Assigns a hash of properties passed to the spin-button during the
creation.
A create-only property.
- step INTEGER
- Determines the multiplication factor for incrementing and decrementing
actions of the spin-button.
Default value: 1
- value INTEGER
- Selects the integer value in the range from
"min" to
"max". The value is 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 the width of the 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 the 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 raised look
Default value: "gr::Sink".
- threshold INTEGER
- Selects the threshold value used to determine if the changes to
"value" are reflected immediately or are
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 the 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 the integer VALUE into a string format and stores it in the REF scalar reference. Default stringifying conversion is identical to a call to sprintf("%2d%%").
Prima::ProgressBar¶
Displays a progress bar
Properties¶
- max INTEGER
- Sets the upper limit for "value".
Default value: 100.
- min INTEGER
- Sets the lower limit for "value".
Default value: 0
- value INTEGER
- Selects the integer value between "min"
and "max", reflected in the progress bar
and an eventual text.
Default value: 0.
Methods¶
- set_bounds MIN, MAX
- Simultaneously sets both "min" and "max" values.
Prima::AbstractSlider¶
The class provides the basic functionality of a sliding bar, equipped with tick marks. The tick marks are supposed to be drawn alongside the main sliding axis or the dialing circle, and provide visual feedback for the user.
The class is not usable directly.
Properties¶
- autoTrack BOOLEAN
- A boolean flag, selects the way notifications are executed when the user
mouse-drags the sliding bar. If 1, the
"Change" notification is executed as
soon as "value" is changed. If 0,
"Change" is deferred until the user
finishes the mouse drag; instead, the
"Track" notification is executed when
the bar is moved.
This property can be used when the "Change" notification handler performs very slowly, 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 user 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 the
dialing circle. ARRAY consists of hashes, each for one tick. The hash must
contain at least a "value" key with an
integer value. The two additional keys
"height" and
"text", select the height of a tick mark
in pixels, and the text is 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
the "ss::XXX" constants. Each constant
produces a different scale; some make use of the
"increment" integer property that
selects a step that is used to place additional text marks. As an example,
the "ss::Thermometer" design with the
default "min",
"max", and
"increment" values would look like this:
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 the "tick" property is explicitly set, "scheme" is reset to "undef".
- snap BOOLEAN
- If 1, "value" cannot accept values that
are not on the tick scale. When such a value is attempted to be set, it is
rounded to the closest tick mark. If 0,
"value" can accept any integer value in
the range from "min" to
"max".
Default value: 0
- step INTEGER
- An integer delta for singular increment and decrement commands, and also a
threshold for "value" when the
"snap" value is 0.
Default value: 1
- value INTEGER
- Selects an integer value between "min"
and "max" and the corresponding sliding
bar position.
Default value: 0.
Events¶
- Change
- Called when the "value" value is changed, with one exception: if the user moves the sliding bar while "autoTrack" is 0, the "Track" notification is called instead.
- Track
- Called when the user moves the sliding bar while the "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 text labels from ticks(), where the default spacing (0) or spacing procedure (drop overlapping labels) does not produce decent results.
- ribbonStrip BOOLEAN
- If 1, the parts of the shaft are painted with different colors to increase
visual feedback. If 0, the shaft is painted with the single default
background color.
Default value: 0
- shaftBreadth INTEGER
- The breadth of the shaft in pixels.
Default value: 6
- tickAlign INTEGER
- One of the "tka::XXX" constants that
correspond to the position of the tick marks:
tka::Normal - ticks are drawn on the left or 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 dependent on the "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 a dialing circle and two increment/decrement buttons. The tick marks are drawn around the perimeter of the dial; the current value is displayed in the center of the dial.
Properties¶
- 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 the range from "min" to "max" into the corresponding angle, and returns two floating-point values: cosine and sine of the angle.
- offset2pt X, Y, VALUE, RADIUS
- Converts integer value in the 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 the (X,Y) format.
- xy2val X, Y
- Converts widget coordinates X and Y into value in the range from "min" to "max" and returns two scalars: the value and the boolean flag, which is set to 1 if the (X,Y) point is inside the dial circle, and to 0 otherwise.
Events¶
- Stringify VALUE, REF
- Converts integer VALUE into a string format and stores it in the REF
scalar reference. The resulting string is displayed in the center of the
dial.
The 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
2024-02-01 | perl v5.38.2 |