Prima::Sliders - sliding bars, spin buttons and input lines, dial widget etc.
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
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.
Prima::AbstractSpinButton
The class is not usable directly.
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.
state
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.
Called when the user finished the mouse transaction.
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.
Increment
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::SpinButton
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.
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
Assigns an input line class.
Create-only property.
Default value: Prima::InputLine
Prima::InputLine
Assigns the input line list of delegated notifications.
Assigns hash of properties, passed to the input line during the creation.
Sets the upper limit for value.
value
Default value: 100.
Sets the lower limit for value.
Determines the multiplication factor for incrementing/decrementing actions of the mouse wheel.
Default value: 10
Assigns a spin-button class.
Default value: Prima::AltSpinButton
Prima::AltSpinButton
Assigns the spin-button list of delegated notifications.
Assigns hash of properties, passed to the spin-button during the creation.
Determines the multiplication factor for incrementing/decrementing actions of the spin-button.
Default value: 1
Selects integer value in range from min to max, reflected in the input line.
min
max
Default value: 0.
Simultaneously sets both min and max values.
Called when value is changed.
An output-only widget class, displays a progress bar and an eventual percentage string. Useful as a progress indicator.
Selects width of a border around the widget.
Selects the style of a border around the widget. Can be one of the following gr::XXX constants:
gr::XXX
gr::Sink - 3d sunken look gr::Border - uniform black border gr::Raise - 3d risen look
Default value: gr::Sink.
gr::Sink
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.
Selects integer value between min and max, reflected in the progress bar and eventual text.
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.
Converts integer VALUE into a string format and puts into REF scalar reference. Default stringifying conversion is identical to sprintf("%2d%%") one.
sprintf("%2d%%")
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.
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.
Change
Track
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.
A step range value, used in scheme for marking the key ticks. See scheme for details.
scheme
If 1, the use cannot change the value by moving the bar or otherwise.
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.
height
text
If ARRAY is undef, no ticks are drawn.
undef
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:
ss::XXX
increment
ss::Thermometer
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.
tick
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.
Integer delta for singular increment / decrement commands and a threshold for value when snap value is 0.
snap
Selects integer value between min and max and the corresponding sliding bar position.
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.
autoTrack
Called when the user moves the sliding bar while autoTrack value is 0; this notification is a substitute to Change.
Presents a linear sliding bar, movable along a linear shaft.
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.
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.
Breadth of the shaft in pixels.
Default value: 6
One of tka::XXX constants, that correspond to the situation of tick marks:
tka::XXX
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.
vertical
Default value: tka::Normal
tka::Normal
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.
Translates integer coordinates pair ( X, Y ) into the value corresponding to the scale, and returns three scalars:
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.
If info is 0 or 1, contains the corresponding value.
info
Offset in pixels along the shaft axis.
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.
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
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.
Converts integer value in range from min to max into the corresponding angle, and return two real values: cosine and sine of the angle.
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.
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.
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.
Dmitry Karasik, <dmitry@karasik.eu.org>, Anton Berezin <tobez@tobez.org>.
Prima, examples/fontdlg.pl
To install Prima, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Prima
CPAN shell
perl -MCPAN -e shell install Prima
For more information on module installation, please visit the detailed CPAN module installation guide.