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 allowEmpty BOOLEAN
73 If set, allows an empty string as a valid value
74 Default value: false
76 circulate BOOLEAN
78 Selects the value modification rule when the increment or decrement
79 action hits the range. If 1, the value is changed to the opposite
80 limit value ( for example, if value is 100 in range 2-100, and the
81 user clicks on 'increment' button, the value is changed to 2 ).
82 If 0, the value does not change.
84 Default value: 0
86 editClass STRING
88 Assigns an input line class.
89 Create-only property.
91 Default value: "Prima::InputLine"
93 editDelegations ARRAY
95 Assigns the input line list of delegated notifications.
96 Create-only property.
98 editProfile HASH
100 Assigns hash of properties, passed to the input line during the
101 creation.
102 Create-only property.
104 max INTEGER
106 Sets the upper limit for "value".
107 Default value: 100.
109 min INTEGER
111 Sets the lower limit for "value".
112 Default value: 0
114 pageStep INTEGER
116 Determines the multiplication factor for incrementing/decrementing
117 actions of the mouse wheel.
118 Default value: 10
120 spinClass STRING
122 Assigns a spin-button class.
123 Create-only property.
125 Default value: "Prima::AltSpinButton"
127 spinProfile ARRAY
129 Assigns the spin-button list of delegated notifications.
130 Create-only property.
132 spinDelegations HASH
134 Assigns hash of properties, passed to the spin-button during the
135 creation.
136 Create-only property.
138 step INTEGER
140 Determines the multiplication factor for incrementing/decrementing
141 actions of the spin-button.
142 Default value: 1
144 value INTEGER
146 Selects integer value in range from "min" to "max", reflected in
147 the input line.
148 Default value: 0.
150 Methods
152 set_bounds MIN, MAX
153 Simultaneously sets both "min" and "max" values.
154 Events
156 Change
157 Called when "value" is changed.
158
160 An output-only widget class, displays a progress bar and an eventual
161 percentage string. Useful as a progress indicator.
162 Properties
164 indent INTEGER
165 Selects width of a border around the widget.
166 Default value: 1
168 max INTEGER
170 Sets the upper limit for "value".
171 Default value: 100.
173 min INTEGER
175 Sets the lower limit for "value".
176 Default value: 0
178 relief INTEGER
180 Selects the style of a border around the widget. Can be one of the
181 following "gr::XXX" constants:
182 gr::Sink - 3d sunken look
184 gr::Border - uniform black border
185 gr::Raise - 3d risen look
186 Default value: "gr::Sink".
188 threshold INTEGER
190 Selects the threshold value used to determine if the changes to
191 "value" are reflected immediately or deferred until the value is
192 changed more significantly. When 0, all calls to "value" result in
193 an immediate repaint request.
194 Default value: 0
196 value INTEGER
198 Selects integer value between "min" and "max", reflected in the
199 progress bar and eventual text.
200 Default value: 0.
202 vertical BOOLEAN
204 If 1, the widget is drawn vertically, and the progress bar moves
205 from bottom to top. If 0, the widget is drawn horizontally, and
206 the progress bar moves from left to right.
207 Default value: 0
209 Methods
211 set_bounds MIN, MAX
212 Simultaneously sets both "min" and "max" values.
213 Events
215 Stringify VALUE, REF
216 Converts integer VALUE into a string format and puts into REF
217 scalar reference. Default stringifying conversion is identical to
218 sprintf("%2d%%") one.
219
221 Displays a progress bar
222 Properties
224 max INTEGER
225 Sets the upper limit for "value".
226 Default value: 100.
228 min INTEGER
230 Sets the lower limit for "value".
231 Default value: 0
233 value INTEGER
235 Selects integer value between "min" and "max", reflected in the
236 progress bar and eventual text.
237 Default value: 0.
239 Methods
241 set_bounds MIN, MAX
242 Simultaneously sets both "min" and "max" values.
243
245 The class provides basic functionality of a sliding bar, equipped with
246 tick marks. Tick marks are supposed to be drawn alongside the main
247 sliding axis or circle and provide visual feedback for the user.
248 The class is not usable directly.
250 Properties
252 autoTrack BOOLEAN
253 A boolean flag, selects the way notifications execute when the user
254 mouse-drags the sliding bar. If 1, "Change" notification is
255 executed as soon as "value" is changed. If 0, "Change" is deferred
256 until the user finished the mouse drag; instead, "Track"
257 notification is executed when the bar is moved.
258 This property can be used when the action, called on "Change"
260 performs very slow, so the eventual fast mouse interactions would
261 not thrash down the program.
262 Default value: 1
264 increment INTEGER
266 A step range value, used in "scheme" for marking the key ticks.
267 See scheme for details.
268 Default value: 10
270 max INTEGER
272 Sets the upper limit for "value".
273 Default value: 100.
275 min INTEGER
277 Sets the lower limit for "value".
278 Default value: 0
280 readOnly BOOLEAN
282 If 1, the use cannot change the value by moving the bar or
283 otherwise.
284 Default value: 0
286 ticks ARRAY
288 Selects the tick marks representation along the sliding axis or
289 circle. ARRAY consists of hashes, each for one tick. The hash must
290 contain at least "value" key, with integer value. The two
291 additional keys, "height" and "text", select the height of a tick
292 mark in pixels and the text drawn near the mark, correspondingly.
293 If ARRAY is "undef", no ticks are drawn.
295 scheme INTEGER
297 "scheme" is a property, that creates a set of tick marks using one
298 of the predefined scale designs, selected by "ss::XXX" constants.
299 Each constant produces different scale; some make use of
300 "increment" integer property, which selects a step by which the
301 additional text marks are drawn. As an example, "ss::Thermometer"
302 design with default "min", "max", and "increment" values would look
303 like that:
304 0 10 20 100
306 | | | |
307 |||||||||||||||....|||
308 The module defines the following constants:
310 ss::Axis - 5 minor ticks per increment
312 ss::Gauge - 1 tick per increment
313 ss::StdMinMax - 2 ticks at the ends of the bar
314 ss::Thermometer - 10 minor ticks per increment, longer text ticks
315 When "tick" property is set, "scheme" is reset to "undef".
317 snap BOOLEAN
319 If 1, "value" cannot accept values that are not on the tick scale.
320 When set such a value, it is rounded to the closest tick mark. If
321 0, "value" can accept any integer value in range from "min" to
322 "max".
323 Default value: 0
325 step INTEGER
327 Integer delta for singular increment / decrement commands and a
328 threshold for "value" when "snap" value is 0.
329 Default value: 1
331 value INTEGER
333 Selects integer value between "min" and "max" and the corresponding
334 sliding bar position.
335 Default value: 0.
337 Events
339 Change
340 Called when "value" value is changed, with one exception: if the
341 user moves the sliding bar while "autoTrack" is 0, "Track"
342 notification is called instead.
343 Track
345 Called when the user moves the sliding bar while "autoTrack" value
346 is 0; this notification is a substitute to "Change".
347
349 Presents a linear sliding bar, movable along a linear shaft.
350 Properties
352 borderWidth INTEGER
353 In horizontal mode, sets extra margin space between the slider line
354 and the widget boundaries. Can be used for fine tuning of
355 displaying text labels from <ticks()>, where the default spacing
356 (0) or spacing procedure (drop overlapping labels) is not enough.
357 ribbonStrip BOOLEAN
359 If 1, the parts of shaft are painted with different colors, to
360 increase visual feedback. If 0, the shaft is painted with single
361 default background color.
362 Default value: 0
364 shaftBreadth INTEGER
366 Breadth of the shaft in pixels.
367 Default value: 6
369 tickAlign INTEGER
371 One of "tka::XXX" constants, that correspond to the situation of
372 tick marks:
373 tka::Normal - ticks are drawn on the left or on the top of the shaft
375 tka::Alternative - ticks are drawn on the right or at the bottom of the shaft
376 tka::Dual - ticks are drawn both ways
377 The ticks orientation ( left or top, right or bottom ) is dependant
379 on "vertical" property value.
380 Default value: "tka::Normal"
382 vertical BOOLEAN
384 If 1, the widget is drawn vertically, and the slider moves from
385 bottom to top. If 0, the widget is drawn horizontally, and the
386 slider moves from left to right.
387 Default value: 0
389 Methods
391 pos2info X, Y
392 Translates integer coordinates pair ( X, Y ) into the value
393 corresponding to the scale, and returns three scalars:
394 info INTEGER
396 If "undef", the user-driven positioning is not possible ( "min"
397 equals to "max" ).
398 If 1, the point is located on the slider.
400 If 0, the point is outside the slider.
402 value INTEGER
404 If "info" is 0 or 1, contains the corresponding "value".
405 aperture INTEGER
407 Offset in pixels along the shaft axis.
408
410 Presents a slider widget with the dial and two increment / decrement
411 buttons. The tick marks are drawn around the perimeter of the dial;
412 current value is displayed in the center of the dial.
413 Properties
415 buttons BOOLEAN
416 If 1, the increment / decrement buttons are shown at the bottom of
417 the dial, and the user can change the value either by the dial or
418 by the buttons. If 0, the buttons are not shown.
419 Default values: 0
421 stdPointer BOOLEAN
423 Determines the style of a value indicator ( pointer ) on the dial.
424 If 1, it is drawn as a black triangular mark. If 0, it is drawn as
425 a small circular knob.
426 Default value: 0
428 Methods
430 offset2data VALUE
431 Converts integer value in range from "min" to "max" into the
432 corresponding angle, and return two real values: cosine and sine of
433 the angle.
434 offset2pt X, Y, VALUE, RADIUS
436 Converts integer value in range from "min" to "max" into the point
437 coordinates, with the RADIUS and dial center coordinates X and Y.
438 Return the calculated point coordinates as two integers in (X,Y)
439 format.
440 xy2val X, Y
442 Converts widget coordinates X and Y into value in range from "min"
443 to "max", and return two scalars: the value and the boolean flag,
444 which is set to 1 if the (X,Y) point is inside the dial circle, and
445 0 otherwise.
446 Events
448 Stringify VALUE, REF
449 Converts integer VALUE into a string format and puts into REF
450 scalar reference. The resulting string is displayed in the center
451 of the dial.
452 Default conversion routine simply copies VALUE to REF as is.
454
456 Dmitry Karasik, <dmitry@karasik.eu.org>, Anton Berezin
457 <tobez@tobez.org>.
458
460 Prima, examples/fontdlg.pl
461perl v5.38.0 2023-07-21 Prima::Sliders(3)