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

FreeBSD Manual Pages

  
 
  

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

NAME
       Prima::Buttons -	button widgets and grouping widgets.

SYNOPSIS
	       use Prima qw(Application	Buttons	StdBitmap);

	       my $window = Prima::MainWindow->	create;
	       Prima::Button-> new(
		       owner =>	$window,
		       text  =>	'Simple	button',
		       pack  =>	{},
	       );
	       $window-> insert( 'Prima::SpeedButton' ,
		       pack => {},
		       image =>	Prima::StdBitmap::icon(0),
	       );

	       run Prima;

DESCRIPTION
       Prima::Buttons provides two separate sets of classes: the button
       widgets and the grouping	widgets. The button widgets include push
       buttons,	check-boxes and	radio buttons.	The grouping widgets are
       designed	for usage as containers	for the	check-boxes and	radio buttons,
       however,	any widget can be inserted in a	grouping widget.

       The module provides the following classes:

	       *Prima::AbstractButton (	derived	from Prima::Widget and Prima::MouseScroller )
		       Prima::Button
			       Prima::SpeedButton
		       *Prima::Cluster
			       Prima::CheckBox
			       Prima::Radio
	       Prima::GroupBox ( derived from Prima::Widget )
		       Prima::RadioGroup       ( obsolete )
		       Prima::CheckBoxGroup    ( obsolete )

       Note: "*" - marked classes are abstract.

USAGE
	       use Prima::Buttons;

	       my $button = $widget-> insert( 'Prima::Button',
		       text => 'Push button',
		       onClick => sub {	print "hey!\n" },
	       );
	       $button-> flat(1);

	       my $group = $widget-> insert( 'Prima::GroupBox',
		       onRadioClick => sub { print $_[1]-> text, "\n"; }
	       );
	       $group->	insert(	'Prima::Radio',	text =>	'Selection 1');
	       $group->	insert(	'Prima::Radio',	text =>	'Selection 2', pressed => 1);
	       $group->	index(0);

Prima::AbstractButton
       Prima::AbstractButton realizes common functionality of buttons.	It
       provides	reaction on mouse and keyboard events, and calls Click
       notification when the user activates the	button.	The mouse activation
       is performed either by mouse double click or successive mouse down and
       mouse up	events within the button boundaries. The keyboard activation
       is performed on the following conditions:

       o   The spacebar	key is pressed

       o   "{default}" ( see default property )	boolean	variable is set	and
	   enter key is	pressed. This condition	holds even if the button is
	   out of focus.

       o   "{accel}" character variable	is assigned and	the corresponding
	   character key is pressed. "{accel}" variable	is extracted
	   automatically from the text string passed to	text property.	This
	   condition holds even	if the button is out of	focus.

   Events
       Check
	   Abstract callback event.

       Click
	   Called whenever the user presses the	button.

   Properties
       hotKey CHAR
	   A key that the button will react to if pressed, even	when out of
	   focus.

       pressed BOOLEAN
	   Represents the state	of button widget, whether it is	pressed	or
	   not.

	   Default value: 0

       text STRING
	   The text that is drawn in the button. If STRING contains ~ (	tilde
	   ) character,	the following character	is treated as a	hot key, and
	   the character is underlined.	If the user presses the	corresponding
	   character key then Click event is called. This is true even when
	   the button is out of	focus.

   Methods
       draw_veil CANVAS, X1, Y1, X2, Y2
	   Draws a rectangular veil shape over CANVAS in given boundaries.
	   This	is the default method of drawing the button in the disabled
	   state.

       draw_caption CANVAS, X, Y
	   Draws single	line of	text, stored in	text property on CANVAS	at X,
	   Y coordinates. Performs underlining of eventual tilde-escaped
	   character, and draws	the text with dimmed colors if the button is
	   disabled. If	the button is focused, draws a dotted line around the
	   text.

       caption_box [ CANVAS = self ]
	   Calculates geometrical extensions of	text string, stored in text
	   property in pixels.	Returns	two integers, the width	and the	height
	   of the string for the font selected on CANVAS.  If CANVAS is
	   undefined, the widget itself	is used	as a graphic device.

Prima::Button
       A push button class, that extends Prima::AbstractButton functionality
       by allowing an image to be drawn	together with the text.

   Properties
       autoHeight BOOLEAN
	   If 1, the button height is automatically changed as text extensions
	   change.

	   Default value: 1

       autoRepeat BOOLEAN
	   If set, the button behaves like a keyboard button - after the first
	   Click event,	a timeout is set, after	which is expired and the
	   button still	pressed, Click event is	repeatedly called until	the
	   button is released. Useful for emulating the	marginal scroll-bar
	   buttons.

	   Default value: 0

       autoWidth BOOLEAN
	   If 1, the button width is automatically changed as text extensions
	   change.

	   Default value: 1

       borderWidth INTEGER
	   Width of 3d-shade border around the button.

	   Default value: 2

       checkable BOOLEAN
	   Selects if the button toggles checked state when the	user presses
	   it.

	   Default value: 0

       checked BOOLEAN
	   Selects whether the button is checked or not. Only actual when
	   checkable property is set. See also holdGlyph.

	   Default value: 0

       default BOOLEAN
	   Defines if the button should	react when the user presses the	enter
	   button.  If set, the	button is drawn	with the black border,
	   indicating that it executes the 'default' action. Useful for	OK-
	   buttons in dialogs.

	   Default value: 0

       defaultGlyph INTEGER
	   Selects index of the	default	sub-image.

	   Default value: 0

       disabledGlyph INTEGER
	   Selects index of the	sub-image for the disabled button state.  If
	   "image" does	not contain such sub-image, the	"defaultGlyph" sub-
	   image is drawn, and is dimmed over with draw_veil method.

	   Default value: 1

       flat BOOLEAN
	   Selects special 'flat' mode,	when a button is painted without a
	   border when the mouse pointer is outside the	button boundaries.
	   This	mode is	useful for the toolbar buttons.	See also hiliteGlyph.

	   Default value: 0

       glyphs INTEGER
	   If a	button is to be	drawn with the image, it can be	passed in the
	   image property. If, however,	the button must	be drawn with several
	   different images, there are no several image-holding	properties.
	   Instead, the	image object can be logically split vertically into
	   several equal sub-images. This allows the button resource to
	   contain all button states into one image file.  The "glyphs"
	   property assigns how	many such sub-images the image object
	   contains.

	   The sub-image indices can be	assigned for rendition of the
	   different states.  These indices are	selected by the	following
	   integer properties: defaultGlyph, hiliteGlyph, disabledGlyph,
	   pressedGlyph, holdGlyph.

	   Default value: 1

       hiliteGlyph INTEGER
	   Selects index of the	sub-image for the state	when the mouse pointer
	   is over the button. This image is used only when flat property is
	   set.	 If "image" does not contain such sub-image, the
	   "defaultGlyph" sub-image is drawn.

	   Default value: 0

       holdGlyph INTEGER
	   Selects index of the	sub-image for the state	when the button	is
	   checked.  This image	is used	only when checkable property is	set.
	   If "image" does not contain such sub-image, the "defaultGlyph" sub-
	   image is drawn.

	   Default value: 3

       image OBJECT
	   If set, the image object is drawn next with the button text,	over
	   or left to it ( see vertical	property ). If OBJECT contains several
	   sub-images, then the	corresponding sub-image	is drawn for each
	   button state. See glyphs property.

	   Default value: undef

       imageFile FILENAME
	   Alternative to image	selection by loading an	image from the file.
	   During the creation state, if set together with image property, is
	   superseded by the latter.

	   To allow easy multiframe image access, FILENAME string is checked
	   if it contains a number after a colon in the	string end. Such,
	   "imageFile('image.gif:3')" call would load the fourth frame in
	   "image.gif" file.

       imageScale SCALE
	   Contains zoom factor	for the	image.

	   Default value: 1

       modalResult INTEGER
	   Contains a custom integer value, preferably one of "mb::XXX"
	   constants.  If a button with	non-zero "modalResult" is owned	by a
	   currently executing modal window, and is pressed, its "modalResult"
	   value is copied to the "modalResult"	property of the	owner window,
	   and the latter is closed.  This scheme is helpful for the dialog
	   design:

		   $dialog-> insert( 'Prima::Button', modalResult => mb::OK,
			   text	=> '~Ok', default => 1);
		   $dialog-> insert( 'Prima::Button', modalResult => mb::Cancel,
			   text	=> 'Cancel);
		   return if $dialog-> execute != mb::OK.

	   The toolkit defines the following constants for "modalResult" use:

		   mb::OK or mb::Ok
		   mb::Cancel
		   mb::Yes
		   mb::No
		   mb::Abort
		   mb::Retry
		   mb::Ignore
		   mb::Help

	   However, any	other integer value can	be safely used.

	   Default value: 0

       smoothScaling BOOL
	   Tries to represent the image	as smooth as possible. When the	system
	   doesn't support ARGB	layering, icon objects smooth scaling will be
	   restricted to integer-scaling only (i.e. 2x,	3x etc)	because	smooth
	   color plane will not	match pixelated	mask plane, and	because	box-
	   scaling with	non-integer zooms looks	ugly.

	   Default value: true

	   See also: "ui_scale"	in Prima::Image	.

       pressedGlyph INTEGER
	   Selects index of the	sub-image for the pressed state	of the button.
	   If "image" does not contain such sub-image, the "defaultGlyph" sub-
	   image is drawn.

       transparent BOOLEAN
	   See "transparent" in	Prima::Widget. If set, the background is not
	   painted.

       vertical	BOOLEAN
	   Determines the position of image next to the	text string. If	1, the
	   image is drawn above	the text; left to the text if 0.  In a special
	   case	when text is an	empty string, image is centered.

Prima::SpeedButton
       A convenience class, same as Prima::Button but with default square
       shape and text property set to an empty string.

Prima::Cluster
       An abstract class with common functionality of Prima::CheckBox and
       Prima::RadioButton. Reassigns default actions on	tab and	back-tab keys,
       so the sibling cluster widgets are not selected.	Has "ownerBackColor"
       property	set to 1, to prevent usage of background color from
       "wc::Button" palette.

   Properties
       auto BOOLEAN
	   If set, the button is automatically checked when the	button is in
	   focus. This functionality allows arrow key walking by the radio
	   buttons without pressing spacebar key. It is	also has a drawback,
	   that	if a radio button gets focused without user intervention, or
	   indirectly, it also gets checked, so	that behavior might cause
	   confusion. The said can be exemplified when an unchecked radio
	   button in a notebook	widget gets active by turning the notebook
	   page.

	   Although this property is present on	the Prima::CheckBox, it	is not
	   used	in there.

   Methods
       check
	   Alias to checked(1)

       uncheck
	   Alias to checked(0)

       toggle
	   Reverts the "checked" state of the button and returns the new
	   state.

Prima::Radio
       Represents a standard radio button, that	can be either in checked, or
       in unchecked state.  When checked, delivers RadioClick event to the
       owner ( if the latter provides one ).

       The button uses the standard toolkit images with	"sbmp::RadioXXX"
       indices.	 If the	images can not be loaded, the button is	drawn with the
       graphic primitives.

   Events
       Check
	   Called when a button	is checked.

Prima::CheckBox
       Represents a standard check box button, that can	be either in checked,
       or in unchecked state.

       The button uses the standard toolkit images with	"sbmp::CheckBoxXXX"
       indices.	 If the	images can not be loaded, the button is	drawn with
       graphic primitives.

Prima::GroupBox
       The class to be used as a container of radio and	check-box buttons.  It
       can, however, contain any other widgets.

       The widget draws	a 3d-shaded box	on its boundaries and a	text string in
       its upper left corner. Uses "transparent" property to determine if it
       needs to	paint its background.

       The class does not provide a method to calculate	the extension of the
       inner rectangle.	 However, it can be safely assumed that	all offsets
       except the upper	are 5 pixels.  The upper offset	is dependent on	a
       font, and constitutes the half of the font height.

   Events
       RadioClick BUTTON
	   Called whenever one of children radio buttons is checked. BUTTON
	   parameter contains the newly	checked	button.

	   The default action of the class is that all checked buttons,	except
	   BUTTON, are unchecked. Since	the flow type of "RadioClick" event is
	   "nt::PrivateFirst", "on_radioclick" method must be directly
	   overloaded to disable this functionality.

   Properties
       index INTEGER
	   Checks the child radio button with "index". The indexing is based
	   on the index	in the widget list, returned by
	   "Prima::Widget::widgets" method.

       value BITFIELD
	   BITFIELD is an unsigned integer, where each bit corresponds to the
	   "checked" state of a	child check-box	button.	The indexing is	based
	   on the index	in the widget list, returned by
	   "Prima::Widget::widgets" method.

Prima::RadioGroup
       This class is obsolete and is same as "Prima::GroupBox".

Prima::CheckBoxGroup
       This class is obsolete and is same as "Prima::GroupBox".

BUGS
       The push	button is not capable of drawing anything other	than single
       line of text and	single image. If an extended functionality is needed,
       instead of fully	rewriting the painting procedure, it might be
       reasonable to overload "put_image_indirect" method of "Prima::Button",
       and perform custom output there.

       Tilde escaping in "text"	is not realized, but is	planned	to. There
       currently is no way to avoid tilde underscoring.

       Radio buttons can get unexpectedly checked when used in notebooks. See
       auto.

       "Prima::GroupBox::value"	parameter is an	integer, which size is
       architecture-dependent.	Shift towards a	vector is considered a good
       idea.

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

SEE ALSO
       Prima, Prima::Widget, Prima::Window, Prima::IntUtils, Prima::StdBitmap,
       examples/buttons.pl, examples/buttons2.pl.

perl v5.24.1			  2017-05-23		     Prima::Buttons(3)

NAME | SYNOPSIS | DESCRIPTION | USAGE | Prima::AbstractButton | Prima::Button | Prima::SpeedButton | Prima::Cluster | Prima::Radio | Prima::CheckBox | Prima::GroupBox | Prima::RadioGroup | Prima::CheckBoxGroup | BUGS | AUTHOR | SEE ALSO

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

home | help