/ 
Prima-1.75
River stage two • 17 direct dependents • 19 total dependents
/ Prima::Sliders

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

indeterminate BOOLEAN

If set, the gauge doesn't show the percentage, but shows a moving color strip, to hint that there's no know percentage. The strip width is sliderLength percents.

max INTEGER

Sets the upper limit for value.

Default value: 100.

min INTEGER

Sets the lower limit for value.

Default value: 0

sliderLength INTEGER

See indeterminate.

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.

See also: indeterminate

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

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 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