.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Prima::Sliders 3" .TH Prima::Sliders 3 "2009-02-24" "perl v5.20.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Prima::Sliders \- sliding bars, spin buttons and input lines, dial widget etc. .SH "DESCRIPTION" .IX Header "DESCRIPTION" The module is a set of widget classes, with one common property; \- all of these provide input and / or output of an integer value. This property unites the following set of class hierarchies: .PP .Vb 3 \& Prima::AbstractSpinButton \& Prima::SpinButton \& Prima::AltSpinButton \& \& Prima::SpinEdit \& \& Prima::Gauge \& \& Prima::AbstractSlider \& Prima::Slider \& Prima::CircularSlider .Ve .SH "Prima::AbstractSpinButton" .IX Header "Prima::AbstractSpinButton" Provides a generic interface to spin-button class functionality, which includes range definition properties and events. Neither \f(CW\*(C`Prima::AbstractSpinButton\*(C'\fR, nor its descendants store the integer value. These provide a mere possibility for the user to send incrementing or decrementing commands. .PP The class is not usable directly. .SS "Properties" .IX Subsection "Properties" .IP "state \s-1INTEGER\s0" 4 .IX Item "state INTEGER" Internal state, reflects widget modal state, for example, is set to non-zero when the user performs a mouse drag action. The exact meaning of \f(CW\*(C`state\*(C'\fR is defined in the descendant classes. .SS "Events" .IX Subsection "Events" .IP "Increment \s-1DELTA\s0" 4 .IX Item "Increment DELTA" Called when the user presses a part of a widget that is responsible for incrementing or decrementing commands. \s-1DELTA\s0 is an integer value, indicating how the associated value must be modified. .IP "TrackEnd" 4 .IX Item "TrackEnd" Called when the user finished the mouse transaction. .SH "Prima::SpinButton" .IX Header "Prima::SpinButton" A rectangular spin button, consists of three parts, divided horizontally. The upper and the lower parts are push-buttons associated with singular increment and decrement commands. The middle part, when dragged by mouse, fires \f(CW\*(C`Increment\*(C'\fR events with delta value, based on a vertical position of the mouse pointer. .SH "Prima::AltSpinButton" .IX Header "Prima::AltSpinButton" A rectangular spin button, consists of two push-buttons, associated with singular increment and decrement command. Comparing to \f(CW\*(C`Prima::SpinButton\*(C'\fR, the class is less functional but has more stylish look. .SH "Prima::SpinEdit" .IX Header "Prima::SpinEdit" The class is a numerical input line, paired with a spin button. The input line value can be change three ways \- either as a direct traditional keyboard input, or as spin button actions, or as mouse wheel response. The class provides value storage and range selection properties. .SS "Properties" .IX Subsection "Properties" .IP "circulate \s-1BOOLEAN\s0" 4 .IX Item "circulate BOOLEAN" Selects the value modification rule when the increment or decrement action hits the range. If 1, the value is changed to the opposite limit value ( for example, if value is 100 in range 2\-100, and the user clicks on 'increment' button, the value is changed to 2 ). .Sp If 0, the value does not change. .Sp Default value: 0 .IP "editClass \s-1STRING\s0" 4 .IX Item "editClass STRING" Assigns an input line class. .Sp Create-only property. .Sp Default value: \f(CW\*(C`Prima::InputLine\*(C'\fR .IP "editDelegations \s-1ARRAY\s0" 4 .IX Item "editDelegations ARRAY" Assigns the input line list of delegated notifications. .Sp Create-only property. .IP "editProfile \s-1HASH\s0" 4 .IX Item "editProfile HASH" Assigns hash of properties, passed to the input line during the creation. .Sp Create-only property. .IP "max \s-1INTEGER\s0" 4 .IX Item "max INTEGER" Sets the upper limit for \f(CW\*(C`value\*(C'\fR. .Sp Default value: 100. .IP "min \s-1INTEGER\s0" 4 .IX Item "min INTEGER" Sets the lower limit for \f(CW\*(C`value\*(C'\fR. .Sp Default value: 0 .IP "pageStep \s-1INTEGER\s0" 4 .IX Item "pageStep INTEGER" Determines the multiplication factor for incrementing/decrementing actions of the mouse wheel. .Sp Default value: 10 .IP "spinClass \s-1STRING\s0" 4 .IX Item "spinClass STRING" Assigns a spin-button class. .Sp Create-only property. .Sp Default value: \f(CW\*(C`Prima::AltSpinButton\*(C'\fR .IP "spinProfile \s-1ARRAY\s0" 4 .IX Item "spinProfile ARRAY" Assigns the spin-button list of delegated notifications. .Sp Create-only property. .IP "spinDelegations \s-1HASH\s0" 4 .IX Item "spinDelegations HASH" Assigns hash of properties, passed to the spin-button during the creation. .Sp Create-only property. .IP "step \s-1INTEGER\s0" 4 .IX Item "step INTEGER" Determines the multiplication factor for incrementing/decrementing actions of the spin-button. .Sp Default value: 1 .IP "value \s-1INTEGER\s0" 4 .IX Item "value INTEGER" Selects integer value in range from \f(CW\*(C`min\*(C'\fR to \f(CW\*(C`max\*(C'\fR, reflected in the input line. .Sp Default value: 0. .SS "Methods" .IX Subsection "Methods" .IP "set_bounds \s-1MIN, MAX\s0" 4 .IX Item "set_bounds MIN, MAX" Simultaneously sets both \f(CW\*(C`min\*(C'\fR and \f(CW\*(C`max\*(C'\fR values. .SS "Events" .IX Subsection "Events" .IP "Change" 4 .IX Item "Change" Called when \f(CW\*(C`value\*(C'\fR is changed. .SH "Prima::Gauge" .IX Header "Prima::Gauge" An output-only widget class, displays a progress bar and an eventual percentage string. Useful as a progress indicator. .SS "Properties" .IX Subsection "Properties" .IP "indent \s-1INTEGER\s0" 4 .IX Item "indent INTEGER" Selects width of a border around the widget. .Sp Default value: 1 .IP "max \s-1INTEGER\s0" 4 .IX Item "max INTEGER" Sets the upper limit for \f(CW\*(C`value\*(C'\fR. .Sp Default value: 100. .IP "min \s-1INTEGER\s0" 4 .IX Item "min INTEGER" Sets the lower limit for \f(CW\*(C`value\*(C'\fR. .Sp Default value: 0 .IP "relief \s-1INTEGER\s0" 4 .IX Item "relief INTEGER" Selects the style of a border around the widget. Can be one of the following \f(CW\*(C`gr::XXX\*(C'\fR constants: .Sp .Vb 3 \& gr::Sink \- 3d sunken look \& gr::Border \- uniform black border \& gr::Raise \- 3d risen look .Ve .Sp Default value: \f(CW\*(C`gr::Sink\*(C'\fR. .IP "threshold \s-1INTEGER\s0" 4 .IX Item "threshold INTEGER" Selects the threshold value used to determine if the changes to \f(CW\*(C`value\*(C'\fR are reflected immediately or deferred until the value is changed more significantly. When 0, all calls to \f(CW\*(C`value\*(C'\fR result in an immediate repaint request. .Sp Default value: 0 .IP "value \s-1INTEGER\s0" 4 .IX Item "value INTEGER" Selects integer value between \f(CW\*(C`min\*(C'\fR and \f(CW\*(C`max\*(C'\fR, reflected in the progress bar and eventual text. .Sp Default value: 0. .IP "vertical \s-1BOOLEAN\s0" 4 .IX Item "vertical BOOLEAN" If 1, the widget is drawn vertically, and the progress bar moves from bottom to top. If 0, the widget is drawn horizontally, and the progress bar moves from left to right. .Sp Default value: 0 .SS "Methods" .IX Subsection "Methods" .IP "set_bounds \s-1MIN, MAX\s0" 4 .IX Item "set_bounds MIN, MAX" Simultaneously sets both \f(CW\*(C`min\*(C'\fR and \f(CW\*(C`max\*(C'\fR values. .SS "Events" .IX Subsection "Events" .IP "Stringify \s-1VALUE, REF\s0" 4 .IX Item "Stringify VALUE, REF" Converts integer \s-1VALUE\s0 into a string format and puts into \s-1REF\s0 scalar reference. Default stringifying conversion is identical to \f(CW\*(C`sprintf("%2d%%")\*(C'\fR one. .SH "Prima::AbstractSlider" .IX Header "Prima::AbstractSlider" The class provides basic functionality of a sliding bar, equipped with tick marks. Tick marks are supposed to be drawn alongside the main sliding axis or circle and provide visual feedback for the user. .PP The class is not usable directly. .SS "Properties" .IX Subsection "Properties" .IP "autoTrack \s-1BOOLEAN\s0" 4 .IX Item "autoTrack BOOLEAN" A boolean flag, selects the way notifications execute when the user mouse-drags the sliding bar. If 1, \f(CW\*(C`Change\*(C'\fR notification is executed as soon as \f(CW\*(C`value\*(C'\fR is changed. If 0, \f(CW\*(C`Change\*(C'\fR is deferred until the user finished the mouse drag; instead, \f(CW\*(C`Track\*(C'\fR notification is executed when the bar is moved. .Sp This property can be used when the action, called on \f(CW\*(C`Change\*(C'\fR performs very slow, so the eventual fast mouse interactions would not thrash down the program. .Sp Default value: 1 .IP "increment \s-1INTEGER\s0" 4 .IX Item "increment INTEGER" A step range value, used in \f(CW\*(C`scheme\*(C'\fR for marking the key ticks. See scheme for details. .Sp Default value: 10 .IP "max \s-1INTEGER\s0" 4 .IX Item "max INTEGER" Sets the upper limit for \f(CW\*(C`value\*(C'\fR. .Sp Default value: 100. .IP "min \s-1INTEGER\s0" 4 .IX Item "min INTEGER" Sets the lower limit for \f(CW\*(C`value\*(C'\fR. .Sp Default value: 0 .IP "readOnly \s-1BOOLEAN\s0" 4 .IX Item "readOnly BOOLEAN" If 1, the use cannot change the value by moving the bar or otherwise. .Sp Default value: 0 .IP "ticks \s-1ARRAY\s0" 4 .IX Item "ticks ARRAY" Selects the tick marks representation along the sliding axis or circle. \&\s-1ARRAY\s0 consists of hashes, each for one tick. The hash must contain at least \f(CW\*(C`value\*(C'\fR key, with integer value. The two additional keys, \&\f(CW\*(C`height\*(C'\fR and \f(CW\*(C`text\*(C'\fR, select the height of a tick mark in pixels and the text drawn near the mark, correspondingly. .Sp If \s-1ARRAY\s0 is \f(CW\*(C`undef\*(C'\fR, no ticks are drawn. .IP "scheme \s-1INTEGER\s0" 4 .IX Item "scheme INTEGER" \&\f(CW\*(C`scheme\*(C'\fR is a property, that creates a set of tick marks using one of the predefined scale designs, selected by \f(CW\*(C`ss::XXX\*(C'\fR constants. Each constant produces different scale; some make use of \f(CW\*(C`increment\*(C'\fR integer property, which selects a step by which the additional text marks are drawn. As an example, \f(CW\*(C`ss::Thermometer\*(C'\fR design with default \f(CW\*(C`min\*(C'\fR, \f(CW\*(C`max\*(C'\fR, and \f(CW\*(C`increment\*(C'\fR values would look like that: .Sp .Vb 3 \& 0 10 20 100 \& | | | | \& |||||||||||||||....||| .Ve .Sp The module defines the following constants: .Sp .Vb 4 \& ss::Axis \- 5 minor ticks per increment \& ss::Gauge \- 1 tick per increment \& ss::StdMinMax \- 2 ticks at the ends of the bar \& ss::Thermometer \- 10 minor ticks per increment, longer text ticks .Ve .Sp When \f(CW\*(C`tick\*(C'\fR property is set, \f(CW\*(C`scheme\*(C'\fR is reset to \f(CW\*(C`undef\*(C'\fR. .IP "snap \s-1BOOLEAN\s0" 4 .IX Item "snap BOOLEAN" If 1, \f(CW\*(C`value\*(C'\fR cannot accept values that are not on the tick scale. When set such a value, it is rounded to the closest tick mark. If 0, \f(CW\*(C`value\*(C'\fR can accept any integer value in range from \f(CW\*(C`min\*(C'\fR to \f(CW\*(C`max\*(C'\fR. .Sp Default value: 0 .IP "step \s-1INTEGER\s0" 4 .IX Item "step INTEGER" Integer delta for singular increment / decrement commands and a threshold for \f(CW\*(C`value\*(C'\fR when \f(CW\*(C`snap\*(C'\fR value is 0. .Sp Default value: 1 .IP "value \s-1INTEGER\s0" 4 .IX Item "value INTEGER" Selects integer value between \f(CW\*(C`min\*(C'\fR and \f(CW\*(C`max\*(C'\fR and the corresponding sliding bar position. .Sp Default value: 0. .SS "Events" .IX Subsection "Events" .IP "Change" 4 .IX Item "Change" Called when \f(CW\*(C`value\*(C'\fR value is changed, with one exception: if the user moves the sliding bar while \f(CW\*(C`autoTrack\*(C'\fR is 0, \f(CW\*(C`Track\*(C'\fR notification is called instead. .IP "Track" 4 .IX Item "Track" Called when the user moves the sliding bar while \f(CW\*(C`autoTrack\*(C'\fR value is 0; this notification is a substitute to \f(CW\*(C`Change\*(C'\fR. .SH "Prima::Slider" .IX Header "Prima::Slider" Presents a linear sliding bar, movable along a linear shaft. .SS "Properties" .IX Subsection "Properties" .IP "borderWidth \s-1INTEGER\s0" 4 .IX Item "borderWidth INTEGER" In horizontal mode, sets extra margin space between the slider line and the widget boundaries. Can be used for fine tuning of displaying text labels from <\fIticks()\fR>, where the default spacing (0) or spacing procedure (drop overlapping labels) is not enough. .IP "ribbonStrip \s-1BOOLEAN\s0" 4 .IX Item "ribbonStrip BOOLEAN" If 1, the parts of shaft are painted with different colors, to increase visual feedback. If 0, the shaft is painted with single default background color. .Sp Default value: 0 .IP "shaftBreadth \s-1INTEGER\s0" 4 .IX Item "shaftBreadth INTEGER" Breadth of the shaft in pixels. .Sp Default value: 6 .IP "tickAlign \s-1INTEGER\s0" 4 .IX Item "tickAlign INTEGER" One of \f(CW\*(C`tka::XXX\*(C'\fR constants, that correspond to the situation of tick marks: .Sp .Vb 3 \& tka::Normal \- ticks are drawn on the left or on the top of the shaft \& tka::Alternative \- ticks are drawn on the right or at the bottom of the shaft \& tka::Dual \- ticks are drawn both ways .Ve .Sp The ticks orientation ( left or top, right or bottom ) is dependant on \f(CW\*(C`vertical\*(C'\fR property value. .Sp Default value: \f(CW\*(C`tka::Normal\*(C'\fR .IP "vertical \s-1BOOLEAN\s0" 4 .IX Item "vertical BOOLEAN" If 1, the widget is drawn vertically, and the slider moves from bottom to top. If 0, the widget is drawn horizontally, and the slider moves from left to right. .Sp Default value: 0 .SS "Methods" .IX Subsection "Methods" .IP "pos2info X, Y" 4 .IX Item "pos2info X, Y" Translates integer coordinates pair ( X, Y ) into the value corresponding to the scale, and returns three scalars: .RS 4 .IP "info \s-1INTEGER\s0" 4 .IX Item "info INTEGER" If \f(CW\*(C`undef\*(C'\fR, the user-driven positioning is not possible ( \f(CW\*(C`min\*(C'\fR equals to \f(CW\*(C`max\*(C'\fR ). .Sp If 1, the point is located on the slider. .Sp If 0, the point is outside the slider. .IP "value \s-1INTEGER\s0" 4 .IX Item "value INTEGER" If \f(CW\*(C`info\*(C'\fR is 0 or 1, contains the corresponding \f(CW\*(C`value\*(C'\fR. .IP "aperture \s-1INTEGER\s0" 4 .IX Item "aperture INTEGER" Offset in pixels along the shaft axis. .RE .RS 4 .RE .SH "Prima::CircularSlider" .IX Header "Prima::CircularSlider" Presents a slider widget with the dial and two increment / decrement buttons. The tick marks are drawn around the perimeter of the dial; current value is displayed in the center of the dial. .SS "Properties" .IX Subsection "Properties" .IP "buttons \s-1BOOLEAN\s0" 4 .IX Item "buttons BOOLEAN" If 1, the increment / decrement buttons are shown at the bottom of the dial, and the user can change the value either by the dial or by the buttons. If 0, the buttons are not shown. .Sp Default values: 0 .IP "stdPointer \s-1BOOLEAN\s0" 4 .IX Item "stdPointer BOOLEAN" Determines the style of a value indicator ( pointer ) on the dial. If 1, it is drawn as a black triangular mark. If 0, it is drawn as a small circular knob. .Sp Default value: 0 .SS "Methods" .IX Subsection "Methods" .IP "offset2data \s-1VALUE\s0" 4 .IX Item "offset2data VALUE" Converts integer value in range from \f(CW\*(C`min\*(C'\fR to \f(CW\*(C`max\*(C'\fR into the corresponding angle, and return two real values: cosine and sine of the angle. .IP "offset2pt X, Y, \s-1VALUE, RADIUS\s0" 4 .IX Item "offset2pt X, Y, VALUE, RADIUS" Converts integer value in range from \f(CW\*(C`min\*(C'\fR to \f(CW\*(C`max\*(C'\fR into the point coordinates, with the \s-1RADIUS\s0 and dial center coordinates X and Y. Return the calculated point coordinates as two integers in (X,Y) format. .IP "xy2val X, Y" 4 .IX Item "xy2val X, Y" Converts widget coordinates X and Y into value in range from \f(CW\*(C`min\*(C'\fR to \f(CW\*(C`max\*(C'\fR, and return two scalars: the value and the boolean flag, which is set to 1 if the (X,Y) point is inside the dial circle, and 0 otherwise. .SS "Events" .IX Subsection "Events" .IP "Stringify \s-1VALUE, REF\s0" 4 .IX Item "Stringify VALUE, REF" Converts integer \s-1VALUE\s0 into a string format and puts into \s-1REF\s0 scalar reference. The resulting string is displayed in the center of the dial. .Sp Default conversion routine simply copies \s-1VALUE\s0 to \s-1REF\s0 as is. .SH "AUTHOR" .IX Header "AUTHOR" Dmitry Karasik, , Anton Berezin . .SH "SEE ALSO" .IX Header "SEE ALSO" Prima, \fIexamples/fontdlg.pl\fR