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:

The spacebar key is pressed
{default} ( see default property ) boolean variable is set and enter key is pressed. This condition holds even if the button is out of focus.
{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 (defined by CHAR) that the button will react to if pressed, if the button has the focus The combination ALT + Key works always if the button has the focus or not

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

autoShaping BOOLEAN

If 1, the button shape is autmatically update when the button size and/or font are updated, if the current skin can make use of non-rectangular shapes. Generally is unneeded unless the owner of the button has a different back color or features some custom painting.

Default value: 0

See also: examples/triangle.pl, examples/dragdrop.pl

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 | IMAGE | METAFILE

Selects index of the default sub-image.

Default value: 0

disabledGlyph INTEGER | IMAGE | METAFILE

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

hilite

Read-only property, return 1 if the button is highlighted, 0 otherwise.

hiliteGlyph INTEGER | IMAGE | METAFILER

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 INTEGE | IMAGE | METAFILER

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.

Can also be a Prima::Drawable::Metafile object, however, imageScale factor wouldn't work on it.

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

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

border BOOLEAN: If set (default), draws a border along the widget boundaries
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>.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

USAGE

Prima::AbstractButton

Events

Properties

Methods

Prima::Button

Properties

Prima::SpeedButton

Prima::Cluster

Properties

Methods

Prima::Radio

Events

Prima::CheckBox

Prima::GroupBox

Events

Properties

Prima::RadioGroup

Prima::CheckBoxGroup

BUGS

AUTHOR

SEE ALSO

Module Install Instructions