1Prima::Buttons(3) User Contributed Perl Documentation Prima::Buttons(3)
2
6 Prima::Buttons - button widgets and grouping widgets.
7
9 use Prima qw(Application Buttons StdBitmap);
10 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 run Prima;
23
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 The module provides the following classes:
32 *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 Note: "*" - marked classes are abstract.
44
46 use Prima::Buttons;
47 my $button = $widget-> insert( 'Prima::Button',
49 text => 'Push button',
50 onClick => sub { print "hey!\n" },
51 );
52 $button-> flat(1);
53 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
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 • The spacebar key is pressed
70 • "{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 • "{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 Events
81 Check
82 Abstract callback event.
83 Click
85 Called whenever the user presses the button.
86 Properties
88 hotKey CHAR
89 A key that the button will react to if pressed, even when out of
90 focus.
91 pressed BOOLEAN
93 Represents the state of button widget, whether it is pressed or
94 not.
95 Default value: 0
97 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 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 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 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
125 A push button class, that extends Prima::AbstractButton functionality
126 by allowing an image to be drawn together with the text.
127 Properties
129 autoHeight BOOLEAN
130 If 1, the button height is automatically changed as text extensions
131 change.
132 Default value: 1
134 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 Default value: 0
143 autoWidth BOOLEAN
145 If 1, the button width is automatically changed as text extensions
146 change.
147 Default value: 1
149 borderWidth INTEGER
151 Width of 3d-shade border around the button.
152 Default value: 2
154 checkable BOOLEAN
156 Selects if the button toggles checked state when the user presses
157 it.
158 Default value: 0
160 checked BOOLEAN
162 Selects whether the button is checked or not. Only actual when
163 checkable property is set. See also holdGlyph.
164 Default value: 0
166 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 Default value: 0
174 defaultGlyph INTEGER | IMAGE | METAFILE
176 Selects index of the default sub-image.
177 Default value: 0
179 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 Default value: 1
186 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 Default value: 0
193 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 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 Default value: 1
210 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 Default value: 0
218 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 Default value: 3
226 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 Can also be a "Prima::Drawable::Metafile" object, however,
234 "imageScale" factor wouldn't work on it.
235 Default value: undef
237 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 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 imageScale SCALE
249 Contains zoom factor for the image.
250 Default value: 1
252 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 $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 The toolkit defines the following constants for "modalResult" use:
268 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 However, any other integer value can be safely used.
279 Default value: 0
281 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 Default value: true
290 See also: "ui_scale" in Prima::Image .
292 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 transparent BOOLEAN
299 See "transparent" in Prima::Widget. If set, the background is not
300 painted.
301 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
308 A convenience class, same as Prima::Button but with default square
309 shape and text property set to an empty string.
310
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 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 Although this property is present on the Prima::CheckBox, it is not
330 used in there.
331 Methods
333 check
334 Alias to checked(1)
335 uncheck
337 Alias to checked(0)
338 toggle
340 Reverts the "checked" state of the button and returns the new
341 state.
342
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 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 Events
353 Check
354 Called when a button is checked.
355
357 Represents a standard check box button, that can be either in checked,
358 or in unchecked state.
359 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
365 The class to be used as a container of radio and check-box buttons. It
366 can, however, contain any other widgets.
367 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 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 Events
378 RadioClick BUTTON
379 Called whenever one of children radio buttons is checked. BUTTON
380 parameter contains the newly checked button.
381 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 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 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
400 This class is obsolete and is same as "Prima::GroupBox".
401
403 This class is obsolete and is same as "Prima::GroupBox".
404
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 Tilde escaping in "text" is not realized, but is planned to. There
413 currently is no way to avoid tilde underscoring.
414 Radio buttons can get unexpectedly checked when used in notebooks. See
416 auto.
417 "Prima::GroupBox::value" parameter is an integer, which size is
419 architecture-dependent. Shift towards a vector is considered a good
420 idea.
421
423 Dmitry Karasik, <dmitry@karasik.eu.org>.
424
426 Prima, Prima::Widget, Prima::Window, Prima::IntUtils,
427 Prima::Drawable::Metafile, Prima::StdBitmap, examples/buttons.pl,
428 examples/buttons2.pl.
429perl v5.36.0 2022-07-22 Prima::Buttons(3)