Provided by: libprima-perl_1.28-1.2_amd64 bug

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