1pod::Prima::Widget(3) User Contributed Perl Documentationpod::Prima::Widget(3)
2
3
4

NAME

6       Prima::Widget - window management
7

SYNOPSIS

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
21          # manipulate the widget
22          $widget-> origin( 10, 10);
23          $widget-> show;
24

DESCRIPTION

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

USAGE

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
44       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

Creation and destruction

49       The widget creation syntax is the same as for the other Prima objects:
50
51          Prima::Widget-> create(
52             name => 'Widget',
53             size => [ 20, 10],
54             onMouseClick => sub { print "click\n"; },
55             owner => $owner,
56          );
57
58       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
66          $owner-> insert( 'Prima::Widget',
67             name => 'Widget',
68             size => [ 20, 10],
69             onMouseClick => sub { print "click\n"; },
70          );
71
72       These two examples produce identical results.
73
74       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
84       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
88       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

Graphic content

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
102   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
109          $widget-> notify('Paint', $some_other_widget);
110
111       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
115       The example of "Paint" callback is quite simple:
116
117          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
130       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
142         $x-> repaint()
143
144       code is a mere alias to
145
146         $x-> invalidate_rect( 0, 0, $x-> size);
147
148       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
158       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
164          $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
172       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
177       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
185   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
192       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
199       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
208          $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
225       And the direct driven:
226
227          $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
235       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
242       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

Geometry

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
260       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
265       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
270   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
278       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
295       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
307       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
312                           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
319       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
327                           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
335   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
348       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
364       The geometry request size is useless under "gt::GrowMode" geometry
365       manager, but Tk managers use it extensively.
366
367   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
378       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
383       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
393       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
400       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

Z-order

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
410       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
416       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
419       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
425       Changes to Z-order trigger "ZOrderChanged" notification.
426

Parent-child relationship

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
442       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
447       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
460       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
467       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

Visibility

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
479       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
494       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
504       Visibility changes trigger "Hide" and "Show" notifications.
505

Focus

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
513       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
518       "::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
528       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
533       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
543       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
550       Changes to focus produce "Enter" and "Leave" notifications.
551
552       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
556   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
563       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
568       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
575       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
585   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
595       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

User input

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
622   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
643           "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
656           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
665           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
673       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
678       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
684           These methods are convenience wrappers for "key_event()" method,
685           which is never used directly.
686
687   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
695           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
709           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
715       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
721       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
727           These methods are convenience wrappers for "mouse_event()" method,
728           which is never used directly.
729
730   Drag and drop
731       Widgets can participate in full drag and drop sessions with other
732       applications and itself, with very few restrictions. See below how to
733       use this functionality.
734
735       Data exchange
736           Prima defines a special clipboard object that serves as an exchange
737           point whenever data is to be either sent or received. In order to
738           either offer to, or choose from, many formats of another DND
739           client, use that clipboard to operate with standard
740           open/fetch/store/close methods (see more at Prima::Clipboard).
741
742           The clipboard can be accessed at any time by calling "
743           $::application-" get_dnd_clipboard >, however during handling of
744           dropping events it will stay read-only.
745
746           To successfully exchange data with other applictions, one may
747           investigate results of "$clipboard-> get_formats(1)" to see what
748           types of data the selected application can exchange. With a high
749           probability many programs can exchange text and image in a system-
750           dependent format, however it is also common to see applications to
751           exchange data in format names that match their MIME description.
752           For example Prima supports image formats like "image/bmp" out of
753           the box, and "text/plain" on X11, that are selected automatically
754           when operating with pseudo-formats "Text" or "Image". Other MIME
755           formats like f.ex.  "text/html" are not known to Prima, but can be
756           exchanged quite easily; one needs to register that format first
757           using "Clipbpard::register_format", once, and then it is ready for
758           exachange.
759
760       Dragging
761           To initiate the drag, first fill the DND clipboard with data to be
762           exchanged, using one or more formats, then call either "start_dnd".
763           Alternatively, call "begin_drag", a wrapper method that can set up
764           clipboard data itself. See their documentation for more details.
765
766           During the dragging, the sender will receive "DragQuery" and
767           "DragResponse" events, in order to decide whether the drag session
768           must continue or stop depending on the user input, and reflect that
769           back to the user. Traditionally, mouse cursors are changed to show
770           whether an application will receive a drop, and if yes, what action
771           (copy, move, or link) it will participate in. Prima will try its
772           best to either use system cursors, or synthesise ones that are
773           informative enough; if that is not sufficient, one may present own
774           cursor schema (see f.ex how "begin_drag" is implemented).
775
776       Dropping
777           To register a widget as a drop target, set its "dndAware" property
778           to either 1, to mark that it will answer to all formats, or to a
779           string, in which case drop events will only be delivered if the DND
780           clipboard contains a format with that string.
781
782           Thereafter, when the user will initiate a DND session and will move
783           mouse pointer over the widget, it will receive a "DragBegin" event,
784           then series of "DragOver" events, and finally a "DragEnd" event
785           with a flag telling whether the user chose to drop the data or
786           cancel the session.
787
788           The "DragOver" and "DragEnd" callbacks have a chance to either
789           allow or deny data, and select an action (if there are more than
790           one allowed by the other application) to proceed with. To do so,
791           set appropriate values to "{allow}" and "{action}" in the last
792           hashref parameter that is sent to these event handlers.
793           Additionally, "DragOver" can set a "{pad}" rectangle that will
794           cache the last answer and will tell the system not to send repeated
795           event with same input while the mouse pointer stays in the same
796           rectangle.
797
798       Portability
799           X11 and Win32 are rather identical in how they are handing a DND
800           session from the user's perspective. The only difference that is
801           significant to Prima here is whether the sender or the receiver is
802           responsible to select an action for available list of actions, when
803           the user presses modifier keys, like CTRL or SHIFT.
804
805           On X11, it is the sender that contols that aspect, and tells the
806           receiver what action at any given moment the user chose, by
807           responding to a "DragQuery" event. On Win32, it is the receiver
808           that selects an action from the list on each "DragOver" event,
809           depending on modifier keys pressed by the user; Windows recommends
810           to adhere to the standard scheme where CTRL mark "dnd::Move"
811           action, and SHIFT the "dnd::Link", but that is up to the receiver.
812
813           Thus, to write an effective portable program, assume that your
814           program may control the actions both as sender and as a receiver;
815           Prima system-dependent code will make sure that there will be no
816           ambiguities on the input. F.ex. a sender on Win32 will never be
817           presented with a combination of several "dnd::" constants inside a
818           "DragQuery" event, and a X11 receiver will similarly never be
819           presented with such combination inside "DragOver". However, a
820           portable program must be prepared to select and return a DND action
821           in either callback.
822
823           Additionally, a X11 non-Prima receiver, when presented with a
824           multiple choice of actions, may ask the user what action to select,
825           or cancel the session altogether. This is okay and is expected by
826           the user.
827

Color schemes

829       Prima::Drawable deals only with such color values, that can be
830       unambiguously decomposed to their red, green and blue components.
831       Prima::Widget extends the range of the values acceptable by its color
832       properties, introducing the color schemes.  The color can be set
833       indirectly, without prior knowledge of what is its RGB value. There are
834       several constants defined in "cl::" name space, that correspond to the
835       default values of different color properties of a widget.
836
837       Prima::Widget revises the usage of "::color" and "::backColor", the
838       properties inherited from Prima::Drawable. Their values are widget's
839       'foreground' and 'background' colors, in addition to their function as
840       template values. Moreover, their dynamic change induces the repainting
841       of a widget, and they can be inherited from the owner. The inheritance
842       is governed by properties "::ownerColor" and "::ownerBackColor". While
843       these are true, changes to owner "::color" or "::backColor" copied
844       automatically to a widget. Once the widget's "::color" or "::backColor"
845       are explicitly set, the owner link breaks automatically by setting
846       "::ownerColor" or "::ownerBackColor" to 0.
847
848       In addition to these two color properties, Prima::Widget introduces six
849       others.  These are "::disabledColor", "::disabledBackColor",
850       "::hiliteColor", "::hiliteBackColor", "::light3DColor", and
851       "::dark3DColor".  The 'disabled' color pair contains the values that
852       are expected to be used as foreground and background when a widget is
853       in the disabled state ( see API, "::enabled" property ). The 'hilite'
854       values serve as the colors for representation of selection inside a
855       widget. Selection may be of any kind, and some widgets do not provide
856       any. But for those that do, the 'hilite' color values provide distinct
857       alternative colors. Examples are selections in the text widgets, or in
858       the list boxes. The last pair, "::light3DColor" and "::dark3DColor" is
859       used for drawing 3D-looking outlines of a widget. The purpose of all
860       these properties is the adequate usage of the color settings, selected
861       by the user using system-specific tools, so the program written with
862       the toolkit would look not such different, and more or less conformant
863       to the user's color preferences.
864
865       The additional "cl::" constants, mentioned above, represent these eight
866       color properties. These named correspondingly, cl::NormalText,
867       cl::Normal, cl::HiliteText, cl::Hilite, cl::DisabledText, cl::Disabled,
868       cl::Light3DColor and cl::Dark3DColor. cl::NormalText is alias to
869       cl::Fore, and cl::Normal - to cl::Back. Another constant set, "ci::"
870       can be used with the "::colorIndex" property, a multiplexer for all
871       eight color properties. "ci::" constants mimic their non-RGB "cl::"
872       counterparts, so the call "hiliteBackColor(cl::Red)" is equal to
873       "colorIndex(ci::Hilite, cl::Red)".
874
875       Mapping from these constants to the RGB color representation is used
876       with "map_color()" method. These "cl::" constants alone are sufficient
877       for acquiring the default values, but the toolkit provides wider
878       functionality than this. The "cl::" constants can be combined with the
879       "wc::" constants, that represent standard widget class.  The widget
880       class is implicitly used when single "cl::" constant is used; its value
881       is read from the "::widgetClass" property, unless one of "wc::"
882       constants is combined with the non-RGB "cl::" value. "wc::" constants
883       are described in "API"; their usage can make call of, for example,
884       "backColor( cl::Back)" on a button and on an input line result in
885       different colors, because the "cl::Back" is translated in the first
886       case into "cl::Back|wc::Button", and in another -
887       "cl::Back|wc::InputLine".
888
889       Dynamic change of the color properties result in the "ColorChanged"
890       notification.
891

Fonts

893       Prima::Widget does not change the handling of fonts - the font
894       selection inside and outside "begin_paint()"/"end_paint()" is not
895       different at all. A matter of difference is how does Prima::Widget
896       select the default font.
897
898       First, if the "::ownerFont" property is set to 1, then font of the
899       owner is copied to the widget, and is maintained all the time while the
900       property is true.  If it is not, the default font values read from the
901       system.
902
903       The default font metrics for a widget returned by "get_default_font()"
904       method, that often deals with system-dependent and user-selected
905       preferences ( see "Additional resources" ). Because a widget can host
906       an eventual Prima::Popup object, it contains "get_default_popup_font()"
907       method, that returns the default font for the popup objects. The
908       dynamic popup font settings governed, naturally, by the "::popupFont"
909       property. Prima::Window extends the functionality to
910       "get_default_menu_font()" and the "::menuFont" property.
911
912       Dynamic change of the font property results in the "FontChanged"
913       notification.
914

Additional resources

916       The resources, operated via Prima::Widget class but not that strictly
917       bound to the widget concept, are gathered in this section. The section
918       includes overview of pointer, cursor, hint, menu objects and user-
919       specified resources.
920
921   Markup text
922       "Prima::Drawable::Markup" provides text-like objects that can include
923       font and color change, and has a primitive image support. Since text
924       methods of "Prima::Drawable" such as "text_out", "get_text_width" etc
925       can detect if a text passed is actually a blessed object, and make a
926       corresponding call on it, the markup objects can be used transparently
927       when rich text is needed, simply by passing them to "text" and "hint"
928       properties.
929
930       There are two ways to construct a markup object: either directly:
931
932          Prima::Drawable::Markup->new( ... )
933
934       or using an imported method "M",
935
936          use Prima::Drawable::Markup q(M);
937          M '...';
938
939       where results of both can be directly set to almost any textual
940       property throughout the whole toolkit, provided that the classes are
941       not peeking inside the object but only calling drawing methods on them.
942
943       In addition to that, "Prima::Widget" and its descendants recognize a
944       third syntax
945
946         Widget->new( text => \ 'markup' )
947
948       treating a scalar reference to a text string as a sign that this is
949       actually the text to be compiled into a markup object.
950
951   Pointer
952       The mouse pointer is the shared resource, that can change its visual
953       representation when it hovers over different kinds of widgets.  It is
954       usually a good practice for a text field, for example, set the pointer
955       icon to a jagged vertical line, or indicate a moving window with a
956       cross-arrowed pointer.
957
958       A widget can select either one of the predefined system pointers,
959       mapped by the "cr::XXX" constant set, or supply its own pointer icon of
960       an arbitrary size and color depth.
961
962       NB: Not all systems allow the colored pointer icons. System value under
963       sv::ColorPointer index containing a boolean value, whether the colored
964       icons are allowed or not. Also, the pointer icon size may have a limit:
965       check if sv::FixedPointerSize is non-zero, in which case the pointer
966       size will be reduced to the system limits.
967
968       In general, the "::pointer" property is enough for these actions.  It
969       discerns whether it has an icon or a constant passed, and sets the
970       appropriate properties. These properties are also accessible
971       separately, although their usage is not encouraged, primarily because
972       of the tangled relationship between them. These properties are:
973       "::pointerType", "::pointerIcon", and "::pointerHotSpot". See their
974       details in the "API" sections.
975
976       Another property, which is present only in Prima::Application name
977       space is called "::pointerVisible", and governs the visibility of the
978       pointer - but for all widget instances at once.
979
980   Cursor
981       The cursor is a blinking rectangular area, indicating the availability
982       of the input focus in a widget. There can be only one active cursor per
983       a GUI space, or none at all. Prima::Widget provides several cursor
984       properties: "::cursorVisible", "::cursorPos", and "::cursorSize". There
985       are also two methods, "show_cursor()" and "hide_cursor()", which are
986       not the convenience shortcuts but the functions accounting the cursor
987       hide count. If "hide_cursor()" was called three times, then
988       "show_cursor()" must be called three times as well for the cursor to
989       become visible.
990
991   Hint
992       "::hint" is a text string, that usually describes the widget's purpose
993       to the user in a brief manner. If the mouse pointer is hovered over the
994       widget longer than some timeout ( see Prima::Application::hintPause ),
995       then a label appears with the hint text, until the pointer is drawn
996       away.  The hint behavior is governed by Prima::Application, but a
997       widget can do two additional things about hint: it can enable and
998       disable it by calling "::showHint" property, and it can inherit the
999       owner's "::hint" and "::showHint" properties using "::ownerHint" and
1000       "::ownerShowHint" properties. If, for example, "::ownerHint" is set to
1001       1, then "::hint" value is automatically copied from the widget's owner,
1002       when it changes. If, however, the widget's "::hint" or "::showHint" are
1003       explicitly set, the owner link breaks automatically by setting
1004       "::ownerHint" or "::ownerShowHint" to 0.
1005
1006       The widget can also operate the "::hintVisible" property, that shows or
1007       hides the hint label immediately, if the mouse pointer is inside the
1008       widget's boundaries.
1009
1010   Menu objects
1011       The default functionality of Prima::Widget coexists with two kinds of
1012       the Prima::AbstractMenu descendants - Prima::AccelTable and
1013       Prima::Popup ( Prima::Window is also equipped with Prima::Menu
1014       reference). The "::items" property of these objects are accessible
1015       through "::accelItems" and "::popupItems", whereas the objects
1016       themselves - through "::accelTable" and "::popup", correspondingly. As
1017       mentioned in "User input", these objects hook the user keyboard input
1018       and call the programmer-defined callback subroutine if the key stroke
1019       equals to one of their table values. As for "::accelTable", its
1020       function ends here. "::popup" provides access to a context pop-up menu,
1021       which can be invoked by either right-clicking or pressing a system-
1022       dependent key combination. As a little customization, the
1023       "::popupColorIndex" and "::popupFont" properties are introduced.  (
1024       "::popupColorIndex" is multiplexed to "::popupColor",
1025       "::popupHiliteColor", "::popupHiliteBackColor", etc etc properties
1026       exactly like the "::colorIndex" property ).
1027
1028       The font and color of a menu object might not always be writable
1029       (Win32).
1030
1031       The Prima::Window class provides equivalent methods for the menu bar,
1032       introducing "::menu", "::menuItems", "::menuColorIndex" ( with
1033       multiplexing ) and "::menuFont" properties.
1034
1035   User-specified resources
1036       It is considered a good idea to incorporate the user preferences into
1037       the toolkit look-and-feel. Prima::Widget relies to the system-specific
1038       code that tries to map these preferences as close as possible to the
1039       toolkit paradigm.
1040
1041       Unix version employs XRDB ( X resource database ), which is the natural
1042       way for the user to tell the preferences with fine granularity. Win32
1043       reads the setting that the user has to set interactively, using system
1044       tools. Nevertheless, the toolkit can not emulate all user settings that
1045       are available on the supported platforms; it rather takes a 'least
1046       common denominator', which is colors and fonts. "fetch_resource()"
1047       method is capable of returning any of such settings, provided it's
1048       format is font, color or a string.  The method is rarely called
1049       directly.
1050
1051       The appealing idea of making every widget property adjustable via the
1052       user-specified resources is not implemented in full.  It can be
1053       accomplished up to a certain degree using "fetch_resource()" existing
1054       functionality, but it is believed that calling up the method for the
1055       every property for the every widget created is prohibitively expensive.
1056

API

1058   Properties
1059       accelItems [ ITEM_LIST ]
1060           Manages items of a Prima::AccelTable object associated with a
1061           widget.  The ITEM_LIST format is same as
1062           "Prima::AbstractMenu::items" and is described in Prima::Menu.
1063
1064           See also: "accelTable"
1065
1066       accelTable OBJECT
1067           Manages a Prima::AccelTable object associated with a widget.  The
1068           sole purpose of the accelTable object is to provide convenience
1069           mapping of key combinations to anonymous subroutines.  Instead of
1070           writing an interface specifically for Prima::Widget, the existing
1071           interface of Prima::AbstractMenu was taken.
1072
1073           The accelTable object can be destroyed safely; its cancellation can
1074           be done either via "accelTable(undef)" or "destroy()" call.
1075
1076           Default value: undef
1077
1078           See also: "accelItems"
1079
1080       autoEnableChildren BOOLEAN
1081           If TRUE, all immediate children widgets maintain the same "enabled"
1082           state as the widget. This property is useful for the group-like
1083           widgets ( ComboBox, SpinEdit etc ), that employ their children for
1084           visual representation.
1085
1086           Default value: 0
1087
1088       backColor COLOR
1089           In widget paint state, reflects background color in the graphic
1090           context.  In widget normal state, manages the basic background
1091           color.  If changed, initiates "ColorChanged" notification and
1092           repaints the widget.
1093
1094           See also: "color", "colorIndex", "ColorChanged"
1095
1096       bottom INTEGER
1097           Maintains the lower boundary of a widget. If changed, does not
1098           affect the widget height; but does so, if called in "set()"
1099           together with "::top".
1100
1101           See also: "left", "right", "top", "origin", "rect", "growMode",
1102           "Move"
1103
1104       briefKeys BOOLEAN
1105           If 1, contracts the repetitive key press events into one
1106           notification, increasing REPEAT parameter of "KeyDown" callbacks.
1107           If 0, REPEAT parameter is always 1.
1108
1109           Default value: 1
1110
1111           See also: "KeyDown"
1112
1113       buffered BOOLEAN
1114           If 1, a widget "Paint" callback draws not on the screen, but on the
1115           off-screen memory instead. The memory content is copied to the
1116           screen then. Used when complex drawing methods are used, or if
1117           output smoothness is desired.
1118
1119           This behavior can not be always granted, however. If there is not
1120           enough memory, then widget draws in the usual manner.
1121
1122           Default value: 0
1123
1124           See also: "Paint"
1125
1126       capture BOOLEAN, CLIP_OBJECT = undef
1127           Manipulates capturing of the mouse events. If 1, the mouse events
1128           are not passed to the widget the mouse pointer is over, but are
1129           redirected to the caller widget. The call for capture might not be
1130           always granted due the race conditions between programs.
1131
1132           If CLIP_OBJECT widget is defined in set-mode call, the pointer
1133           movements are confined to CLIP_OBJECT inferior.
1134
1135           See also: "MouseDown", "MouseUp", "MouseMove", "MouseWheel",
1136           "MouseClick".
1137
1138       centered BOOLEAN
1139           A write-only property. Once set, widget is centered by X and Y axis
1140           relative to its owner.
1141
1142           See also: "x_centered", "y_centered", "growMode", "origin", "Move".
1143
1144       clipChildren BOOLEAN
1145           Affects the drawing mode when children widgets are present and
1146           obscuring the drawing area.  If set, the children widgets are
1147           automatically added to the clipping area, and drawing over them
1148           will not happen. If unset, the painting can be done over the
1149           children widgets.
1150
1151           Default: 1
1152
1153       clipOwner BOOLEAN
1154           If 1, a widget is clipped by its owner boundaries.  It is the
1155           default and expected behavior. If clipOwner is 0, a widget behaves
1156           differently: it does not clipped by the owner, it is not moved
1157           together with the parent, the origin offset is calculated not from
1158           the owner's coordinates but from the screen, and mouse events in a
1159           widget do not transgress to the top-level window decorations. In
1160           short, it itself becomes a top-level window, that, contrary to the
1161           one created from Prima::Window class, does not have any
1162           interference with system-dependent window stacking and positioning
1163           ( and any other ) policy, and is not ornamented by the window
1164           manager decorations.
1165
1166           Default value: 1
1167
1168           See "Parent-child relationship"
1169
1170           See also: "Prima::Object" owner section, "parentHandle"
1171
1172       color COLOR
1173           In widget paint state, reflects foreground color in the graphic
1174           context.  In widget normal state, manages the basic foreground
1175           color.  If changed, initiates "ColorChanged" notification and
1176           repaints the widget.
1177
1178           See also: "backColor", "colorIndex", "ColorChanged"
1179
1180       colorIndex INDEX, COLOR
1181           Manages the basic color properties indirectly, by accessing via
1182           "ci::XXX" constant. Is a complete alias for "::color",
1183           "::backColor", "::hiliteColor", "::hiliteBackColor",
1184           "::disabledColor", "::disabledBackColor", "::light3DColor", and
1185           "::dark3DColor" properties. The "ci::XXX" constants are:
1186
1187              ci::NormalText or ci::Fore
1188              ci::Normal or ci::Back
1189              ci::HiliteText
1190              ci::Hilite
1191              ci::DisabledText
1192              ci::Disabled
1193              ci::Light3DColor
1194              ci::Dark3DColor
1195
1196           The non-RGB "cl::" constants, specific to the Prima::Widget color
1197           usage are identical to their "ci::" counterparts:
1198
1199              cl::NormalText or cl::Fore
1200              cl::Normal or cl::Back
1201              cl::HiliteText
1202              cl::Hilite
1203              cl::DisabledText
1204              cl::Disabled
1205              cl::Light3DColor
1206              cl::Dark3DColor
1207
1208           See also: "color", "backColor", "ColorChanged"
1209
1210       current BOOLEAN
1211           If 1, a widget (or one of its children) is marked as the one to be
1212           focused ( or selected) when the owner widget receives "select()"
1213           call.  Within children widgets, only one or none at all can be
1214           marked as a current.
1215
1216           See also: "currentWidget", "selectable", "selected",
1217           "selectedWidget", "focused"
1218
1219       currentWidget OBJECT
1220           Points to a children widget, that is to be focused ( or selected)
1221           when the owner widget receives "select()" call.
1222
1223           See also: "current", "selectable", "selected", "selectedWidget",
1224           "focused"
1225
1226       cursorPos X_OFFSET Y_OFFSET
1227           Specifies the lower left corner of the cursor
1228
1229           See also: "cursorSize", "cursorVisible"
1230
1231       cursorSize WIDTH HEIGHT
1232           Specifies width and height of the cursor
1233
1234           See also: "cursorPos", "cursorVisible"
1235
1236       cursorVisible BOOLEAN
1237           Specifies cursor visibility flag. Default value is 0.
1238
1239           See also: "cursorSize", "cursorPos"
1240
1241       dark3DColor COLOR
1242           The color used to draw dark shades.
1243
1244           See also: "light3DColor", "colorIndex", "ColorChanged"
1245
1246       designScale X_SCALE Y_SCALE
1247           The width and height of a font, that was used when a widget (
1248           usually  a dialog or a grouping widget ) was designed.
1249
1250           See also: "scaleChildren", "width", "height", "size", "font"
1251
1252       disabledBackColor COLOR
1253           The color used to substitute "::backColor" when a widget is in its
1254           disabled state.
1255
1256           See also: "disabledColor", "colorIndex", "ColorChanged"
1257
1258       disabledColor COLOR
1259           The color used to substitute "::color" when a widget is in its
1260           disabled state.
1261
1262           See also: "disabledBackColor", "colorIndex", "ColorChanged"
1263
1264       dndAware 0 | 1 | FORMAT
1265           To register a widget as a drop target, set its "dndAware" property
1266           to either 1, to mark that it will answer to all formats, or to a
1267           string, in which case drop events will only be delivered if the DND
1268           clipboard contains a format with that string.
1269
1270           Default: 0
1271
1272           See also: "Drag and Drop"
1273
1274       enabled BOOLEAN
1275           Specifies if a widget can accept focus, keyboard and mouse events.
1276           Default value is 1, however, being 'enabled' does not automatically
1277           allow the widget become focused. Only the reverse is true - if
1278           enabled is 0, focusing can never happen.
1279
1280           See also: "responsive", "visible", "Enable", "Disable"
1281
1282       font %FONT
1283           Manages font context. Same syntax as in Prima::Drawable.  If
1284           changed, initiates "FontChanged" notification and repaints the
1285           widget.
1286
1287           See also: "designScale", "FontChanged", "ColorChanged"
1288
1289       geometry INTEGER
1290           Selects one of the available geometry managers. The corresponding
1291           integer constants are:
1292
1293              gt::GrowMode, gt::Default - the default grow-mode algorithm
1294              gt::Pack                  - Tk packer
1295              gt::Place                 - Tk placer
1296
1297           See "growMode", Prima::Widget::pack, Prima::Widget::place.
1298
1299       growMode MODE
1300           Specifies widget behavior, when its owner is resized or moved.
1301           MODE can be 0 ( default ) or a combination of the following
1302           constants:
1303
1304           Basic constants
1305                gm::GrowLoX      widget's left side is kept in constant
1306                                 distance from owner's right side
1307                gm::GrowLoY      widget's bottom side is kept in constant
1308                                 distance from owner's top side
1309                gm::GrowHiX      widget's right side is kept in constant
1310                                 distance from owner's right side
1311                gm::GrowHiY      widget's top side is kept in constant
1312                                 distance from owner's top side
1313                gm::XCenter      widget is kept in center on its owner's
1314                                 horizontal axis
1315                gm::YCenter      widget is kept in center on its owner's
1316                                 vertical axis
1317                gm::DontCare     widgets origin is maintained constant relative
1318                                 to the screen
1319
1320           Derived or aliased constants
1321                gm::GrowAll      gm::GrowLoX|gm::GrowLoY|gm::GrowHiX|gm::GrowHiY
1322                gm::Center       gm::XCenter|gm::YCenter
1323                gm::Client       gm::GrowHiX|gm::GrowHiY
1324                gm::Right        gm::GrowLoX|gm::GrowHiY
1325                gm::Left         gm::GrowHiY
1326                gm::Floor        gm::GrowHiX
1327
1328           See also: "Move", "origin"
1329
1330       firstClick BOOLEAN
1331           If 0, a widget bypasses first mouse click on it, if the top-level
1332           window it belongs to was not activated, so selecting such a widget
1333           it takes two mouse clicks.
1334
1335           Default value is 1
1336
1337           See also: "MouseDown", "selectable", "selected", "focused",
1338           "selectingButtons"
1339
1340       focused BOOLEAN
1341           Specifies whether a widget possesses the input focus or not.
1342           Disregards "::selectable" property on set-call.
1343
1344           See also: "selectable", "selected", "selectedWidget", "KeyDown"
1345
1346       geomWidth, geomHeight, geomSize
1347           Three properties that select geometry request size. Writing and
1348           reading to "::geomWidth" and "::geomHeight" is equivalent to
1349           "::geomSize". The properies are run-time only, and behave
1350           differently under different circumstances:
1351
1352           •   As the properties are run-time only, they can not be set in the
1353               profile, and their initial value is fetched from "::size"
1354               property. Thus, setting the explicit size is aditionally sets
1355               the advised size in case the widget is to be used with the Tk
1356               geometry managers.
1357
1358           •   Setting the properties under the "gt::GrowMode" geometry
1359               manager also sets the corresponding "::width", "::height", or
1360               "::size". When the properties are read, though, the real size
1361               properties are not read; the values are kept separately.
1362
1363           •   Setting the properties under Tk geometry managers cause widgets
1364               size and position changed according to the geometry manager
1365               policy.
1366
1367       height
1368           Maintains the height of a widget.
1369
1370           See also: "width", "growMode", "Move", "Size", "get_virtual_size",
1371           "sizeMax", "sizeMin"
1372
1373       helpContext STRING
1374           A string that binds a widget, a logical part it plays with the
1375           application and an interactive help topic. STRING format is defined
1376           as POD link ( see perlpod ) - "manpage/section", where 'manpage' is
1377           the file with POD content and 'section' is the topic inside the
1378           manpage.
1379
1380           See also: "help"
1381
1382       hiliteBackColor COLOR
1383           The color used to draw alternate background areas with high
1384           contrast.
1385
1386           See also: "hiliteColor", "colorIndex", "ColorChanged"
1387
1388       hiliteColor COLOR
1389           The color used to draw alternate foreground areas with high
1390           contrast.
1391
1392           See also: "hiliteBackColor", "colorIndex", "ColorChanged"
1393
1394       hint TEXT
1395           A text, shown under mouse pointer if it is hovered over a widget
1396           longer than "Prima::Application::hintPause" timeout. The text shows
1397           only if the "::showHint" is 1.
1398
1399           See also: "hintVisible", "showHint", "ownerHint", "ownerShowHint"
1400
1401       hintVisible BOOLEAN
1402           If called in get-form, returns whether the hint label is shown or
1403           not. If in set-form, immediately turns on or off the hint label,
1404           disregarding the timeouts. It does regard the mouse pointer
1405           location, however, and does not turn on the hint label if the
1406           pointer is away.
1407
1408           See also: "hint", "showHint", "ownerHint", "ownerShowHint"
1409
1410       layered BOOLEAN
1411           If set, the widget will try to use alpha transparency available on
1412           the system.  See "Layering" in Prima::Image for more details.
1413
1414           Default: false
1415
1416           See also: "is_surface_layered"
1417
1418           Note: In Windows, mouse events will not be delivered to the layered
1419           widget if the pixel under the mouse pointer is fully transparent.
1420
1421           In X11, you need to run a composition manager, f.ex. compiz or
1422           xcompmgr.
1423
1424       left INTEGER
1425           Maintains the left boundary of a widget. If changed, does not
1426           affect the widget width; but does so, if called in "set()" together
1427           with "::right".
1428
1429           See also: "bottom", "right", "top", "origin", "rect", "growMode",
1430           "Move"
1431
1432       light3DColor COLOR
1433           The color used to draw light shades.
1434
1435           See also: "dark3DColor", "colorIndex", "ColorChanged"
1436
1437       ownerBackColor BOOLEAN
1438           If 1, the background color is synchronized with the owner's.
1439           Automatically set to 0 if "::backColor" property is explicitly set.
1440
1441           See also: "ownerColor", "backColor", "colorIndex"
1442
1443       ownerColor BOOLEAN
1444           If 1, the foreground color is synchronized with the owner's.
1445           Automatically set to 0 if "::color" property is explicitly set.
1446
1447           See also: "ownerBackColor", "color", "colorIndex"
1448
1449       ownerFont BOOLEAN
1450           If 1, the font is synchronized with the owner's.  Automatically set
1451           to 0 if "::font" property is explicitly set.
1452
1453           See also: "font", "FontChanged"
1454
1455       ownerHint BOOLEAN
1456           If 1, the hint is synchronized with the owner's.  Automatically set
1457           to 0 if "::hint" property is explicitly set.
1458
1459           See also: "hint", "showHint", "hintVisible", "ownerShowHint"
1460
1461       ownerShowHint BOOLEAN
1462           If 1, the show hint flag is synchronized with the owner's.
1463           Automatically set to 0 if "::showHint" property is explicitly set.
1464
1465           See also: "hint", "showHint", "hintVisible", "ownerHint"
1466
1467       ownerPalette BOOLEAN
1468           If 1, the palette array is synchronized with the owner's.
1469           Automatically set to 0 if "::palette" property is explicitly set.
1470
1471           See also: "palette"
1472
1473       origin X Y
1474           Maintains the left and bottom boundaries of a widget relative to
1475           its owner ( or to the screen if "::clipOwner" is set to 0 ).
1476
1477           See also: "bottom", "right", "top", "left", "rect", "growMode",
1478           "Move"
1479
1480       packInfo %OPTIONS
1481           See Prima::Widget::pack
1482
1483       palette [ @PALETTE ]
1484           Specifies array of colors, that are desired to be present into the
1485           system palette, as close to the PALETTE as possible.  This property
1486           works only if the graphic device allows palette operations. See
1487           "palette" in Prima::Drawable.
1488
1489           See also: "ownerPalette"
1490
1491       parentHandle SYSTEM_WINDOW
1492           If SYSTEM_WINDOW is a valid system-dependent window handle, then a
1493           widget becomes the child of the window specified, given the
1494           widget's "::clipOwner" is 0.  The parent window can belong to
1495           another application.
1496
1497           Default value is undef.
1498
1499           See also: "clipOwner"
1500
1501       placeInfo %OPTIONS
1502           See Prima::Widget::place
1503
1504       pointer cr::XXX or ICON
1505           Specifies the pointer icon; discerns between "cr::XXX" constants
1506           and an icon. If an icon contains a hash variable "__pointerHotSpot"
1507           with an array of two integers, these integers will be treated as
1508           the pointer hot spot. In get-mode call, this variable is
1509           automatically assigned to an icon, if the result is an icon object.
1510
1511           See also: "pointerHotSpot", "pointerIcon", "pointerType"
1512
1513       pointerHotSpot X_OFFSET Y_OFFSET
1514           Specifies the hot spot coordinates of a pointer icon, associated
1515           with a widget.
1516
1517           See also: "pointer", "pointerIcon", "pointerType"
1518
1519       pointerIcon ICON
1520           Specifies the pointer icon, associated with a widget.
1521
1522           See also: "pointerHotSpot", "pointer", "pointerType"
1523
1524       pointerPos X_OFFSET Y_OFFSET
1525           Specifies the mouse pointer coordinates relative to widget's
1526           coordinates.
1527
1528           See also: "get_mouse_state", "screen_to_client", "client_to_screen"
1529
1530       pointerType TYPE
1531           Specifies the type of the pointer, associated with the widget.
1532           TYPE can accept one constant of "cr::XXX" set:
1533
1534              cr::Default                 same pointer type as owner's
1535              cr::Arrow                   arrow pointer
1536              cr::Text                    text entry cursor-like pointer
1537              cr::Wait                    hourglass
1538              cr::Size                    general size action pointer
1539              cr::Move                    general move action pointer
1540              cr::SizeWest, cr::SizeW     right-move action pointer
1541              cr::SizeEast, cr::SizeE     left-move action pointer
1542              cr::SizeWE                  general horizontal-move action pointer
1543              cr::SizeNorth, cr::SizeN    up-move action pointer
1544              cr::SizeSouth, cr::SizeS    down-move action pointer
1545              cr::SizeNS                  general vertical-move action pointer
1546              cr::SizeNW                  up-right move action pointer
1547              cr::SizeSE                  down-left move action pointer
1548              cr::SizeNE                  up-left move action pointer
1549              cr::SizeSW                  down-right move action pointer
1550              cr::Invalid                 invalid action pointer
1551              cr::DragNone                pointer for an invalid dragging target
1552              cr::DragCopy                pointer to indicate that a dnd::Copy action can be accepted
1553              cr::DragMove                pointer to indicate that a dnd::Move action can be accepted
1554              cr::DragLink                pointer to indicate that a dnd::Link action can be accepted
1555              cr::User                    user-defined icon
1556
1557           All constants except "cr::User" and "cr::Default" present a system-
1558           defined pointers, their icons and hot spot offsets. "cr::User" is a
1559           sign that an icon object was specified explicitly via
1560           "::pointerIcon" property.  "cr::Default" is a way to tell that a
1561           widget inherits its owner pointer type, no matter is it a system-
1562           defined pointer or a custom icon.
1563
1564           See also: "pointerHotSpot", "pointerIcon", "pointer"
1565
1566       popup OBJECT
1567           Manages a Prima::Popup object associated with a widget.  The
1568           purpose of the popup object is to show a context menu when the user
1569           right-clicks or selects the corresponding keyboard combination.
1570           Prima::Widget can host many children objects, Prima::Popup as well.
1571           But only the one that is set in "::popup" property will be
1572           activated automatically.
1573
1574           The popup object can be destroyed safely; its cancellation can be
1575           done either via "popup(undef)" or "destroy()" call.
1576
1577           See also: "Prima::Menu", "Popup", "Menu", "popupItems",
1578           "popupColorIndex", "popupFont"
1579
1580       popupColorIndex INDEX, COLOR
1581           Maintains eight color properties of a pop-up context menu,
1582           associated with a widget. INDEX must be one of "ci::XXX" constants
1583           ( see "::colorIndex" property ).
1584
1585           See also: "popupItems", "popupFont", "popup"
1586
1587       popupColor COLOR
1588           Basic foreground in a popup context menu color.
1589
1590           See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1591
1592       popupBackColor COLOR
1593           Basic background in a popup context menu color.
1594
1595           See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1596
1597       popupDark3DColor COLOR
1598           Color for drawing dark shadings in a popup context menu.
1599
1600           See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1601
1602       popupDisabledColor COLOR
1603           Foreground color for disabled items in a popup context menu.
1604
1605           See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1606
1607       popupDisabledBackColor COLOR
1608           Background color for disabled items in a popup context menu.
1609
1610           See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1611
1612       popupFont %FONT
1613           Maintains the font of a pop-up context menu, associated with a
1614           widget.
1615
1616           See also: "popupItems", "popupColorIndex", "popup"
1617
1618       popupHiliteColor COLOR
1619           Foreground color for selected items in a popup context menu.
1620
1621           See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1622
1623       popupHiliteBackColor COLOR
1624           Background color for selected items in a popup context menu.
1625
1626           See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1627
1628       popupItems [ ITEM_LIST ]
1629           Manages items of a Prima::Popup object associated with a widget.
1630           The ITEM_LIST format is same as "Prima::AbstractMenu::items" and is
1631           described in Prima::Menu.
1632
1633           See also: "popup", "popupColorIndex", "popupFont"
1634
1635       popupLight3DColor COLOR
1636           Color for drawing light shadings in a popup context menu.
1637
1638           See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1639
1640       rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET Y_TOP_OFFSET
1641           Maintains the rectangular boundaries of a widget relative to its
1642           owner ( or to the screen if "::clipOwner" is set to 0 ).
1643
1644           See also: "bottom", "right", "top", "left", "origin", "width",
1645           "height", "size" "growMode", "Move", "Size", "get_virtual_size",
1646           "sizeMax", "sizeMin"
1647
1648       right INTEGER
1649           Maintains the right boundary of a widget. If changed, does not
1650           affect the widget width; but does so, if called in "set()" together
1651           with "::left".
1652
1653           See also: "left", "bottom", "top", "origin", "rect", "growMode",
1654           "Move"
1655
1656       scaleChildren BOOLEAN
1657           If a widget has "::scaleChildren" set to 1, then the newly-created
1658           children widgets inserted in it will be scaled corresponding to the
1659           owner's "::designScale", given that widget's "::designScale" is not
1660           "undef" and the owner's is not [0,0].
1661
1662           Default is 1.
1663
1664           See also: "designScale"
1665
1666       selectable BOOLEAN
1667           If 1, a widget can be granted focus implicitly, or by means of the
1668           user actions. "select()" regards this property, and does not focus
1669           a widget that has "::selectable" set to 0.
1670
1671           Default value is 0
1672
1673           See also: "current", "currentWidget", "selected", "selectedWidget",
1674           "focused"
1675
1676       selected BOOLEAN
1677           If called in get-mode, returns whether a widget or one of its
1678           (grand-) children is focused. If in set-mode, either simply turns
1679           the system with no-focus state ( if 0 ), or sends input focus to
1680           itself or one of the widgets tracked down by "::currentWidget"
1681           chain.
1682
1683           See also: "current", "currentWidget", "selectable",
1684           "selectedWidget", "focused"
1685
1686       selectedWidget OBJECT
1687           Points to a child widget, that has property "::selected" set to 1.
1688
1689           See also: "current", "currentWidget", "selectable", "selected",
1690           "focused"
1691
1692       selectingButtons FLAGS
1693           FLAGS is a combination of "mb::XXX" ( mouse button ) flags.  If a
1694           widget receives a click with a mouse button, that has the
1695           corresponding bit set in "::selectingButtons", then "select()" is
1696           called.
1697
1698           See also: "MouseDown", "firstClick", "selectable", "selected",
1699           "focused"
1700
1701       shape REGION
1702           Maintains the non-rectangular shape of a widget.  When setting,
1703           REGION is either a Prima::Image object, with 0 bits treated as
1704           transparent pixels, and 1 bits as opaque pixels, or a Prima::Region
1705           object.  When getting, it is either undef or a Prima::Region
1706           object.
1707
1708           Successive only if "sv::ShapeExtension" value is true.
1709
1710       showHint BOOLEAN
1711           If 1, the toolkit is allowed to show the hint label over a widget.
1712           If 0, the display of the hint is forbidden. The "::hint" property
1713           must contain non-empty string as well, if the hint label must be
1714           shown.
1715
1716           Default value is 1.
1717
1718           See also: "hint", "ownerShowHint", "hintVisible", "ownerHint"
1719
1720       size WIDTH HEIGHT
1721           Maintains the width and height of a widget.
1722
1723           See also: "width", "height" "growMode", "Move", "Size",
1724           "get_virtual_size", "sizeMax", "sizeMin"
1725
1726       sizeMax WIDTH HEIGHT
1727           Specifies the maximal size for a widget that it is allowed to
1728           accept.
1729
1730           See also: "width", "height", "size" "growMode", "Move", "Size",
1731           "get_virtual_size", "sizeMin"
1732
1733       sizeMin WIDTH HEIGHT
1734           Specifies the minimal size for a widget that it is allowed to
1735           accept.
1736
1737           See also: "width", "height", "size" "growMode", "Move", "Size",
1738           "get_virtual_size", "sizeMax"
1739
1740       syncPaint BOOLEAN
1741           If 0, the "Paint" request notifications are stacked until the event
1742           loop is called. If 1, every time the widget surface gets
1743           invalidated, the "Paint" notification is called.
1744
1745           Default value is 0.
1746
1747           See also: "invalidate_rect", "repaint", "validate_rect", "Paint"
1748
1749       tabOrder INTEGER
1750           Maintains the order in which tab- and shift-tab- key navigation
1751           algorithms select the sibling widgets. INTEGER is unique among the
1752           sibling widgets. In set mode, if INTEGER value is already taken,
1753           the occupier is assigned another unique value, but without
1754           destruction of a queue - widgets with ::tabOrder greater than of
1755           the widget, receive their new values too. Special value -1 is
1756           accepted as 'the end of list' indicator; the negative value is
1757           never returned.
1758
1759           See also: "tabStop", "next_tab", "selectable", "selected",
1760           "focused"
1761
1762       tabStop BOOLEAN
1763           Specifies whether a widget is interested in tab- and shift-tab- key
1764           navigation or not.
1765
1766           Default value is 1.
1767
1768           See also: "tabOrder", "next_tab", "selectable", "selected",
1769           "focused"
1770
1771       text TEXT
1772           A text string for generic purpose. Many Prima::Widget descendants
1773           use this property heavily - buttons, labels, input lines etc, but
1774           Prima::Widget itself does not.
1775
1776           If "TEXT" is a reference to a string, it is translated as a markup
1777           string, and is compiled into a "Prima::Drawable::Markup" object
1778           internally.
1779
1780           See Prima::Drawable::Markup, examples/markup.pl
1781
1782       top INTEGER
1783           Maintains the upper boundary of a widget. If changed, does not
1784           affect the widget height; but does so, if called in "set()"
1785           together with "::bottom".
1786
1787           See also: "left", "right", "bottom", "origin", "rect", "growMode",
1788           "Move"
1789
1790       transparent BOOLEAN
1791           Specifies whether the background of a widget before it starts
1792           painting is of any importance. If 1, a widget can gain certain
1793           transparency look if it does not clear the background during
1794           "Paint" event.
1795
1796           Default value is 0
1797
1798           See also: "Paint", "buffered".
1799
1800       visible BOOLEAN
1801           Specifies whether a widget is visible or not.  See "Visibility".
1802
1803           See also: "Show", "Hide", "showing", "exposed"
1804
1805       widgetClass CLASS
1806           Maintains the integer value, designating the color class that is
1807           defined by the system and is associated with Prima::Widget eight
1808           basic color properties. CLASS can be one of "wc::XXX" constants:
1809
1810              wc::Undef
1811              wc::Button
1812              wc::CheckBox
1813              wc::Combo
1814              wc::Dialog
1815              wc::Edit
1816              wc::InputLine
1817              wc::Label
1818              wc::ListBox
1819              wc::Menu
1820              wc::Popup
1821              wc::Radio
1822              wc::ScrollBar
1823              wc::Slider
1824              wc::Widget or wc::Custom
1825              wc::Window
1826              wc::Application
1827
1828           These constants are not associated with the toolkit classes; any
1829           class can use any of these constants in "::widgetClass".
1830
1831           See also: "map_color", "colorIndex"
1832
1833       widgets @WIDGETS
1834           In get-mode, returns list of immediate children widgets (identical
1835           to "get_widgets"). In set-mode accepts set of widget profiles, as
1836           "insert" does, as a list or an array. This way it is possible to
1837           create widget hierarchy in a single call.
1838
1839       width WIDTH
1840           Maintains the width of a widget.
1841
1842           See also: "height" "growMode", "Move", "Size", "get_virtual_size",
1843           "sizeMax", "sizeMin"
1844
1845       x_centered BOOLEAN
1846           A write-only property. Once set, widget is centered by the
1847           horizontal axis relative to its owner.
1848
1849           See also: "centered", "y_centered", "growMode", "origin", "Move".
1850
1851       y_centered BOOLEAN
1852           A write-only property. Once set, widget is centered by the vertical
1853           axis relative to its owner.
1854
1855           See also: "x_centered", "centered", "growMode", "origin", "Move".
1856
1857   Methods
1858       begin_drag [ DATA | %OPTIONS ]
1859           Wrapper over "dnd_start" that takes care of some DND session
1860           aspects other than the default system's. All input is contained in
1861           %OPTIONS hash, except for the case of a single-parameter call, in
1862           which case it is equivalent to "text => DATA" when "DATA" is a
1863           scalar, and to "image => DATA" when "DATA" is a reference.
1864
1865           Returns -1 if a session cannot start, "dnd::None" if it was
1866           cancelled by the user, or any other "dnd::" constant when the DND
1867           receiver has selected and successfully performed that action. For
1868           example, after a call to "dnd_start" returning "dnd::Move"
1869           (depending on a context), the caller may remove the data the user
1870           selected to move ("Prima::InputLine" and "Prima::Edit" do exactly
1871           this).
1872
1873           In "wantarray" context also returns the widget that accepted the
1874           drop, if that was a Prima widget. Check this before handling
1875           "dnd::Move" actions that require data to be deleted on the source,
1876           to not occasionally delete the freshly transferred data. The method
1877           uses a precaution for this scenario and by default won't let the
1878           widget to be both a sender and a receiver though ( see "self_aware"
1879           below ).
1880
1881           The following input is recognized:
1882
1883           actions INTEGER = dnd::Copy
1884               Combination of "dnd::" constants, to tell a DND receiver
1885               whether copying, moving, and/or linking of the data is allowed.
1886               The method fails on the invalid "actions" input.
1887
1888           format FORMAT, data INPUT
1889               If set, the clipboard will be assigned to contain a single
1890               entry of "INPUT" of the "FORMAT" format, where format is either
1891               one of the standard "Text" or "Image", or one of the format
1892               registered by "Clipboard::register_format".
1893
1894               If not set, the caller needs to fill the clipboard in advance,
1895               f.ex. to offer data in more than one format.
1896
1897           image INPUT
1898               Shortcut for " format =" 'Image', data => $INPUT, preview =>
1899               $INPUT >
1900
1901           preview INPUT
1902               If set, mouse pointers sending feedback to the user will be
1903               equipped with either text or image (depending on whether
1904               "INPUT" is a scalar or an image reference).
1905
1906           self_aware BOOLEAN = 1
1907               If unset the widget's "dndAware" will be temporarily set to 0,
1908               to exclude a possibility of an operation that may end in
1909               sending data to itself.
1910
1911           text INPUT
1912               Shortcut for " format =" 'Text', data => $INPUT, preview =>
1913               $INPUT >
1914
1915           track INTEGER = 5
1916               When set, waits with starting the DND process until the user
1917               moves the pointer from the starting point further than "track"
1918               pixels, which makes sense if the method to be called directly
1919               from a "MouseDown" event handler.
1920
1921               If the drag did not happen because the user released the button
1922               or otherwise marked that this is not a drag, -1 is returned. In
1923               that case, the caller should continue to handle "MouseDown"
1924               event as if no drag sesssion was ever started.
1925
1926       bring_to_front
1927           Sends a widget on top of all other siblings widgets
1928
1929           See also: "insert_behind", "send_to_back", "ZOrderChanged"
1930           ,"first", "next", "prev", "last"
1931
1932       can_close
1933           Sends "Close" message, and returns its boolean exit state.
1934
1935           See also: "Close", "close"
1936
1937       client_to_screen @OFFSETS
1938           Maps array of X and Y integer offsets from widget to screen
1939           coordinates.  Returns the mapped OFFSETS.
1940
1941           See also: "screen_to_client", "clipOwner"
1942
1943       close
1944           Calls "can_close()", and if successful, destroys a widget.  Returns
1945           the "can_close()" result.
1946
1947           See also: "can_close", "Close"
1948
1949       defocus
1950           Alias for focused(0) call
1951
1952           See also: "focus", "focused", "Enter", "Leave"
1953
1954       deselect
1955           Alias for selected(0) call
1956
1957           See also: "select", "selected", "Enter", "Leave"
1958
1959       dnd_start ACTIONS = dnd::Copy, USE_DEFAULT_POINTERS = 1
1960           Starts a drag and drop session with a combination of "ACTIONS"
1961           allowed.  It is expected that a DND clipboard will be filled with
1962           data that are prepared to be sent to a DND receiver.
1963
1964           Returns -1 if a session cannot start, "dnd::None" if it was
1965           cancelled by the user, or any other "dnd::" constant when the DND
1966           receiver has selected and successfully performed that action. For
1967           example, after a call to "dnd_start" returning "dnd::Move"
1968           (depending on a context), the called may remove the data the user
1969           selected to move ("Prima::InputLine" and "Prima::Edit" do exactly
1970           this).
1971
1972           Also returns the widget that accepted the drop, if that was a Prima
1973           widget within the same program.
1974
1975           If USE_DEFAULT_POINTERS is set, then the system will use default
1976           drag pointers.  Otherwise it is expected that a "DragResponse"
1977           action will change them according to current action, to give the
1978           user a visual feedback.
1979
1980           See "begin_drag" for a wrapper over this method that handles also
1981           for other DND aspects.
1982
1983           See also: "Drag and Drop", "DragQuery", "DragResponse".
1984
1985       exposed
1986           Returns a boolean value, indicating whether a widget is at least
1987           partly visible on the screen.  Never returns 1 if a widget has
1988           "::visible" set to 0.
1989
1990           See also: "visible", "showing", "Show", "Hide"
1991
1992       fetch_resource CLASS_NAME, NAME, CLASS_RESOURCE, RESOURCE, OWNER,
1993       RESOURCE_TYPE = fr::String
1994           Returns a system-defined scalar of resource, defined by the widget
1995           hierarchy, its class, name and owner. RESOURCE_TYPE can be one of
1996           type qualificators:
1997
1998              fr::Color  - color resource
1999              fr::Font   - font resource
2000              fs::String - text string resource
2001
2002           Such a number of the parameters is used because the method can be
2003           called before a widget is created.  CLASS_NAME is widget class
2004           string, NAME is widget name.  CLASS_RESOURCE is class of resource,
2005           and RESOURCE is the resource name.
2006
2007           For example, resources 'color' and 'disabledColor' belong to the
2008           resource class 'Foreground'.
2009
2010       first
2011           Returns the first ( from bottom ) sibling widget in Z-order.
2012
2013           See also: "last", "next", "prev"
2014
2015       focus
2016           Alias for focused(1) call
2017
2018           See also: "defocus", "focused", "Enter", "Leave"
2019
2020       hide
2021           Sets widget "::visible" to 0.
2022
2023           See also: "hide", "visible", "Show", "Hide", "showing", "exposed"
2024
2025       hide_cursor
2026           Hides the cursor. As many times "hide_cursor()" was called, as many
2027           time its counterpart "show_cursor()" must be called to reach the
2028           cursor's initial state.
2029
2030           See also: "show_cursor", "cursorVisible"
2031
2032       help
2033           Starts an interactive help viewer opened on "::helpContext" string
2034           value.
2035
2036           The string value is combined from the widget's owner
2037           "::helpContext" strings if the latter is empty or begins with a
2038           slash.  A special meaning is assigned to an empty string " " - the
2039           help() call fails when such value is found to be the section
2040           component.  This feature can be useful when a window or a dialog
2041           presents a standalone functionality in a separate module, and the
2042           documentation is related more to the module than to an embedding
2043           program. In such case, the grouping widget holds "::helpContext" as
2044           a pod manpage name with a trailing slash, and its children widgets
2045           are assigned "::helpContext" to the topics without the manpage but
2046           the leading slash instead.  If the grouping widget has an empty
2047           string " " as "::helpContext" then the help is forced to be
2048           unavailable for all the children widgets.
2049
2050           See also: "helpContext"
2051
2052       insert CLASS, %PROFILE [[ CLASS, %PROFILE], ... ]
2053           Creates one or more widgets with "owner" property set to the caller
2054           widget, and returns the list of references to the newly created
2055           widgets.
2056
2057           Has two calling formats:
2058
2059           Single widget
2060                 $parent-> insert( 'Child::Class',
2061                    name => 'child',
2062                    ....
2063                 );
2064
2065           Multiple widgets
2066                 $parent-> insert(
2067                   [
2068                      'Child::Class1',
2069                         name => 'child1',
2070                         ....
2071                   ],
2072                   [
2073                      'Child::Class2',
2074                         name => 'child2',
2075                         ....
2076                   ],
2077                 );
2078
2079       insert_behind OBJECT
2080           Sends a widget behind the OBJECT on Z-axis, given that the OBJECT
2081           is a sibling to the widget.
2082
2083           See also: "bring_to_front", "send_to_back", "ZOrderChanged"
2084           ,"first", "next", "prev", "last"
2085
2086       invalidate_rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET
2087       Y_TOP_OFFSET
2088           Marks the rectangular area of a widget as 'invalid', so re-painting
2089           of the area happens. See "Graphic content".
2090
2091           See also: "validate_rect", "get_invalid_rect", "repaint", "Paint",
2092           "syncPaint", "update_view"
2093
2094       is_surface_layered
2095           Returns true if both the widget and it's top-most parent are
2096           layered.  If the widget itself is top-most, i.e. a window, a non-
2097           clipOwner widget, or a child to application, then is the same as
2098           "layered".
2099
2100           See also: "layered"
2101
2102       key_down CODE, KEY = kb::NoKey, MOD = 0, REPEAT = 1, POST = 0
2103           The method sends or posts ( POST flag ) simulated "KeyDown" event
2104           to the system. CODE, KEY, MOD and REPEAT are the parameters to be
2105           passed to the notification callbacks.
2106
2107           See also: "key_up", "key_event", "KeyDown"
2108
2109       key_event COMMAND, CODE, KEY = kb::NoKey, MOD = 0, REPEAT = 1, POST = 0
2110           The method sends or posts ( POST flag ) simulated keyboard event to
2111           the system. CODE, KEY, MOD and REPEAT are the parameters to be
2112           passed to an eventual "KeyDown" or "KeyUp" notifications.  COMMAND
2113           is allowed to be either "cm::KeyDown" or "cm::KeyUp".
2114
2115           See also: "key_down", "key_up", "KeyDown", "KeyUp"
2116
2117       key_up CODE, KEY = kb::NoKey, MOD = 0, POST = 0
2118           The method sends or posts ( POST flag ) simulated "KeyUp" event to
2119           the system. CODE, KEY and MOD are the parameters to be passed to
2120           the notification callbacks.
2121
2122           See also: "key_down", "key_event", "KeyUp"
2123
2124       last
2125           Returns the last ( the topmost ) sibling widget in Z-order.
2126
2127           See also: "first", "next", "prev"
2128
2129       lock
2130           Turns off the ability of a widget to re-paint itself.  As many
2131           times "lock()" was called, as may times its counterpart, "unlock()"
2132           must be called to enable re-painting again.  Returns a boolean
2133           success flag.
2134
2135           See also: "unlock", "repaint", "Paint", "get_locked"
2136
2137       map_color COLOR
2138           Transforms "cl::XXX" and "ci::XXX" combinations into RGB color
2139           representation and returns the result. If COLOR is already in RGB
2140           format, no changes are made.
2141
2142           See also: "colorIndex"
2143
2144       mouse_click BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, DBL_CLICK = 0,
2145       POST = 0
2146           The method sends or posts ( POST flag ) simulated "MouseClick"
2147           event to the system. BUTTON, MOD, X, Y, and DBL_CLICK are the
2148           parameters to be passed to the notification callbacks.
2149
2150           See also: "MouseDown", "MouseUp", "MouseWheel", "MouseMove",
2151           "MouseEnter", "MouseLeave"
2152
2153       mouse_down BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, POST = 0
2154           The method sends or posts ( POST flag ) simulated "MouseDown" event
2155           to the system. BUTTON, MOD, X, and Y are the parameters to be
2156           passed to the notification callbacks.
2157
2158           See also: "MouseUp", "MouseWheel", "MouseClick", "MouseMove",
2159           "MouseEnter", "MouseLeave"
2160
2161       mouse_enter MOD = 0, X = 0, Y = 0, POST = 0
2162           The method sends or posts ( POST flag ) simulated "MouseEnter"
2163           event to the system. MOD, X, and Y are the parameters to be passed
2164           to the notification callbacks.
2165
2166           See also: "MouseDown", "MouseUp", "MouseWheel", "MouseClick",
2167           "MouseMove", "MouseLeave"
2168
2169       mouse_event COMMAND = cm::MouseDown, BUTTON = mb::Left, MOD = 0, X = 0,
2170       Y = 0, DBL_CLICK = 0, POST = 0
2171           The method sends or posts ( POST flag ) simulated mouse event to
2172           the system. BUTTON, MOD, X, Y and DBL_CLICK are the parameters to
2173           be passed to an eventual mouse notifications.  COMMAND is allowed
2174           to be one of "cm::MouseDown", "cm::MouseUp", "cm::MouseWheel",
2175           "cm::MouseClick", "cm::MouseMove", "cm::MouseEnter",
2176           "cm::MouseLeave" constants.
2177
2178           See also: "mouse_down", "mouse_up", "mouse_wheel", "mouse_click",
2179           "mouse_move", "mouse_enter", "mouse_leave", "MouseDown", "MouseUp",
2180           "MouseWheel", "MouseClick", "MouseMove", "MouseEnter", "MouseLeave"
2181
2182       mouse_leave
2183           The method sends or posts ( POST flag ) simulated "MouseLeave"
2184           event to the system.
2185
2186           See also: "MouseDown", "MouseUp", "MouseWheel", "MouseClick",
2187           "MouseMove", "MouseEnter", "MouseLeave"
2188
2189       mouse_move MOD = 0, X = 0, Y = 0, POST = 0
2190           The method sends or posts ( POST flag ) simulated "MouseMove" event
2191           to the system. MOD, X, and Y are the parameters to be passed to the
2192           notification callbacks.
2193
2194           See also: "MouseDown", "MouseUp", "MouseWheel", "MouseClick",
2195           "MouseEnter", "MouseLeave"
2196
2197       mouse_up BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, POST = 0
2198           The method sends or posts ( POST flag ) simulated "MouseUp" event
2199           to the system. BUTTON, MOD, X, and Y are the parameters to be
2200           passed to the notification callbacks.
2201
2202           See also: "MouseDown", "MouseWheel", "MouseClick", "MouseMove",
2203           "MouseEnter", "MouseLeave"
2204
2205       mouse_wheel MOD = 0, X = 0, Y = 0, INCR = 0, POST = 0
2206           The method sends or posts ( POST flag ) simulated "MouseUp" event
2207           to the system. MOD, X, Y and INCR are the parameters to be passed
2208           to the notification callbacks.
2209
2210           See also: "MouseDown", "MouseUp", "MouseClick", "MouseMove",
2211           "MouseEnter", "MouseLeave"
2212
2213       next
2214           Returns the neighbor sibling widget, next ( above ) in Z-order.  If
2215           none found, undef is returned.
2216
2217           See also: "first", "last", "prev"
2218
2219       next_tab FORWARD = 1
2220           Returns the next widget in the sorted by "::tabOrder" list of
2221           sibling widgets. FORWARD is a boolean lookup direction flag.  If
2222           none found, the first ( or the last, depending on FORWARD flag )
2223           widget is returned. Only widgets with "::tabStop" set to 1
2224           participate.
2225
2226           Also used by the internal keyboard navigation code.
2227
2228           See also: "next_positional", "tabOrder", "tabStop", "selectable"
2229
2230       next_positional DELTA_X DELTA_Y
2231           Returns a sibling, (grand-)child of a sibling or (grand-)child
2232           widget, that matched best the direction specified by DELTA_X and
2233           DELTA_Y.  At one time, only one of these parameters can be zero;
2234           another parameter must be either 1 or -1.
2235
2236           Also used by the internal keyboard navigation code.
2237
2238           See also: "next_tab", "origin"
2239
2240       pack, packForget, packSlaves
2241           See Prima::Widget::pack
2242
2243       place, placeForget, placeSlaves
2244           See Prima::Widget::place
2245
2246       prev
2247           Returns the neighbor sibling widget, previous ( below ) in Z-order.
2248           If none found, undef is returned.
2249
2250           See also: "first", "last", "next"
2251
2252       repaint
2253           Marks the whole widget area as 'invalid', so re-painting of the
2254           area happens. See "Graphic content".
2255
2256           See also: "validate_rect", "get_invalid_rect", "invalidate_rect",
2257           "Paint", "update_view", "syncPaint"
2258
2259       rect_bevel $CANVAS, @RECT, %OPTIONS
2260           Draws a rectangular area, similar to produced by "rect3d" over
2261           @RECT that is 4-integer coordinates of the area, but implicitly
2262           using widget's "light3DColor" and "dark3DColor" properties' values.
2263           The following options are recognized:
2264
2265           fill COLOR
2266               If set, the area is filled with COLOR, ortherwise is left
2267               intact.
2268
2269           width INTEGER
2270               Width of the border in pixels
2271
2272           concave BOOLEAN
2273               If 1, draw a concave area, bulged otherwise
2274
2275       responsive
2276           Returns a boolean flag, indicating whether a widget and its owners
2277           have all "::enabled" 1 or not. Useful for fast check if a widget
2278           should respond to the user actions.
2279
2280           See also: "enabled"
2281
2282       screen_to_client @OFFSETS
2283           Maps array of X and Y integer offsets from screen to widget
2284           coordinates.  Returns the mapped OFFSETS.
2285
2286           See also: "client_to_screen"
2287
2288       scroll DELTA_X DELTA_Y %OPTIONS
2289           Scrolls the graphic context area by DELTA_X and DELTA_Y pixels.
2290           OPTIONS is hash, that contains optional parameters to the scrolling
2291           procedure:
2292
2293           clipRect [X1, Y1, X2, Y2]
2294               The clipping area is confined by X1, Y1, X2, Y2 rectangular
2295               area.  If not specified, the clipping area covers the whole
2296               widget.  Only the bits, covered by clipRect are affected.  Bits
2297               scrolled from the outside of the rectangle to the inside are
2298               painted; bits scrolled from the inside of the rectangle to the
2299               outside are not painted.
2300
2301           confineRect [X1, Y1, X2, Y2]
2302               The scrolling area is confined by X1, Y1, X2, Y2 rectangular
2303               area.  If not specified, the scrolling area covers the whole
2304               widget.
2305
2306           withChildren BOOLEAN
2307               If 1, the scrolling performs with the eventual children widgets
2308               change their positions to DELTA_X and DELTA_Y as well.
2309
2310           Returns one of the following constants:
2311
2312                   scr::Error           - failure
2313                   scr::NoExpose        - call resulted in no new exposed areas
2314                   scr::Expose          - call resulted in new exposed areas, expect a repaint
2315
2316           Cannot be used inside paint state.
2317
2318           See also: "Paint", "get_invalid_rect"
2319
2320       select
2321           Alias for selected(1) call
2322
2323           See also: "deselect", "selected", "Enter", "Leave"
2324
2325       send_to_back
2326           Sends a widget at bottom of all other siblings widgets
2327
2328           See also: "insert_behind", "bring_to_front", "ZOrderChanged"
2329           ,"first", "next", "prev", "last"
2330
2331       show
2332           Sets widget "::visible" to 1.
2333
2334           See also: "hide", "visible", "Show", "Hide", "showing", "exposed"
2335
2336       show_cursor
2337           Shows the cursor. As many times "hide_cursor()" was called, as many
2338           time its counterpart "show_cursor()" must be called to reach the
2339           cursor's initial state.
2340
2341           See also: "hide_cursor", "cursorVisible"
2342
2343       showing
2344           Returns a boolean value, indicating whether the widget and its
2345           owners have all "::visible" 1 or not.
2346
2347       unlock
2348           Turns on the ability of a widget to re-paint itself.  As many times
2349           "lock()" was called, as may times its counterpart, "unlock()" must
2350           be called to enable re-painting again.  When last "unlock()" is
2351           called, an implicit "repaint()" call is made.  Returns a boolean
2352           success flag.
2353
2354           See also: "lock", "repaint", "Paint", "get_locked"
2355
2356       update_view
2357           If any parts of a widget were marked as 'invalid' by either
2358           "invalidate_rect()" or "repaint()" calls or the exposure caused by
2359           window movements ( or any other), then "Paint" notification is
2360           immediately called.  If no parts are invalid, no action is
2361           performed.  If a widget has "::syncPaint" set to 1, "update_view()"
2362           is always a no-operation call.
2363
2364           See also: "invalidate_rect", "get_invalid_rect", "repaint",
2365           "Paint", "syncPaint", "update_view"
2366
2367       validate_rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET Y_TOP_OFFSET
2368           Reverses the effect of "invalidate_rect()", restoring the original,
2369           'valid' state of widget area covered by the rectangular area
2370           passed. If a widget with previously invalid areas was wholly
2371           validated by this method, no "Paint" notifications occur.
2372
2373           See also: "invalidate_rect", "get_invalid_rect", "repaint",
2374           "Paint", "syncPaint", "update_view"
2375
2376   Get-methods
2377       get_default_font
2378           Returns the default font for a Prima::Widget class.
2379
2380           See also: "font"
2381
2382       get_default_popup_font
2383           Returns the default font for a Prima::Popup class.
2384
2385           See also: "font"
2386
2387       get_invalid_rect
2388           Returns the result of successive calls "invalidate_rect()",
2389           "validate_rect()" and "repaint()", as a rectangular area ( four
2390           integers ) that cover all invalid regions in a widget.  If none
2391           found, (0,0,0,0) is returned.
2392
2393           See also: "validate_rect", "invalidate_rect", "repaint", "Paint",
2394           "syncPaint", "update_view"
2395
2396       get_handle
2397           Returns a system handle for a widget
2398
2399           See also: "get_parent_handle", "Window::get_client_handle"
2400
2401       get_locked
2402           Returns 1 if a widget is in "lock()" - initiated repaint-blocked
2403           state.
2404
2405           See also: "lock", "unlock"
2406
2407       get_mouse_state
2408           Returns a combination of "mb::XXX" constants, reflecting the
2409           currently pressed mouse buttons.
2410
2411           See also: "pointerPos", "get_shift_state"
2412
2413       get_parent
2414           Returns the owner widget that clips the widget boundaries, or
2415           application object if a widget is top-level.
2416
2417           See also: "clipOwner"
2418
2419       get_parent_handle
2420           Returns a system handle for a parent of a widget, a window that
2421           belongs to another program. Returns 0 if the widget's owner and
2422           parent are in the same application and process space.
2423
2424           See also: "get_handle", "clipOwner"
2425
2426       get_pointer_size
2427           Returns two integers, width and height of a icon, that the system
2428           accepts as valid for a pointer.  If the icon is supplied that is
2429           more or less than these values, it is truncated or padded with
2430           transparency bits, but is not stretched.  Can be called with class
2431           syntax.
2432
2433       get_shift_state
2434           Returns a combination of "km::XXX" constants, reflecting the
2435           currently pressed keyboard modificator buttons.
2436
2437           See also: "get_shift_state"
2438
2439       get_virtual_size
2440           Returns virtual width and height of a widget.  See "Geometry",
2441           Implicit size regulations.
2442
2443           See also: "width", "height", "size" "growMode", "Move", "Size",
2444           "sizeMax", "sizeMin"
2445
2446       get_widgets
2447           Returns list of children widgets.
2448
2449   Events
2450       Change
2451           Generic notification, used for Prima::Widget descendants;
2452           Prima::Widget itself neither calls not uses the event.  Designed to
2453           be called when an arbitrary major state of a widget is changed.
2454
2455       Click
2456           Generic notification, used for Prima::Widget descendants;
2457           Prima::Widget itself neither calls not uses the event.  Designed to
2458           be called when an arbitrary major action for a widget is called.
2459
2460       Close
2461           Triggered by "can_close()" and "close()" functions.  If the event
2462           flag is cleared during execution, these functions fail.
2463
2464           See also: "close", "can_close"
2465
2466       ColorChanged INDEX
2467           Called when one of widget's color properties is changed, either by
2468           direct property change or by the system. INDEX is one of "ci::XXX"
2469           constants.
2470
2471           See also: "colorIndex"
2472
2473       Disable
2474           Triggered by a successive enabled(0) call
2475
2476           See also: "Enable", "enabled", "responsive"
2477
2478       DragBegin CLIPBOARD, ACTION, MOD, X, Y, COUNTERPART
2479           Triggered on a receiver widget when a mouse with a DND object
2480           enters it.  "CLIPBOARD" contains the DND data, "ACTION" is a
2481           combination of "dnd::" constants, the actions the sender is ready
2482           to offer, "MOD" is a combination of modifier keys ("kb::"), and "X"
2483           and "Y" are coordinates where the mouse has entered the widget.
2484           This event, and the following "DragOver" and "DragEnd" events are
2485           happening only if the property "dndAware" is set either to 1, or if
2486           it matches a clipboard format that exists in "CLIPBOARD".
2487
2488           "COUNTERPART" is the Prima DND sender widget, if the session is
2489           initiated within the same program.
2490
2491           See also: "Drag and Drop", "DragOver", "DragEnd"
2492
2493       DragEnd CLIPBOARD, ACTION, MOD, X, Y, COUNTERPART, ANSWER
2494           Triggered on a received widget when the user either drops or
2495           cancels the DND session. In case of a cancelled drop, "CLIPBOARD"
2496           is set to "undef" and "ACTION" to "dnd::None". On a successful
2497           drop, input data are same as on "DragBegin", and output data are to
2498           be stored in hashref "ANSWER", if any.  The following answers can
2499           be stored:
2500
2501           allow BOOLEAN
2502               Is pre-set to 1. If changed to 0, a signal will be send to the
2503               sender that a drop is not accepted.
2504
2505           action INTEGER
2506               A "dnd::" constant (not a combination) to be returned to the
2507               sender with the action the receiver has accepted, if any.
2508
2509           "COUNTERPART" is the Prima DND sender widget, if the session is
2510           initiated within the same program.
2511
2512           See also: "Drag and Drop", "DragBegin", "DragOver"
2513
2514       DragOver CLIPBOARD, ACTION, MOD, X, Y, COUNTERPART, ANSWER
2515           Triggered on a received widget when a mouse with a DND moves within
2516           the widget.  Input data are same as on "DragBegin", and output data
2517           are to be stored in hashref "ANSWER", if any. The following answers
2518           can be stored:
2519
2520           allow BOOLEAN
2521               Is pre-set to 1. If changed to 0, a signal will be send to the
2522               sender that a drop action cannot happen with the input
2523               provided.
2524
2525           action INTEGER
2526               A "dnd::" constant (not a combination) to be returned to the
2527               sender with the action the receiver is ready to accept, if any.
2528
2529           pad X, Y, WIDTH, HEIGHT
2530               If set, instructs the sender not to repeat "DragOver" events
2531               that contains same input data, while the mouse pointer is
2532               within these geometrical limits.
2533
2534           "COUNTERPART" is the Prima DND sender widget, if the session is
2535           initiated within the same program.
2536
2537       DragQuery MOD, ANSWERS, COUNTERPART
2538           Triggered on a sender DND widget when there was detected a change
2539           in mouse or modifier buttons, or the user pressed "Escape" key to
2540           cancel the DND session.  The combination of mouse and modifier
2541           buttons is stored in "MOD" integer, together with a special
2542           "km::Escape" constant for the "Escape" key.
2543
2544           It is up to this event to decide whether to continue the drag
2545           session or not, and if it is decided not to continue,
2546           "$answer-"{allow}> must be set to 0.
2547
2548           Additionally, "$answer-"{action}> can be set to select a single
2549           "dnd::" action that will be used to propose to the receiver a
2550           single concrete action based on the "MOD" value (f.ex. a
2551           "dnd::Move" if a control modifier was pressed).
2552
2553           Note: This action will only forward the change to the receiver on
2554           X11, but it is advised to implement it anyway for portability.
2555
2556           "COUNTERPART" is the Prima DND receiver widget, if within the same
2557           program.
2558
2559           See also: "Drag and Drop", "DragResponse"
2560
2561       DragResponse ALLOW, ACTION, COUNTERPART
2562           Triggered on a sender DND widget when there was detected a change
2563           in mouse or modifier buttons, or the mouse was moved from one DND
2564           target to another.  The sender event is then presented with the new
2565           input, collected from interaction with the new target; there,
2566           "ALLOW" is set to a boolean value whether the sender is allowed to
2567           drop data, and "ACTION" is a "dnd::" constant with the action the
2568           receiver has agreed to accept, if any.
2569
2570           If the drag and drop session was told not to update mouse pointers
2571           on such event, the handle should update the pointer in this
2572           callback. It is not needed though to save and restore mouse
2573           pointers before and after the DND session.
2574
2575           "COUNTERPART" is the Prima DND receiver widget, if within the same
2576           program.  See also: "Drag and Drop", "dnd_start", "begin_drag".
2577
2578       Enable
2579           Triggered by a successive enabled(1) call
2580
2581           See also: "Disable", "enabled", "responsive"
2582
2583       Enter
2584           Called when a widget receives the input focus.
2585
2586           See also: "Leave", "focused", "selected"
2587
2588       FontChanged
2589           Called when a widget font is changed either by direct property
2590           change or by the system.
2591
2592           See also: "font", "ColorChanged"
2593
2594       Hide
2595           Triggered by a successive visible(0) call
2596
2597           See also: "Show", "visible", "showing", "exposed"
2598
2599       Hint SHOW_FLAG
2600           Called when the hint label is about to show or hide, depending on
2601           SHOW_FLAG. The hint show or hide action fails, if the event flag is
2602           cleared during execution.
2603
2604           See also: "showHint", "ownerShowHint", "hintVisible", "ownerHint"
2605
2606       KeyDown CODE, KEY, MOD, REPEAT
2607           Sent to the focused widget when the user presses a key.  CODE
2608           contains an eventual character code, KEY is one of "kb::XXX"
2609           constants, MOD is a combination of the modificator keys pressed
2610           when the event occurred ( "km::XXX" ). REPEAT is how many times the
2611           key was pressed; usually it is 1.  ( see "::briefKeys" ).
2612
2613           The valid "km::" constants are:
2614
2615              km::Shift
2616              km::Ctrl
2617              km::Alt
2618              km::KeyPad
2619              km::DeadKey
2620              km::Unicode
2621
2622           The valid "kb::" constants are grouped in several sets.  Some codes
2623           are aliased, like, "kb::PgDn" and "kb::PageDown".
2624
2625           Modificator keys
2626                  kb::ShiftL   kb::ShiftR   kb::CtrlL      kb::CtrlR
2627                  kb::AltL     kb::AltR     kb::MetaL      kb::MetaR
2628                  kb::SuperL   kb::SuperR   kb::HyperL     kb::HyperR
2629                  kb::CapsLock kb::NumLock  kb::ScrollLock kb::ShiftLock
2630
2631           Keys with character code defined
2632                  kb::Backspace  kb::Tab    kb::Linefeed   kb::Enter
2633                  kb::Return     kb::Escape kb::Esc        kb::Space
2634
2635           Function keys
2636                  kb::F1 .. kb::F30
2637                  kb::L1 .. kb::L10
2638                  kb::R1 .. kb::R10
2639
2640           Other
2641                  kb::Clear    kb::Pause   kb::SysRq  kb::SysReq
2642                  kb::Delete   kb::Home    kb::Left   kb::Up
2643                  kb::Right    kb::Down    kb::PgUp   kb::Prior
2644                  kb::PageUp   kb::PgDn    kb::Next   kb::PageDown
2645                  kb::End      kb::Begin   kb::Select kb::Print
2646                  kb::PrintScr kb::Execute kb::Insert kb::Undo
2647                  kb::Redo     kb::Menu    kb::Find   kb::Cancel
2648                  kb::Help     kb::Break   kb::BackTab
2649
2650           See also: "KeyUp", "briefKeys", "key_down", "help", "popup",
2651           "tabOrder", "tabStop", "accelTable"
2652
2653       KeyUp CODE, KEY, MOD
2654           Sent to the focused widget when the user releases a key.  CODE
2655           contains an eventual character code, KEY is one of "kb::XXX"
2656           constants, MOD is a combination of the modificator keys pressed
2657           when the event occurred ( "km::XXX" ).
2658
2659           See also: "KeyDown", "key_up"
2660
2661       Leave
2662           Called when the input focus is removed from a widget
2663
2664           See also: "Enter", "focused", "selected"
2665
2666       Menu MENU VAR_NAME
2667           Called before the user-navigated menu ( pop-up or pull-down ) is
2668           about to show another level of submenu on the screen. MENU is
2669           Prima::AbstractMenu descendant, that children to a widget, and
2670           VAR_NAME is the name of the menu item that is about to be shown.
2671
2672           Used for making changes in the menu structures dynamically.
2673
2674           See also: "popupItems"
2675
2676       MouseClick BUTTON, MOD, X, Y, DOUBLE_CLICK
2677           Called when a mouse click ( button is pressed, and then released
2678           within system-defined interval of time ) is happened in the widget
2679           area. BUTTON is one of "mb::XXX" constants, MOD is a combination of
2680           "km::XXX" constants, reflecting pressed modificator keys during the
2681           event, X and Y are the mouse pointer coordinates. DOUBLE_CLICK is a
2682           boolean flag, set to 1 if it was a double click, 0 if a single.
2683
2684           "mb::XXX" constants are:
2685
2686              mb::b1 or mb::Left
2687              mb::b2 or mb::Middle
2688              mb::b3 or mb::Right
2689              mb::b4
2690              mb::b5
2691              mb::b6
2692              mb::b7
2693              mb::b8
2694
2695           See also: "MouseDown", "MouseUp", "MouseWheel", "MouseMove",
2696           "MouseEnter", "MouseLeave"
2697
2698       MouseDown BUTTON, MOD, X, Y
2699           Occurs when the user presses mouse button on a widget.  BUTTON is
2700           one of "mb::XXX" constants, MOD is a combination of "km::XXX"
2701           constants, reflecting the pressed modificator keys during the
2702           event, X and Y are the mouse pointer coordinates.
2703
2704           See also: "MouseUp", "MouseClick", "MouseWheel", "MouseMove",
2705           "MouseEnter", "MouseLeave"
2706
2707       MouseEnter MOD, X, Y
2708           Occurs when the mouse pointer is entered the area occupied by a
2709           widget ( without mouse button pressed ).  MOD is a combination of
2710           "km::XXX" constants, reflecting the pressed modificator keys during
2711           the event, X and Y are the mouse pointer coordinates.
2712
2713           See also: "MouseDown", "MouseUp", "MouseClick", "MouseWheel",
2714           "MouseMove", "MouseLeave"
2715
2716       MouseLeave
2717           Occurs when the mouse pointer is driven off the area occupied by a
2718           widget ( without mouse button pressed ).
2719
2720           See also: "MouseDown", "MouseUp", "MouseClick", "MouseWheel",
2721           "MouseMove", "MouseEnter"
2722
2723       MouseMove MOD, X, Y
2724           Occurs when the mouse pointer is transported over a widget.  MOD is
2725           a combination of  "km::XXX" constants, reflecting the pressed
2726           modificator keys during the event, X and Y are the mouse pointer
2727           coordinates.
2728
2729           See also: "MouseDown", "MouseUp", "MouseClick", "MouseWheel",
2730           "MouseEnter", "MouseLeave"
2731
2732       MouseUp BUTTON, MOD, X, Y
2733           Occurs when the user depresses mouse button on a widget.  BUTTON is
2734           one of "mb::XXX" constants, MOD is a combination of "km::XXX"
2735           constants, reflecting the pressed modificator keys during the
2736           event, X and Y are the mouse pointer coordinates.
2737
2738           See also: "MouseDown", "MouseClick", "MouseWheel", "MouseMove",
2739           "MouseEnter", "MouseLeave"
2740
2741       MouseWheel MOD, X, Y, INCR
2742           Occurs when the user rotates mouse wheel on a widget.  MOD is a
2743           combination of "km::XXX" constants, reflecting the pressed
2744           modificator keys during the event, INCR is the wheel movement,
2745           scaled by 120.  +120 is a step upwards, or -120 downwards.  For
2746           wheels which are discrete button clicks INCR is +/-120 but other
2747           devices may give other amounts.  A widget should scroll by INCR/120
2748           many units, or partial unit, for whatever its unit of movement
2749           might be, such as lines of text, slider ticks, etc.
2750
2751           A widget might like to vary its unit move according to the MOD
2752           keys.  For example "Prima::SpinEdit" has a "step" and "pageStep"
2753           and moves by "pageStep" when "km::Ctrl" is held down (see
2754           Prima::Sliders).
2755
2756           See also: "MouseDown", "MouseUp", "MouseClick", "MouseMove",
2757           "MouseEnter", "MouseLeave"
2758
2759       Move OLD_X, OLD_Y, NEW_X, NEW_Y
2760           Triggered when widget changes its position relative to its parent,
2761           either by Prima::Widget methods or by the user.  OLD_X and OLD_Y
2762           are the old coordinates of a widget, NEW_X and NEW_Y are the new
2763           ones.
2764
2765           See also: "Size", "origin", "growMode", "centered", "clipOwner"
2766
2767       Paint CANVAS
2768           Caused when the system calls for the refresh of a graphic context,
2769           associated with a widget. CANVAS is the widget itself, however its
2770           usage instead of widget is recommended ( see "Graphic content" ).
2771
2772           See also: "repaint", "syncPaint", "get_invalid_rect", "scroll",
2773           "colorIndex", "font"
2774
2775       Popup BY_MOUSE, X, Y
2776           Called by the system when the user presses a key or mouse
2777           combination defined for a context pop-up menu execution.  By
2778           default executes the associated Prima::Popup object, if it is
2779           present. If the event flag is cleared during the execution of
2780           callbacks, the pop-up menu is not shown.
2781
2782           See also: "popup"
2783
2784       Setup
2785           This message is posted right after "Create" notification, and comes
2786           first from the event loop. Prima::Widget does not use it.
2787
2788       Show
2789           Triggered by a successive visible(1) call
2790
2791           See also: "Show", "visible", "showing", "exposed"
2792
2793       Size OLD_WIDTH, OLD_HEIGHT, NEW_WIDTH, NEW_HEIGHT
2794           Triggered when widget changes its size, either by Prima::Widget
2795           methods or by the user.  OLD_WIDTH and OLD_HEIGHT are the old
2796           extensions of a widget, NEW_WIDTH and NEW_HEIGHT are the new ones.
2797
2798           See also: "Move", "origin", "size", "growMode", "sizeMax",
2799           "sizeMin", "rect", "clipOwner"
2800
2801       SysHandle
2802           Same as in "Component", but introduces the following "Widget"
2803           properties can trigger it:
2804
2805           "clipOwner", "syncPaint", "layered", "transparent"
2806
2807           This event will be only needed when the system handle (that can be
2808           acquired by "get_handle" ) is needed.
2809
2810       TranslateAccel CODE, KEY, MOD
2811           A distributed "KeyDown" event. Traverses all the object tree that
2812           the widget which received original "KeyDown" event belongs to. Once
2813           the event flag is cleared, the iteration stops.
2814
2815           Used for tracking keyboard events by out-of-focus widgets.
2816
2817           See also: "KeyDown"
2818
2819       ZOrderChanged
2820           Triggered when a widget changes its stacking order, or Z-order
2821           among its siblings, either by Prima::Widget methods or by the user.
2822
2823           See also: "bring_to_front", "insert_behind", "send_to_back"
2824

AUTHOR

2826       Dmitry Karasik, <dmitry@karasik.eu.org>.
2827

SEE ALSO

2829       Prima, Prima::Object, Prima::Drawable.
2830
2831
2832
2833perl v5.34.0                      2021-07-22             pod::Prima::Widget(3)
Impressum