1Prima::Buttons(3)     User Contributed Perl Documentation    Prima::Buttons(3)
2
3
4

NAME

6       Prima::Buttons - button widgets and grouping widgets.
7

SYNOPSIS

9               use Prima qw(Application Buttons StdBitmap);
10
11               my $window = Prima::MainWindow-> create;
12               Prima::Button-> new(
13                       owner => $window,
14                       text  => 'Simple button',
15                       pack  => {},
16               );
17               $window-> insert( 'Prima::SpeedButton' ,
18                       pack => {},
19                       image => Prima::StdBitmap::icon(0),
20               );
21
22               run Prima;
23

DESCRIPTION

25       Prima::Buttons provides two separate sets of classes: the button
26       widgets and the grouping widgets. The button widgets include push
27       buttons, check-boxes and radio buttons.  The grouping widgets are
28       designed for usage as containers for the check-boxes and radio buttons,
29       however, any widget can be inserted in a grouping widget.
30
31       The module provides the following classes:
32
33               *Prima::AbstractButton ( derived from Prima::Widget and Prima::MouseScroller )
34                       Prima::Button
35                               Prima::SpeedButton
36                       *Prima::Cluster
37                               Prima::CheckBox
38                               Prima::Radio
39               Prima::GroupBox ( derived from Prima::Widget )
40                       Prima::RadioGroup       ( obsolete )
41                       Prima::CheckBoxGroup    ( obsolete )
42
43       Note: "*" - marked classes are abstract.
44

USAGE

46               use Prima::Buttons;
47
48               my $button = $widget-> insert( 'Prima::Button',
49                       text => 'Push button',
50                       onClick => sub { print "hey!\n" },
51               );
52               $button-> flat(1);
53
54               my $group = $widget-> insert( 'Prima::GroupBox',
55                       onRadioClick => sub { print $_[1]-> text, "\n"; }
56               );
57               $group-> insert( 'Prima::Radio', text => 'Selection 1');
58               $group-> insert( 'Prima::Radio', text => 'Selection 2', pressed => 1);
59               $group-> index(0);
60

Prima::AbstractButton

62       Prima::AbstractButton realizes common functionality of buttons.  It
63       provides reaction on mouse and keyboard events, and calls Click
64       notification when the user activates the button. The mouse activation
65       is performed either by mouse double click or successive mouse down and
66       mouse up events within the button boundaries. The keyboard activation
67       is performed on the following conditions:
68
69       •   The spacebar key is pressed
70
71       •   "{default}" ( see default property ) boolean variable is set and
72           enter key is pressed. This condition holds even if the button is
73           out of focus.
74
75       •   "{accel}" character variable is assigned and the corresponding
76           character key is pressed. "{accel}" variable is extracted
77           automatically from the text string passed to text property.  This
78           condition holds even if the button is out of focus.
79
80   Events
81       Check
82           Abstract callback event.
83
84       Click
85           Called whenever the user presses the button.
86
87   Properties
88       hotKey CHAR
89           A key that the button will react to if pressed, even when out of
90           focus.
91
92       pressed BOOLEAN
93           Represents the state of button widget, whether it is pressed or
94           not.
95
96           Default value: 0
97
98       text STRING
99           The text that is drawn in the button. If STRING contains ~ ( tilde
100           ) character, the following character is treated as a hot key, and
101           the character is underlined. If the user presses the corresponding
102           character key then Click event is called. This is true even when
103           the button is out of focus.
104
105   Methods
106       draw_veil CANVAS, X1, Y1, X2, Y2
107           Draws a rectangular veil shape over CANVAS in given boundaries.
108           This is the default method of drawing the button in the disabled
109           state.
110
111       draw_caption CANVAS, X, Y
112           Draws single line of text, stored in text property on CANVAS at X,
113           Y coordinates. Performs underlining of eventual tilde-escaped
114           character, and draws the text with dimmed colors if the button is
115           disabled. If the button is focused, draws a dotted line around the
116           text.
117
118       caption_box [ CANVAS = self ]
119           Calculates geometrical extensions of text string, stored in text
120           property in pixels.  Returns two integers, the width and the height
121           of the string for the font selected on CANVAS.  If CANVAS is
122           undefined, the widget itself is used as a graphic device.
123

Prima::Button

125       A push button class, that extends Prima::AbstractButton functionality
126       by allowing an image to be drawn together with the text.
127
128   Properties
129       autoHeight BOOLEAN
130           If 1, the button height is automatically changed as text extensions
131           change.
132
133           Default value: 1
134
135       autoRepeat BOOLEAN
136           If set, the button behaves like a keyboard button - after the first
137           Click event, a timeout is set, after which is expired and the
138           button still pressed, Click event is repeatedly called until the
139           button is released. Useful for emulating the marginal scroll-bar
140           buttons.
141
142           Default value: 0
143
144       autoWidth BOOLEAN
145           If 1, the button width is automatically changed as text extensions
146           change.
147
148           Default value: 1
149
150       borderWidth INTEGER
151           Width of 3d-shade border around the button.
152
153           Default value: 2
154
155       checkable BOOLEAN
156           Selects if the button toggles checked state when the user presses
157           it.
158
159           Default value: 0
160
161       checked BOOLEAN
162           Selects whether the button is checked or not. Only actual when
163           checkable property is set. See also holdGlyph.
164
165           Default value: 0
166
167       default BOOLEAN
168           Defines if the button should react when the user presses the enter
169           button.  If set, the button is drawn with the black border,
170           indicating that it executes the 'default' action. Useful for OK-
171           buttons in dialogs.
172
173           Default value: 0
174
175       defaultGlyph INTEGER | IMAGE | METAFILE
176           Selects index of the default sub-image.
177
178           Default value: 0
179
180       disabledGlyph INTEGER | IMAGE | METAFILE
181           Selects index of the sub-image for the disabled button state.  If
182           "image" does not contain such sub-image, the "defaultGlyph" sub-
183           image is drawn, and is dimmed over with draw_veil method.
184
185           Default value: 1
186
187       flat BOOLEAN
188           Selects special 'flat' mode, when a button is painted without a
189           border when the mouse pointer is outside the button boundaries.
190           This mode is useful for the toolbar buttons. See also hiliteGlyph.
191
192           Default value: 0
193
194       glyphs INTEGER
195           If a button is to be drawn with the image, it can be passed in the
196           image property. If, however, the button must be drawn with several
197           different images, there are no several image-holding properties.
198           Instead, the image object can be logically split vertically into
199           several equal sub-images. This allows the button resource to
200           contain all button states into one image file.  The "glyphs"
201           property assigns how many such sub-images the image object
202           contains.
203
204           The sub-image indices can be assigned for rendition of the
205           different states.  These indices are selected by the following
206           integer properties: defaultGlyph, hiliteGlyph, disabledGlyph,
207           pressedGlyph, holdGlyph.
208
209           Default value: 1
210
211       hiliteGlyph INTEGE | IMAGE | METAFILER
212           Selects index of the sub-image for the state when the mouse pointer
213           is over the button. This image is used only when flat property is
214           set.  If "image" does not contain such sub-image, the
215           "defaultGlyph" sub-image is drawn.
216
217           Default value: 0
218
219       holdGlyph INTEGE | IMAGE | METAFILER
220           Selects index of the sub-image for the state when the button is
221           checked.  This image is used only when checkable property is set.
222           If "image" does not contain such sub-image, the "defaultGlyph" sub-
223           image is drawn.
224
225           Default value: 3
226
227       image OBJECT
228           If set, the image object is drawn next with the button text, over
229           or left to it ( see vertical property ). If OBJECT contains several
230           sub-images, then the corresponding sub-image is drawn for each
231           button state. See glyphs property.
232
233           Can also be a "Prima::Drawable::Metafile" object, however,
234           "imageScale" factor wouldn't work on it.
235
236           Default value: undef
237
238       imageFile FILENAME
239           Alternative to image selection by loading an image from the file.
240           During the creation state, if set together with image property, is
241           superseded by the latter.
242
243           To allow easy multiframe image access, FILENAME string is checked
244           if it contains a number after a colon in the string end. Such,
245           "imageFile('image.gif:3')" call would load the fourth frame in
246           "image.gif" file.
247
248       imageScale SCALE
249           Contains zoom factor for the image.
250
251           Default value: 1
252
253       modalResult INTEGER
254           Contains a custom integer value, preferably one of "mb::XXX"
255           constants.  If a button with non-zero "modalResult" is owned by a
256           currently executing modal window, and is pressed, its "modalResult"
257           value is copied to the "modalResult" property of the owner window,
258           and the latter is closed.  This scheme is helpful for the dialog
259           design:
260
261                   $dialog-> insert( 'Prima::Button', modalResult => mb::OK,
262                           text => '~Ok', default => 1);
263                   $dialog-> insert( 'Prima::Button', modalResult => mb::Cancel,
264                           text => 'Cancel);
265                   return if $dialog-> execute != mb::OK.
266
267           The toolkit defines the following constants for "modalResult" use:
268
269                   mb::OK or mb::Ok
270                   mb::Cancel
271                   mb::Yes
272                   mb::No
273                   mb::Abort
274                   mb::Retry
275                   mb::Ignore
276                   mb::Help
277
278           However, any other integer value can be safely used.
279
280           Default value: 0
281
282       smoothScaling BOOL
283           Tries to represent the image as smooth as possible. When the system
284           doesn't support ARGB layering, icon objects smooth scaling will be
285           restricted to integer-scaling only (i.e. 2x, 3x etc) because smooth
286           color plane will not match pixelated mask plane, and because box-
287           scaling with non-integer zooms looks ugly.
288
289           Default value: true
290
291           See also: "ui_scale" in Prima::Image .
292
293       pressedGlyph INTEGER | IMAGE | METAFILE
294           Selects index of the sub-image for the pressed state of the button.
295           If "image" does not contain such sub-image, the "defaultGlyph" sub-
296           image is drawn.
297
298       transparent BOOLEAN
299           See "transparent" in Prima::Widget. If set, the background is not
300           painted.
301
302       vertical BOOLEAN
303           Determines the position of image next to the text string. If 1, the
304           image is drawn above the text; left to the text if 0.  In a special
305           case when text is an empty string, image is centered.
306

Prima::SpeedButton

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

Prima::Cluster

312       An abstract class with common functionality of Prima::CheckBox and
313       Prima::RadioButton. Reassigns default actions on tab and back-tab keys,
314       so the sibling cluster widgets are not selected. Has "ownerBackColor"
315       property set to 1, to prevent usage of background color from
316       "wc::Button" palette.
317
318   Properties
319       auto BOOLEAN
320           If set, the button is automatically checked when the button is in
321           focus. This functionality allows arrow key walking by the radio
322           buttons without pressing spacebar key. It is also has a drawback,
323           that if a radio button gets focused without user intervention, or
324           indirectly, it also gets checked, so that behavior might cause
325           confusion. The said can be exemplified when an unchecked radio
326           button in a notebook widget gets active by turning the notebook
327           page.
328
329           Although this property is present on the Prima::CheckBox, it is not
330           used in there.
331
332   Methods
333       check
334           Alias to checked(1)
335
336       uncheck
337           Alias to checked(0)
338
339       toggle
340           Reverts the "checked" state of the button and returns the new
341           state.
342

Prima::Radio

344       Represents a standard radio button, that can be either in checked, or
345       in unchecked state.  When checked, delivers RadioClick event to the
346       owner ( if the latter provides one ).
347
348       The button uses the standard toolkit images with "sbmp::RadioXXX"
349       indices.  If the images can not be loaded, the button is drawn with the
350       graphic primitives.
351
352   Events
353       Check
354           Called when a button is checked.
355

Prima::CheckBox

357       Represents a standard check box button, that can be either in checked,
358       or in unchecked state.
359
360       The button uses the standard toolkit images with "sbmp::CheckBoxXXX"
361       indices.  If the images can not be loaded, the button is drawn with
362       graphic primitives.
363

Prima::GroupBox

365       The class to be used as a container of radio and check-box buttons.  It
366       can, however, contain any other widgets.
367
368       The widget draws a 3d-shaded box on its boundaries and a text string in
369       its upper left corner. Uses "transparent" property to determine if it
370       needs to paint its background.
371
372       The class does not provide a method to calculate the extension of the
373       inner rectangle.  However, it can be safely assumed that all offsets
374       except the upper are 5 pixels.  The upper offset is dependent on a
375       font, and constitutes the half of the font height.
376
377   Events
378       RadioClick BUTTON
379           Called whenever one of children radio buttons is checked. BUTTON
380           parameter contains the newly checked button.
381
382           The default action of the class is that all checked buttons, except
383           BUTTON, are unchecked. Since the flow type of "RadioClick" event is
384           "nt::PrivateFirst", "on_radioclick" method must be directly
385           overloaded to disable this functionality.
386
387   Properties
388       index INTEGER
389           Checks the child radio button with "index". The indexing is based
390           on the index in the widget list, returned by
391           "Prima::Widget::widgets" method.
392
393       value BITFIELD
394           BITFIELD is an unsigned integer, where each bit corresponds to the
395           "checked" state of a child check-box button. The indexing is based
396           on the index in the widget list, returned by
397           "Prima::Widget::widgets" method.
398

Prima::RadioGroup

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

Prima::CheckBoxGroup

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

BUGS

406       The push button is not capable of drawing anything other than single
407       line of text and single image. If an extended functionality is needed,
408       instead of fully rewriting the painting procedure, it might be
409       reasonable to overload "put_image_indirect" method of "Prima::Button",
410       and perform custom output there.
411
412       Tilde escaping in "text" is not realized, but is planned to. There
413       currently is no way to avoid tilde underscoring.
414
415       Radio buttons can get unexpectedly checked when used in notebooks. See
416       auto.
417
418       "Prima::GroupBox::value" parameter is an integer, which size is
419       architecture-dependent.  Shift towards a vector is considered a good
420       idea.
421

AUTHOR

423       Dmitry Karasik, <dmitry@karasik.eu.org>.
424

SEE ALSO

426       Prima, Prima::Widget, Prima::Window, Prima::IntUtils,
427       Prima::Drawable::Metafile, Prima::StdBitmap, examples/buttons.pl,
428       examples/buttons2.pl.
429
430
431
432perl v5.34.0                      2021-07-22                 Prima::Buttons(3)
Impressum