Provided by: libprima-perl_1.28-1.2_amd64 bug

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

       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.