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::AbstractSlider
23 Prima::Slider
24 Prima::CircularSlider
25
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 The class is not usable directly.
34 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 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 TrackEnd
48 Called when the user finished the mouse transaction.
49
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
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
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 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 If 0, the value does not change.
78 Default value: 0
80 editClass STRING
82 Assigns an input line class.
83 Create-only property.
85 Default value: "Prima::InputLine"
87 editDelegations ARRAY
89 Assigns the input line list of delegated notifications.
90 Create-only property.
92 editProfile HASH
94 Assigns hash of properties, passed to the input line during the
95 creation.
96 Create-only property.
98 max INTEGER
100 Sets the upper limit for "value".
101 Default value: 100.
103 min INTEGER
105 Sets the lower limit for "value".
106 Default value: 0
108 pageStep INTEGER
110 Determines the multiplication factor for incrementing/decrementing
111 actions of the mouse wheel.
112 Default value: 10
114 spinClass STRING
116 Assigns a spin-button class.
117 Create-only property.
119 Default value: "Prima::AltSpinButton"
121 spinProfile ARRAY
123 Assigns the spin-button list of delegated notifications.
124 Create-only property.
126 spinDelegations HASH
128 Assigns hash of properties, passed to the spin-button during the
129 creation.
130 Create-only property.
132 step INTEGER
134 Determines the multiplication factor for incrementing/decrementing
135 actions of the spin-button.
136 Default value: 1
138 value INTEGER
140 Selects integer value in range from "min" to "max", reflected in
141 the input line.
142 Default value: 0.
144 Methods
146 set_bounds MIN, MAX
147 Simultaneously sets both "min" and "max" values.
148 Events
150 Change
151 Called when "value" is changed.
152
154 An output-only widget class, displays a progress bar and an eventual
155 percentage string. Useful as a progress indicator.
156 Properties
158 indent INTEGER
159 Selects width of a border around the widget.
160 Default value: 1
162 max INTEGER
164 Sets the upper limit for "value".
165 Default value: 100.
167 min INTEGER
169 Sets the lower limit for "value".
170 Default value: 0
172 relief INTEGER
174 Selects the style of a border around the widget. Can be one of the
175 following "gr::XXX" constants:
176 gr::Sink - 3d sunken look
178 gr::Border - uniform black border
179 gr::Raise - 3d risen look
180 Default value: "gr::Sink".
182 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 Default value: 0
190 value INTEGER
192 Selects integer value between "min" and "max", reflected in the
193 progress bar and eventual text.
194 Default value: 0.
196 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 Default value: 0
203 Methods
205 set_bounds MIN, MAX
206 Simultaneously sets both "min" and "max" values.
207 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
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 The class is not usable directly.
220 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 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 Default value: 1
234 increment INTEGER
236 A step range value, used in "scheme" for marking the key ticks.
237 See scheme for details.
238 Default value: 10
240 max INTEGER
242 Sets the upper limit for "value".
243 Default value: 100.
245 min INTEGER
247 Sets the lower limit for "value".
248 Default value: 0
250 readOnly BOOLEAN
252 If 1, the use cannot change the value by moving the bar or
253 otherwise.
254 Default value: 0
256 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 If ARRAY is "undef", no ticks are drawn.
265 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 0 10 20 100
276 | | | |
277 |||||||||||||||....|||
278 The module defines the following constants:
280 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 When "tick" property is set, "scheme" is reset to "undef".
287 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 Default value: 0
295 step INTEGER
297 Integer delta for singular increment / decrement commands and a
298 threshold for "value" when "snap" value is 0.
299 Default value: 1
301 value INTEGER
303 Selects integer value between "min" and "max" and the corresponding
304 sliding bar position.
305 Default value: 0.
307 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 Track
315 Called when the user moves the sliding bar while "autoTrack" value
316 is 0; this notification is a substitute to "Change".
317
319 Presents a linear sliding bar, movable along a linear shaft.
320 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 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 Default value: 0
334 shaftBreadth INTEGER
336 Breadth of the shaft in pixels.
337 Default value: 6
339 tickAlign INTEGER
341 One of "tka::XXX" constants, that correspond to the situation of
342 tick marks:
343 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 The ticks orientation ( left or top, right or bottom ) is dependant
349 on "vertical" property value.
350 Default value: "tka::Normal"
352 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 Default value: 0
359 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 info INTEGER
366 If "undef", the user-driven positioning is not possible ( "min"
367 equals to "max" ).
368 If 1, the point is located on the slider.
370 If 0, the point is outside the slider.
372 value INTEGER
374 If "info" is 0 or 1, contains the corresponding "value".
375 aperture INTEGER
377 Offset in pixels along the shaft axis.
378
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 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 Default values: 0
391 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 Default value: 0
398 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 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 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 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 Default conversion routine simply copies VALUE to REF as is.
424
426 Dmitry Karasik, <dmitry@karasik.eu.org>, Anton Berezin
427 <tobez@tobez.org>.
428
430 Prima, examples/fontdlg.pl
431perl v5.28.1 2019-02-02 Prima::Sliders(3)