1Prima::Sliders(3) User Contributed Perl Documentation Prima::Sliders(3)
2
6 Prima::Sliders - sliding bars, spin buttons and input lines, dial
7 widget etc.
8
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 Prima::AbstractSpinButton
15 Prima::SpinButton
16 Prima::AltSpinButton
17 Prima::SpinEdit
19 Prima::Gauge
21 Prima::PrigressBar
22 Prima::AbstractSlider
24 Prima::Slider
25 Prima::CircularSlider
26
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 The class is not usable directly.
35 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 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 TrackEnd
49 Called when the user finished the mouse transaction.
50
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
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
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 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 If 0, the value does not change.
79 Default value: 0
81 editClass STRING
83 Assigns an input line class.
84 Create-only property.
86 Default value: "Prima::InputLine"
88 editDelegations ARRAY
90 Assigns the input line list of delegated notifications.
91 Create-only property.
93 editProfile HASH
95 Assigns hash of properties, passed to the input line during the
96 creation.
97 Create-only property.
99 max INTEGER
101 Sets the upper limit for "value".
102 Default value: 100.
104 min INTEGER
106 Sets the lower limit for "value".
107 Default value: 0
109 pageStep INTEGER
111 Determines the multiplication factor for incrementing/decrementing
112 actions of the mouse wheel.
113 Default value: 10
115 spinClass STRING
117 Assigns a spin-button class.
118 Create-only property.
120 Default value: "Prima::AltSpinButton"
122 spinProfile ARRAY
124 Assigns the spin-button list of delegated notifications.
125 Create-only property.
127 spinDelegations HASH
129 Assigns hash of properties, passed to the spin-button during the
130 creation.
131 Create-only property.
133 step INTEGER
135 Determines the multiplication factor for incrementing/decrementing
136 actions of the spin-button.
137 Default value: 1
139 value INTEGER
141 Selects integer value in range from "min" to "max", reflected in
142 the input line.
143 Default value: 0.
145 Methods
147 set_bounds MIN, MAX
148 Simultaneously sets both "min" and "max" values.
149 Events
151 Change
152 Called when "value" is changed.
153
155 An output-only widget class, displays a progress bar and an eventual
156 percentage string. Useful as a progress indicator.
157 Properties
159 indent INTEGER
160 Selects width of a border around the widget.
161 Default value: 1
163 max INTEGER
165 Sets the upper limit for "value".
166 Default value: 100.
168 min INTEGER
170 Sets the lower limit for "value".
171 Default value: 0
173 relief INTEGER
175 Selects the style of a border around the widget. Can be one of the
176 following "gr::XXX" constants:
177 gr::Sink - 3d sunken look
179 gr::Border - uniform black border
180 gr::Raise - 3d risen look
181 Default value: "gr::Sink".
183 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 Default value: 0
191 value INTEGER
193 Selects integer value between "min" and "max", reflected in the
194 progress bar and eventual text.
195 Default value: 0.
197 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 Default value: 0
204 Methods
206 set_bounds MIN, MAX
207 Simultaneously sets both "min" and "max" values.
208 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
216 Displays a progress bar
217 Properties
219 max INTEGER
220 Sets the upper limit for "value".
221 Default value: 100.
223 min INTEGER
225 Sets the lower limit for "value".
226 Default value: 0
228 value INTEGER
230 Selects integer value between "min" and "max", reflected in the
231 progress bar and eventual text.
232 Default value: 0.
234 Methods
236 set_bounds MIN, MAX
237 Simultaneously sets both "min" and "max" values.
238
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 The class is not usable directly.
245 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 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 Default value: 1
259 increment INTEGER
261 A step range value, used in "scheme" for marking the key ticks.
262 See scheme for details.
263 Default value: 10
265 max INTEGER
267 Sets the upper limit for "value".
268 Default value: 100.
270 min INTEGER
272 Sets the lower limit for "value".
273 Default value: 0
275 readOnly BOOLEAN
277 If 1, the use cannot change the value by moving the bar or
278 otherwise.
279 Default value: 0
281 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 If ARRAY is "undef", no ticks are drawn.
290 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 0 10 20 100
301 | | | |
302 |||||||||||||||....|||
303 The module defines the following constants:
305 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 When "tick" property is set, "scheme" is reset to "undef".
312 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 Default value: 0
320 step INTEGER
322 Integer delta for singular increment / decrement commands and a
323 threshold for "value" when "snap" value is 0.
324 Default value: 1
326 value INTEGER
328 Selects integer value between "min" and "max" and the corresponding
329 sliding bar position.
330 Default value: 0.
332 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 Track
340 Called when the user moves the sliding bar while "autoTrack" value
341 is 0; this notification is a substitute to "Change".
342
344 Presents a linear sliding bar, movable along a linear shaft.
345 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 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 Default value: 0
359 shaftBreadth INTEGER
361 Breadth of the shaft in pixels.
362 Default value: 6
364 tickAlign INTEGER
366 One of "tka::XXX" constants, that correspond to the situation of
367 tick marks:
368 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 The ticks orientation ( left or top, right or bottom ) is dependant
374 on "vertical" property value.
375 Default value: "tka::Normal"
377 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 Default value: 0
384 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 info INTEGER
391 If "undef", the user-driven positioning is not possible ( "min"
392 equals to "max" ).
393 If 1, the point is located on the slider.
395 If 0, the point is outside the slider.
397 value INTEGER
399 If "info" is 0 or 1, contains the corresponding "value".
400 aperture INTEGER
402 Offset in pixels along the shaft axis.
403
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 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 Default values: 0
416 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 Default value: 0
423 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 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 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 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 Default conversion routine simply copies VALUE to REF as is.
449
451 Dmitry Karasik, <dmitry@karasik.eu.org>, Anton Berezin
452 <tobez@tobez.org>.
453
455 Prima, examples/fontdlg.pl
456perl v5.34.1 2022-04-20 Prima::Sliders(3)