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 autoShaping BOOLEAN
145 If 1, the button "shape" is autmatically update when the button
146 size and/or font are updated, if the current skin can make use of
147 non-rectangular shapes. Generally is unneeded unless the owner of
148 the button has a different back color or features some custom
149 painting.
150 Default value: 0
152 See also: examples/triangle.pl, examples/dragdrop.pl
154 autoWidth BOOLEAN
156 If 1, the button width is automatically changed as text extensions
157 change.
158 Default value: 1
160 borderWidth INTEGER
162 Width of 3d-shade border around the button.
163 Default value: 2
165 checkable BOOLEAN
167 Selects if the button toggles checked state when the user presses
168 it.
169 Default value: 0
171 checked BOOLEAN
173 Selects whether the button is checked or not. Only actual when
174 checkable property is set. See also holdGlyph.
175 Default value: 0
177 default BOOLEAN
179 Defines if the button should react when the user presses the enter
180 button. If set, the button is drawn with the black border,
181 indicating that it executes the 'default' action. Useful for OK-
182 buttons in dialogs.
183 Default value: 0
185 defaultGlyph INTEGER | IMAGE | METAFILE
187 Selects index of the default sub-image.
188 Default value: 0
190 disabledGlyph INTEGER | IMAGE | METAFILE
192 Selects index of the sub-image for the disabled button state. If
193 "image" does not contain such sub-image, the "defaultGlyph" sub-
194 image is drawn, and is dimmed over with draw_veil method.
195 Default value: 1
197 flat BOOLEAN
199 Selects special 'flat' mode, when a button is painted without a
200 border when the mouse pointer is outside the button boundaries.
201 This mode is useful for the toolbar buttons. See also hiliteGlyph.
202 Default value: 0
204 glyphs INTEGER
206 If a button is to be drawn with the image, it can be passed in the
207 image property. If, however, the button must be drawn with several
208 different images, there are no several image-holding properties.
209 Instead, the image object can be logically split vertically into
210 several equal sub-images. This allows the button resource to
211 contain all button states into one image file. The "glyphs"
212 property assigns how many such sub-images the image object
213 contains.
214 The sub-image indices can be assigned for rendition of the
216 different states. These indices are selected by the following
217 integer properties: defaultGlyph, hiliteGlyph, disabledGlyph,
218 pressedGlyph, holdGlyph.
219 Default value: 1
221 hiliteGlyph INTEGE | IMAGE | METAFILER
223 Selects index of the sub-image for the state when the mouse pointer
224 is over the button. This image is used only when flat property is
225 set. If "image" does not contain such sub-image, the
226 "defaultGlyph" sub-image is drawn.
227 Default value: 0
229 holdGlyph INTEGE | IMAGE | METAFILER
231 Selects index of the sub-image for the state when the button is
232 checked. This image is used only when checkable property is set.
233 If "image" does not contain such sub-image, the "defaultGlyph" sub-
234 image is drawn.
235 Default value: 3
237 image OBJECT
239 If set, the image object is drawn next with the button text, over
240 or left to it ( see vertical property ). If OBJECT contains several
241 sub-images, then the corresponding sub-image is drawn for each
242 button state. See glyphs property.
243 Can also be a "Prima::Drawable::Metafile" object, however,
245 "imageScale" factor wouldn't work on it.
246 Default value: undef
248 imageFile FILENAME
250 Alternative to image selection by loading an image from the file.
251 During the creation state, if set together with image property, is
252 superseded by the latter.
253 To allow easy multiframe image access, FILENAME string is checked
255 if it contains a number after a colon in the string end. Such,
256 imageFile('image.gif:3') call would load the fourth frame in
257 "image.gif" file.
258 imageScale SCALE
260 Contains zoom factor for the image.
261 Default value: 1
263 modalResult INTEGER
265 Contains a custom integer value, preferably one of "mb::XXX"
266 constants. If a button with non-zero "modalResult" is owned by a
267 currently executing modal window, and is pressed, its "modalResult"
268 value is copied to the "modalResult" property of the owner window,
269 and the latter is closed. This scheme is helpful for the dialog
270 design:
271 $dialog-> insert( 'Prima::Button', modalResult => mb::OK,
273 text => '~Ok', default => 1);
274 $dialog-> insert( 'Prima::Button', modalResult => mb::Cancel,
275 text => 'Cancel);
276 return if $dialog-> execute != mb::OK.
277 The toolkit defines the following constants for "modalResult" use:
279 mb::OK or mb::Ok
281 mb::Cancel
282 mb::Yes
283 mb::No
284 mb::Abort
285 mb::Retry
286 mb::Ignore
287 mb::Help
288 However, any other integer value can be safely used.
290 Default value: 0
292 smoothScaling BOOL
294 Tries to represent the image as smooth as possible. When the system
295 doesn't support ARGB layering, icon objects smooth scaling will be
296 restricted to integer-scaling only (i.e. 2x, 3x etc) because smooth
297 color plane will not match pixelated mask plane, and because box-
298 scaling with non-integer zooms looks ugly.
299 Default value: true
301 See also: "ui_scale" in Prima::Image .
303 pressedGlyph INTEGER | IMAGE | METAFILE
305 Selects index of the sub-image for the pressed state of the button.
306 If "image" does not contain such sub-image, the "defaultGlyph" sub-
307 image is drawn.
308 transparent BOOLEAN
310 See "transparent" in Prima::Widget. If set, the background is not
311 painted.
312 vertical BOOLEAN
314 Determines the position of image next to the text string. If 1, the
315 image is drawn above the text; left to the text if 0. In a special
316 case when text is an empty string, image is centered.
317
319 A convenience class, same as Prima::Button but with default square
320 shape and text property set to an empty string.
321
323 An abstract class with common functionality of Prima::CheckBox and
324 Prima::RadioButton. Reassigns default actions on tab and back-tab keys,
325 so the sibling cluster widgets are not selected. Has "ownerBackColor"
326 property set to 1, to prevent usage of background color from
327 "wc::Button" palette.
328 Properties
330 auto BOOLEAN
331 If set, the button is automatically checked when the button is in
332 focus. This functionality allows arrow key walking by the radio
333 buttons without pressing spacebar key. It is also has a drawback,
334 that if a radio button gets focused without user intervention, or
335 indirectly, it also gets checked, so that behavior might cause
336 confusion. The said can be exemplified when an unchecked radio
337 button in a notebook widget gets active by turning the notebook
338 page.
339 Although this property is present on the Prima::CheckBox, it is not
341 used in there.
342 Methods
344 check
345 Alias to checked(1)
346 uncheck
348 Alias to checked(0)
349 toggle
351 Reverts the "checked" state of the button and returns the new
352 state.
353
355 Represents a standard radio button, that can be either in checked, or
356 in unchecked state. When checked, delivers RadioClick event to the
357 owner ( if the latter provides one ).
358 The button uses the standard toolkit images with "sbmp::RadioXXX"
360 indices. If the images can not be loaded, the button is drawn with the
361 graphic primitives.
362 Events
364 Check
365 Called when a button is checked.
366
368 Represents a standard check box button, that can be either in checked,
369 or in unchecked state.
370 The button uses the standard toolkit images with "sbmp::CheckBoxXXX"
372 indices. If the images can not be loaded, the button is drawn with
373 graphic primitives.
374
376 The class to be used as a container of radio and check-box buttons. It
377 can, however, contain any other widgets.
378 The widget draws a 3d-shaded box on its boundaries and a text string in
380 its upper left corner. Uses "transparent" property to determine if it
381 needs to paint its background.
382 The class does not provide a method to calculate the extension of the
384 inner rectangle. However, it can be safely assumed that all offsets
385 except the upper are 5 pixels. The upper offset is dependent on a
386 font, and constitutes the half of the font height.
387 Events
389 RadioClick BUTTON
390 Called whenever one of children radio buttons is checked. BUTTON
391 parameter contains the newly checked button.
392 The default action of the class is that all checked buttons, except
394 BUTTON, are unchecked. Since the flow type of "RadioClick" event is
395 "nt::PrivateFirst", "on_radioclick" method must be directly
396 overloaded to disable this functionality.
397 Properties
399 border BOOLEAN
400 If set (default), draws a border along the widget boundaries
401 index INTEGER
403 Checks the child radio button with "index". The indexing is based
404 on the index in the widget list, returned by
405 "Prima::Widget::widgets" method.
406 value BITFIELD
408 BITFIELD is an unsigned integer, where each bit corresponds to the
409 "checked" state of a child check-box button. The indexing is based
410 on the index in the widget list, returned by
411 "Prima::Widget::widgets" method.
412
414 This class is obsolete and is same as "Prima::GroupBox".
415
417 This class is obsolete and is same as "Prima::GroupBox".
418
420 The push button is not capable of drawing anything other than single
421 line of text and single image. If an extended functionality is needed,
422 instead of fully rewriting the painting procedure, it might be
423 reasonable to overload "put_image_indirect" method of "Prima::Button",
424 and perform custom output there.
425 Tilde escaping in "text" is not realized, but is planned to. There
427 currently is no way to avoid tilde underscoring.
428 Radio buttons can get unexpectedly checked when used in notebooks. See
430 auto.
431 "Prima::GroupBox::value" parameter is an integer, which size is
433 architecture-dependent. Shift towards a vector is considered a good
434 idea.
435
437 Dmitry Karasik, <dmitry@karasik.eu.org>.
438
440 Prima, Prima::Widget, Prima::Window, Prima::Drawable::Metafile,
441 Prima::StdBitmap, examples/buttons.pl, examples/buttons2.pl.
442perl v5.38.0 2023-07-21 Prima::Buttons(3)