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               Prima::PrigressBar
22
23               Prima::AbstractSlider
24                       Prima::Slider
25                       Prima::CircularSlider
26

Prima::AbstractSpinButton

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

Prima::SpinButton

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

Prima::AltSpinButton

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

Prima::SpinEdit

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

Prima::Gauge

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

Prima::ProgressBar

216       Displays a progress bar
217
218   Properties
219       max INTEGER
220           Sets the upper limit for "value".
221
222           Default value: 100.
223
224       min INTEGER
225           Sets the lower limit for "value".
226
227           Default value: 0
228
229       value INTEGER
230           Selects integer value between "min" and "max", reflected in the
231           progress bar and eventual text.
232
233           Default value: 0.
234
235   Methods
236       set_bounds MIN, MAX
237           Simultaneously sets both "min" and "max" values.
238

Prima::AbstractSlider

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

Prima::Slider

344       Presents a linear sliding bar, movable along a linear shaft.
345
346   Properties
347       borderWidth INTEGER
348           In horizontal mode, sets extra margin space between the slider line
349           and the widget boundaries. Can be used for fine tuning of
350           displaying text labels from <ticks()>, where the default spacing
351           (0) or spacing procedure (drop overlapping labels) is not enough.
352
353       ribbonStrip BOOLEAN
354           If 1, the parts of shaft are painted with different colors, to
355           increase visual feedback. If 0, the shaft is painted with single
356           default background color.
357
358           Default value: 0
359
360       shaftBreadth INTEGER
361           Breadth of the shaft in pixels.
362
363           Default value: 6
364
365       tickAlign INTEGER
366           One of "tka::XXX" constants, that correspond to the situation of
367           tick marks:
368
369                   tka::Normal        - ticks are drawn on the left or on the top of the shaft
370                   tka::Alternative   - ticks are drawn on the right or at the bottom of the shaft
371                   tka::Dual          - ticks are drawn both ways
372
373           The ticks orientation ( left or top, right or bottom ) is dependant
374           on "vertical" property value.
375
376           Default value: "tka::Normal"
377
378       vertical BOOLEAN
379           If 1, the widget is drawn vertically, and the slider moves from
380           bottom to top.  If 0, the widget is drawn horizontally, and the
381           slider moves from left to right.
382
383           Default value: 0
384
385   Methods
386       pos2info X, Y
387           Translates integer coordinates pair ( X, Y ) into the value
388           corresponding to the scale, and returns three scalars:
389
390           info INTEGER
391               If "undef", the user-driven positioning is not possible ( "min"
392               equals to "max" ).
393
394               If 1, the point is located on the slider.
395
396               If 0, the point is outside the slider.
397
398           value INTEGER
399               If "info" is 0 or 1, contains the corresponding "value".
400
401           aperture INTEGER
402               Offset in pixels along the shaft axis.
403

Prima::CircularSlider

405       Presents a slider widget with the dial and two increment / decrement
406       buttons.  The tick marks are drawn around the perimeter of the dial;
407       current value is displayed in the center of the dial.
408
409   Properties
410       buttons BOOLEAN
411           If 1, the increment / decrement buttons are shown at the bottom of
412           the dial, and the user can change the value either by the dial or
413           by the buttons.  If 0, the buttons are not shown.
414
415           Default values: 0
416
417       stdPointer BOOLEAN
418           Determines the style of a value indicator ( pointer ) on the dial.
419           If 1, it is drawn as a black triangular mark.  If 0, it is drawn as
420           a small circular knob.
421
422           Default value: 0
423
424   Methods
425       offset2data VALUE
426           Converts integer value in range from "min" to "max" into the
427           corresponding angle, and return two real values: cosine and sine of
428           the angle.
429
430       offset2pt X, Y, VALUE, RADIUS
431           Converts integer value in range from "min" to "max" into the point
432           coordinates, with the RADIUS and dial center coordinates X and Y.
433           Return the calculated point coordinates as two integers in (X,Y)
434           format.
435
436       xy2val X, Y
437           Converts widget coordinates X and Y into value in range from "min"
438           to "max", and return two scalars: the value and the boolean flag,
439           which is set to 1 if the (X,Y) point is inside the dial circle, and
440           0 otherwise.
441
442   Events
443       Stringify VALUE, REF
444           Converts integer VALUE into a string format and puts into REF
445           scalar reference.  The resulting string is displayed in the center
446           of the dial.
447
448           Default conversion routine simply copies VALUE to REF as is.
449

AUTHOR

451       Dmitry Karasik, <dmitry@karasik.eu.org>, Anton Berezin
452       <tobez@tobez.org>.
453

SEE ALSO

455       Prima, examples/fontdlg.pl
456
457
458
459perl v5.32.1                      2021-01-27                 Prima::Sliders(3)
Impressum