.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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" ''
'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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" 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::Buttons 3"
.TH Prima::Buttons 3 "2009-02-24" "perl v5.14.2" "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::Buttons \- button widgets and grouping widgets.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        use Prima qw(Application Buttons StdBitmap);
\&
\&        my $window = Prima::MainWindow\-> create;
\&        Prima::Button\-> new(
\&                owner => $window,
\&                text  => \*(AqSimple button\*(Aq,
\&                pack  => {},
\&        );
\&        $window\-> insert( \*(AqPrima::SpeedButton\*(Aq , 
\&                pack => {},
\&                image => Prima::StdBitmap::icon(0),
\&        );
\&
\&        run Prima;
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
The module provides the following classes:
.PP
.Vb 9
\&        *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 )
.Ve
.PP
Note: \f(CW\*(C`*\*(C'\fR \- marked classes are abstract.
.SH "USAGE"
.IX Header "USAGE"
.Vb 1
\&        use Prima::Buttons;
\&
\&        my $button = $widget\-> insert( \*(AqPrima::Button\*(Aq, 
\&                text => \*(AqPush button\*(Aq,
\&                onClick => sub { print "hey!\en" },
\&        );
\&        $button\-> flat(1);
\&
\&        my $group = $widget\-> insert( \*(AqPrima::GroupBox\*(Aq, 
\&                onRadioClick => sub { print $_[1]\-> text, "\en"; }
\&        );
\&        $group\-> insert( \*(AqPrima::Radio\*(Aq, text => \*(AqSelection 1\*(Aq);
\&        $group\-> insert( \*(AqPrima::Radio\*(Aq, text => \*(AqSelection 2\*(Aq, pressed => 1);
\&        $group\-> index(0);
.Ve
.SH "Prima::AbstractButton"
.IX Header "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:
.IP "\(bu" 4
The spacebar key is pressed
.IP "\(bu" 4
\&\f(CW\*(C`{default}\*(C'\fR ( see default property ) boolean variable is
set and enter key is pressed. This condition holds even if the button is out of focus.
.IP "\(bu" 4
\&\f(CW\*(C`{accel}\*(C'\fR character variable is assigned and the corresponding character key 
is pressed. \f(CW\*(C`{accel}\*(C'\fR variable is extracted automatically from the text string
passed to text property. 
This condition holds even if the button is out of focus.
.SS "Events"
.IX Subsection "Events"
.IP "Check" 4
.IX Item "Check"
Abstract callback event.
.IP "Click" 4
.IX Item "Click"
Called whenever the user presses the button.
.SS "Properties"
.IX Subsection "Properties"
.IP "pressed \s-1BOOLEAN\s0" 4
.IX Item "pressed BOOLEAN"
Represents the state of button widget, whether it is pressed or not.
.Sp
Default value: 0
.IP "text \s-1STRING\s0" 4
.IX Item "text STRING"
The text that is drawn in the button. If \s-1STRING\s0 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.
.SS "Methods"
.IX Subsection "Methods"
.IP "draw_veil \s-1CANVAS\s0, X1, Y1, X2, Y2" 4
.IX Item "draw_veil CANVAS, X1, Y1, X2, Y2"
Draws a rectangular veil shape over \s-1CANVAS\s0 in given boundaries.
This is the default method of drawing the button in the disabled state.
.IP "draw_caption \s-1CANVAS\s0, X, Y" 4
.IX Item "draw_caption CANVAS, X, Y"
Draws single line of text, stored in text property on \s-1CANVAS\s0 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.
.IP "caption_box [ \s-1CANVAS\s0 = self ]" 4
.IX Item "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 \s-1CANVAS\s0.
If \s-1CANVAS\s0 is undefined, the widget itself is used as a graphic device.
.SH "Prima::Button"
.IX Header "Prima::Button"
A push button class, that extends Prima::AbstractButton functionality by allowing
an image to be drawn together with the text.
.SS "Properties"
.IX Subsection "Properties"
.IP "autoHeight \s-1BOOLEAN\s0" 4
.IX Item "autoHeight BOOLEAN"
If 1, the button height is automatically changed as text extensions
change.
.Sp
Default value: 1
.IP "autoRepeat \s-1BOOLEAN\s0" 4
.IX Item "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.
.Sp
Default value: 0
.IP "autoWidth \s-1BOOLEAN\s0" 4
.IX Item "autoWidth BOOLEAN"
If 1, the button width is automatically changed as text extensions
change.
.Sp
Default value: 1
.IP "borderWidth \s-1INTEGER\s0" 4
.IX Item "borderWidth INTEGER"
Width of 3d\-shade border around the button.
.Sp
Default value: 2
.IP "checkable \s-1BOOLEAN\s0" 4
.IX Item "checkable BOOLEAN"
Selects if the button toggles checked state when the user
presses it.
.Sp
Default value: 0
.IP "checked \s-1BOOLEAN\s0" 4
.IX Item "checked BOOLEAN"
Selects whether the button is checked or not. Only actual
when checkable property is set. See also holdGlyph.
.Sp
Default value: 0
.IP "default \s-1BOOLEAN\s0" 4
.IX Item "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.
.Sp
Default value: 0
.IP "defaultGlyph \s-1INTEGER\s0" 4
.IX Item "defaultGlyph INTEGER"
Selects index of the default sub-image.
.Sp
Default value: 0
.IP "disabledGlyph \s-1INTEGER\s0" 4
.IX Item "disabledGlyph INTEGER"
Selects index of the sub-image for the disabled button state.
If \f(CW\*(C`image\*(C'\fR does not contain such sub-image, the \f(CW\*(C`defaultGlyph\*(C'\fR
sub-image is drawn, and is dimmed over with draw_veil method.
.Sp
Default value: 1
.IP "flat \s-1BOOLEAN\s0" 4
.IX Item "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.
.Sp
Default value: 0
.IP "glyphs \s-1INTEGER\s0" 4
.IX Item "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 \f(CW\*(C`glyphs\*(C'\fR property assigns how many such sub-images the image object contains.
.Sp
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.
.Sp
Default value: 1
.IP "hiliteGlyph \s-1INTEGER\s0" 4
.IX Item "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 \f(CW\*(C`image\*(C'\fR does not contain such sub-image, the \f(CW\*(C`defaultGlyph\*(C'\fR sub-image is drawn.
.Sp
Default value: 0
.IP "holdGlyph \s-1INTEGER\s0" 4
.IX Item "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 \f(CW\*(C`image\*(C'\fR does not contain such sub-image, the \f(CW\*(C`defaultGlyph\*(C'\fR sub-image is drawn.
.Sp
Default value: 3
.IP "image \s-1OBJECT\s0" 4
.IX Item "image OBJECT"
If set, the image object is drawn next with the button text, over or left to it
( see vertical property ). If \s-1OBJECT\s0 contains several sub-images, then the
corresponding sub-image is drawn for each button state. See glyphs property.
.Sp
Default value: undef
.IP "imageFile \s-1FILENAME\s0" 4
.IX Item "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.
.Sp
To allow easy multiframe image access, \s-1FILENAME\s0 string is checked if it contains
a number after a colon in the string end. Such, \f(CW\*(C`imageFile(\*(Aqimage.gif:3\*(Aq)\*(C'\fR call
would load the fourth frame in \f(CW\*(C`image.gif\*(C'\fR file.
.IP "imageScale \s-1SCALE\s0" 4
.IX Item "imageScale SCALE"
Contains zoom factor for the image.
.Sp
Default value: 1
.IP "modalResult \s-1INTEGER\s0" 4
.IX Item "modalResult INTEGER"
Contains a custom integer value, preferably one of \f(CW\*(C`mb::XXX\*(C'\fR constants.
If a button with non-zero \f(CW\*(C`modalResult\*(C'\fR is owned by a currently executing 
modal window, and is pressed, its \f(CW\*(C`modalResult\*(C'\fR value is copied to the \f(CW\*(C`modalResult\*(C'\fR 
property of the owner window, and the latter is closed. 
This scheme is helpful for the dialog design:
.Sp
.Vb 5
\&        $dialog\-> insert( \*(AqPrima::Button\*(Aq, modalResult => mb::OK, 
\&                text => \*(Aq~Ok\*(Aq, default => 1);
\&        $dialog\-> insert( \*(AqPrima::Button\*(Aq, modalResult => mb::Cancel, 
\&                text => \*(AqCancel);
\&        return if $dialog\-> execute != mb::OK.
.Ve
.Sp
The toolkit defines the following constants for \f(CW\*(C`modalResult\*(C'\fR use:
.Sp
.Vb 8
\&        mb::OK or mb::Ok        
\&        mb::Cancel    
\&        mb::Yes       
\&        mb::No        
\&        mb::Abort     
\&        mb::Retry     
\&        mb::Ignore    
\&        mb::Help
.Ve
.Sp
However, any other integer value can be safely used.
.Sp
Default value: 0
.IP "pressedGlyph \s-1INTEGER\s0" 4
.IX Item "pressedGlyph INTEGER"
Selects index of the sub-image for the pressed state of the button. 
If \f(CW\*(C`image\*(C'\fR does not contain such sub-image, the \f(CW\*(C`defaultGlyph\*(C'\fR sub-image is drawn.
.IP "transparent \s-1BOOLEAN\s0" 4
.IX Item "transparent BOOLEAN"
See \*(L"transparent\*(R" in Prima::Widget. If set, the background is not painted.
.IP "vertical \s-1BOOLEAN\s0" 4
.IX Item "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.
.SH "Prima::SpeedButton"
.IX Header "Prima::SpeedButton"
A convenience class, same as Prima::Button but with default
square shape and text property set to an empty string.
.SH "Prima::Cluster"
.IX Header "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 \f(CW\*(C`ownerBackColor\*(C'\fR property 
set to 1, to prevent usage of background color from \f(CW\*(C`wc::Button\*(C'\fR palette.
.SS "Properties"
.IX Subsection "Properties"
.IP "auto \s-1BOOLEAN\s0" 4
.IX Item "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.
.Sp
Although this property is present on the Prima::CheckBox, it is not used in there.
.SS "Methods"
.IX Subsection "Methods"
.IP "check" 4
.IX Item "check"
Alias to \f(CWchecked(1)\fR
.IP "uncheck" 4
.IX Item "uncheck"
Alias to \f(CWchecked(0)\fR
.IP "toggle" 4
.IX Item "toggle"
Reverts the \f(CW\*(C`checked\*(C'\fR state of the button and returns the new state.
.SH "Prima::Radio"
.IX Header "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 ).
.PP
The button uses the standard toolkit images with \f(CW\*(C`sbmp::RadioXXX\*(C'\fR indices. 
If the images can not be loaded, the button is drawn with the graphic primitives.
.SS "Events"
.IX Subsection "Events"
.IP "Check" 4
.IX Item "Check"
Called when a button is checked.
.SH "Prima::CheckBox"
.IX Header "Prima::CheckBox"
Represents a standard check box button, that can be either in checked, or in unchecked state.
.PP
The button uses the standard toolkit images with \f(CW\*(C`sbmp::CheckBoxXXX\*(C'\fR indices. 
If the images can not be loaded, the button is drawn with graphic primitives.
.SH "Prima::GroupBox"
.IX Header "Prima::GroupBox"
The class to be used as a container of radio and check-box buttons.
It can, however, contain any other widgets.
.PP
The widget draws a 3d\-shaded box on its boundaries and a text string in its
upper left corner. Uses \f(CW\*(C`transparent\*(C'\fR property to determine if it needs to
paint its background.
.PP
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.
.SS "Events"
.IX Subsection "Events"
.IP "RadioClick \s-1BUTTON\s0" 4
.IX Item "RadioClick BUTTON"
Called whenever one of children radio buttons is checked. \s-1BUTTON\s0
parameter contains the newly checked button.
.Sp
The default action of the class is that all checked buttons, 
except \s-1BUTTON\s0, are unchecked. Since the flow type of \f(CW\*(C`RadioClick\*(C'\fR event
is \f(CW\*(C`nt::PrivateFirst\*(C'\fR, \f(CW\*(C`on_radioclick\*(C'\fR method must be directly overloaded
to disable this functionality.
.SS "Properties"
.IX Subsection "Properties"
.IP "index \s-1INTEGER\s0" 4
.IX Item "index INTEGER"
Checks the child radio button with \f(CW\*(C`index\*(C'\fR. The indexing is
based on the index in the widget list, returned by \f(CW\*(C`Prima::Widget::widgets\*(C'\fR method.
.IP "value \s-1BITFIELD\s0" 4
.IX Item "value BITFIELD"
\&\s-1BITFIELD\s0 is an unsigned integer, where each bit corresponds to the
\&\f(CW\*(C`checked\*(C'\fR state of a child check-box button. The indexing is
based on the index in the widget list, returned by \f(CW\*(C`Prima::Widget::widgets\*(C'\fR method.
.SH "Prima::RadioGroup"
.IX Header "Prima::RadioGroup"
This class is obsolete and is same as \f(CW\*(C`Prima::GroupBox\*(C'\fR.
.SH "Prima::CheckBoxGroup"
.IX Header "Prima::CheckBoxGroup"
This class is obsolete and is same as \f(CW\*(C`Prima::GroupBox\*(C'\fR.
.SH "BUGS"
.IX Header "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 \f(CW\*(C`put_image_indirect\*(C'\fR
method of \f(CW\*(C`Prima::Button\*(C'\fR, and perform custom output there.
.PP
Tilde escaping in \f(CW\*(C`text\*(C'\fR is not realized, but is planned to. There currently is no way
to avoid tilde underscoring.
.PP
Radio buttons can get unexpectedly checked when used in notebooks. See auto.
.PP
\&\f(CW\*(C`Prima::GroupBox::value\*(C'\fR parameter is an integer, which size is architecture-dependent.
Shift towards a vector is considered a good idea.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dmitry Karasik, <dmitry@karasik.eu.org>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Prima, Prima::Widget, Prima::Window, Prima::IntUtils, 
Prima::StdBitmap, \fIexamples/buttons.pl\fR, \fIexamples/buttons2.pl\fR.