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
176           Selects index of the default sub-image.
177
178           Default value: 0
179
180       disabledGlyph INTEGER
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 INTEGER
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 INTEGER
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           Default value: undef
234
235       imageFile FILENAME
236           Alternative to image selection by loading an image from the file.
237           During the creation state, if set together with image property, is
238           superseded by the latter.
239
240           To allow easy multiframe image access, FILENAME string is checked
241           if it contains a number after a colon in the string end. Such,
242           "imageFile('image.gif:3')" call would load the fourth frame in
243           "image.gif" file.
244
245       imageScale SCALE
246           Contains zoom factor for the image.
247
248           Default value: 1
249
250       modalResult INTEGER
251           Contains a custom integer value, preferably one of "mb::XXX"
252           constants.  If a button with non-zero "modalResult" is owned by a
253           currently executing modal window, and is pressed, its "modalResult"
254           value is copied to the "modalResult" property of the owner window,
255           and the latter is closed.  This scheme is helpful for the dialog
256           design:
257
258                   $dialog-> insert( 'Prima::Button', modalResult => mb::OK,
259                           text => '~Ok', default => 1);
260                   $dialog-> insert( 'Prima::Button', modalResult => mb::Cancel,
261                           text => 'Cancel);
262                   return if $dialog-> execute != mb::OK.
263
264           The toolkit defines the following constants for "modalResult" use:
265
266                   mb::OK or mb::Ok
267                   mb::Cancel
268                   mb::Yes
269                   mb::No
270                   mb::Abort
271                   mb::Retry
272                   mb::Ignore
273                   mb::Help
274
275           However, any other integer value can be safely used.
276
277           Default value: 0
278
279       smoothScaling BOOL
280           Tries to represent the image as smooth as possible. When the system
281           doesn't support ARGB layering, icon objects smooth scaling will be
282           restricted to integer-scaling only (i.e. 2x, 3x etc) because smooth
283           color plane will not match pixelated mask plane, and because box-
284           scaling with non-integer zooms looks ugly.
285
286           Default value: true
287
288           See also: "ui_scale" in Prima::Image .
289
290       pressedGlyph INTEGER
291           Selects index of the sub-image for the pressed state of the button.
292           If "image" does not contain such sub-image, the "defaultGlyph" sub-
293           image is drawn.
294
295       transparent BOOLEAN
296           See "transparent" in Prima::Widget. If set, the background is not
297           painted.
298
299       vertical BOOLEAN
300           Determines the position of image next to the text string. If 1, the
301           image is drawn above the text; left to the text if 0.  In a special
302           case when text is an empty string, image is centered.
303

Prima::SpeedButton

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

Prima::Cluster

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

Prima::Radio

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

Prima::CheckBox

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

Prima::GroupBox

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

Prima::RadioGroup

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

Prima::CheckBoxGroup

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

BUGS

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

AUTHOR

420       Dmitry Karasik, <dmitry@karasik.eu.org>.
421

SEE ALSO

423       Prima, Prima::Widget, Prima::Window, Prima::IntUtils, Prima::StdBitmap,
424       examples/buttons.pl, examples/buttons2.pl.
425
426
427
428perl v5.32.0                      2020-07-28                 Prima::Buttons(3)
Impressum