Man Linux: Main Page and Category List


       Prima::Buttons - button widgets and grouping widgets.


               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;


       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::GroupBox ( derived from Prima::Widget )
                       Prima::RadioGroup       ( obsolete )
                       Prima::CheckBoxGroup    ( obsolete )

       Note: "*" - marked classes are abstract.


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

           Abstract callback event.

           Called whenever the user presses the button.

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

           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.

       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

       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

       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.


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

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

           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

           Default value: 0

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

           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

           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

           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

                   $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

           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

       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.


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


       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.

       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

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

           Alias to checked(1)

           Alias to checked(0)

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


       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.

           Called when a button is checked.


       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.


       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.

       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.

       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.


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


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


       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

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


       Dmitry Karasik, <>.


       Prima, Prima::Widget, Prima::Window, Prima::IntUtils, Prima::StdBitmap,
       examples/, examples/