1Prima::Sliders(3)     User Contributed Perl Documentation    Prima::Sliders(3)
2
3
4

NAME

6       Prima::Sliders - sliding bars, spin buttons and input lines, dial
7       widget etc.
8

DESCRIPTION

10       The module is a set of widget classes, with one common property; - all
11       of these provide input and / or output of an integer value.  This
12       property unites the following set of class hierarchies:
13
14               Prima::AbstractSpinButton
15                       Prima::SpinButton
16                       Prima::AltSpinButton
17
18               Prima::SpinEdit
19
20               Prima::Gauge
21
22               Prima::AbstractSlider
23                       Prima::Slider
24                       Prima::CircularSlider
25

Prima::AbstractSpinButton

27       Provides a generic interface to spin-button class functionality, which
28       includes range definition properties and events. Neither
29       "Prima::AbstractSpinButton", nor its descendants store the integer
30       value. These provide a mere possibility for the user to send
31       incrementing or decrementing commands.
32
33       The class is not usable directly.
34
35   Properties
36       state INTEGER
37           Internal state, reflects widget modal state, for example, is set to
38           non-zero when the user performs a mouse drag action. The exact
39           meaning of "state" is defined in the descendant classes.
40
41   Events
42       Increment DELTA
43           Called when the user presses a part of a widget that is responsible
44           for incrementing or decrementing commands. DELTA is an integer
45           value, indicating how the associated value must be modified.
46
47       TrackEnd
48           Called when the user finished the mouse transaction.
49

Prima::SpinButton

51       A rectangular spin button, consists of three parts, divided
52       horizontally.  The upper and the lower parts are push-buttons
53       associated with singular increment and decrement commands. The middle
54       part, when dragged by mouse, fires "Increment" events with delta value,
55       based on a vertical position of the mouse pointer.
56

Prima::AltSpinButton

58       A rectangular spin button, consists of two push-buttons, associated
59       with singular increment and decrement command. Comparing to
60       "Prima::SpinButton", the class is less functional but has more stylish
61       look.
62

Prima::SpinEdit

64       The class is a numerical input line, paired with a spin button.  The
65       input line value can be change three ways - either as a direct
66       traditional keyboard input, or as spin button actions, or as mouse
67       wheel response. The class provides value storage and range selection
68       properties.
69
70   Properties
71       circulate BOOLEAN
72           Selects the value modification rule when the increment or decrement
73           action hits the range. If 1, the value is changed to the opposite
74           limit value ( for example, if value is 100 in range 2-100, and the
75           user clicks on 'increment' button, the value is changed to 2 ).
76
77           If 0, the value does not change.
78
79           Default value: 0
80
81       editClass STRING
82           Assigns an input line class.
83
84           Create-only property.
85
86           Default value: "Prima::InputLine"
87
88       editDelegations ARRAY
89           Assigns the input line list of delegated notifications.
90
91           Create-only property.
92
93       editProfile HASH
94           Assigns hash of properties, passed to the input line during the
95           creation.
96
97           Create-only property.
98
99       max INTEGER
100           Sets the upper limit for "value".
101
102           Default value: 100.
103
104       min INTEGER
105           Sets the lower limit for "value".
106
107           Default value: 0
108
109       pageStep INTEGER
110           Determines the multiplication factor for incrementing/decrementing
111           actions of the mouse wheel.
112
113           Default value: 10
114
115       spinClass STRING
116           Assigns a spin-button class.
117
118           Create-only property.
119
120           Default value: "Prima::AltSpinButton"
121
122       spinProfile ARRAY
123           Assigns the spin-button list of delegated notifications.
124
125           Create-only property.
126
127       spinDelegations HASH
128           Assigns hash of properties, passed to the spin-button during the
129           creation.
130
131           Create-only property.
132
133       step INTEGER
134           Determines the multiplication factor for incrementing/decrementing
135           actions of the spin-button.
136
137           Default value: 1
138
139       value INTEGER
140           Selects integer value in range from "min" to "max", reflected in
141           the input line.
142
143           Default value: 0.
144
145   Methods
146       set_bounds MIN, MAX
147           Simultaneously sets both "min" and "max" values.
148
149   Events
150       Change
151           Called when "value" is changed.
152

Prima::Gauge

154       An output-only widget class, displays a progress bar and an eventual
155       percentage string.  Useful as a progress indicator.
156
157   Properties
158       indent INTEGER
159           Selects width of a border around the widget.
160
161           Default value: 1
162
163       max INTEGER
164           Sets the upper limit for "value".
165
166           Default value: 100.
167
168       min INTEGER
169           Sets the lower limit for "value".
170
171           Default value: 0
172
173       relief INTEGER
174           Selects the style of a border around the widget. Can be one of the
175           following "gr::XXX" constants:
176
177                   gr::Sink    - 3d sunken look
178                   gr::Border  - uniform black border
179                   gr::Raise   - 3d risen look
180
181           Default value: "gr::Sink".
182
183       threshold INTEGER
184           Selects the threshold value used to determine if the changes to
185           "value" are reflected immediately or deferred until the value is
186           changed more significantly. When 0, all calls to "value" result in
187           an immediate repaint request.
188
189           Default value: 0
190
191       value INTEGER
192           Selects integer value between "min" and "max", reflected in the
193           progress bar and eventual text.
194
195           Default value: 0.
196
197       vertical BOOLEAN
198           If 1, the widget is drawn vertically, and the progress bar moves
199           from bottom to top.  If 0, the widget is drawn horizontally, and
200           the progress bar moves from left to right.
201
202           Default value: 0
203
204   Methods
205       set_bounds MIN, MAX
206           Simultaneously sets both "min" and "max" values.
207
208   Events
209       Stringify VALUE, REF
210           Converts integer VALUE into a string format and puts into REF
211           scalar reference.  Default stringifying conversion is identical to
212           "sprintf("%2d%%")" one.
213

Prima::AbstractSlider

215       The class provides basic functionality of a sliding bar, equipped with
216       tick marks. Tick marks are supposed to be drawn alongside the main
217       sliding axis or circle and provide visual feedback for the user.
218
219       The class is not usable directly.
220
221   Properties
222       autoTrack BOOLEAN
223           A boolean flag, selects the way notifications execute when the user
224           mouse-drags the sliding bar. If 1, "Change" notification is
225           executed as soon as "value" is changed. If 0, "Change" is deferred
226           until the user finished the mouse drag; instead, "Track"
227           notification is executed when the bar is moved.
228
229           This property can be used when the action, called on "Change"
230           performs very slow, so the eventual fast mouse interactions would
231           not thrash down the program.
232
233           Default value: 1
234
235       increment INTEGER
236           A step range value, used in "scheme" for marking the key ticks.
237           See scheme for details.
238
239           Default value: 10
240
241       max INTEGER
242           Sets the upper limit for "value".
243
244           Default value: 100.
245
246       min INTEGER
247           Sets the lower limit for "value".
248
249           Default value: 0
250
251       readOnly BOOLEAN
252           If 1, the use cannot change the value by moving the bar or
253           otherwise.
254
255           Default value: 0
256
257       ticks ARRAY
258           Selects the tick marks representation along the sliding axis or
259           circle.  ARRAY consists of hashes, each for one tick. The hash must
260           contain at least "value" key, with integer value. The two
261           additional keys, "height" and "text", select the height of a tick
262           mark in pixels and the text drawn near the mark, correspondingly.
263
264           If ARRAY is "undef", no ticks are drawn.
265
266       scheme INTEGER
267           "scheme" is a property, that creates a set of tick marks using one
268           of the predefined scale designs, selected by "ss::XXX" constants.
269           Each constant produces different scale; some make use of
270           "increment" integer property, which selects a step by which the
271           additional text marks are drawn. As an example, "ss::Thermometer"
272           design with default "min", "max", and "increment" values would look
273           like that:
274
275                   0   10   20        100
276                   |    |    |          |
277                   |||||||||||||||....|||
278
279           The module defines the following constants:
280
281                   ss::Axis           - 5 minor ticks per increment
282                   ss::Gauge          - 1 tick per increment
283                   ss::StdMinMax      - 2 ticks at the ends of the bar
284                   ss::Thermometer    - 10 minor ticks per increment, longer text ticks
285
286           When "tick" property is set, "scheme" is reset to "undef".
287
288       snap BOOLEAN
289           If 1, "value" cannot accept values that are not on the tick scale.
290           When set such a value, it is rounded to the closest tick mark.  If
291           0, "value" can accept any integer value in range from "min" to
292           "max".
293
294           Default value: 0
295
296       step INTEGER
297           Integer delta for singular increment / decrement commands and a
298           threshold for "value" when "snap" value is 0.
299
300           Default value: 1
301
302       value INTEGER
303           Selects integer value between "min" and "max" and the corresponding
304           sliding bar position.
305
306           Default value: 0.
307
308   Events
309       Change
310           Called when "value" value is changed, with one exception: if the
311           user moves the sliding bar while "autoTrack" is 0, "Track"
312           notification is called instead.
313
314       Track
315           Called when the user moves the sliding bar while "autoTrack" value
316           is 0; this notification is a substitute to "Change".
317

Prima::Slider

319       Presents a linear sliding bar, movable along a linear shaft.
320
321   Properties
322       borderWidth INTEGER
323           In horizontal mode, sets extra margin space between the slider line
324           and the widget boundaries. Can be used for fine tuning of
325           displaying text labels from <ticks()>, where the default spacing
326           (0) or spacing procedure (drop overlapping labels) is not enough.
327
328       ribbonStrip BOOLEAN
329           If 1, the parts of shaft are painted with different colors, to
330           increase visual feedback. If 0, the shaft is painted with single
331           default background color.
332
333           Default value: 0
334
335       shaftBreadth INTEGER
336           Breadth of the shaft in pixels.
337
338           Default value: 6
339
340       tickAlign INTEGER
341           One of "tka::XXX" constants, that correspond to the situation of
342           tick marks:
343
344                   tka::Normal        - ticks are drawn on the left or on the top of the shaft
345                   tka::Alternative   - ticks are drawn on the right or at the bottom of the shaft
346                   tka::Dual          - ticks are drawn both ways
347
348           The ticks orientation ( left or top, right or bottom ) is dependant
349           on "vertical" property value.
350
351           Default value: "tka::Normal"
352
353       vertical BOOLEAN
354           If 1, the widget is drawn vertically, and the slider moves from
355           bottom to top.  If 0, the widget is drawn horizontally, and the
356           slider moves from left to right.
357
358           Default value: 0
359
360   Methods
361       pos2info X, Y
362           Translates integer coordinates pair ( X, Y ) into the value
363           corresponding to the scale, and returns three scalars:
364
365           info INTEGER
366               If "undef", the user-driven positioning is not possible ( "min"
367               equals to "max" ).
368
369               If 1, the point is located on the slider.
370
371               If 0, the point is outside the slider.
372
373           value INTEGER
374               If "info" is 0 or 1, contains the corresponding "value".
375
376           aperture INTEGER
377               Offset in pixels along the shaft axis.
378

Prima::CircularSlider

380       Presents a slider widget with the dial and two increment / decrement
381       buttons.  The tick marks are drawn around the perimeter of the dial;
382       current value is displayed in the center of the dial.
383
384   Properties
385       buttons BOOLEAN
386           If 1, the increment / decrement buttons are shown at the bottom of
387           the dial, and the user can change the value either by the dial or
388           by the buttons.  If 0, the buttons are not shown.
389
390           Default values: 0
391
392       stdPointer BOOLEAN
393           Determines the style of a value indicator ( pointer ) on the dial.
394           If 1, it is drawn as a black triangular mark.  If 0, it is drawn as
395           a small circular knob.
396
397           Default value: 0
398
399   Methods
400       offset2data VALUE
401           Converts integer value in range from "min" to "max" into the
402           corresponding angle, and return two real values: cosine and sine of
403           the angle.
404
405       offset2pt X, Y, VALUE, RADIUS
406           Converts integer value in range from "min" to "max" into the point
407           coordinates, with the RADIUS and dial center coordinates X and Y.
408           Return the calculated point coordinates as two integers in (X,Y)
409           format.
410
411       xy2val X, Y
412           Converts widget coordinates X and Y into value in range from "min"
413           to "max", and return two scalars: the value and the boolean flag,
414           which is set to 1 if the (X,Y) point is inside the dial circle, and
415           0 otherwise.
416
417   Events
418       Stringify VALUE, REF
419           Converts integer VALUE into a string format and puts into REF
420           scalar reference.  The resulting string is displayed in the center
421           of the dial.
422
423           Default conversion routine simply copies VALUE to REF as is.
424

AUTHOR

426       Dmitry Karasik, <dmitry@karasik.eu.org>, Anton Berezin
427       <tobez@tobez.org>.
428

SEE ALSO

430       Prima, examples/fontdlg.pl
431
432
433
434perl v5.32.0                      2020-07-28                 Prima::Sliders(3)
Impressum