1pod::Prima::Widget(3) User Contributed Perl Documentationpod::Prima::Widget(3)
2
6 Prima::Widget - window management
7
9 # create a widget
10 my $widget = Prima::Widget-> new(
11 size => [ 200, 200],
12 color => cl::Green,
13 visible => 0,
14 onPaint => sub {
15 my ($self,$canvas) = @_;
16 $canvas-> clear;
17 $canvas-> text_out( "Hello world!", 10, 10);
18 },
19 );
20 # manipulate the widget
22 $widget-> origin( 10, 10);
23 $widget-> show;
24
26 Prima::Widget is a descendant of Prima::Component, a class, especially
27 crafted to reflect and govern properties of a system-dependent window,
28 such as its position, hierarchy, outlook etc. Prima::Widget is mapped
29 into the screen space as a rectangular area, with distinct boundaries,
30 pointer and sometimes cursor, and a user-selectable input focus.
31
33 Prima::Widget class and its descendants are used widely throughout the
34 toolkit, and, indeed provide almost all its user interaction and input-
35 output. The notification system, explained in Prima::Object, is
36 employed in Prima::Widget heavily, providing the programmer with
37 unified access to the system-generated events, that occur when the user
38 moves windows, clicks the mouse, types the keyboard, etc. Descendants
39 of Prima::Widget use the internal, the direct method of overriding the
40 notifications, whereas end programs tend to use the toolkit widgets
41 equipped with anonymous subroutines ( see Prima::Object for the
42 details).
43 The class functionality is much more extensive comparing to the other
45 built-in classes, and therefore the explanations are grouped in several
46 topics.
47
49 The widget creation syntax is the same as for the other Prima objects:
50 Prima::Widget-> create(
52 name => 'Widget',
53 size => [ 20, 10],
54 onMouseClick => sub { print "click\n"; },
55 owner => $owner,
56 );
57 In the real life, a widget must be almost always explicitly told about
59 its owner. The owner object is either a Prima::Widget descendant, in
60 which case the widget is drawn inside its inferior, or the application
61 object, and in the latter case a widget becomes top-level. This is the
62 reason why the "insert" syntax is much more often used, as it is more
63 illustrative and is more convenient for creating several widgets in one
64 call ( see Prima::Object ).
65 $owner-> insert( 'Prima::Widget',
67 name => 'Widget',
68 size => [ 20, 10],
69 onMouseClick => sub { print "click\n"; },
70 );
71 These two examples produce identical results.
73 As a descendant of Prima::Component, Prima::Widget sends "Create"
75 notification when created ( more precisely, after its init stage is
76 finished. See Prima::Object for details). This notification is called
77 and processed within "create()" call. In addition, another notification
78 "Setup" is sent after the widget is created. This message is posted, so
79 it is called within "create()" but processed in the application event
80 loop. This means that the execution time of "Setup" is uncertain, as it
81 is with all posted messages; its delivery time is system-dependent, so
82 its use must be considered with care.
83 After a widget is created, it is usually asked to render its content,
85 provided that the widget is visible. This request is delivered by means
86 of "Paint" notification.
87 When the life time of a widget is over, its method "destroy()" is
89 called, often implicitly. If a widget gets destroyed because its owner
90 also does, it is guaranteed that the children widgets will be destroyed
91 first, and the owner afterwards. In such situation, widget can operate
92 with a limited functionality both on itself and its owners ( see
93 Prima::Object, Creation section ).
94
96 A widget can use two different ways for representing its graphic
97 content to the user. The first method is event-driven, when the "Paint"
98 notification arrives, notifying the widget that it must re-paint
99 itself. The second is the 'direct' method, when the widget generates
100 graphic output unconditionally.
101 Event-driven rendering
103 A notification responsible for widget repainting is "Paint". It
104 provides a single ( besides the widget itself ) parameter, an object,
105 where the drawing is performed. In an event-driven call, it is always
106 equals to the widget. However, if a custom mechanism should be used
107 that directly calls, for example,
108 $widget-> notify('Paint', $some_other_widget);
110 for whatever purpose, it is recommended ( not required, though ), to
112 use this parameter, not the widget itself for painting and drawing
113 calls.
114 The example of "Paint" callback is quite simple:
116 Prima::Widget-> create(
118 ...
119 onPaint => sub {
120 my ( $self, $canvas) = @_;
121 $canvas-> clear;
122 $canvas-> text_out("Clicked $self->{clicked} times", 10, 10);
123 },
124 onMouseClick => sub {
125 $_[0]-> {clicked}++;
126 $_[0]-> repaint;
127 },
128 );
129 The example uses several important features of the event-driven
131 mechanism. First, no "begin_paint()"/"end_paint()" brackets are used
132 within the callback. These are called implicitly. Second, when the
133 custom refresh of the widget's graphic content is needed, no code like
134 "notify(q(Paint))" is used - "repaint()" method is used instead. It
135 must be noted, that the actual execution of "Paint" callbacks might or
136 might not occur inside the "repaint()" call. This behavior is governed
137 by the "::syncPaint" property. "repaint()" marks the whole widget's
138 area to be refreshed, or invalidates the area. For the finer gradation
139 of the area that should be repainted, "invalidate_rect()" and
140 "validate_rect()" pair of functions is used. Thus,
141 $x-> repaint()
143 code is a mere alias to
145 $x-> invalidate_rect( 0, 0, $x-> size);
147 call. It must be realized, that the area, passed to "invalidate_rect()"
149 only in its ideal ( but a quite often ) execution case will be
150 pertained as a clipping rectangle when a widget executes its "Paint"
151 notification. The user and system interactions can result in
152 exposition of other parts of a widget ( like, moving windows over a
153 widget ), and the resulting clipping rectangle can be different from
154 the one that was passed to "invalidate_rect()". Moreover, the clipping
155 rectangle can become empty as the result of these influences, and the
156 notification will not be called at all.
157 Invalid rectangle is presented differently inside and outside the
159 drawing mode. The first, returned by "::clipRect", employs inclusive-
160 inclusive coordinates, whereas "invalidate_rect()", "validate_rect()"
161 and "get_invalid_rect()" - inclusive-exclusive coordinates. The ideal
162 case exemplifies the above said:
163 $x-> onPaint( sub {
165 my @c = $_[0]-> clipRect;
166 print "clip rect:@c\n";
167 });
168 $x-> invalidate_rect( 10, 10, 20, 20);
169 ...
170 clip rect: 10 10 19 19
171 As noted above, "::clipRect" property is set to the clipping rectangle
173 of the widget area that is needed to be refreshed, and an event handler
174 code can take advantage of this information, increasing the efficiency
175 of the painting procedure.
176 Further assignments of "::clipRect" property do not make possible over-
178 painting on the screen area that lies outside the original clipping
179 region. This is also valid for all paint operations, however since the
180 original clipping rectangle is the full area of a canvas, this rule is
181 implicit and unnecessary, because whatever large the clipping rectangle
182 is, drawing and painting cannot be performed outside the physical
183 boundaries of the canvas.
184 Direct rendering
186 The direct rendering, contrary to the event-driven, is initiated by the
187 program, not by the system. If a programmer wishes to paint over a
188 widget immediately, then "begin_paint()" is called, and, if successful,
189 the part of the screen occupied by the widget is accessible to the
190 drawing and painting routines.
191 This method is useful, for example, for graphic demonstration programs,
193 that draw continuously without any input. Another field is the screen
194 drawing, which is performed with Prima::Application class, that does
195 not have "Paint" notification. Application's graphic canvas represents
196 the whole screen, allowing over-drawing the graphic content of other
197 programs.
198 The event-driven rendering method adds implicit
200 "begin_paint()"/"end_paint()" brackets ( plus some system-dependent
201 actions ) and is a convenience version of the direct rendering.
202 Sometimes, however, the changes needed to be made to a widget's graphic
203 context are so insignificant, so the direct rendering method is
204 preferable, because of the cleaner and terser code. As an example might
205 serve a simple progress bar, that draws a simple colored bar. The
206 event-driven code would be ( in short, omitting many details ) as such:
207 $bar = Widget-> create(
209 width => 100,
210 onPaint => sub {
211 my ( $self, $canvas) = @_;
212 $canvas-> color( cl::Blue);
213 $canvas-> bar( 0, 0, $self-> {progress}, $self-> height);
214 $canvas-> color( cl::Back);
215 $canvas-> bar( $self-> {progress}, 0, $self-> size);
216 },
217 );
218 ...
219 $bar-> {progress} += 10;
220 $bar-> repaint;
221 # or, more efficiently, ( but clumsier )
222 # $bar-> invalidate_rect( $bar->{progress}-10, 0,
223 # $bar->{progress}, $bar-> height);
224 And the direct driven:
226 $bar = Widget-> create( width => 100 );
228 ...
229 $bar-> begin_paint;
230 $bar-> color( cl::Blue);
231 $bar-> bar( $progress, 0, $progress + 10, $bar-> height);
232 $bar-> end_paint;
233 $progress += 10;
234 The pros and contras are obvious: the event-driven rendered widget
236 correctly represents the status after an eventual repaint, for example
237 when the user sweeps a window over the progress bar widget. The direct
238 method cannot be that smart, but if the status bar is an insignificant
239 part of the program, the trade-off of the functionality in favor to the
240 code simplicity might be preferred.
241 Both methods can be effectively disabled using the paint locking
243 mechanism. The "lock()" and "unlock()" methods can be called several
244 times, stacking the requests. This feature is useful because many
245 properties implicitly call "repaint()", and if several of these
246 properties activate in a row, the unnecessary redrawing of the widget
247 can be avoided. The drawback is that the last "unlock()" call triggers
248 "repaint()" unconditionally.
249
251 Basic properties
252 A widget always has its position and size determined, even if it is not
253 visible on the screen. Prima::Widget provides several properties with
254 overlapping functionality, that govern the geometry of a widget. The
255 base properties are "::origin" and "::size", and the derived are
256 "::left", "::bottom", "::right", "::top", "::width", "::height" and
257 "::rect". "::origin" and "::size" operate with two integers, "::rect"
258 with four, others with one integer value.
259 As the Prima toolkit coordinate space begins in the lower bottom
261 corner, the combination of "::left" and "::bottom" is same as
262 "::origin", and combination of "::left", "::bottom", "::right" and
263 "::top" - same as "::rect".
264 When a widget is moved or resized, correspondingly two notifications
266 occur: "Move" and "Size". The parameters to both are old and new
267 position and size. The notifications occur irrespectable to whether the
268 geometry change was issued by the program itself or by the user.
269 Implicit size regulations
271 Concerning the size of a widget, two additional two-integer properties
272 exist, "::sizeMin" and "::sizeMax", that constrain the extension of a
273 widget in their boundaries. The direct call that assigns values to the
274 size properties that lie outside "::sizeMin" and "::sizeMax"
275 boundaries, will fail - the widget extension will be adjusted to the
276 boundary values, not to the specified ones.
277 Change to widget's position and size can occur not only by an explicit
279 call to one of the geometry properties. The toolkit contains implicit
280 rules, that can move and resize a widget corresponding to the flags,
281 given to the "::growMode" property. The exact meaning of the "gm::XXX"
282 flags is not given here ( see description to "::growMode" in API
283 section ), but in short, it is possible with simple means to maintain
284 widget's size and position regarding its owner, when the latter is
285 resized. By default, and the default behavior corresponds to
286 "::growMode" 0, widget does not change neither its size nor position
287 when its owner is resized. It stays always in 'the left bottom corner'.
288 When, for example, a widget is expected to stay in 'the right bottom
289 corner', or 'the left top corner', the "gm::GrowLoX" and "gm::GrowLoY"
290 values must be used, correspondingly. When a widget is expected to
291 cover, for example, its owner's lower part and change its width in
292 accord with the owner's, ( a horizontal scroll bar in an editor window
293 is the example), the "gm::GrowHiX" value must be used.
294 When this implicit size change does occur, the "::sizeMin" and
296 "::sizeMax" do take their part as well - they still do not allow the
297 widget's size to exceed their boundaries. However, this algorithm has a
298 problem, that is illustrated by the following setup. Imagine a widget
299 with size-dependent "::growMode" ( with "gm::GrowHiX" or "gm::GrowHiY"
300 bits set ) that must maintain certain relation between the owner's size
301 and its own. If the implicit size change would depend on the actual
302 widget size, derived as a result from the previous implicit size
303 action, then its size (and probably position) will be incorrect after
304 an attempt is made to change the widget's size to values outside the
305 size boundaries.
306 Example: child widget has width 100, growMode set to "gm::GrowHiX" and
308 sizeMin set to (95, 95). Its owner has width 200. If the owner widget
309 changes gradually its width from 200 to 190 and then back, the
310 following width table emerges:
311 Owner Child
313 Initial state 200 100
314 Shrink 195 -5 95
315 Shrink 190 -5 95 - as it can not be less than 95.
316 Grow 195 +5 100
317 Grow 200 +5 105
318 That effect would exist if the differential-size algorithm would be
320 implemented, - the owner changes width by 5, and the child does the
321 same. The situation is fixed by introducing the virtual size term.
322 The "::size" property is derived from virtual size, and as "::size"
323 cannot exceed the size boundaries, virtual size can. It can even
324 accept the negative values. With this intermediate stage added, the
325 correct picture occurs:
326 Owner Child's Child's
328 virtual width width
329 Initial state 200 100 100
330 Shrink 195 -5 95 95
331 Shrink 190 -5 90 95
332 Grow 195 +5 95 95
333 Grow 200 +5 100 100
334 Geometry managers
336 The concept of geometry managers is imported from Tk, which in turn is
337 a port of Tcl-Tk. The idea behind it is that a widget size and position
338 is governed by one of the managers, which operate depending on the
339 specific options given to the widget. The selection is operated by
340 "::geometry" property, and is one of "gt::XXX" constants. The native (
341 and the default ) geometry manager is the described above grow-mode
342 algorithm ( "gt::GrowMode" ). The currently implemented Tk managers are
343 packer ( "gt::Pack" ) and placer ( "gt::Place"). Each has its own set
344 of options and methods, and their manuals are provided separately in
345 Prima::Widget::pack and Prima::Widget::place ( the manpages are also
346 imported from Tk ).
347 Another concept that comes along with geometry managers is the
349 'geometry request size'. It is realized as a two-integer property
350 "::geomSize", which reflects the size deduced by some intrinsic widget
351 knowledge. The idea is that "::geomSize" it is merely a request to a
352 geometry manager, whereas the latter changes "::size" accordingly. For
353 example, a button might set its 'intrinsic' width in accord with the
354 width of text string displayed in it. If the default width for such a
355 button is not overridden, it is assigned with such a width. By default,
356 under "gt::GrowMode" geometry manager, setting "::geomSize" ( and its
357 two semi-alias properties "::geomWidth" and "::geomHeight" ) also
358 changes the actual widget size.Moreover, when the size is passed to the
359 Widget initialization code, "::size" properties are used to initialize
360 "::geomSize". Such design minimizes the confusion between the two
361 properties, and also minimizes the direct usage of "::geomSize",
362 limiting it for selecting advisory size in widget internal code.
363 The geometry request size is useless under "gt::GrowMode" geometry
365 manager, but Tk managers use it extensively.
366 Relative coordinates
368 Another geometry issue, or rather a programming technique must be
369 mentioned - the relative coordinates. It is the well-known problem,
370 when a dialog window, developed with one font looks garbled on another
371 system with another font. The relative coordinates solve that problem;
372 the solution is to use the "::designScale" two-integer property, the
373 width and height of the font, that was used when the dialog window was
374 designed. With this property supplied, the position and size supplied
375 when a widget is actually created, are transformed in proportion
376 between the designed and the actual font metrics.
377 The relative coordinates can be used only when passing the geometry
379 properties values, and only before the creation stage, before a widget
380 is created, because the scaling calculations perform in
381 Prima::Widget::"profile_check_in()" method.
382 In order to employ the relative coordinates scheme, the owner ( or the
384 dialog ) widget must set its "::designScale" to the font metrics and
385 "::scaleChildren" property to 1. Widgets, created with owner that
386 meets these requirements, participate in the relative coordinates
387 scheme. If a widget must be excluded from the relative geometry
388 applications, either the owner's property "::scaleChildren" must be set
389 to 0, or the widget's "::designScale" must be set to "undef". As the
390 default "::designScale" value is "undef", no default implicit relative
391 geometry schemes are applied.
392 The "::designScale" property is auto-inherited; its value is copied to
394 the children widgets, unless the explicit "::designScale" was given
395 during the widget's creation. This is used when such a child widget
396 serves as an owner for some other grand-children widgets; the
397 inheritance scheme allows the grand- ( grand- etc ) children to
398 participate in the relative geometry scheme.
399 Note: it is advised to test such applications with the Prima::Stress
401 module, which assigns a random font as the default, so the testing
402 phase does not involve tweaking of the system settings.
403
405 In case when two widgets overlap, one of these is drawn in full,
406 whereas the another only partly. Prima::Widget provides management of
407 the Z-axis ordering, but since Z-ordering paradigm can hardly be fit
408 into the properties scheme, the toolkit uses methods instead.
409 A widget can use four query methods: "first()", "last()", "next()", and
411 "prev()". These return, correspondingly, the first and the last widgets
412 in Z-order stack, and the direct neighbors of a widget ( $widget->
413 next-> prev always equals to the $widget itself, given that $widget->
414 next exists ).
415 The last widget is the topmost one, the one that is drawn fully. The
417 first is the most obscured one, given that all the widgets overlap.
418 Z-order can also be changed at runtime ( but not during widget's
420 creation). There are three methods: "bring_to_front()", that sets the
421 widget last in the order, making it topmost, "send_to_back()", that
422 does the reverse, and "insert_behind()", that sets a widget behind the
423 another widget, passed as an argument.
424 Changes to Z-order trigger "ZOrderChanged" notification.
426
428 By default, if a widget is a child to a widget or a window, it
429 maintains two features: it is clipped by its owner's boundaries and is
430 moved together as the owner widget moves, i.e. a child is inferior to
431 its parent. However, a widget without a parent still does have a valid
432 owner. Instead of implementing parent property, the "::clipOwner"
433 property was devised. It is 1 by default, and if it is 1, then owner of
434 a widget is its parent, at the same time. However, when it is 0, many
435 things change. The widget is neither clipped nor moved together with
436 its parent. The widget become parentless, or, more strictly speaking,
437 the screen becomes its parent. Moreover, the widget's origin offset is
438 calculated then not from the owner's coordinates but from the screen,
439 and mouse events in the widget do not transgress implicitly to the
440 owner's top-level window eventual decorations.
441 The same results are produced if a widget is inserted in the
443 application object, which does not have screen visualization. A widget
444 that belongs to the application object, can not reset its "::clipOwner"
445 value to 1.
446 The "::clipOwner" property opens a possibility for the toolkit widgets
448 to live inside other programs' windows. If the "::parentHandle" is
449 changed from its default "undef" value to a valid system window handle,
450 the widget becomes child to this window, which can belong to any
451 application residing on the same display. This option is dangerous,
452 however: normally widgets never get destroyed by no reason. A top-level
453 window is never destroyed before its "Close" notification grants the
454 destruction. The case with "::parentHandle" is special, because a
455 widget, inserted into an alien application, must be prepared to be
456 destroyed at any moment. It is recommended to use prior knowledge about
457 such the application, and, even better, use one or another inter-
458 process communication scheme to interact with it.
459 A widget does not need to undertake anything special to become an
461 'owner'. Any widget, that was set in "::owner" property on any other
462 widget, becomes an owner automatically. Its "get_widgets()" method
463 returns non-empty widget list. "get_widgets()" serves same purpose as
464 Prima::Component::"get_components()", but returns only Prima::Widget
465 descendants.
466 A widget can change its owner at any moment. The "::owner" property is
468 both readable and writable, and if a widget is visible during the owner
469 change, it is immediately appeared under different coordinates and
470 different clipping condition after the property change, given that its
471 "::clipOwner" is set to 1.
472
474 A widget is created visible by default. Visible means that it is shown
475 on the screen if it is not shadowed by other widgets or windows. The
476 visibility is governed by the "::visible" property, and its two
477 convenience aliases, "show()" and "hide()".
478 When a widget is invisible, its geometry is not discarded; the widget
480 pertains its position and size, and is subject to all previously
481 discussed implicit sizing issues. When change to "::visible" property
482 is made, the screen is not updated immediately, but in the next event
483 loop invocation, because uncovering of the underlying area of a hidden
484 widget, and repainting of a new-shown widget both depend onto the
485 event-driven rendering functionality. If the graphic content must be
486 updated, "update_view()" must be called, but there's a problem. It is
487 obvious that if a widget is shown, the only content to be updated is
488 its own. When a widget becomes hidden, it may uncover more than one
489 widget, depending on the geometry, so it is unclear what widgets must
490 be updated. For the practical reasons, it is enough to get one event
491 loop passed, by calling "yield()" method of the $::application object.
492 The other notifications may pass here as well, however.
493 There are other kinds of visibility. A widget might be visible, but one
495 of its owners might not. Or, a widget and its owners might be visible,
496 but they might be over-shadowed by the other windows. These conditions
497 are returned by "showing()" and "exposed()" functions, correspondinly.
498 These return boolean values corresponding to the condition described.
499 So, if a widget is 'exposed', it is 'showing' and 'visible';
500 "exposed()" returns always 0 if a widget is either not 'showing' or not
501 'visible'. If a widget is 'showing', then it is always 'visible'.
502 "showing()" returns always 0 if a widget is invisible.
503 Visibility changes trigger "Hide" and "Show" notifications.
505
507 One of the key points of any GUI is that only one window at a time can
508 possess a focus. The widget is focused, if the user's keyboard input is
509 directed to it. The toolkit adds another layer in the focusing scheme,
510 as often window managers do, highlighting the decorations of a top-
511 level window over a window with the input focus.
512 Prima::Widget property "::focused" governs the focused state of a
514 widget. It is sometimes too powerful to be used. Its more often
515 substitutes, "::selected" and "::current" properties provide more
516 respect to widget hierarchy.
517 "::selected" property sets focus to a widget if it is allowed to be
519 focused, by the usage of the "::selectable" property. With this
520 granted, the focus is passed to the widget or to the one of its (
521 grand-) children. So to say, when 'selecting' a window with a text
522 field by clicking on a window, one does not expect the window itself to
523 be focused, but the text field. To achieve this goal and reduce
524 unnecessary coding, the "::current" property is introduced. With all
525 equal conditions, a widget that is 'current' gets precedence in getting
526 selected over widgets that are not 'current'.
527 De-selecting, in its turn, leaves the system in such a state when no
529 window has input focus. There are two convenience shortcuts "select()"
530 and "deselect()" defined, aliased to selected(1) and selected(0),
531 correspondingly.
532 As within the GUI space, there can be only one 'focused' widget, so
534 within the single widget space, there can be only one 'current' widget.
535 A widget can be marked as a current by calling "::current" ( or,
536 identically, "::currentWidget" on the owner widget ). The
537 reassignments are performed automatically when a widget is focused.
538 The reverse is also true: if a widget is explicitly marked as
539 'current', and belongs to the widget tree with the focus in one of its
540 widgets, then the focus passed to the 'current' widget, or down to its
541 hierarchy if it is not selectable.
542 These relations between current widget pointer and focus allow the
544 toolkit easily implement the focusing hierarchy. The focused widget is
545 always on the top of the chain of its owner widgets, each of whose is a
546 'current' widget. If, for example, a window that contains a widget that
547 contains a focused button, become un-focused, and then user selects the
548 window again, then the button will become focused automatically.
549 Changes to focus produce "Enter" and "Leave" notifications.
551 Below discussed mouse- and keyboard- driven focusing schemes. Note
553 that all of these work via "::selected", and do not focus the widgets
554 with "::selectable" property set to 0.
555 Mouse-aided focusing
557 Typically, when the user clicks the left mouse button on a widget, the
558 latter becomes focused. One can note that not all widgets become
559 focused after the mouse click - scroll bars are the examples. Another
560 kind of behavior is the described above window with the text field -
561 clicking mouse on a window focuses a text field.
562 Prima::Widget has the "::selectingButtons" property, a combination of
564 mb::XXX ( mouse buttons ) flags. If the bits corresponding to the
565 buttons are set, then click of this button will automatically call
566 ::selected(1) ( not ::focused(1) ).
567 Another boolean property, "::firstClick" determines the behavior when
569 the mouse button action is up to focus a widget, but the widget's top-
570 level window is not active. The default value of "::firstClick" is 1,
571 but if set otherwise, the user must click twice to a widget to get it
572 focused. The property does not influence anything if the top-level
573 window was already active when the click event occured.
574 Due to different GUI designs, it is hardly possibly to force selection
576 of one top-level window when the click was on the another. The window
577 manager or the OS can interfere, although this does not always happen,
578 and produces different results on different platforms. Since the
579 primary goal of the toolkit is portability, such functionality must be
580 considered with care. Moreover, when the user selects a window by
581 clicking not on the toolkit-created widgets, but on the top-level
582 window decorations, it is not possible to discern the case from any
583 other kind of focusing.
584 Keyboard focusing
586 The native way to navigate between the toolkit widgets are tab- and
587 arrow- navigation. The tab ( and its reverse, shift-tab ) key
588 combinations circulate the focus between the widgets in same top-level
589 group ( but not inside the same owner widget group ). The arrow keys,
590 if the focused widget is not interested in these keystrokes, move the
591 focus in the specified direction, if it is possible. The methods that
592 provide the navigations are available and called "next_tab()" and
593 "next_positional()", correspondingly ( see API for the details).
594 When "next_positional()" operates with the geometry of the widgets,
596 "next_tab()" uses the "::tabStop" and "::tabOrder" properties.
597 "::tabStop", the boolean property, set to 1 by default, tells if a
598 widget is willing to participate in tab-aided focus circulation. If it
599 doesn't, "next_tab()" never uses it in its iterations. "::tabOrder"
600 value is an integer, unique within the sibling widgets ( sharing same
601 owner ) list, and is used as simple tag when the next tab-focus
602 candidate is picked up. The default "::tabOrder" value is -1, which
603 changes automatically after widget creation to a unique value.
604
606 The toolkit responds to the two basic means of the user input - the
607 keyboard and the mouse. Below described three aspects of the input
608 handling - the event-driven, the polling and the simulated input
609 issues. The event-driven input is the more or less natural way of
610 communicating with the user, so when the user presses the key or moves
611 the mouse, a system event occurs and triggers the notification in one
612 or more widgets. Polling methods provide the immediate state of the
613 input devices; the polling is rarely employed, primarily because of its
614 limited usability, and because the information it provides is passed to
615 the notification callbacks anyway. The simulated input is little more
616 than "notify()" call with specifically crafted parameters. It interacts
617 with the system, so the emulation can gain the higher level of
618 similarity to the user actions. The simulated input functions allow the
619 notifications to be called right away, or post it, delaying the
620 notification until the next event loop invocation.
621 Keyboard
623 Event-driven
624 Keyboard input generates several notifications, where the most
625 important are "KeyDown" and "KeyUp". Both have almost the same list
626 of parameters ( see API ), that contain the key code, its modifiers
627 ( if any ) that were pressed and an eventual character code. The
628 algorithms that extract the meaning of the key, for example,
629 discretion between character and functional keys etc are not
630 described here. The reader is advised to look at Prima::KeySelector
631 module, which provides convenience functions for keyboard input
632 values transformations, and to the Prima::Edit and Prima::InputLine
633 modules, the classes that use extensively the keyboard input. But
634 in short, the key code is one of the "kb::XXX" ( like, kb::F10,
635 kb::Esc ) constants, and the modifier value is a combination of the
636 "km::XXX" ( km::Ctrl, km::Shift) constants. The notable exception
637 is kb::None value, which hints that the character code is of value.
638 Some other "kb::XXX"-marked keys have the character code as well,
639 and it is up to a programmer how to treat these combinations. It is
640 advised, however, to look at the key code first, and then to the
641 character code.
642 "KeyDown" event has also the repeat integer parameter, that shows
644 the repetitive count how many times the key was pressed. Usually
645 it is 1, but if a widget was not able to get its portion of events
646 between the key presses, its value can be higher. If a code
647 doesn't check for this parameter, some keyboard input may be lost.
648 If the code will be too much complicated by introducing the repeat-
649 value, one may consider setting the "::briefKeys" property to 0.
650 "::briefKeys", the boolean property, is 1 by default. If set to 0,
651 it guarantees that the repeat value will always be 1, but with the
652 price of certain under-optimization. If the core "KeyDown"
653 processing code sees repeat value greater than 1, it simply calls
654 the notification again.
655 Along with these two notifications, the "TranslateAccel" event is
657 generated after "KeyDown", if the focused widget is not interested
658 in the key event. Its usage covers the needs of the other widgets
659 that are willing to read the user input, even being out of focus.
660 A notable example can be a button with a hot key, that reacts on
661 the key press when the focus is elsewhere within its top-level
662 window. "TranslateAccel" has same parameters as "KeyDown", except
663 the REPEAT parameter.
664 Such out-of-focus input is also used with built-in menu keys
666 translations. If a descendant of Prima::AbstractMenu is in the
667 reach of the widget tree hierarchy, then it is checked whether it
668 contains some hot keys that match the user input. See Prima::Menu
669 for the details. In particular, Prima::Widget has "::accelTable"
670 property, a mere slot for an object that contains a table of hot
671 keys mappings to custom subroutines.
672 Polling
674 The polling function for the keyboard is limited to the modifier
675 keys only. "get_shift_state()" method returns the press state of
676 the modifier keys, a combination of "km::XXX" constants.
677 Simulated input
679 There are two methods, corresponding to the major notifications -
680 "key_up()" and "key_down()", that accept the same parameters as the
681 "KeyUp" and "KeyDown" notifications do, plus the POST boolean flag.
682 See "API" for details.
683 These methods are convenience wrappers for "key_event()" method,
685 which is never used directly.
686 Mouse
688 Event-driven
689 Mouse notifications are send in response when the user moves the
690 mouse, or presses and releases mouse buttons. The notifications
691 are logically grouped in two sets, the first contains "MouseDown",
692 "MouseUp", "MouseClick", and "MouseWheel", and the second -
693 "MouseMove", "MouseEnter", end "MouseLeave".
694 The first set deals with button actions. Pressing, de-pressing,
696 clicking ( and double-clicking ), the turn of mouse wheel
697 correspond to the four notifications. The notifications are sent
698 together with the mouse pointer coordinates, the button that was
699 touched, and the eventual modifier keys that were pressed. In
700 addition, "MouseClick" provides the boolean flag if the click was
701 single or double, and "MouseWheel" the wheel turn amount. These
702 notifications occur when the mouse event occurs within the
703 geometrical bounds of a widget, with one notable exception, when a
704 widget is in capture mode. If the "::capture" is set to 1, then
705 these events are sent to the widget even if the mouse pointer is
706 outside, and not sent to the widgets and windows that reside under
707 the pointer.
708 The second set deals with the pointer movements. When the pointer
710 passes over a widget, it receives first "MouseEnter", then series
711 of "MouseMove", and finally "MouseLeave". "MouseMove" and
712 "MouseEnter" notifications provide X,Y-coordinates and modificator
713 keys; "MouseLeave" passes no parameters.
714 Polling
716 The mouse input polling procedures are "get_mouse_state()" method,
717 that returns combination of "mb::XXX" constants, and the
718 "::pointerPos" two-integer property that reports the current
719 position of the mouse pointer.
720 Simulated input
722 There are five methods, corresponding to the mouse events -
723 "mouse_up()", "mouse_down()", "mouse_click()", "mouse_wheel()" and
724 "mouse_move()", that accept the same parameters as their event
725 counterparts do, plus the POST boolean flag. See "API" for details.
726 These methods are convenience wrappers for "mouse_event()" method,
728 which is never used directly.
729
731 Prima::Drawable deals only with such color values, that can be
732 unambiguously decomposed to their red, green and blue components.
733 Prima::Widget extends the range of the values acceptable by its color
734 properties, introducing the color schemes. The color can be set
735 indirectly, without prior knowledge of what is its RGB value. There are
736 several constants defined in "cl::" name space, that correspond to the
737 default values of different color properties of a widget.
738 Prima::Widget revises the usage of "::color" and "::backColor", the
740 properties inherited from Prima::Drawable. Their values are widget's
741 'foreground' and 'background' colors, in addition to their function as
742 template values. Moreover, their dynamic change induces the repainting
743 of a widget, and they can be inherited from the owner. The inheritance
744 is governed by properties "::ownerColor" and "::ownerBackColor". While
745 these are true, changes to owner "::color" or "::backColor" copied
746 automatically to a widget. Once the widget's "::color" or "::backColor"
747 are explicitly set, the owner link breaks automatically by setting
748 "::ownerColor" or "::ownerBackColor" to 0.
749 In addition to these two color properties, Prima::Widget introduces six
751 others. These are "::disabledColor", "::disabledBackColor",
752 "::hiliteColor", "::hiliteBackColor", "::light3DColor", and
753 "::dark3DColor". The 'disabled' color pair contains the values that
754 are expected to be used as foreground and background when a widget is
755 in the disabled state ( see API, "::enabled" property ). The 'hilite'
756 values serve as the colors for representation of selection inside a
757 widget. Selection may be of any kind, and some widgets do not provide
758 any. But for those that do, the 'hilite' color values provide distinct
759 alternative colors. Examples are selections in the text widgets, or in
760 the list boxes. The last pair, "::light3DColor" and "::dark3DColor" is
761 used for drawing 3D-looking outlines of a widget. The purpose of all
762 these properties is the adequate usage of the color settings, selected
763 by the user using system-specific tools, so the program written with
764 the toolkit would look not such different, and more or less conformant
765 to the user's color preferences.
766 The additional "cl::" constants, mentioned above, represent these eight
768 color properties. These named correspondingly, cl::NormalText,
769 cl::Normal, cl::HiliteText, cl::Hilite, cl::DisabledText, cl::Disabled,
770 cl::Light3DColor and cl::Dark3DColor. cl::NormalText is alias to
771 cl::Fore, and cl::Normal - to cl::Back. Another constant set, "ci::"
772 can be used with the "::colorIndex" property, a multiplexer for all
773 eight color properties. "ci::" constants mimic their non-RGB "cl::"
774 counterparts, so the call "hiliteBackColor(cl::Red)" is equal to
775 "colorIndex(ci::Hilite, cl::Red)".
776 Mapping from these constants to the RGB color representation is used
778 with "map_color()" method. These "cl::" constants alone are sufficient
779 for acquiring the default values, but the toolkit provides wider
780 functionality than this. The "cl::" constants can be combined with the
781 "wc::" constants, that represent standard widget class. The widget
782 class is implicitly used when single "cl::" constant is used; its value
783 is read from the "::widgetClass" property, unless one of "wc::"
784 constants is combined with the non-RGB "cl::" value. "wc::" constants
785 are described in "API"; their usage can make call of, for example,
786 "backColor( cl::Back)" on a button and on an input line result in
787 different colors, because the "cl::Back" is translated in the first
788 case into "cl::Back|wc::Button", and in another -
789 "cl::Back|wc::InputLine".
790 Dynamic change of the color properties result in the "ColorChanged"
792 notification.
793
795 Prima::Widget does not change the handling of fonts - the font
796 selection inside and outside "begin_paint()"/"end_paint()" is not
797 different at all. A matter of difference is how does Prima::Widget
798 select the default font.
799 First, if the "::ownerFont" property is set to 1, then font of the
801 owner is copied to the widget, and is maintained all the time while the
802 property is true. If it is not, the default font values read from the
803 system.
804 The default font metrics for a widget returned by "get_default_font()"
806 method, that often deals with system-dependent and user-selected
807 preferences ( see "Additional resources" ). Because a widget can host
808 an eventual Prima::Popup object, it contains "get_default_popup_font()"
809 method, that returns the default font for the popup objects. The
810 dynamic popup font settings governed, naturally, by the "::popupFont"
811 property. Prima::Window extends the functionality to
812 "get_default_menu_font()" and the "::menuFont" property.
813 Dynamic change of the font property results in the "FontChanged"
815 notification.
816
818 The resources, operated via Prima::Widget class but not that strictly
819 bound to the widget concept, are gathered in this section. The section
820 includes overview of pointer, cursor, hint, menu objects and user-
821 specified resources.
822 Pointer
824 The mouse pointer is the shared resource, that can change its visual
825 representation when it hovers over different kinds of widgets. It is
826 usually a good practice for a text field, for example, set the pointer
827 icon to a jagged vertical line, or indicate a moving window with a
828 cross-arrowed pointer.
829 A widget can select either one of the predefined system pointers,
831 mapped by the "cr::XXX" constant set, or supply its own pointer icon of
832 an arbitrary size and color depth.
833 NB: Not all systems allow the colored pointer icons. System value under
835 sv::ColorPointer index containing a boolean value, whether the colored
836 icons are allowed or not. Also, the pointer icon size may have a limit:
837 check if sv::FixedPointerSize is non-zero, in which case the pointer
838 size will be reduced to the system limits.
839 In general, the "::pointer" property is enough for these actions. It
841 discerns whether it has an icon or a constant passed, and sets the
842 appropriate properties. These properties are also accessible
843 separately, although their usage is not encouraged, primarily because
844 of the tangled relationship between them. These properties are:
845 "::pointerType", "::pointerIcon", and "::pointerHotSpot". See their
846 details in the "API" sections.
847 Another property, which is present only in Prima::Application name
849 space is called "::pointerVisible", and governs the visibility of the
850 pointer - but for all widget instances at once.
851 Cursor
853 The cursor is a blinking rectangular area, indicating the availability
854 of the input focus in a widget. There can be only one active cursor per
855 a GUI space, or none at all. Prima::Widget provides several cursor
856 properties: "::cursorVisible", "::cursorPos", and "::cursorSize". There
857 are also two methods, "show_cursor()" and "hide_cursor()", which are
858 not the convenience shortcuts but the functions accounting the cursor
859 hide count. If "hide_cursor()" was called three times, then
860 "show_cursor()" must be called three times as well for the cursor to
861 become visible.
862 Hint
864 "::hint" is a text string, that usually describes the widget's purpose
865 to the user in a brief manner. If the mouse pointer is hovered over the
866 widget longer than some timeout ( see Prima::Application::hintPause ),
867 then a label appears with the hint text, until the pointer is drawn
868 away. The hint behavior is governed by Prima::Application, but a
869 widget can do two additional things about hint: it can enable and
870 disable it by calling "::showHint" property, and it can inherit the
871 owner's "::hint" and "::showHint" properties using "::ownerHint" and
872 "::ownerShowHint" properties. If, for example, "::ownerHint" is set to
873 1, then "::hint" value is automatically copied from the widget's owner,
874 when it changes. If, however, the widget's "::hint" or "::showHint" are
875 explicitly set, the owner link breaks automatically by setting
876 "::ownerHint" or "::ownerShowHint" to 0.
877 The widget can also operate the "::hintVisible" property, that shows or
879 hides the hint label immediately, if the mouse pointer is inside the
880 widget's boundaries.
881 Menu objects
883 The default functionality of Prima::Widget coexists with two kinds of
884 the Prima::AbstractMenu descendants - Prima::AccelTable and
885 Prima::Popup ( Prima::Window is also equipped with Prima::Menu
886 reference). The "::items" property of these objects are accessible
887 through "::accelItems" and "::popupItems", whereas the objects
888 themselves - through "::accelTable" and "::popup", correspondingly. As
889 mentioned in "User input", these objects hook the user keyboard input
890 and call the programmer-defined callback subroutine if the key stroke
891 equals to one of their table values. As for "::accelTable", its
892 function ends here. "::popup" provides access to a context pop-up menu,
893 which can be invoked by either right-clicking or pressing a system-
894 dependent key combination. As a little customization, the
895 "::popupColorIndex" and "::popupFont" properties are introduced. (
896 "::popupColorIndex" is multiplexed to "::popupColor",
897 "::popupHiliteColor", "::popupHiliteBackColor", etc etc properties
898 exactly like the "::colorIndex" property ).
899 The font and color of a menu object might not always be writable
901 (Win32).
902 The Prima::Window class provides equivalent methods for the menu bar,
904 introducing "::menu", "::menuItems", "::menuColorIndex" ( with
905 multiplexing ) and "::menuFont" properties.
906 User-specified resources
908 It is considered a good idea to incorporate the user preferences into
909 the toolkit look-and-feel. Prima::Widget relies to the system-specific
910 code that tries to map these preferences as close as possible to the
911 toolkit paradigm.
912 Unix version employs XRDB ( X resource database ), which is the natural
914 way for the user to tell the preferences with fine granularity. Win32
915 reads the setting that the user has to set interactively, using system
916 tools. Nevertheless, the toolkit can not emulate all user settings that
917 are available on the supported platforms; it rather takes a 'least
918 common denominator', which is colors and fonts. "fetch_resource()"
919 method is capable of returning any of such settings, provided it's
920 format is font, color or a string. The method is rarely called
921 directly.
922 The appealing idea of making every widget property adjustable via the
924 user-specified resources is not implemented in full. It can be
925 accomplished up to a certain degree using "fetch_resource()" existing
926 functionality, but it is believed that calling up the method for the
927 every property for the every widget created is prohibitively expensive.
928
930 Properties
931 accelItems [ ITEM_LIST ]
932 Manages items of a Prima::AccelTable object associated with a
933 widget. The ITEM_LIST format is same as
934 "Prima::AbstractMenu::items" and is described in Prima::Menu.
935 See also: "accelTable"
937 accelTable OBJECT
939 Manages a Prima::AccelTable object associated with a widget. The
940 sole purpose of the accelTable object is to provide convenience
941 mapping of key combinations to anonymous subroutines. Instead of
942 writing an interface specifically for Prima::Widget, the existing
943 interface of Prima::AbstractMenu was taken.
944 The accelTable object can be destroyed safely; its cancellation can
946 be done either via "accelTable(undef)" or "destroy()" call.
947 Default value: undef
949 See also: "accelItems"
951 autoEnableChildren BOOLEAN
953 If TRUE, all immediate children widgets maintain the same "enabled"
954 state as the widget. This property is useful for the group-like
955 widgets ( ComboBox, SpinEdit etc ), that employ their children for
956 visual representation.
957 Default value: 0
959 backColor COLOR
961 In widget paint state, reflects background color in the graphic
962 context. In widget normal state, manages the basic background
963 color. If changed, initiates "ColorChanged" notification and
964 repaints the widget.
965 See also: "color", "colorIndex", "ColorChanged"
967 bottom INTEGER
969 Maintains the lower boundary of a widget. If changed, does not
970 affect the widget height; but does so, if called in "set()"
971 together with "::top".
972 See also: "left", "right", "top", "origin", "rect", "growMode",
974 "Move"
975 briefKeys BOOLEAN
977 If 1, contracts the repetitive key press events into one
978 notification, increasing REPEAT parameter of "KeyDown" callbacks.
979 If 0, REPEAT parameter is always 1.
980 Default value: 1
982 See also: "KeyDown"
984 buffered BOOLEAN
986 If 1, a widget "Paint" callback draws not on the screen, but on the
987 off-screen memory instead. The memory content is copied to the
988 screen then. Used when complex drawing methods are used, or if
989 output smoothness is desired.
990 This behavior can not be always granted, however. If there is not
992 enough memory, then widget draws in the usual manner.
993 Default value: 0
995 See also: "Paint"
997 capture BOOLEAN, CLIP_OBJECT = undef
999 Manipulates capturing of the mouse events. If 1, the mouse events
1000 are not passed to the widget the mouse pointer is over, but are
1001 redirected to the caller widget. The call for capture might not be
1002 always granted due the race conditions between programs.
1003 If CLIP_OBJECT widget is defined in set-mode call, the pointer
1005 movements are confined to CLIP_OBJECT inferior.
1006 See also: "MouseDown", "MouseUp", "MouseMove", "MouseWheel",
1008 "MouseClick".
1009 centered BOOLEAN
1011 A write-only property. Once set, widget is centered by X and Y axis
1012 relative to its owner.
1013 See also: "x_centered", "y_centered", "growMode", "origin", "Move".
1015 clipChildren BOOLEAN
1017 Affects the drawing mode when children widgets are present and
1018 obscuring the drawing area. If set, the children widgets are
1019 automatically added to the clipping area, and drawing over them
1020 will not happen. If unset, the painting can be done over the
1021 children widgets.
1022 Default: 1
1024 clipOwner BOOLEAN
1026 If 1, a widget is clipped by its owner boundaries. It is the
1027 default and expected behavior. If clipOwner is 0, a widget behaves
1028 differently: it does not clipped by the owner, it is not moved
1029 together with the parent, the origin offset is calculated not from
1030 the owner's coordinates but from the screen, and mouse events in a
1031 widget do not transgress to the top-level window decorations. In
1032 short, it itself becomes a top-level window, that, contrary to the
1033 one created from Prima::Window class, does not have any
1034 interference with system-dependent window stacking and positioning
1035 ( and any other ) policy, and is not ornamented by the window
1036 manager decorations.
1037 Default value: 1
1039 See "Parent-child relationship"
1041 See also: "Prima::Object" owner section, "parentHandle"
1043 color COLOR
1045 In widget paint state, reflects foreground color in the graphic
1046 context. In widget normal state, manages the basic foreground
1047 color. If changed, initiates "ColorChanged" notification and
1048 repaints the widget.
1049 See also: "backColor", "colorIndex", "ColorChanged"
1051 colorIndex INDEX, COLOR
1053 Manages the basic color properties indirectly, by accessing via
1054 "ci::XXX" constant. Is a complete alias for "::color",
1055 "::backColor", "::hiliteColor", "::hiliteBackColor",
1056 "::disabledColor", "::disabledBackColor", "::light3DColor", and
1057 "::dark3DColor" properties. The "ci::XXX" constants are:
1058 ci::NormalText or ci::Fore
1060 ci::Normal or ci::Back
1061 ci::HiliteText
1062 ci::Hilite
1063 ci::DisabledText
1064 ci::Disabled
1065 ci::Light3DColor
1066 ci::Dark3DColor
1067 The non-RGB "cl::" constants, specific to the Prima::Widget color
1069 usage are identical to their "ci::" counterparts:
1070 cl::NormalText or cl::Fore
1072 cl::Normal or cl::Back
1073 cl::HiliteText
1074 cl::Hilite
1075 cl::DisabledText
1076 cl::Disabled
1077 cl::Light3DColor
1078 cl::Dark3DColor
1079 See also: "color", "backColor", "ColorChanged"
1081 current BOOLEAN
1083 If 1, a widget (or one of its children) is marked as the one to be
1084 focused ( or selected) when the owner widget receives "select()"
1085 call. Within children widgets, only one or none at all can be
1086 marked as a current.
1087 See also: "currentWidget", "selectable", "selected",
1089 "selectedWidget", "focused"
1090 currentWidget OBJECT
1092 Points to a children widget, that is to be focused ( or selected)
1093 when the owner widget receives "select()" call.
1094 See also: "current", "selectable", "selected", "selectedWidget",
1096 "focused"
1097 cursorPos X_OFFSET Y_OFFSET
1099 Specifies the lower left corner of the cursor
1100 See also: "cursorSize", "cursorVisible"
1102 cursorSize WIDTH HEIGHT
1104 Specifies width and height of the cursor
1105 See also: "cursorPos", "cursorVisible"
1107 cursorVisible BOOLEAN
1109 Specifies cursor visibility flag. Default value is 0.
1110 See also: "cursorSize", "cursorPos"
1112 dark3DColor COLOR
1114 The color used to draw dark shades.
1115 See also: "light3DColor", "colorIndex", "ColorChanged"
1117 designScale X_SCALE Y_SCALE
1119 The width and height of a font, that was used when a widget (
1120 usually a dialog or a grouping widget ) was designed.
1121 See also: "scaleChildren", "width", "height", "size", "font"
1123 disabledBackColor COLOR
1125 The color used to substitute "::backColor" when a widget is in its
1126 disabled state.
1127 See also: "disabledColor", "colorIndex", "ColorChanged"
1129 disabledColor COLOR
1131 The color used to substitute "::color" when a widget is in its
1132 disabled state.
1133 See also: "disabledBackColor", "colorIndex", "ColorChanged"
1135 enabled BOOLEAN
1137 Specifies if a widget can accept focus, keyboard and mouse events.
1138 Default value is 1, however, being 'enabled' does not automatically
1139 allow the widget become focused. Only the reverse is true - if
1140 enabled is 0, focusing can never happen.
1141 See also: "responsive", "visible", "Enable", "Disable"
1143 font %FONT
1145 Manages font context. Same syntax as in Prima::Drawable. If
1146 changed, initiates "FontChanged" notification and repaints the
1147 widget.
1148 See also: "designScale", "FontChanged", "ColorChanged"
1150 geometry INTEGER
1152 Selects one of the available geometry managers. The corresponding
1153 integer constants are:
1154 gt::GrowMode, gt::Default - the default grow-mode algorithm
1156 gt::Pack - Tk packer
1157 gt::Place - Tk placer
1158 See "growMode", Prima::Widget::pack, Prima::Widget::place.
1160 growMode MODE
1162 Specifies widget behavior, when its owner is resized or moved.
1163 MODE can be 0 ( default ) or a combination of the following
1164 constants:
1165 Basic constants
1167 gm::GrowLoX widget's left side is kept in constant
1168 distance from owner's right side
1169 gm::GrowLoY widget's bottom side is kept in constant
1170 distance from owner's top side
1171 gm::GrowHiX widget's right side is kept in constant
1172 distance from owner's right side
1173 gm::GrowHiY widget's top side is kept in constant
1174 distance from owner's top side
1175 gm::XCenter widget is kept in center on its owner's
1176 horizontal axis
1177 gm::YCenter widget is kept in center on its owner's
1178 vertical axis
1179 gm::DontCare widgets origin is maintained constant relative
1180 to the screen
1181 Derived or aliased constants
1183 gm::GrowAll gm::GrowLoX|gm::GrowLoY|gm::GrowHiX|gm::GrowHiY
1184 gm::Center gm::XCenter|gm::YCenter
1185 gm::Client gm::GrowHiX|gm::GrowHiY
1186 gm::Right gm::GrowLoX|gm::GrowHiY
1187 gm::Left gm::GrowHiY
1188 gm::Floor gm::GrowHiX
1189 See also: "Move", "origin"
1191 firstClick BOOLEAN
1193 If 0, a widget bypasses first mouse click on it, if the top-level
1194 window it belongs to was not activated, so selecting such a widget
1195 it takes two mouse clicks.
1196 Default value is 1
1198 See also: "MouseDown", "selectable", "selected", "focused",
1200 "selectingButtons"
1201 focused BOOLEAN
1203 Specifies whether a widget possesses the input focus or not.
1204 Disregards "::selectable" property on set-call.
1205 See also: "selectable", "selected", "selectedWidget", "KeyDown"
1207 geomWidth, geomHeight, geomSize
1209 Three properties that select geometry request size. Writing and
1210 reading to "::geomWidth" and "::geomHeight" is equivalent to
1211 "::geomSize". The properies are run-time only, and behave
1212 differently under different circumstances:
1213 · As the properties are run-time only, they can not be set in the
1215 profile, and their initial value is fetched from "::size"
1216 property. Thus, setting the explicit size is aditionally sets
1217 the advised size in case the widget is to be used with the Tk
1218 geometry managers.
1219 · Setting the properties under the "gt::GrowMode" geometry
1221 manager also sets the corresponding "::width", "::height", or
1222 "::size". When the properties are read, though, the real size
1223 properties are not read; the values are kept separately.
1224 · Setting the properties under Tk geometry managers cause widgets
1226 size and position changed according to the geometry manager
1227 policy.
1228 height
1230 Maintains the height of a widget.
1231 See also: "width", "growMode", "Move", "Size", "get_virtual_size",
1233 "sizeMax", "sizeMin"
1234 helpContext STRING
1236 A string that binds a widget, a logical part it plays with the
1237 application and an interactive help topic. STRING format is defined
1238 as POD link ( see perlpod ) - "manpage/section", where 'manpage' is
1239 the file with POD content and 'section' is the topic inside the
1240 manpage.
1241 See also: "help"
1243 hiliteBackColor COLOR
1245 The color used to draw alternate background areas with high
1246 contrast.
1247 See also: "hiliteColor", "colorIndex", "ColorChanged"
1249 hiliteColor COLOR
1251 The color used to draw alternate foreground areas with high
1252 contrast.
1253 See also: "hiliteBackColor", "colorIndex", "ColorChanged"
1255 hint TEXT
1257 A text, shown under mouse pointer if it is hovered over a widget
1258 longer than "Prima::Application::hintPause" timeout. The text shows
1259 only if the "::showHint" is 1.
1260 See also: "hintVisible", "showHint", "ownerHint", "ownerShowHint"
1262 hintVisible BOOLEAN
1264 If called in get-form, returns whether the hint label is shown or
1265 not. If in set-form, immediately turns on or off the hint label,
1266 disregarding the timeouts. It does regard the mouse pointer
1267 location, however, and does not turn on the hint label if the
1268 pointer is away.
1269 See also: "hint", "showHint", "ownerHint", "ownerShowHint"
1271 layered BOOLEAN
1273 If set, the widget will try to use alpha transparency available on
1274 the system. See "Layering" in Prima::Image for more details.
1275 Default: false
1277 See also: "is_surface_layered"
1279 Note: In Windows, mouse events will not be delivered to the layered
1281 widget if the pixel under the mouse pointer is fully transparent.
1282 In X11, you need to run a composition manager, f.ex. compiz or
1284 xcompmgr.
1285 left INTEGER
1287 Maintains the left boundary of a widget. If changed, does not
1288 affect the widget width; but does so, if called in "set()" together
1289 with "::right".
1290 See also: "bottom", "right", "top", "origin", "rect", "growMode",
1292 "Move"
1293 light3DColor COLOR
1295 The color used to draw light shades.
1296 See also: "dark3DColor", "colorIndex", "ColorChanged"
1298 ownerBackColor BOOLEAN
1300 If 1, the background color is synchronized with the owner's.
1301 Automatically set to 0 if "::backColor" property is explicitly set.
1302 See also: "ownerColor", "backColor", "colorIndex"
1304 ownerColor BOOLEAN
1306 If 1, the foreground color is synchronized with the owner's.
1307 Automatically set to 0 if "::color" property is explicitly set.
1308 See also: "ownerBackColor", "color", "colorIndex"
1310 ownerFont BOOLEAN
1312 If 1, the font is synchronized with the owner's. Automatically set
1313 to 0 if "::font" property is explicitly set.
1314 See also: "font", "FontChanged"
1316 ownerHint BOOLEAN
1318 If 1, the hint is synchronized with the owner's. Automatically set
1319 to 0 if "::hint" property is explicitly set.
1320 See also: "hint", "showHint", "hintVisible", "ownerShowHint"
1322 ownerShowHint BOOLEAN
1324 If 1, the show hint flag is synchronized with the owner's.
1325 Automatically set to 0 if "::showHint" property is explicitly set.
1326 See also: "hint", "showHint", "hintVisible", "ownerHint"
1328 ownerPalette BOOLEAN
1330 If 1, the palette array is synchronized with the owner's.
1331 Automatically set to 0 if "::palette" property is explicitly set.
1332 See also: "palette"
1334 origin X Y
1336 Maintains the left and bottom boundaries of a widget relative to
1337 its owner ( or to the screen if "::clipOwner" is set to 0 ).
1338 See also: "bottom", "right", "top", "left", "rect", "growMode",
1340 "Move"
1341 packInfo %OPTIONS
1343 See Prima::Widget::pack
1344 palette [ @PALETTE ]
1346 Specifies array of colors, that are desired to be present into the
1347 system palette, as close to the PALETTE as possible. This property
1348 works only if the graphic device allows palette operations. See
1349 "palette" in Prima::Drawable.
1350 See also: "ownerPalette"
1352 parentHandle SYSTEM_WINDOW
1354 If SYSTEM_WINDOW is a valid system-dependent window handle, then a
1355 widget becomes the child of the window specified, given the
1356 widget's "::clipOwner" is 0. The parent window can belong to
1357 another application.
1358 Default value is undef.
1360 See also: "clipOwner"
1362 placeInfo %OPTIONS
1364 See Prima::Widget::place
1365 pointer cr::XXX or ICON
1367 Specifies the pointer icon; discerns between "cr::XXX" constants
1368 and an icon. If an icon contains a hash variable "__pointerHotSpot"
1369 with an array of two integers, these integers will be treated as
1370 the pointer hot spot. In get-mode call, this variable is
1371 automatically assigned to an icon, if the result is an icon object.
1372 See also: "pointerHotSpot", "pointerIcon", "pointerType"
1374 pointerHotSpot X_OFFSET Y_OFFSET
1376 Specifies the hot spot coordinates of a pointer icon, associated
1377 with a widget.
1378 See also: "pointer", "pointerIcon", "pointerType"
1380 pointerIcon ICON
1382 Specifies the pointer icon, associated with a widget.
1383 See also: "pointerHotSpot", "pointer", "pointerType"
1385 pointerPos X_OFFSET Y_OFFSET
1387 Specifies the mouse pointer coordinates relative to widget's
1388 coordinates.
1389 See also: "get_mouse_state", "screen_to_client", "client_to_screen"
1391 pointerType TYPE
1393 Specifies the type of the pointer, associated with the widget.
1394 TYPE can accept one constant of "cr::XXX" set:
1395 cr::Default same pointer type as owner's
1397 cr::Arrow arrow pointer
1398 cr::Text text entry cursor-like pointer
1399 cr::Wait hourglass
1400 cr::Size general size action pointer
1401 cr::Move general move action pointer
1402 cr::SizeWest, cr::SizeW right-move action pointer
1403 cr::SizeEast, cr::SizeE left-move action pointer
1404 cr::SizeWE general horizontal-move action pointer
1405 cr::SizeNorth, cr::SizeN up-move action pointer
1406 cr::SizeSouth, cr::SizeS down-move action pointer
1407 cr::SizeNS general vertical-move action pointer
1408 cr::SizeNW up-right move action pointer
1409 cr::SizeSE down-left move action pointer
1410 cr::SizeNE up-left move action pointer
1411 cr::SizeSW down-right move action pointer
1412 cr::Invalid invalid action pointer
1413 cr::User user-defined icon
1414 All constants except "cr::User" and "cr::Default" present a system-
1416 defined pointers, their icons and hot spot offsets. "cr::User" is a
1417 sign that an icon object was specified explicitly via
1418 "::pointerIcon" property. "cr::Default" is a way to tell that a
1419 widget inherits its owner pointer type, no matter is it a system-
1420 defined pointer or a custom icon.
1421 See also: "pointerHotSpot", "pointerIcon", "pointer"
1423 popup OBJECT
1425 Manages a Prima::Popup object associated with a widget. The
1426 purpose of the popup object is to show a context menu when the user
1427 right-clicks or selects the corresponding keyboard combination.
1428 Prima::Widget can host many children objects, Prima::Popup as well.
1429 But only the one that is set in "::popup" property will be
1430 activated automatically.
1431 The popup object can be destroyed safely; its cancellation can be
1433 done either via "popup(undef)" or "destroy()" call.
1434 See also: "Prima::Menu", "Popup", "Menu", "popupItems",
1436 "popupColorIndex", "popupFont"
1437 popupColorIndex INDEX, COLOR
1439 Maintains eight color properties of a pop-up context menu,
1440 associated with a widget. INDEX must be one of "ci::XXX" constants
1441 ( see "::colorIndex" property ).
1442 See also: "popupItems", "popupFont", "popup"
1444 popupColor COLOR
1446 Basic foreground in a popup context menu color.
1447 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1449 popupBackColor COLOR
1451 Basic background in a popup context menu color.
1452 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1454 popupDark3DColor COLOR
1456 Color for drawing dark shadings in a popup context menu.
1457 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1459 popupDisabledColor COLOR
1461 Foreground color for disabled items in a popup context menu.
1462 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1464 popupDisabledBackColor COLOR
1466 Background color for disabled items in a popup context menu.
1467 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1469 popupFont %FONT
1471 Maintains the font of a pop-up context menu, associated with a
1472 widget.
1473 See also: "popupItems", "popupColorIndex", "popup"
1475 popupHiliteColor COLOR
1477 Foreground color for selected items in a popup context menu.
1478 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1480 popupHiliteBackColor COLOR
1482 Background color for selected items in a popup context menu.
1483 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1485 popupItems [ ITEM_LIST ]
1487 Manages items of a Prima::Popup object associated with a widget.
1488 The ITEM_LIST format is same as "Prima::AbstractMenu::items" and is
1489 described in Prima::Menu.
1490 See also: "popup", "popupColorIndex", "popupFont"
1492 popupLight3DColor COLOR
1494 Color for drawing light shadings in a popup context menu.
1495 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1497 rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET Y_TOP_OFFSET
1499 Maintains the rectangular boundaries of a widget relative to its
1500 owner ( or to the screen if "::clipOwner" is set to 0 ).
1501 See also: "bottom", "right", "top", "left", "origin", "width",
1503 "height", "size" "growMode", "Move", "Size", "get_virtual_size",
1504 "sizeMax", "sizeMin"
1505 right INTEGER
1507 Maintains the right boundary of a widget. If changed, does not
1508 affect the widget width; but does so, if called in "set()" together
1509 with "::left".
1510 See also: "left", "bottom", "top", "origin", "rect", "growMode",
1512 "Move"
1513 scaleChildren BOOLEAN
1515 If a widget has "::scaleChildren" set to 1, then the newly-created
1516 children widgets inserted in it will be scaled corresponding to the
1517 owner's "::designScale", given that widget's "::designScale" is not
1518 "undef" and the owner's is not [0,0].
1519 Default is 1.
1521 See also: "designScale"
1523 selectable BOOLEAN
1525 If 1, a widget can be granted focus implicitly, or by means of the
1526 user actions. "select()" regards this property, and does not focus
1527 a widget that has "::selectable" set to 0.
1528 Default value is 0
1530 See also: "current", "currentWidget", "selected", "selectedWidget",
1532 "focused"
1533 selected BOOLEAN
1535 If called in get-mode, returns whether a widget or one of its
1536 (grand-) children is focused. If in set-mode, either simply turns
1537 the system with no-focus state ( if 0 ), or sends input focus to
1538 itself or one of the widgets tracked down by "::currentWidget"
1539 chain.
1540 See also: "current", "currentWidget", "selectable",
1542 "selectedWidget", "focused"
1543 selectedWidget OBJECT
1545 Points to a child widget, that has property "::selected" set to 1.
1546 See also: "current", "currentWidget", "selectable", "selected",
1548 "focused"
1549 selectingButtons FLAGS
1551 FLAGS is a combination of "mb::XXX" ( mouse button ) flags. If a
1552 widget receives a click with a mouse button, that has the
1553 corresponding bit set in "::selectingButtons", then "select()" is
1554 called.
1555 See also: "MouseDown", "firstClick", "selectable", "selected",
1557 "focused"
1558 shape REGION
1560 Maintains the non-rectangular shape of a widget. When setting,
1561 REGION is either a Prima::Image object, with 0 bits treated as
1562 transparent pixels, and 1 bits as opaque pixels, or a Prima::Region
1563 object. When getting, it is either undef or a Prima::Region
1564 object.
1565 Successive only if "sv::ShapeExtension" value is true.
1567 showHint BOOLEAN
1569 If 1, the toolkit is allowed to show the hint label over a widget.
1570 If 0, the display of the hint is forbidden. The "::hint" property
1571 must contain non-empty string as well, if the hint label must be
1572 shown.
1573 Default value is 1.
1575 See also: "hint", "ownerShowHint", "hintVisible", "ownerHint"
1577 size WIDTH HEIGHT
1579 Maintains the width and height of a widget.
1580 See also: "width", "height" "growMode", "Move", "Size",
1582 "get_virtual_size", "sizeMax", "sizeMin"
1583 sizeMax WIDTH HEIGHT
1585 Specifies the maximal size for a widget that it is allowed to
1586 accept.
1587 See also: "width", "height", "size" "growMode", "Move", "Size",
1589 "get_virtual_size", "sizeMin"
1590 sizeMin WIDTH HEIGHT
1592 Specifies the minimal size for a widget that it is allowed to
1593 accept.
1594 See also: "width", "height", "size" "growMode", "Move", "Size",
1596 "get_virtual_size", "sizeMax"
1597 syncPaint BOOLEAN
1599 If 0, the "Paint" request notifications are stacked until the event
1600 loop is called. If 1, every time the widget surface gets
1601 invalidated, the "Paint" notification is called.
1602 Default value is 0.
1604 See also: "invalidate_rect", "repaint", "validate_rect", "Paint"
1606 tabOrder INTEGER
1608 Maintains the order in which tab- and shift-tab- key navigation
1609 algorithms select the sibling widgets. INTEGER is unique among the
1610 sibling widgets. In set mode, if INTEGER value is already taken,
1611 the occupier is assigned another unique value, but without
1612 destruction of a queue - widgets with ::tabOrder greater than of
1613 the widget, receive their new values too. Special value -1 is
1614 accepted as 'the end of list' indicator; the negative value is
1615 never returned.
1616 See also: "tabStop", "next_tab", "selectable", "selected",
1618 "focused"
1619 tabStop BOOLEAN
1621 Specifies whether a widget is interested in tab- and shift-tab- key
1622 navigation or not.
1623 Default value is 1.
1625 See also: "tabOrder", "next_tab", "selectable", "selected",
1627 "focused"
1628 text TEXT
1630 A text string for generic purpose. Many Prima::Widget descendants
1631 use this property heavily - buttons, labels, input lines etc, but
1632 Prima::Widget itself does not.
1633 top INTEGER
1635 Maintains the upper boundary of a widget. If changed, does not
1636 affect the widget height; but does so, if called in "set()"
1637 together with "::bottom".
1638 See also: "left", "right", "bottom", "origin", "rect", "growMode",
1640 "Move"
1641 transparent BOOLEAN
1643 Specifies whether the background of a widget before it starts
1644 painting is of any importance. If 1, a widget can gain certain
1645 transparency look if it does not clear the background during
1646 "Paint" event.
1647 Default value is 0
1649 See also: "Paint", "buffered".
1651 visible BOOLEAN
1653 Specifies whether a widget is visible or not. See "Visibility".
1654 See also: "Show", "Hide", "showing", "exposed"
1656 widgetClass CLASS
1658 Maintains the integer value, designating the color class that is
1659 defined by the system and is associated with Prima::Widget eight
1660 basic color properties. CLASS can be one of "wc::XXX" constants:
1661 wc::Undef
1663 wc::Button
1664 wc::CheckBox
1665 wc::Combo
1666 wc::Dialog
1667 wc::Edit
1668 wc::InputLine
1669 wc::Label
1670 wc::ListBox
1671 wc::Menu
1672 wc::Popup
1673 wc::Radio
1674 wc::ScrollBar
1675 wc::Slider
1676 wc::Widget or wc::Custom
1677 wc::Window
1678 wc::Application
1679 These constants are not associated with the toolkit classes; any
1681 class can use any of these constants in "::widgetClass".
1682 See also: "map_color", "colorIndex"
1684 widgets @WIDGETS
1686 In get-mode, returns list of immediate children widgets (identical
1687 to "get_widgets"). In set-mode accepts set of widget profiles, as
1688 "insert" does, as a list or an array. This way it is possible to
1689 create widget hierarchy in a single call.
1690 width WIDTH
1692 Maintains the width of a widget.
1693 See also: "height" "growMode", "Move", "Size", "get_virtual_size",
1695 "sizeMax", "sizeMin"
1696 x_centered BOOLEAN
1698 A write-only property. Once set, widget is centered by the
1699 horizontal axis relative to its owner.
1700 See also: "centered", "y_centered", "growMode", "origin", "Move".
1702 y_centered BOOLEAN
1704 A write-only property. Once set, widget is centered by the vertical
1705 axis relative to its owner.
1706 See also: "x_centered", "centered", "growMode", "origin", "Move".
1708 Methods
1710 bring_to_front
1711 Sends a widget on top of all other siblings widgets
1712 See also: "insert_behind", "send_to_back", "ZOrderChanged"
1714 ,"first", "next", "prev", "last"
1715 can_close
1717 Sends "Close" message, and returns its boolean exit state.
1718 See also: "Close", "close"
1720 client_to_screen @OFFSETS
1722 Maps array of X and Y integer offsets from widget to screen
1723 coordinates. Returns the mapped OFFSETS.
1724 See also: "screen_to_client", "clipOwner"
1726 close
1728 Calls "can_close()", and if successful, destroys a widget. Returns
1729 the "can_close()" result.
1730 See also: "can_close", "Close"
1732 defocus
1734 Alias for focused(0) call
1735 See also: "focus", "focused", "Enter", "Leave"
1737 deselect
1739 Alias for selected(0) call
1740 See also: "select", "selected", "Enter", "Leave"
1742 exposed
1744 Returns a boolean value, indicating whether a widget is at least
1745 partly visible on the screen. Never returns 1 if a widget has
1746 "::visible" set to 0.
1747 See also: "visible", "showing", "Show", "Hide"
1749 fetch_resource CLASS_NAME, NAME, CLASS_RESOURCE, RESOURCE, OWNER,
1751 RESOURCE_TYPE = fr::String
1752 Returns a system-defined scalar of resource, defined by the widget
1753 hierarchy, its class, name and owner. RESOURCE_TYPE can be one of
1754 type qualificators:
1755 fr::Color - color resource
1757 fr::Font - font resource
1758 fs::String - text string resource
1759 Such a number of the parameters is used because the method can be
1761 called before a widget is created. CLASS_NAME is widget class
1762 string, NAME is widget name. CLASS_RESOURCE is class of resource,
1763 and RESOURCE is the resource name.
1764 For example, resources 'color' and 'disabledColor' belong to the
1766 resource class 'Foreground'.
1767 first
1769 Returns the first ( from bottom ) sibling widget in Z-order.
1770 See also: "last", "next", "prev"
1772 focus
1774 Alias for focused(1) call
1775 See also: "defocus", "focused", "Enter", "Leave"
1777 hide
1779 Sets widget "::visible" to 0.
1780 See also: "hide", "visible", "Show", "Hide", "showing", "exposed"
1782 hide_cursor
1784 Hides the cursor. As many times "hide_cursor()" was called, as many
1785 time its counterpart "show_cursor()" must be called to reach the
1786 cursor's initial state.
1787 See also: "show_cursor", "cursorVisible"
1789 help
1791 Starts an interactive help viewer opened on "::helpContext" string
1792 value.
1793 The string value is combined from the widget's owner
1795 "::helpContext" strings if the latter is empty or begins with a
1796 slash. A special meaning is assigned to an empty string " " - the
1797 help() call fails when such value is found to be the section
1798 component. This feature can be useful when a window or a dialog
1799 presents a standalone functionality in a separate module, and the
1800 documentation is related more to the module than to an embedding
1801 program. In such case, the grouping widget holds "::helpContext" as
1802 a pod manpage name with a trailing slash, and its children widgets
1803 are assigned "::helpContext" to the topics without the manpage but
1804 the leading slash instead. If the grouping widget has an empty
1805 string " " as "::helpContext" then the help is forced to be
1806 unavailable for all the children widgets.
1807 See also: "helpContext"
1809 insert CLASS, %PROFILE [[ CLASS, %PROFILE], ... ]
1811 Creates one or more widgets with "owner" property set to the caller
1812 widget, and returns the list of references to the newly created
1813 widgets.
1814 Has two calling formats:
1816 Single widget
1818 $parent-> insert( 'Child::Class',
1819 name => 'child',
1820 ....
1821 );
1822 Multiple widgets
1824 $parent-> insert(
1825 [
1826 'Child::Class1',
1827 name => 'child1',
1828 ....
1829 ],
1830 [
1831 'Child::Class2',
1832 name => 'child2',
1833 ....
1834 ],
1835 );
1836 insert_behind OBJECT
1838 Sends a widget behind the OBJECT on Z-axis, given that the OBJECT
1839 is a sibling to the widget.
1840 See also: "bring_to_front", "send_to_back", "ZOrderChanged"
1842 ,"first", "next", "prev", "last"
1843 invalidate_rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET
1845 Y_TOP_OFFSET
1846 Marks the rectangular area of a widget as 'invalid', so re-painting
1847 of the area happens. See "Graphic content".
1848 See also: "validate_rect", "get_invalid_rect", "repaint", "Paint",
1850 "syncPaint", "update_view"
1851 is_surface_layered
1853 Returns true if both the widget and it's top-most parent are
1854 layered. If the widget itself is top-most, i.e. a window, a non-
1855 clipOwner widget, or a child to application, then is the same as
1856 "layered".
1857 See also: layered
1859 key_down CODE, KEY = kb::NoKey, MOD = 0, REPEAT = 1, POST = 0
1861 The method sends or posts ( POST flag ) simulated "KeyDown" event
1862 to the system. CODE, KEY, MOD and REPEAT are the parameters to be
1863 passed to the notification callbacks.
1864 See also: "key_up", "key_event", "KeyDown"
1866 key_event COMMAND, CODE, KEY = kb::NoKey, MOD = 0, REPEAT = 1, POST = 0
1868 The method sends or posts ( POST flag ) simulated keyboard event to
1869 the system. CODE, KEY, MOD and REPEAT are the parameters to be
1870 passed to an eventual "KeyDown" or "KeyUp" notifications. COMMAND
1871 is allowed to be either "cm::KeyDown" or "cm::KeyUp".
1872 See also: "key_down", "key_up", "KeyDown", "KeyUp"
1874 key_up CODE, KEY = kb::NoKey, MOD = 0, POST = 0
1876 The method sends or posts ( POST flag ) simulated "KeyUp" event to
1877 the system. CODE, KEY and MOD are the parameters to be passed to
1878 the notification callbacks.
1879 See also: "key_down", "key_event", "KeyUp"
1881 last
1883 Returns the last ( the topmost ) sibling widget in Z-order.
1884 See also: "first", "next", "prev"
1886 lock
1888 Turns off the ability of a widget to re-paint itself. As many
1889 times "lock()" was called, as may times its counterpart, "unlock()"
1890 must be called to enable re-painting again. Returns a boolean
1891 success flag.
1892 See also: "unlock", "repaint", "Paint", "get_locked"
1894 map_color COLOR
1896 Transforms "cl::XXX" and "ci::XXX" combinations into RGB color
1897 representation and returns the result. If COLOR is already in RGB
1898 format, no changes are made.
1899 See also: "colorIndex"
1901 mouse_click BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, DBL_CLICK = 0,
1903 POST = 0
1904 The method sends or posts ( POST flag ) simulated "MouseClick"
1905 event to the system. BUTTON, MOD, X, Y, and DBL_CLICK are the
1906 parameters to be passed to the notification callbacks.
1907 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseMove",
1909 "MouseEnter", "MouseLeave"
1910 mouse_down BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, POST = 0
1912 The method sends or posts ( POST flag ) simulated "MouseDown" event
1913 to the system. BUTTON, MOD, X, and Y are the parameters to be
1914 passed to the notification callbacks.
1915 See also: "MouseUp", "MouseWheel", "MouseClick", "MouseMove",
1917 "MouseEnter", "MouseLeave"
1918 mouse_enter MOD = 0, X = 0, Y = 0, POST = 0
1920 The method sends or posts ( POST flag ) simulated "MouseEnter"
1921 event to the system. MOD, X, and Y are the parameters to be passed
1922 to the notification callbacks.
1923 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseClick",
1925 "MouseMove", "MouseLeave"
1926 mouse_event COMMAND = cm::MouseDown, BUTTON = mb::Left, MOD = 0, X = 0,
1928 Y = 0, DBL_CLICK = 0, POST = 0
1929 The method sends or posts ( POST flag ) simulated mouse event to
1930 the system. BUTTON, MOD, X, Y and DBL_CLICK are the parameters to
1931 be passed to an eventual mouse notifications. COMMAND is allowed
1932 to be one of "cm::MouseDown", "cm::MouseUp", "cm::MouseWheel",
1933 "cm::MouseClick", "cm::MouseMove", "cm::MouseEnter",
1934 "cm::MouseLeave" constants.
1935 See also: "mouse_down", "mouse_up", "mouse_wheel", "mouse_click",
1937 "mouse_move", "mouse_enter", "mouse_leave", "MouseDown", "MouseUp",
1938 "MouseWheel", "MouseClick", "MouseMove", "MouseEnter", "MouseLeave"
1939 mouse_leave
1941 The method sends or posts ( POST flag ) simulated "MouseLeave"
1942 event to the system.
1943 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseClick",
1945 "MouseMove", "MouseEnter", "MouseLeave"
1946 mouse_move MOD = 0, X = 0, Y = 0, POST = 0
1948 The method sends or posts ( POST flag ) simulated "MouseMove" event
1949 to the system. MOD, X, and Y are the parameters to be passed to the
1950 notification callbacks.
1951 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseClick",
1953 "MouseEnter", "MouseLeave"
1954 mouse_up BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, POST = 0
1956 The method sends or posts ( POST flag ) simulated "MouseUp" event
1957 to the system. BUTTON, MOD, X, and Y are the parameters to be
1958 passed to the notification callbacks.
1959 See also: "MouseDown", "MouseWheel", "MouseClick", "MouseMove",
1961 "MouseEnter", "MouseLeave"
1962 mouse_wheel MOD = 0, X = 0, Y = 0, INCR = 0, POST = 0
1964 The method sends or posts ( POST flag ) simulated "MouseUp" event
1965 to the system. MOD, X, Y and INCR are the parameters to be passed
1966 to the notification callbacks.
1967 See also: "MouseDown", "MouseUp", "MouseClick", "MouseMove",
1969 "MouseEnter", "MouseLeave"
1970 next
1972 Returns the neighbor sibling widget, next ( above ) in Z-order. If
1973 none found, undef is returned.
1974 See also: "first", "last", "prev"
1976 next_tab FORWARD = 1
1978 Returns the next widget in the sorted by "::tabOrder" list of
1979 sibling widgets. FORWARD is a boolean lookup direction flag. If
1980 none found, the first ( or the last, depending on FORWARD flag )
1981 widget is returned. Only widgets with "::tabStop" set to 1
1982 participate.
1983 Also used by the internal keyboard navigation code.
1985 See also: "next_positional", "tabOrder", "tabStop", "selectable"
1987 next_positional DELTA_X DELTA_Y
1989 Returns a sibling, (grand-)child of a sibling or (grand-)child
1990 widget, that matched best the direction specified by DELTA_X and
1991 DELTA_Y. At one time, only one of these parameters can be zero;
1992 another parameter must be either 1 or -1.
1993 Also used by the internal keyboard navigation code.
1995 See also: "next_tab", "origin"
1997 pack, packForget, packSlaves
1999 See Prima::Widget::pack
2000 place, placeForget, placeSlaves
2002 See Prima::Widget::place
2003 prev
2005 Returns the neighbor sibling widget, previous ( below ) in Z-order.
2006 If none found, undef is returned.
2007 See also: "first", "last", "next"
2009 repaint
2011 Marks the whole widget area as 'invalid', so re-painting of the
2012 area happens. See "Graphic content".
2013 See also: "validate_rect", "get_invalid_rect", "invalidate_rect",
2015 "Paint", "update_view", "syncPaint"
2016 rect_bevel $CANVAS, @RECT, %OPTIONS
2018 Draws a rectangular area, similar to produced by "rect3d" over
2019 @RECT that is 4-integer coordinates of the area, but implicitly
2020 using widget's "light3DColor" and "dark3DColor" properties' values.
2021 The following options are recognized:
2022 fill COLOR
2024 If set, the area is filled with COLOR, ortherwise is left
2025 intact.
2026 width INTEGER
2028 Width of the border in pixels
2029 concave BOOLEAN
2031 If 1, draw a concave area, bulged otherwise
2032 responsive
2034 Returns a boolean flag, indicating whether a widget and its owners
2035 have all "::enabled" 1 or not. Useful for fast check if a widget
2036 should respond to the user actions.
2037 See also: "enabled"
2039 screen_to_client @OFFSETS
2041 Maps array of X and Y integer offsets from screen to widget
2042 coordinates. Returns the mapped OFFSETS.
2043 See also: "client_to_screen"
2045 scroll DELTA_X DELTA_Y %OPTIONS
2047 Scrolls the graphic context area by DELTA_X and DELTA_Y pixels.
2048 OPTIONS is hash, that contains optional parameters to the scrolling
2049 procedure:
2050 clipRect [X1, Y1, X2, Y2]
2052 The clipping area is confined by X1, Y1, X2, Y2 rectangular
2053 area. If not specified, the clipping area covers the whole
2054 widget. Only the bits, covered by clipRect are affected. Bits
2055 scrolled from the outside of the rectangle to the inside are
2056 painted; bits scrolled from the inside of the rectangle to the
2057 outside are not painted.
2058 confineRect [X1, Y1, X2, Y2]
2060 The scrolling area is confined by X1, Y1, X2, Y2 rectangular
2061 area. If not specified, the scrolling area covers the whole
2062 widget.
2063 withChildren BOOLEAN
2065 If 1, the scrolling performs with the eventual children widgets
2066 change their positions to DELTA_X and DELTA_Y as well.
2067 Cannot be used inside paint state.
2069 See also: "Paint", "get_invalid_rect"
2071 select
2073 Alias for selected(1) call
2074 See also: "deselect", "selected", "Enter", "Leave"
2076 send_to_back
2078 Sends a widget at bottom of all other siblings widgets
2079 See also: "insert_behind", "bring_to_front", "ZOrderChanged"
2081 ,"first", "next", "prev", "last"
2082 show
2084 Sets widget "::visible" to 1.
2085 See also: "hide", "visible", "Show", "Hide", "showing", "exposed"
2087 show_cursor
2089 Shows the cursor. As many times "hide_cursor()" was called, as many
2090 time its counterpart "show_cursor()" must be called to reach the
2091 cursor's initial state.
2092 See also: "hide_cursor", "cursorVisible"
2094 showing
2096 Returns a boolean value, indicating whether the widget and its
2097 owners have all "::visible" 1 or not.
2098 unlock
2100 Turns on the ability of a widget to re-paint itself. As many times
2101 "lock()" was called, as may times its counterpart, "unlock()" must
2102 be called to enable re-painting again. When last "unlock()" is
2103 called, an implicit "repaint()" call is made. Returns a boolean
2104 success flag.
2105 See also: "lock", "repaint", "Paint", "get_locked"
2107 update_view
2109 If any parts of a widget were marked as 'invalid' by either
2110 "invalidate_rect()" or "repaint()" calls or the exposure caused by
2111 window movements ( or any other), then "Paint" notification is
2112 immediately called. If no parts are invalid, no action is
2113 performed. If a widget has "::syncPaint" set to 1, "update_view()"
2114 is always a no-operation call.
2115 See also: "invalidate_rect", "get_invalid_rect", "repaint",
2117 "Paint", "syncPaint", "update_view"
2118 validate_rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET Y_TOP_OFFSET
2120 Reverses the effect of "invalidate_rect()", restoring the original,
2121 'valid' state of widget area covered by the rectangular area
2122 passed. If a widget with previously invalid areas was wholly
2123 validated by this method, no "Paint" notifications occur.
2124 See also: "invalidate_rect", "get_invalid_rect", "repaint",
2126 "Paint", "syncPaint", "update_view"
2127 Get-methods
2129 get_default_font
2130 Returns the default font for a Prima::Widget class.
2131 See also: "font"
2133 get_default_popup_font
2135 Returns the default font for a Prima::Popup class.
2136 See also: "font"
2138 get_invalid_rect
2140 Returns the result of successive calls "invalidate_rect()",
2141 "validate_rect()" and "repaint()", as a rectangular area ( four
2142 integers ) that cover all invalid regions in a widget. If none
2143 found, (0,0,0,0) is returned.
2144 See also: "validate_rect", "invalidate_rect", "repaint", "Paint",
2146 "syncPaint", "update_view"
2147 get_handle
2149 Returns a system handle for a widget
2150 See also: "get_parent_handle", "Window::get_client_handle"
2152 get_locked
2154 Returns 1 if a widget is in "lock()" - initiated repaint-blocked
2155 state.
2156 See also: "lock", "unlock"
2158 get_mouse_state
2160 Returns a combination of "mb::XXX" constants, reflecting the
2161 currently pressed mouse buttons.
2162 See also: "pointerPos", "get_shift_state"
2164 get_parent
2166 Returns the owner widget that clips the widget boundaries, or
2167 application object if a widget is top-level.
2168 See also: "clipOwner"
2170 get_parent_handle
2172 Returns a system handle for a parent of a widget, a window that
2173 belongs to another program. Returns 0 if the widget's owner and
2174 parent are in the same application and process space.
2175 See also: "get_handle", "clipOwner"
2177 get_pointer_size
2179 Returns two integers, width and height of a icon, that the system
2180 accepts as valid for a pointer. If the icon is supplied that is
2181 more or less than these values, it is truncated or padded with
2182 transparency bits, but is not stretched. Can be called with class
2183 syntax.
2184 get_shift_state
2186 Returns a combination of "km::XXX" constants, reflecting the
2187 currently pressed keyboard modificator buttons.
2188 See also: "get_shift_state"
2190 get_virtual_size
2192 Returns virtual width and height of a widget. See "Geometry",
2193 Implicit size regulations.
2194 See also: "width", "height", "size" "growMode", "Move", "Size",
2196 "sizeMax", "sizeMin"
2197 get_widgets
2199 Returns list of children widgets.
2200 Events
2202 Change
2203 Generic notification, used for Prima::Widget descendants;
2204 Prima::Widget itself neither calls not uses the event. Designed to
2205 be called when an arbitrary major state of a widget is changed.
2206 Click
2208 Generic notification, used for Prima::Widget descendants;
2209 Prima::Widget itself neither calls not uses the event. Designed to
2210 be called when an arbitrary major action for a widget is called.
2211 Close
2213 Triggered by "can_close()" and "close()" functions. If the event
2214 flag is cleared during execution, these functions fail.
2215 See also: "close", "can_close"
2217 ColorChanged INDEX
2219 Called when one of widget's color properties is changed, either by
2220 direct property change or by the system. INDEX is one of "ci::XXX"
2221 constants.
2222 See also: "colorIndex"
2224 Disable
2226 Triggered by a successive enabled(0) call
2227 See also: "Enable", "enabled", "responsive"
2229 DragDrop X Y
2231 Design in progress. Supposed to be triggered when a drag-and-drop
2232 session started by the widget. X and Y are mouse pointer
2233 coordinates on the session start.
2234 See also: "DragOver", "EndDrag"
2236 DragOver X Y STATE
2238 Design in progress. Supposed to be called when a mouse pointer is
2239 passed over a widget during a drag-and-drop session. X and Y are
2240 mouse pointer coordinates, identical to "MouseMove" X Y parameters.
2241 STATE value is undefined.
2242 See also: "DragDrop", "EndDrag"
2244 Enable
2246 Triggered by a successive enabled(1) call
2247 See also: "Disable", "enabled", "responsive"
2249 EndDrag X Y
2251 Design in progress. Supposed to be called when a drag-and-drop
2252 session is finished successfully over a widget. X and Y are mouse
2253 pointer coordinates on the session end.
2254 See also: "DragDrop", "DragOver"
2256 Enter
2258 Called when a widget receives the input focus.
2259 See also: "Leave", "focused", "selected"
2261 FontChanged
2263 Called when a widget font is changed either by direct property
2264 change or by the system.
2265 See also: "font", "ColorChanged"
2267 Hide
2269 Triggered by a successive visible(0) call
2270 See also: "Show", "visible", "showing", "exposed"
2272 Hint SHOW_FLAG
2274 Called when the hint label is about to show or hide, depending on
2275 SHOW_FLAG. The hint show or hide action fails, if the event flag is
2276 cleared during execution.
2277 See also: "showHint", "ownerShowHint", "hintVisible", "ownerHint"
2279 KeyDown CODE, KEY, MOD, REPEAT
2281 Sent to the focused widget when the user presses a key. CODE
2282 contains an eventual character code, KEY is one of "kb::XXX"
2283 constants, MOD is a combination of the modificator keys pressed
2284 when the event occurred ( "km::XXX" ). REPEAT is how many times the
2285 key was pressed; usually it is 1. ( see "::briefKeys" ).
2286 The valid "km::" constants are:
2288 km::Shift
2290 km::Ctrl
2291 km::Alt
2292 km::KeyPad
2293 km::DeadKey
2294 km::Unicode
2295 The valid "kb::" constants are grouped in several sets. Some codes
2297 are aliased, like, "kb::PgDn" and "kb::PageDown".
2298 Modificator keys
2300 kb::ShiftL kb::ShiftR kb::CtrlL kb::CtrlR
2301 kb::AltL kb::AltR kb::MetaL kb::MetaR
2302 kb::SuperL kb::SuperR kb::HyperL kb::HyperR
2303 kb::CapsLock kb::NumLock kb::ScrollLock kb::ShiftLock
2304 Keys with character code defined
2306 kb::Backspace kb::Tab kb::Linefeed kb::Enter
2307 kb::Return kb::Escape kb::Esc kb::Space
2308 Function keys
2310 kb::F1 .. kb::F30
2311 kb::L1 .. kb::L10
2312 kb::R1 .. kb::R10
2313 Other
2315 kb::Clear kb::Pause kb::SysRq kb::SysReq
2316 kb::Delete kb::Home kb::Left kb::Up
2317 kb::Right kb::Down kb::PgUp kb::Prior
2318 kb::PageUp kb::PgDn kb::Next kb::PageDown
2319 kb::End kb::Begin kb::Select kb::Print
2320 kb::PrintScr kb::Execute kb::Insert kb::Undo
2321 kb::Redo kb::Menu kb::Find kb::Cancel
2322 kb::Help kb::Break kb::BackTab
2323 See also: "KeyUp", "briefKeys", "key_down", "help", "popup",
2325 "tabOrder", "tabStop", "accelTable"
2326 KeyUp CODE, KEY, MOD
2328 Sent to the focused widget when the user releases a key. CODE
2329 contains an eventual character code, KEY is one of "kb::XXX"
2330 constants, MOD is a combination of the modificator keys pressed
2331 when the event occurred ( "km::XXX" ).
2332 See also: "KeyDown", "key_up"
2334 Leave
2336 Called when the input focus is removed from a widget
2337 See also: "Enter", "focused", "selected"
2339 Menu MENU VAR_NAME
2341 Called before the user-navigated menu ( pop-up or pull-down ) is
2342 about to show another level of submenu on the screen. MENU is
2343 Prima::AbstractMenu descendant, that children to a widget, and
2344 VAR_NAME is the name of the menu item that is about to be shown.
2345 Used for making changes in the menu structures dynamically.
2347 See also: "popupItems"
2349 MouseClick BUTTON, MOD, X, Y, DOUBLE_CLICK
2351 Called when a mouse click ( button is pressed, and then released
2352 within system-defined interval of time ) is happened in the widget
2353 area. BUTTON is one of "mb::XXX" constants, MOD is a combination of
2354 "km::XXX" constants, reflecting pressed modificator keys during the
2355 event, X and Y are the mouse pointer coordinates. DOUBLE_CLICK is a
2356 boolean flag, set to 1 if it was a double click, 0 if a single.
2357 "mb::XXX" constants are:
2359 mb::b1 or mb::Left
2361 mb::b2 or mb::Middle
2362 mb::b3 or mb::Right
2363 mb::b4
2364 mb::b5
2365 mb::b6
2366 mb::b7
2367 mb::b8
2368 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseMove",
2370 "MouseEnter", "MouseLeave"
2371 MouseDown BUTTON, MOD, X, Y
2373 Occurs when the user presses mouse button on a widget. BUTTON is
2374 one of "mb::XXX" constants, MOD is a combination of "km::XXX"
2375 constants, reflecting the pressed modificator keys during the
2376 event, X and Y are the mouse pointer coordinates.
2377 See also: "MouseUp", "MouseClick", "MouseWheel", "MouseMove",
2379 "MouseEnter", "MouseLeave"
2380 MouseEnter MOD, X, Y
2382 Occurs when the mouse pointer is entered the area occupied by a
2383 widget ( without mouse button pressed ). MOD is a combination of
2384 "km::XXX" constants, reflecting the pressed modificator keys during
2385 the event, X and Y are the mouse pointer coordinates.
2386 See also: "MouseDown", "MouseUp", "MouseClick", "MouseWheel",
2388 "MouseMove", "MouseLeave"
2389 MouseLeave
2391 Occurs when the mouse pointer is driven off the area occupied by a
2392 widget ( without mouse button pressed ).
2393 See also: "MouseDown", "MouseUp", "MouseClick", "MouseWheel",
2395 "MouseMove", "MouseEnter"
2396 MouseMove MOD, X, Y
2398 Occurs when the mouse pointer is transported over a widget. MOD is
2399 a combination of "km::XXX" constants, reflecting the pressed
2400 modificator keys during the event, X and Y are the mouse pointer
2401 coordinates.
2402 See also: "MouseDown", "MouseUp", "MouseClick", "MouseWheel",
2404 "MouseEnter", "MouseLeave"
2405 MouseUp BUTTON, MOD, X, Y
2407 Occurs when the user depresses mouse button on a widget. BUTTON is
2408 one of "mb::XXX" constants, MOD is a combination of "km::XXX"
2409 constants, reflecting the pressed modificator keys during the
2410 event, X and Y are the mouse pointer coordinates.
2411 See also: "MouseDown", "MouseClick", "MouseWheel", "MouseMove",
2413 "MouseEnter", "MouseLeave"
2414 MouseWheel MOD, X, Y, INCR
2416 Occurs when the user rotates mouse wheel on a widget. MOD is a
2417 combination of "km::XXX" constants, reflecting the pressed
2418 modificator keys during the event, INCR is the wheel movement,
2419 scaled by 120. +120 is a step upwards, or -120 downwards. For
2420 wheels which are discrete button clicks INCR is +/-120 but other
2421 devices may give other amounts. A widget should scroll by INCR/120
2422 many units, or partial unit, for whatever its unit of movement
2423 might be, such as lines of text, slider ticks, etc.
2424 A widget might like to vary its unit move according to the MOD
2426 keys. For example "Prima::SpinEdit" has a "step" and "pageStep"
2427 and moves by "pageStep" when "km::Ctrl" is held down (see
2428 Prima::Sliders).
2429 See also: "MouseDown", "MouseUp", "MouseClick", "MouseMove",
2431 "MouseEnter", "MouseLeave"
2432 Move OLD_X, OLD_Y, NEW_X, NEW_Y
2434 Triggered when widget changes its position relative to its parent,
2435 either by Prima::Widget methods or by the user. OLD_X and OLD_Y
2436 are the old coordinates of a widget, NEW_X and NEW_Y are the new
2437 ones.
2438 See also: "Size", "origin", "growMode", "centered", "clipOwner"
2440 Paint CANVAS
2442 Caused when the system calls for the refresh of a graphic context,
2443 associated with a widget. CANVAS is the widget itself, however its
2444 usage instead of widget is recommended ( see "Graphic content" ).
2445 See also: "repaint", "syncPaint", "get_invalid_rect", "scroll",
2447 "colorIndex", "font"
2448 Popup BY_MOUSE, X, Y
2450 Called by the system when the user presses a key or mouse
2451 combination defined for a context pop-up menu execution. By
2452 default executes the associated Prima::Popup object, if it is
2453 present. If the event flag is cleared during the execution of
2454 callbacks, the pop-up menu is not shown.
2455 See also: "popup"
2457 Setup
2459 This message is posted right after "Create" notification, and comes
2460 first from the event loop. Prima::Widget does not use it.
2461 Show
2463 Triggered by a successive visible(1) call
2464 See also: "Show", "visible", "showing", "exposed"
2466 Size OLD_WIDTH, OLD_HEIGHT, NEW_WIDTH, NEW_HEIGHT
2468 Triggered when widget changes its size, either by Prima::Widget
2469 methods or by the user. OLD_WIDTH and OLD_HEIGHT are the old
2470 extensions of a widget, NEW_WIDTH and NEW_HEIGHT are the new ones.
2471 See also: "Move", "origin", "size", "growMode", "sizeMax",
2473 "sizeMin", "rect", "clipOwner"
2474 SysHandle
2476 Same as in "Component", but introduces the following "Widget"
2477 properties can trigger it:
2478 clipOwner, syncPaint, layered, transparent
2480 This event will be only needed when the system handle (that can be
2482 acquired by "get_handle" ) is needed.
2483 TranslateAccel CODE, KEY, MOD
2485 A distributed "KeyDown" event. Traverses all the object tree that
2486 the widget which received original "KeyDown" event belongs to. Once
2487 the event flag is cleared, the iteration stops.
2488 Used for tracking keyboard events by out-of-focus widgets.
2490 See also: "KeyDown"
2492 ZOrderChanged
2494 Triggered when a widget changes its stacking order, or Z-order
2495 among its siblings, either by Prima::Widget methods or by the user.
2496 See also: "bring_to_front", "insert_behind", "send_to_back"
2498
2500 Dmitry Karasik, <dmitry@karasik.eu.org>.
2501
2503 Prima, Prima::Object, Prima::Drawable.
2504perl v5.30.1 2020-01-30 pod::Prima::Widget(3)