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
176 Selects index of the default sub-image.
177 Default value: 0
179 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 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 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 Default value: 0
218 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 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 Default value: undef
234 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 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 imageScale SCALE
246 Contains zoom factor for the image.
247 Default value: 1
249 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 $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 The toolkit defines the following constants for "modalResult" use:
265 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 However, any other integer value can be safely used.
276 Default value: 0
278 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 Default value: true
287 See also: "ui_scale" in Prima::Image .
289 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 transparent BOOLEAN
296 See "transparent" in Prima::Widget. If set, the background is not
297 painted.
298 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
305 A convenience class, same as Prima::Button but with default square
306 shape and text property set to an empty string.
307
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 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 Although this property is present on the Prima::CheckBox, it is not
327 used in there.
328 Methods
330 check
331 Alias to checked(1)
332 uncheck
334 Alias to checked(0)
335 toggle
337 Reverts the "checked" state of the button and returns the new
338 state.
339
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 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 Events
350 Check
351 Called when a button is checked.
352
354 Represents a standard check box button, that can be either in checked,
355 or in unchecked state.
356 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
362 The class to be used as a container of radio and check-box buttons. It
363 can, however, contain any other widgets.
364 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 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 Events
375 RadioClick BUTTON
376 Called whenever one of children radio buttons is checked. BUTTON
377 parameter contains the newly checked button.
378 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 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 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
397 This class is obsolete and is same as "Prima::GroupBox".
398
400 This class is obsolete and is same as "Prima::GroupBox".
401
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 Tilde escaping in "text" is not realized, but is planned to. There
410 currently is no way to avoid tilde underscoring.
411 Radio buttons can get unexpectedly checked when used in notebooks. See
413 auto.
414 "Prima::GroupBox::value" parameter is an integer, which size is
416 architecture-dependent. Shift towards a vector is considered a good
417 idea.
418
420 Dmitry Karasik, <dmitry@karasik.eu.org>.
421
423 Prima, Prima::Widget, Prima::Window, Prima::IntUtils, Prima::StdBitmap,
424 examples/buttons.pl, examples/buttons2.pl.
425perl v5.32.0 2020-07-28 Prima::Buttons(3)