Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Prima::Sliders(3)     User Contributed Perl Documentation    Prima::Sliders(3)

NAME
       Prima::Sliders -	sliding	bars, spin buttons and input lines, dial
       widget etc.

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:

	       Prima::AbstractSpinButton
		       Prima::SpinButton
		       Prima::AltSpinButton

	       Prima::SpinEdit

	       Prima::Gauge

	       Prima::AbstractSlider
		       Prima::Slider
		       Prima::CircularSlider

Prima::AbstractSpinButton
       Provides	a generic interface to spin-button class functionality,	which
       includes	range definition properties and	events.	Neither
       "Prima::AbstractSpinButton", nor	its descendants	store the integer
       value. These provide a mere possibility for the user to send
       incrementing or decrementing commands.

       The class is not	usable directly.

   Properties
       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 "state" is defined in the	descendant classes.

   Events
       Increment DELTA
	   Called when the user	presses	a part of a widget that	is responsible
	   for incrementing or decrementing commands. DELTA is an integer
	   value, indicating how the associated	value must be modified.

       TrackEnd
	   Called when the user	finished the mouse transaction.

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 "Increment" events with delta	value,
       based on	a vertical position of the mouse pointer.

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

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.

   Properties
       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	).

	   If 0, the value does	not change.

	   Default value: 0

       editClass STRING
	   Assigns an input line class.

	   Create-only property.

	   Default value: "Prima::InputLine"

       editDelegations ARRAY
	   Assigns the input line list of delegated notifications.

	   Create-only property.

       editProfile HASH
	   Assigns hash	of properties, passed to the input line	during the
	   creation.

	   Create-only property.

       max INTEGER
	   Sets	the upper limit	for "value".

	   Default value: 100.

       min INTEGER
	   Sets	the lower limit	for "value".

	   Default value: 0

       pageStep	INTEGER
	   Determines the multiplication factor	for incrementing/decrementing
	   actions of the mouse	wheel.

	   Default value: 10

       spinClass STRING
	   Assigns a spin-button class.

	   Create-only property.

	   Default value: "Prima::AltSpinButton"

       spinProfile ARRAY
	   Assigns the spin-button list	of delegated notifications.

	   Create-only property.

       spinDelegations HASH
	   Assigns hash	of properties, passed to the spin-button during	the
	   creation.

	   Create-only property.

       step INTEGER
	   Determines the multiplication factor	for incrementing/decrementing
	   actions of the spin-button.

	   Default value: 1

       value INTEGER
	   Selects integer value in range from "min" to	"max", reflected in
	   the input line.

	   Default value: 0.

   Methods
       set_bounds MIN, MAX
	   Simultaneously sets both "min" and "max" values.

   Events
       Change
	   Called when "value" is changed.

Prima::Gauge
       An output-only widget class, displays a progress	bar and	an eventual
       percentage string.  Useful as a progress	indicator.

   Properties
       indent INTEGER
	   Selects width of a border around the	widget.

	   Default value: 1

       max INTEGER
	   Sets	the upper limit	for "value".

	   Default value: 100.

       min INTEGER
	   Sets	the lower limit	for "value".

	   Default value: 0

       relief INTEGER
	   Selects the style of	a border around	the widget. Can	be one of the
	   following "gr::XXX" constants:

		   gr::Sink    - 3d sunken look
		   gr::Border  - uniform black border
		   gr::Raise   - 3d risen look

	   Default value: "gr::Sink".

       threshold INTEGER
	   Selects the threshold value used to determine if the	changes	to
	   "value" are reflected immediately or	deferred until the value is
	   changed more	significantly. When 0, all calls to "value" result in
	   an immediate	repaint	request.

	   Default value: 0

       value INTEGER
	   Selects integer value between "min" and "max", reflected in the
	   progress bar	and eventual text.

	   Default value: 0.

       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.

	   Default value: 0

   Methods
       set_bounds MIN, MAX
	   Simultaneously sets both "min" and "max" values.

   Events
       Stringify VALUE,	REF
	   Converts integer VALUE into a string	format and puts	into REF
	   scalar reference.  Default stringifying conversion is identical to
	   "sprintf("%2d%%")" one.

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.

       The class is not	usable directly.

   Properties
       autoTrack BOOLEAN
	   A boolean flag, selects the way notifications execute when the user
	   mouse-drags the sliding bar.	If 1, "Change" notification is
	   executed as soon as "value" is changed. If 0, "Change" is deferred
	   until the user finished the mouse drag; instead, "Track"
	   notification	is executed when the bar is moved.

	   This	property can be	used when the action, called on	"Change"
	   performs very slow, so the eventual fast mouse interactions would
	   not thrash down the program.

	   Default value: 1

       increment INTEGER
	   A step range	value, used in "scheme"	for marking the	key ticks.
	   See scheme for details.

	   Default value: 10

       max INTEGER
	   Sets	the upper limit	for "value".

	   Default value: 100.

       min INTEGER
	   Sets	the lower limit	for "value".

	   Default value: 0

       readOnly	BOOLEAN
	   If 1, the use cannot	change the value by moving the bar or
	   otherwise.

	   Default value: 0

       ticks ARRAY
	   Selects the tick marks representation along the sliding axis	or
	   circle.  ARRAY consists of hashes, each for one tick. The hash must
	   contain at least "value" key, with integer value. The two
	   additional keys, "height" and "text", select	the height of a	tick
	   mark	in pixels and the text drawn near the mark, correspondingly.

	   If ARRAY is "undef",	no ticks are drawn.

       scheme INTEGER
	   "scheme" is a property, that	creates	a set of tick marks using one
	   of the predefined scale designs, selected by	"ss::XXX" constants.
	   Each	constant produces different scale; some	make use of
	   "increment" integer property, which selects a step by which the
	   additional text marks are drawn. As an example, "ss::Thermometer"
	   design with default "min", "max", and "increment" values would look
	   like	that:

		   0   10   20	      100
		   |	|    |		|
		   |||||||||||||||....|||

	   The module defines the following constants:

		   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

	   When	"tick" property	is set,	"scheme" is reset to "undef".

       snap BOOLEAN
	   If 1, "value" 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, "value" can accept any integer value in range from "min" to
	   "max".

	   Default value: 0

       step INTEGER
	   Integer delta for singular increment	/ decrement commands and a
	   threshold for "value" when "snap" value is 0.

	   Default value: 1

       value INTEGER
	   Selects integer value between "min" and "max" and the corresponding
	   sliding bar position.

	   Default value: 0.

   Events
       Change
	   Called when "value" value is	changed, with one exception: if	the
	   user	moves the sliding bar while "autoTrack"	is 0, "Track"
	   notification	is called instead.

       Track
	   Called when the user	moves the sliding bar while "autoTrack"	value
	   is 0; this notification is a	substitute to "Change".

Prima::Slider
       Presents	a linear sliding bar, movable along a linear shaft.

   Properties
       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 <ticks()>, where	the default spacing
	   (0) or spacing procedure (drop overlapping labels) is not enough.

       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.

	   Default value: 0

       shaftBreadth INTEGER
	   Breadth of the shaft	in pixels.

	   Default value: 6

       tickAlign INTEGER
	   One of "tka::XXX" constants,	that correspond	to the situation of
	   tick	marks:

		   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

	   The ticks orientation ( left	or top,	right or bottom	) is dependant
	   on "vertical" property value.

	   Default value: "tka::Normal"

       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.

	   Default value: 0

   Methods
       pos2info	X, Y
	   Translates integer coordinates pair ( X, Y )	into the value
	   corresponding to the	scale, and returns three scalars:

	   info	INTEGER
	       If "undef", the user-driven positioning is not possible ( "min"
	       equals to "max" ).

	       If 1, the point is located on the slider.

	       If 0, the point is outside the slider.

	   value INTEGER
	       If "info" is 0 or 1, contains the corresponding "value".

	   aperture INTEGER
	       Offset in pixels	along the shaft	axis.

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.

   Properties
       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.

	   Default values: 0

       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.

	   Default value: 0

   Methods
       offset2data VALUE
	   Converts integer value in range from	"min" to "max" into the
	   corresponding angle,	and return two real values: cosine and sine of
	   the angle.

       offset2pt X, Y, VALUE, RADIUS
	   Converts integer value in range from	"min" to "max" into the	point
	   coordinates,	with the RADIUS	and dial center	coordinates X and Y.
	   Return the calculated point coordinates as two integers in (X,Y)
	   format.

       xy2val X, Y
	   Converts widget coordinates X and Y into value in range from	"min"
	   to "max", 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.

   Events
       Stringify VALUE,	REF
	   Converts integer VALUE into a string	format and puts	into REF
	   scalar reference.  The resulting string is displayed	in the center
	   of the dial.

	   Default conversion routine simply copies VALUE to REF as is.

AUTHOR
       Dmitry Karasik, <dmitry@karasik.eu.org>,	Anton Berezin
       <tobez@tobez.org>.

SEE ALSO
       Prima, examples/fontdlg.pl

perl v5.24.1			  2017-05-15		     Prima::Sliders(3)

NAME | DESCRIPTION | Prima::AbstractSpinButton | Prima::SpinButton | Prima::AltSpinButton | Prima::SpinEdit | Prima::Gauge | Prima::AbstractSlider | Prima::Slider | Prima::CircularSlider | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Prima::Sliders&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help