=head1 NAME

Prima::Widget - window management

=head1 SYNOPSIS

   # create a widget
   my $widget = Prima::Widget-> new(
       size    => [ 200, 200],
       color   => cl::Green,
       visible => 0,
       onPaint => sub {
          my ($self,$canvas) = @_;
          $canvas-> clear;
          $canvas-> text_out( "Hello world!", 10, 10);
       },
   );

   # manipulate the widget
   $widget-> origin( 10, 10);
   $widget-> show;

=head1 DESCRIPTION

Prima::Widget is a descendant of the Prima::Component class, that provides
comprehensive management of system-dependent windows. Objects of the
Prima::Widget class are mapped to the screen space as a rectangular area, with
distinct boundaries, a pointer and sometimes a cursor, and a user-selectable
input focus.

=head1 USAGE

The Prima::Widget class and its descendants are used widely throughout the
toolkit and are at the center of almost all its user interaction and
input-output functions.  The notification system, explained in
L<Prima::Object>, is heavily used in the Prima::Widget class, providing the
programmer with unified access to the system-generated events that occur
when for example the user moves a window, clicks the mouse, types on the
keyboard, etc.

=head1 Creation and destruction

The widget creation syntax is the same as for creating other Prima objects:

   Prima::Widget-> new(
      name => 'Widget',
      size => [ 20, 10],
      onMouseClick => sub { print "click\n"; },
      owner => $owner,
   );

A widget must almost always be explicitly assigned an owner. The owner
object is either a Prima::Widget descendant, in which case the widget is drawn
inside its inferior, or the application object so that the widget becomes a
top-level screen object. This is the reason why the C<insert> syntax is
preferred, as it is more illustrative and is more convenient for creating
several widgets in one call ( see L<Prima::Object> ).

   $owner-> insert( 'Prima::Widget',
      name => 'Widget',
      size => [ 20, 10],
      onMouseClick => sub { print "click\n"; },
   );

These two examples produce identical results.

As a descendant of the Prima::Component class, Prima::Widget objects also send
the C<Create> notification while being created ( more precisely, after its init
stage is finished. See L<Prima::Object> for details). This notification is
called and processed within the C<new()> method. Another notification C<Setup>
is sent after the widget finishes the creation process. This message is
I<posted> though, i e it is invoked within the C<new()> method but is processed
inside the application event loop. This means that the moment when the C<Setup>
event is executed is uncertain, as it is with all posted messages. Its delivery
is system-dependent, so its use must be considered with care.

After the widget is created, it is usually asked to render its visual
content by the system, provided that the widget is visible. This request is
delivered by the C<Paint> notification.

When the lifetime of the widget is over, its method C<destroy()> should be
called.  In some circumstances, the method can be also called implicitly by the
toolkit.  If the widget gets destroyed because its owner also gets destroyed, it
is guaranteed that its widget children will be destroyed first, and the owner
only afterward. In such situation the widget can still operate but with 
limited functionality ( see L<Prima::Object>, the B<Creation> section ).

=head1 Graphic content

There are two ways graphics can be displayed in a widget.  The first is the
event-driven method when the C<Paint> notification arrives, notifying the
widget that it must re-paint itself.  The second is the 'direct' method when
the program itself begins drawing on the widget.

=head2 Event-driven rendering

When the system decides that a widget needs to update its graphics it sends the
C<Paint> notification to the program. The notification has a single ( besides
the widget itself ) parameter, referred to as I<canvas>, the object where the
drawing is performed.  During the event-driven call initiated by the system, it
is always the widget itself. Other callers of the C<Paint> notification
though can provide another object to draw on:

   $widget-> notify('Paint', $some_other_widget);

When programming this notification use this parameter, not the widget itself,
for the painting.

An example of the C<Paint> notification handler could be a simple like this:

   Prima::Widget-> new(
       ...
       onPaint => sub {
          my ( $self, $canvas) = @_;
          $canvas-> clear;
          $canvas-> text_out("Clicked $self->{clicked} times", 10, 10);
       },
       onMouseClick => sub {
          $_[0]-> {clicked}++;
          $_[0]-> repaint;
       },
   );

The example shows several important features of the event-driven mechanism.
First, no C<begin_paint()>/C<end_paint()> brackets are used within the callback
- these are called implicitly. Second, when the widget graphics need to be
changed (after a mouse click, for example), no code like C<notify(q(Paint))> is
needed - the C<repaint()> method is used instead. Note that the execution of
C<Paint> callbacks may or may not occur inside the C<repaint()> call. This
behavior is managed by the C<::syncPaint> property.  A call to C<repaint()>
marks the whole widget's area to be refreshed, or I<invalidates> the area. For
the finer access to the area that should be repainted, the functions
C<invalidate_rect()> and C<validate_rect()> are used. Thus the call

  $x-> repaint()

is identical to the

  $x-> invalidate_rect( 0, 0, $x-> size);

call.

The area passed to the C<invalidate_rect()> method will be accessible as the
clipping rectangle inside the C<Paint> notification.  However, the interaction
between the program logic and the system logic can result in situations where
the system may request repainting of the other parts of the widget, not only those
that were requested by the C<invalidate_rect> call.  This can happen for
example when windows from another program move over the widget. In these cases,
the clipping rectangle might not be exactly the same.  Moreover, the clipping
rectangle can even become empty as a result of these interactions, and the
notification won't be called at all.

The clipping rectangle is represented differently inside and outside the
drawing mode. To access the rectangle, the C<::clipRect> property is used.
Inside the C<Paint> call (or, strictly speaking, inside the
C<begin_paint>/C<end_paint> brackets) the rectangle is measured in the
inclusive-inclusive coordinates, whereas the C<invalidate_rect()>,
C<validate_rect()>, and C<get_invalid_rect()> method use the
inclusive-exclusive coordinates. Assuming the clipping rectangle is not
changed by the system, the example below illustrates the difference:

   $x-> onPaint( sub {
      my @c = $_[0]-> clipRect;
      print "clip rect:@c\n";
   });
   $x-> invalidate_rect( 10, 10, 20, 20);
   ...
   clip rect: 10 10 19 19

The notification handler can use the C<::clipRect> property to optimize the
painting code, drawing only the parts that are necessary to draw.

In the drawing mode it is possible to change the C<::clipRect> property,
however, increasing the clipping rectangle in such a way won't
make it possible to draw on the screen area that lies outside
the original clipping region. This is part of the same mechanism
that doesn't allow drawing outside the widget's geometric boundaries.

=head2 Direct rendering

The direct rendering, contrary to the event-driven, is initiated by the
program, not by the system. If a programmer wishes to paint over a widget
immediately, then the C<begin_paint()> method should be called first, and, if
it is successful, the part of the screen occupied by the widget is accessible
for drawing.

This method is useful, for example, for graphic demonstration programs, that
draw continuously without any input.  Another use of this method is the drawing
directly on the screen, which is performed by entering the drawing mode on the
C<$::application> object, that does not have the C<Paint> notification.
The application's graphic canvas represents the whole screen, allowing drawing the
windows that also belong to other programs.

The majority of the widget rendering code is using the event-driven drawing.
Sometimes, however, the changes needed to be made to the widget's graphic
context are so insignificant, so the direct rendering method is preferable,
because of the cleaner and terser code. Below is an example of a simple
progress bar that draws a simple colored stripe. The event-driven code would be
( in short, omitting many details ) like this:

   $bar = Widget-> new(
     width => 100,
     onPaint => sub {
        my ( $self, $canvas) = @_;
        $canvas-> color( cl::Blue);
        $canvas-> bar( 0, 0, $self-> {progress}, $self-> height);
        $canvas-> color( cl::Back);
        $canvas-> bar( $self-> {progress}, 0, $self-> size);
     },
   );
   ...
   $bar-> {progress} += 10;
   $bar-> repaint;
   # or, more efficiently, 
   # $bar-> invalidate_rect( $bar->{progress}-10, 0,
   #                 $bar->{progress}, $bar-> height);

While the version with the direct drawing would be

   $bar = Widget-> new( width => 100 );
   ...
   $bar-> begin_paint;
   $bar-> color( cl::Blue);
   $bar-> bar( $progress, 0, $progress + 10, $bar-> height);
   $bar-> end_paint;
   $progress += 10;

The pros and the contras are obvious: the event-driven rendered widget
correctly represents the status after an eventual repaint, for example when the
user sweeps a window over the progress bar widget. The direct method is not
that smart, but if the status bar is an insignificant part of the program it
can be used instead.

Both methods can be effectively disabled by using the locking mechanism.
The C<lock()> and C<unlock()> methods can be called several times, counting the
requests. This feature is useful because many properties implicitly call
C<repaint()>, and if several of these properties are called in a row or within
each other, the unnecessary redrawing of the widget can be avoided by wrapping
such calls in the lock/unlock brackets.  The drawback is that the last
C<unlock()> call triggers the C<repaint()> method unconditionally.

=head1 Geometry

=head2 Basic properties

A widget always has its position and size determined, even when it is not
visible on the screen. Prima::Widget provides several properties with
overlapping functionality that manage the geometry of widgets. The base
properties are C<::origin> and C<::size>, and the derived ones are C<::left>,
C<::bottom>, C<::right>, C<::top>, C<::width>, C<::height>, and C<::rect>.
C<::origin> and C<::size> operate on two integers, C<::rect> on four, others on
one integer value.

The Prima toolkit coordinate space begins in the lower bottom corner, so the
combination of C<::left> and C<::bottom> is the same as C<::origin>, and the
combination of C<::left>, C<::bottom>, C<::right> and C<::top> - same as the
C<::rect> property.

When widgets are moved or resized, two notifications may occur,
correspondingly, C<Move> and C<Size>. The parameters for both are the old and
the new position and size. The notifications occur irrespective of whether the
geometry change was issued by the program itself or by the user.

=head2 Implicit size regulations

There exist two other properties that regulate widget size, C<::sizeMin> and
C<::sizeMax>. They keep the minimum and the maximum sizes the widget may have.
A call that would try to assign the widget size outside the C<::sizeMin> and
C<::sizeMax> limits will fail; the widget size will always be adjusted to
the limits' values.

Changes to the widget's position and size can also occur automatically if the
widget's owner changes its size.  The toolkit contains several implicit rules
that define how exactly these changes should occur. For example, the
C<::growMode> property accepts a set of C<gm::XXX> flags that encode this
behavior. The exact meaning of the C<gm::XXX> flags is not given here ( see the
description to C<::growMode> in the API section ), but in short, it is possible
using fairly simple means to program changes to widget size and position when
its owner is resized. By default, the value of the  C<::growMode> property is
0, so widgets don't change either their size or position on these
occasions. A widget with C<::growMode> set to 0 stays always in the left bottom
corner of its owner. When, for example, a widget is expected to stay in the
right bottom corner, or the left top corner, the C<gm::GrowLoX> and
C<gm::GrowLoY> values must be used, correspondingly.  If a widget is expected
to cover its owner's lower part and change its width following the
owner's, ( a horizontal scroll bar in an editor window is a good example of
this behavior), the C<gm::GrowHiX> value must be used.

When such implicit size change occurs, the C<::sizeMin> and C<::sizeMax>
properties still play their part - they still do not allow the widget's size to
exceed these limits. However, this algorithm has a problem, that is
illustrated by the following example. Imagine a widget with the size-dependent
C<::growMode> set to C<gm::GrowHiX>, which means that the increase or decrease
of the owner width would result in a similar change in the widget.  If the
implicit width change would match verbatim the change of the owner's width,
then the widget's size (and probably its position) will be incorrect after an
attempt is made to change the widget's size to values outside the size
limits.

Here's the example: let's assume that the child widget has width of a 100 pixels,
its growMode property is set to C<gm::GrowHiX>, and its sizeMin property is
set to (95, 95). The widget's owner has a width of 200 pixels.  If the owner
widget changes its width from 200 to 195 and then to 190 pixels, and then back
again, then one naively could expect that the child widget's width would
undergo the following changes:

                    Owner        Child
  Initial state      200           100
  Shrink             195   -5       95
  Shrink             190   -5       95 - as it can not be less than 95.
  Grow               195   +5      100
  Grow               200   +5      105

The situation here is fixed by introducing the I<virtual size> . The C<::size>
property is derived from the virtual size, but while C<::size> cannot exceed the size
limits, the virtual size can. Moreover, it can even accept negative values. This
algorithm produces the correct sizes:

                    Owner        Child's       Child's
                                 virtual width  width
  Initial state      200           100           100
  Shrink             195   -5       95            95
  Shrink             190   -5       90            95
  Grow               195   +5       95            95
  Grow               200   +5      100           100

=head2 Geometry managers

The concept of geometry managers is imported from the Tk, which in turn is a
port of the Tcl-Tk. The idea behind it is that the widget size and position are
governed by one of the I<managers>, and each manager has its own set of
properties.  One can select the manager by assigning the C<::geometry> property
one the of C<gt::XXX> constants. The native ( and the default ) geometry
manager is the described above grow-mode algorithm ( C<gt::GrowMode>). The
currently implemented Tk managers are packer ( C<gt::Pack> ) and placer (
C<gt::Place>).  Each has its own set of options and methods, and their manuals
are provided separately in L<Prima::Widget::pack> and L<Prima::Widget::place> (
the manpages are also imported from the Tk ).

Another concept that comes along with geometry managers is the 'geometry
request size'.  It is realized as a two-integer property C<::geomSize>, which
reflects the size deduced by some intrinsic widget knowledge. The idea is that
C<::geomSize> is merely a request to a geometry manager, whereas the latter
changes C<::size> accordingly. For example, a button might set its 'intrinsic'
width in accord with the width of the text string displayed in it. If the default
width for such a button is not overridden, it is assigned with such a width. By
default, under the C<gt::GrowMode> geometry manager, setting C<::geomSize> (
and its two semi-alias properties C<::geomWidth> and C<::geomHeight> ) also
changes the actual widget size. Moreover, when the size is passed to the Widget
initialization code, the C<::size> property is used to initialize C<::geomSize>.
Such design minimizes the confusion between the two properties, and also
minimizes the direct usage of C<::geomSize>, limiting it to selecting the advisory
size in the internal code.

The geometry request size is useless under the C<gt::GrowMode> geometry
manager, but Tk managers use it extensively.

=head2 Relative coordinates

Another geometry issue, or rather a programming technique, must be mentioned -
the I<relative coordinates>. It is a well-known problem, when a dialog
window, developed with one font looks garbled on another system with another
font. The relative coordinates technique solves this problem by introducing the
C<::designScale> two-integer property, the width and height of the font that
was used when the dialog window was designed. With this property supplied, the
position and size supplied when the widget is created on another setup
using another font, are adjusted proportionally to the actual font metrics.

The relative coordinates can only be used when passing the geometry properties
values, and only before the creation stage, before the widget is created. This
is because the scaling calculations are made in the
Prima::Widget::C<profile_check_in()> method.

To use the relative coordinates technique the owner ( or the I<dialog> ) widget
must set its C<::designScale> property to the font metrics, and the
C<::scaleChildren> property to 1.  Widgets created with an owner that meets
these requirements automatically participate in the relative coordinates
scheme. If a widget must be excluded from the relative geometry applications,
either the owner's property C<::scaleChildren> must be set to 0, or the
widget's C<::designScale> must be set to C<undef>.  As the default
C<::designScale> value is C<undef>, no implicit relative geometry schemes are
applied by default.

The C<::designScale> property is automatically propagated to the children
widgets, unless the explicit C<::designScale> overrides it.  This is useful
when a child widget is a complex widget container, and was designed on yet
another setup with different font sizes.

Note: it is advised to test your applications with the Prima::Stress module
that assigns a random font as the default. See L<Prima::Stress> for more.

=head1 Z-order

When two widgets overlap on the screen, one of these is drawn in full whereas
the other only partly. Prima::Widget provides management of the I<Z-axis>
ordering, with these four methods:  C<first()>, C<last()>, C<next()>, and
C<prev()>. The methods return, correspondingly, the first and the last widgets
in the Z-order stack, and the direct neighbors of the widget ( $widget-> next->
prev always is the $widget itself given that $widget-> next exists ).
If a widget is I<last> that means that it is not obscured by its sibling
widgets, i e the topmost one.

The Z-order can also be changed at runtime ( but not during the widget's creation).
Three methods that change the Z-order: C<bring_to_front()> sends
the widget to the top of the stack, C<send_to_back()> sends it to the bottom,
and C<insert_behind()> sets a widget behind another widget

Changes to Z-order trigger the C<ZOrderChanged> notification.

=head1 Parent-child relationship

By default, if a widget is the child of another widget or a window, it is
clipped by its owner's boundaries and is moved together with its owner if the
latter changes its position.  In this case, the child's owner is also its
parent.

A widget must always have an owner, however, not necessarily a parent.  The
C<::clipOwner> which is 1 by default, is set to 0, switches the widget into the
parent-less mode. That means that the widget is neither clipped nor moved
together with its parent. The widget becomes parent-less, or, more strictly
speaking, the screen becomes its parent. Moreover, in this mode, the widget's
origin offset is calculated not from the owner's coordinates but from the
screen, and clicking on the widget does not bring its owner's top-level window
to the front.

The same result can be also achieved if a widget is inserted in the application
object which does not have any screen visualization.  A widget that belongs to
the application object, has its C<::clipOwner> value set to 0, and it cannot be
changed.

The C<::clipOwner> property opens a possibility for the toolkit widgets to live
inside other programs' windows. The C<::parentHandle> property can be assigned
a valid system window handle, so the widget becomes a child of this window. 
This option has a caveat, because normal widgets are never destroyed for
no reason, and likewise, top-level windows are never destroyed before their
C<Close> notification agrees to their destruction.  When a widget is inserted
into another application it must be prepared to be destroyed at any moment. It
is recommended to use prior knowledge about such an application, and, even
better, use one or another inter-process communication scheme to interact with
it.

A widget doesn't need to do any special action to become an 'owner'.  A widget
that was referred to in the C<::owner> property of another widget, becomes an
owner of the latter automatically. The C<get_widgets()> method returns the list
of these children widgets, similar to the C<Prima::Component::get_components()>
method, but returns only Prima::Widget descendant objects.

Widgets can change their owner at any moment. The C<::owner> property is both
readable and writable, and if a widget is visible during the owner change, it
immediately appears under different coordinates and different clipping
conditions after the property change, given that its C<::clipOwner> property is
set to 1.

=head1 Visibility

Widgets are created visible by default. The visibility status is managed by
the C<::visible> property, and its two convenience alias methods, C<show()> and
C<hide()>.

When a widget gets hidden its geometry is not discarded; the widget retains its
position and size and is still subject to all previously discussed implicit
sizing issues. When the change to the C<::visible> property is made, the screen
is not updated immediately but in the next event loop invocation because
uncovering the underlying area of a hidden widget, and repainting a
newly-shown widget, both depend on the event-driven rendering functionality. If
the graphic content must be updated immediately, the C<update_view()> method
must be called, but there's a caveat. It is obvious that if a widget is shown,
the only content to be updated is its own. When a widget becomes
invisible, it may uncover more than one underlying widget, and
even if the uncovered widgets belong to the same program, it is unclear what
widgets must be updated and when.  For practical reasons, it is enough to
get one event loop passed, by calling the C<yield()> method on the
C<$::application> object.  The other notifications may pass here as well,
however.

There are other kinds of visibility. A widget might be visible, but one of its
owners might not. Or, a widget and its owners might be visible, but they might
be overshadowed by the other windows. These conditions are returned by
C<showing()> and C<exposed()> functions, correspondingly.  So, if a widget is
'exposed', it is 'showing' and 'visible'; the C<exposed()> method always
returns 0 if the widget is either not 'showing' or not 'visible'. If a widget
is 'showing', then it is always 'visible'. C<showing()> always returns 0 if a
widget is invisible.

Change to the visibility status trigger the C<Hide> and C<Show> notifications.

=head1 Focus

One of the key points of any GUI system is that only one window at a time
can possess a I<focus>. The widget is I<focused> if the keyboard
input is directed to it. 

Prima::Widget property C<::focused> manages the focused state of the widget. It
is often too powerful to be used directly, however. Its wrappers, the
C<::selected> and the C<::current> properties are usually more convenient to
operate.

The C<::selected> property sets focus to a widget only if it is allowed to be
focused, by consulting with the value of the C<::selectable> property. When the
widget is selectable, the focus may be passed to either the widget itself or to
one of its ( grand-) children.  For example, when 'selecting' a window
with a text field by clicking on a window, one does not expect the window
itself to be focused, but the text field. To achieve this and reduce
unnecessary coding, the C<::current> property is introduced.  The 'current'
widget gets precedence in getting selected over widgets that are not 'current'.

De-selecting, in turn, leaves the system in such a state when no window has
input focus. There are two convenience shortcuts C<select()> and C<deselect()>
defined, aliased to selected(1) and selected(0), correspondingly.

Within the whole GUI space, there can be only one focused widget, and in the
same fashion there can be only one current widget for each owner widget.  A
widget can be marked as current by calling either its C<::current> property or
the owner widget's C<::currentWidget> property. When a widget gets focused, the
reassignments of the current widgets happen automatically.  The reverse is also
true: if a widget becomes current while it belongs to the widget tree with the
focus in one of its widgets, then the focus is automatically passed to it, or
down to its hierarchy if the widget itself is not selectable.

These relations between the current widget pointer and focus allow the toolkit
to implement the focusing hierarchy easily. The focused widget is always on the
top of the chain of its owner widgets, where each is the current widget. If,
for example, a window that contains a widget that contains a focused button,
becomes un-focused, and then the user selects the window again, then the button
will become focused automatically.

Changes to the focus produce the C<Enter> and C<Leave> notifications.

The next section discusses the mouse- and keyboard-driven focusing schemes.
Note that all of these work via the C<::selected> property, and do not allow to
focus the widgets with their C<::selectable> property set to 0.

=head2 Mouse-aided focusing

Typically when the user clicks the left mouse button on a widget, the latter
becomes focused.  One can note that not all widgets become focused after the
mouse click - scroll bars for example. Another behavior is the one described above
the window with the text field - clicking the mouse on the window focuses the text
field, not the window.

Prima::Widget has also the C<::selectingButtons> property, a combination of the
mb::XXX ( mouse buttons ) flags. If the bits corresponding to the buttons are
present there then the click of this mouse button will automatically call
C<::selected(1)> on the widget that received the mouse click.

Another boolean property C<::firstClick> determines the behavior when the mouse
button action is about to focus a widget, but the widget's top-level window is
not active. The default value of C<::firstClick> is 1, but if it is set
otherwise, the user must click twice on the widget to get it focused. The
property does not influence anything if the top-level window was already active
when the click event occurred.

Due to different GUI designs, it is hardly possible to force the selection of a
top-level window when the user clicked another window.  The window manager or
the OS can interfere, although this does not always happen, and the results may
be different depending on the system. Since the primary goal of the toolkit is
portability, such functionality must be considered with care.  Moreover, when
the user selects a window by clicking not on the toolkit-created widgets, but
on the top-level window decorations, it is not possible to discern the case
from any other kind of focusing.

=head2 Keyboard focusing

The Prima has a built-in way to navigate between the widgets using the tab
and arrow keys. The tab ( and its reverse, shift-tab ) key combinations move
the focus between the widgets in the same top-level group ( but not inside the same
owner widget group ). The arrow keys, if the focused widget is not interested
in these keystrokes, move the focus in the specified direction, if it is
possible. The methods that calculate the widget to be focused depending on the
keystroke are C<next_tab()> and C<next_positional()> ( see API for the
details).

The C<next_positional()> method uses the geometry of the widgets to calculate
which widget is the best candidate when the user presses an arrow key.  The
C<next_tab()> method uses the C<::tabStop> and C<::tabOrder> properties for
this.  The boolean property C<::tabStop> is set to 1 by default and is used to
check whether the widget is willing to participate in the tab-aided focus
circulation or not. If it doesn't the C<next_tab()> never returns that widget
as a candidate to be selected.  The value of the C<::tabOrder> property value
is an integer that is unique within the sibling widgets ( i e those that share
the same owner ) list. That integer value is used as a simple tag when the next
tab-focus candidate is considered. The default C<::tabOrder> value is -1, which
changes to a unique value automatically after the widget creation.

=head1 User input

The toolkit responds to the two basic means of user input - the keyboard
and the mouse. Below are the three aspects of the input handling - the
event-driven, the polling, and the simulated input.

The event-driven input is the more or less natural way of communicating with
the user; when the user presses the key or moves the mouse, a system event
occurs and triggers the notification in one or more widgets. Polling provides
the immediate state of the input devices. The polling technique is rarely
chosen, primarily because of its limited usability, and because the information
it provides is passed to the notification callbacks anyway.  The simulated
input is little more than a C<notify()> call with specifically crafted
parameters. It interacts with the system, by sending the event through the
system API so that the input emulation can be more similar to the user
actions. The simulated input functions allow the notifications to be called
right away, or to be I<post>'ed, delaying the notification until the next
invocation of the event loop.

=head2 Keyboard

=over

=item Event-driven

Keyboard input generates several notifications, where the most important are the
C<KeyDown> and C<KeyUp>. Both have almost the same list of parameters ( see the
API ) that contain the keycode, the modifier keys ( if any ) that were
pressed, and an eventual character code. The algorithms that extract the
meaning of the key, for example, discern between the character and functional
keys, etc are not described here. The reader is advised to look at the
Prima::KeySelector module which provides some convenience functions for various
transformations of the keyboard input values. And to the Prima::Edit and
Prima::InputLine modules, the classes that use extensively the keyboard input.
But in short, the keycode is one of the C<kb::XXX> ( like, kb::F10, kb::Esc )
constants and the key modifier value is a combination of the C<km::XXX> (
km::Ctrl, km::Shift) constants. The notable exception is the kb::None constant
that hints that there is a character code present in the event. Some other
C<kb::XXX>-marked keys have the character code as well, and it is up to a
programmer to decide how to treat these combinations. It is advised, however,
to look at the keycode first, and then at the character code later after to
decide what type of key combination the user pressed.

The C<KeyDown> event has also the I<repeat> integer parameter that shows the
count of how many times the key was repeatedly pressed.  Usually, it is set to 1,
but if a widget is not able to get its portion of events between the key
presses, its value can be higher.  If the code doesn't check for this
parameter, some keyboard input may be lost. If the code will be too 
complicated by introducing the repeat-value, one may consider setting the
C<::briefKeys> property to 0. C<::briefKeys>, the boolean property, is 1 by
default.  If it is set to 0, it guarantees that the repeat value will always be
1, but that comes with the price of certain under-optimization. If the core
C<KeyDown> processing code sees a repeat value greater than 1, it simply calls
the notification again.

Along with these two notifications, the C<TranslateAccel> event is generated
after C<KeyDown>, if the focused widget is not interested in the key event. Its
usage covers the eventual needs of the other widgets to read the user input,
even while being out of focus.  A notable example can be a button with a
hotkey, that reacts on the key press when the focus is elsewhere within its
top-level window.  C<TranslateAccel> has the same parameters as C<KeyDown>, except
the REPEAT parameter.

Such an out-of-focus input scheme is also used when Prima checks if a keypress event
should trigger a menu item because the menu items API allows to declare
hotkeys in the Menu definitions.  Thus, if a descendant of the
Prima::AbstractMenu class is in the widget's children tree hierarchy, then it
is checked whether it contains some hotkeys that match the user input. See
L<Prima::Menu> for the details. In particular, Prima::Widget has the C<::accelTable>
property, a mere slot for an object that contains a table of hotkeys mapped to
the custom subroutines.

=item Polling

The keyboard can only be polled for the states of the modifier keys.  The
C<get_shift_state()> method returns the state of the modifier keys as a
combination of the C<km::XXX> constants.

=item Simulated input

There are two methods C<key_up()> and C<key_down()> that generate the simulated
keyboard input.  They accept the same parameters as the C<KeyUp> and C<KeyDown>
notifications plus the POST boolean flag. See L</"API"> for details. These
methods are convenience wrappers for the C<key_event()> method, which is never
used directly.

=back

=head2 Mouse

=over

=item Event-driven

The mouse notifications are sent when the user moves the mouse, presses the
mouse buttons, or releases them.  The notifications are grouped in two sets,
after their function. The first set consists of the <MouseDown>, C<MouseUp>,
C<MouseClick>, and C<MouseWheel> notifications, and the second of C<MouseMove>,
C<MouseEnter>, end C<MouseLeave>.

The notifications from the first set respond to the mouse button actions.
Pressing, de-pressing, clicking ( and double-clicking ), and turning the mouse
wheel, all these actions result in the generation of the four notifications from
the group. The notifications are sent together with the mouse pointer
coordinates, the button that the user was operating on, and the eventual
modifier keys that were pressed, if any.  In addition, the C<MouseClick>
notification provides an integer parameter of how many clicks occurred on the
same button; that one can distinguish between the single, double, triple, etc mouse
clicks.  The C<MouseWheel> notification provides the numeric argument that
reflects how far the mouse wheel was turned. All of these notifications occur
when the user operates the mouse while the mouse pointer is within the
geometrical bounds of a widget.  If the widget is in the I<capture> mode, then
these events are sent to it even if the mouse pointer is outside the widget's
boundaries, and are not sent to the widgets and windows that reside under the
mouse pointer.

The second set of notifications responds to the mouse pointer movements. When
the pointer passes over a widget, it receives first the C<MouseEnter> event,
then a series of C<MouseMove> events, and finally the C<MouseLeave> event. The
C<MouseMove> and C<MouseEnter> notifications provide the X,Y-coordinates and the
eventual modifier keys; C<MouseLeave> provides no parameters.

=item Polling

The C<get_mouse_state()> method returns a combination of the C<mb::XXX>
constants.  The C<::pointerPos> two-integer property reflects the current
position of the mouse pointer.

=item Simulated input

There are five methods, - C<mouse_up()>, C<mouse_down()>, C<mouse_click()>,
C<mouse_wheel()>, and C<mouse_move()>, that accept the same parameters as their
event counterparts do, plus the POST boolean flag. See L</"API"> for details.

These methods are convenience wrappers for the C<mouse_event()> method that is
never used directly.

=back

=head2 Drag and drop

Widgets can participate in drag-and-drop sessions, interacting with other
applications as well as with themselves, with very few restrictions. See below how
to use this functionality.

=over

=item Data exchange

Prima defines a special clipboard object that serves as an exchange agent
whenever data is to be either sent or received in a DND session. To
either offer to or choose from many formats that another DND client can work
with, use this clipboard (see more in L<Prima::Clipboard>).  The DND clipboard
can be accessed at any time by calling the C< $::application->
get_dnd_clipboard > method.

To successfully exchange data with other applications, one should investigate the
results of a C<< $clipboard-> get_formats(1) >> call to see what types of data
the selected application can send or accept. Programs can often exchange text
and images in the system-dependent format, and other data in the formats named
after the MIME type of the data.  For example, Prima supports image formats
like C<image/bmp> out of the box, and C<text/plain> on X11, which are selected
automatically when operating with pseudo-formats C<Text> or C<Image>. Other
MIME formats like f.ex.  C<text/html> are not known to Prima, but can be
exchanged quite easily; the program only needs to register these formats by
calling the C<Clipboard::register_format> method at the start of the program.

=item Dragging

To begin a dragging session first fill the DND clipboard with data to be
exchanged, using one or more formats, then call the L</start_dnd> method.
Alternatively, call L</begin_drag>, a wrapper method that can set up the
necessary clipboard data itself. See the documentation on these methods for
more details.

During the dragging, the sender will receive the L</DragQuery> and
L</DragResponse> events, to decide whether the drag session must
continue or stop depending on the user interactions, and reflect that decision
to the user. Traditionally, mouse pointers are changed to show whether an
application will receive dropped data, and if yes, what action (copy, move, or
link) it will recognize. Prima will try its best to either use system pointers
or synthesize ones that are informative enough; if that is not sufficient, one
may present its own pointer schema (see f.ex how C<begin_drag> is implemented).

=item Dropping

To register a widget as a drop target, set its L</dndAware> property to either
1, to mark that it will answer to every format, or to a string, in which case
drop events will only be delivered if the DND clipboard contains a format with
that string as its name.

When the user initiates a DND session and moves the mouse pointer over the
widget, it receives the related events: first a L</DragBegin> event, then a
series of the L</DragOver> events, and finally a L</DragEnd> event with a flag
telling whether the user chose to drop the data to the widget or cancel the
session.

The C<DragOver> and C<DragEnd> callbacks provide the possibility to either allow
or deny data and select an action (if there is more than one allowed by the
other application) to proceed with. To do so, set appropriate values to the
C<{allow}> and the C<{action}> fields in the last hashref parameter that is
sent to these event handlers. Additionally, the program can respond to the
C<DragOver> by setting the C<{pad}> rectangle that will cache the last answer
and tell the system to not send repeated events with the same input while the
mouse pointer stays in the rectangle.

=item Portability

X11 and Win32 are rather identical in how they handle DND sessions from
the user perspective. The only difference that is significant to Prima here is
whether the sender or the receiver is responsible for selecting an action for the
available list of actions when the user presses the modifier keys, like CTRL
or SHIFT.

On X11, it is the sender that controls that aspect, and tells the receiver what
action at any given moment the user chose, by responding to a C<DragQuery>
event. On Win32, it is the receiver that selects an action from the list on
each C<DragOver> event, depending on the modifier keys pressed by the user;
Win32 recommends adhering to the standard scheme where the CTRL key means the
C<dnd::Move> action, and the SHIFT key the C<dnd::Link> action, but that is up
to the receiver.

Thus, to write a robust and portable program, assume that it may control the
actions both as the sender and as the receiver. The toolkit's system-dependent
code will make sure that there will be no ambiguities in the input. F.ex. the
sender on Win32 will never be presented with combination of several C<dnd::>
constants inside a C<DragQuery> event, and the X11 receiver will similarly
never be presented with such combination inside C<DragOver>. Nevertheless, a
portable program must be prepared to select and return a DND action in
either callback.

Additionally, the X11 DND protocol describes the situation when the receiver is
presented with the choice of actions, and may also ask the user what action to
select, or cancel the session altogether. This is okay and is expected by the
user, and it is up to your program to use that possibility or not.

=back

=head1 Colors

Prima::Widget extends the functionality of C<::color> and C<::backColor>, the
properties inherited from the Prima::Drawable class. Their values are the widget's
'foreground' and 'background' colors, in addition to their function as template
values. Moreover, their dynamic change induces the repainting of the widget.
The values of these properties can be inherited from the owner; the inheritance
is managed by the properties C<::ownerColor> and C<::ownerBackColor>. If these
are set to 1 then changes to the owner's properties C<::color> or
C<::backColor> are copied automatically to the widget. Once the widget's
C<::color> or C<::backColor> is explicitly set, the owner link breaks
automatically by setting C<::ownerColor> or C<::ownerBackColor> to 0.

In addition to these two existing color properties, Prima::Widget introduces
six others.  These are: C<::disabledColor>, C<::disabledBackColor>,
C<::hiliteColor>, C<::hiliteBackColor>, C<::light3DColor>, and
C<::dark3DColor>.  The 'disabled' color pair contains the values that are
expected to be used as the foreground and the background when the widget is in
the disabled state ( see API, C<::enabled> property ). The 'hilite' values
serve as colors painting a selection inside of the widget. Selection may be of
any kind, and some widgets do not provide any. But for those that do, the
'hilite' color values provide distinct alternative colors. The examples are the
selections in the text widgets or the list boxes. The last pair,
C<::light3DColor> and C<::dark3DColor> is used for drawing 3D-bevelled outlines
on the widget. The purpose of all these properties is to respect the system
colors and draw the Prima GUI as close as possible to the native system look.

There are eight additional C<cl::> constants that can be used to access these
system colors.  These named correspondingly, cl::NormalText, cl::Normal,
cl::HiliteText, cl::Hilite, cl::DisabledText, cl::Disabled, cl::Light3DColor,
and cl::Dark3DColor. The cl::NormalText constant is an alias to cl::Fore, and
cl::Normal - to the cl::Back constant. Another constant set, C<ci::> can be
used with the C<::colorIndex> property, a multiplexer method for all the eight
color properties. C<ci::> constants mimic their non-RGB C<cl::> counterparts,
so that a call to C<hiliteBackColor(cl::Red)> is equal to
C<colorIndex(ci::Hilite, cl::Red)>.

The C<map_color> translates these special constants to the 24-bit RGB integer
values.  The C<cl::> constants alone are sufficient for acquiring the default
values, but the toolkit provides even wider functionality to address default
colors for different types of widgets. The C<cl::> constants can be combined
with the C<wc::> constants, that represent the standard widget classes. If the
color property was assigned with a C<cl::> constant not combined with a C<wc::>
constant, the widget class value is read from the C<::widgetClass> property.
Thus a call to, for example, C<backColor( cl::Back)> on a button and an
input line may result in different colors because the C<cl::Back> is translated
in the first case to C<cl::Back|wc::Button>, and in another to
C<cl::Back|wc::InputLine>. The C<wc::> constants are described in L</"API">.

Dynamic changes of the color properties result in the
C<ColorChanged> notification.

=head1 Fonts

The default font can be automatically inherited from the owner if the
C<::ownerFont> property is set to 1. If it is set to 0, then the font returned
by the C<get_default_font> method is used instead. The method may return
different fonts depending on the widget class, name, and user preferences (
see L</"Additional resources"> ).  A similar method C<get_default_popup_font>
is used to query the default popup font and the C<::popupFont> property for
accessing it.  The Prima::Window class has also similar functions, the
C<get_default_menu_font> method and the C<::menuFont> property.

Dynamic changes to the font property result in the C<FontChanged> notification.

=head1 Additional resources

The resources operated via the Prima::Widget class but not that strictly bound
to the widget concept are gathered in this section. The section includes an
overview of pointer, cursor, hint, menus, and user-specified resources.

=head2 Markup text

The C<Prima::Drawable::Markup> class provides text-like objects that can draw
rich text with various fonts and colors and has primitive support for
painting images. The methods of C<Prima::Drawable> that handle text output such
as C<text_out>, and C<get_text_width>, etc can detect if the text passed is
a blessed object, and make a corresponding call on it. The markup
objects can employ this mechanism to be used transparently in the C<text>
and the C<hint> properties.

There are two ways to construct a markup object: either directly:

   Prima::Drawable::Markup->new( ... )

or using an imported method C<M>,

   use Prima::Drawable::Markup q(M);
   M '...';

where the results of both calls can be directly set to almost any textual
property throughout the whole toolkit, provided that the classes are not
peeking inside the object but only calling the drawing methods on them.

In addition to that, the C<Prima::Widget> class and its descendants recognize the
third syntax:

  Widget->new( text => \ 'markup' )

treating a scalar reference to a text string as a sign that this is 
the text to be compiled into a markup object.

=head2 Pointer

The mouse pointer is the shared resource that can change its visual
representation when it hovers over different kinds of widgets.  It is usually a
good practice for a text field, for example, to set the pointer icon to a
vertical line, or indicate a moving window with a cross-arrow pointer.

A widget can select any of the predefined system pointers mapped by the
C<cr::XXX> constant set, or supply own pointer icon of arbitrary size
and color depth.

NB: Not all systems support colored pointer icons. The system value
sv::ColorPointer index contains a boolean value, whether the colored icons
are allowed or not. Also, the pointer icon size may have a limit: check if
sv::FixedPointerSize is non-zero, in which case the pointer size will be
forcibly reduced to the system limits.

In general, the C<::pointer> property is enough to access these functions of
the mouse pointer.  The property can deduce whether it is an icon or a constant
passed and set the appropriate system properties. These properties are also
accessible separately, although their usage is not encouraged, primarily
because of the tangled relationship between them. These properties are:
C<::pointerType>, C<::pointerIcon>, and C<::pointerHotSpot>. See the details in
the L</"API"> sections.

Another property called C<Prima::Application::pointerVisible> manages the
visibility of the mouse pointer for all widgets at once.

=head2 Cursor

The cursor is a blinking rectangular area that signals that the widget has the
input focus. There can be only one active cursor or no active cursor at all.
The Prima::Widget class provides several cursor properties: C<::cursorVisible>,
C<::cursorPos>, and C<::cursorSize>. There are also two methods,
C<show_cursor()> and C<hide_cursor()> that govern the cursor visibility.  Note:
If the C<hide_cursor()> method was called three times, then C<show_cursor()>
must be called three times as well for the cursor to become visible.

=head2 Hints

C<::hint> is a text string that describes the widget's purpose to the user in a
terse manner. If the mouse pointer hovers over the widget longer than some
timeout ( see Prima::Application::hintPause ), then a small I<tooltip> window
appears with the hint text, which stays on the screen until the pointer is
drawn away.  The hint behavior is managed by Prima::Application, but a widget
can do two additional things about its hint: it can enable and disable it by
setting the C<::showHint> property, and it can inherit the owner's C<::hint>
and C<::showHint> properties using the C<::ownerHint> and C<::ownerShowHint>
properties. If, for example, the widgets' C<::ownerHint> property is set to 1,
then the C<::hint> value is automatically copied from the widget's owner when
it changes. If, however, the widget's C<::hint> or C<::showHint> are explicitly
set, the owner link breaks automatically by setting C<::ownerHint> or
C<::ownerShowHint> to 0.

The widget can also operate the C<::hintVisible> property that shows or hides
the hint label immediately if the mouse pointer is inside the widget's
boundaries.

=head2 Menu objects

Prima::Widget objects may have a special relationship with registered object
instances of the Prima::AccelTable and Prima::Popup class ( for Prima::Window
this is also valid for Prima::Menu objects ). The registration and/or automatic
creation of these objects can happen by using the C<::accelTable>, C<::popup>,
and C<::menu> properties. Also the C<::items> property of these objects can
also be accessed via the C<::accelItems>, C<::popupItems>, and C<::menuItems>
properties.  As mentioned in L</"User input">, these objects intercept the user
keyboard input and call the programmer-defined callback subroutine if the
keystroke matches one of their key definitions.  C<::popup> provides access to
a context pop-up menu, which can be invoked by either right-clicking the mouse
or pressing a system-dependent key combination.

The widget also provides the C<::popupColorIndex> and C<::popupFont>
properties.  The multiplexer method C<::popupColorIndex> can be also used to
access the C<::popupColor>, C<::popupHiliteColor>, C<::popupHiliteBackColor>,
etc properties exactly like the C<::colorIndex> property.  The Prima::Window
class provides equivalent methods for the menu bar, introducing C<::menu>,
C<::menuItems>, C<::menuColorIndex>, and C<::menuFont> properties.

Win32 doesn't support custom font and color of the menu and popup objects.
Check the L<Prima::Menu> for the implementation of the menu widgets without
using the system menu objects.

=head2 User-specified resources

It is considered a good idea to incorporate user preferences into the
toolkit look and feel. Prima::Widget relies on the system-specific code that
tries to map these preferences as closely as possible to the toolkit.

The X11 backend uses XRDB ( X resource database ) which is the natural (but
mostly obsolete as of now) way for the user to tell the preferences with fine
granularity. Win32 reads the setting that the user has to set interactively,
using system tools. Nevertheless, the toolkit can not emulate all user settings
that are available on the supported platforms; it rather takes the 'least
common denominator', which is colors and fonts only. The C<fetch_resource()>
method is capable of accessing such settings, in font, color, or a generic text
format. The method is rarely called directly.

A somewhat appealing idea of making every widget property adjustable via the
user-specified resources is not implemented in full.  It can be accomplished up
to a certain degree using the C<fetch_resource()> method, but it is believed
that calling the method for every property on every widget is prohibitively
expensive.

=head1 API

=head2 Properties

=over

=item accelItems [ ITEM_LIST ]

Manages items of a Prima::AccelTable object associated with a widget.
The ITEM_LIST format is the same as C<Prima::AbstractMenu::items>
and is described in L<Prima::Menu>.

See also: C<accelTable>

=item accelTable OBJECT

Manages a Prima::AccelTable object associated with a widget.
The sole purpose of the accelTable object is to provide
convenience mapping of key combinations to anonymous subroutines.
Instead of writing an interface specifically for Prima::Widget,
the existing interface of Prima::AbstractMenu was taken.

The accelTable object can be destroyed safely; its cancellation
can be done either via C<accelTable(undef)> or C<destroy()> call.

Default value: undef

See also: C<accelItems>

=item autoEnableChildren BOOLEAN

If TRUE, all immediate children widgets maintain the same C<enabled> state as
the widget. This property is useful for group-like widgets ( ComboBox,

Default value: 0

=item backColor COLOR

In the paint state, manages the background color of the graphic context.  In the
normal state, manages the background color property.  When changed initiates the
C<ColorChanged> notification and repaints the widget.

See also: C<color>, C<colorIndex>, C<ColorChanged>

=item bottom INTEGER

Maintains the lower boundary of the widget. If changed does not affect the
widget height, however does so if called in the C<set()> method together with
the C<::top> property.

See also: C<left>, C<right>, C<top>, C<origin>, C<rect>,
C<growMode>, C<Move>

=item briefKeys BOOLEAN

If 1 compresses the repetitive C<KeyDown> events into a single event and
reports the number of the events compressed in the REPEAT parameter.  If 0 the
REPEAT parameter is always 1.

Default value: 1

See also: C<KeyDown>

=item buffered BOOLEAN

If 1, request the system to allocate a memory buffer for painting the widget.
The memory content is copied to the screen then. Used when complex drawing
methods are used, or if output smoothness is desired.

This behavior can not be always granted, however. If there is not enough memory
then the widget draws in the usual manner. One can check whether the buffering
request is granted by calling the C<is_surface_buffered> method.

Default value: 0

See also: C<Paint>, L</is_surface_buffered>.

=item capture BOOLEAN, CLIP_OBJECT = undef

Manipulates capturing of the mouse events. If 1, the mouse events are not
passed to the widget the mouse pointer is over but is redirected to the
caller widget. The call for capture might not be always granted due to the race
conditions between programs.

If the CLIP_OBJECT widget is defined in the set-mode call,
the pointer movements are confined to CLIP_OBJECT inferior.

See also: C<MouseDown>, C<MouseUp>, C<MouseMove>, C<MouseWheel>, C<MouseClick>.

=item centered BOOLEAN

A write-only property. Once set the widget is centered by X and Y
axis relative to its owner.

See also: C<x_centered>, C<y_centered>, C<growMode>, C<origin>, C<Move>.

=item clipChildren BOOLEAN

Affects the drawing mode when the children widgets are present and obscuring
the drawing area.  If set, the children widgets are automatically added to the
clipping area, and drawing over them will not happen. If unset, the painting
can be done over the children widgets.

Default: 1

=item clipOwner BOOLEAN

If 1, the widget is clipped by its owner boundaries.  It is the default and
expected behavior. If clipOwner is 0, the widget behaves differently: it does
not get clipped by the owner, it is not moved together with the parent, the
origin offset is calculated not from the owner's coordinates but from the
screen, and mouse events in the widget do not transgress to the top-level
window decorations.  In short, it becomes a top-level window, that,
contrary to the one created from the Prima::Window class, does not have any
interference with the system-dependent window stacking and positioning ( and
any other ) policy, and it is neither equipped with the window manager
decorations.

Default value: 1

See L</"Parent-child relationship">

See also: C<Prima::Object> owner section, C<parentHandle>

=item color COLOR

In the paint state manages, the foreground color of the graphic context.  In the
normal state, manages the basic foreground color property.  When changed
initiates C<ColorChanged> notification and repaints the widget.

See also: C<backColor>, C<colorIndex>, C<ColorChanged>

=item colorIndex INDEX, COLOR

Manages the basic color properties indirectly by accessing them via the C<ci::XXX>
constants. Is a complete alias for C<::color>, C<::backColor>, C<::hiliteColor>,
C<::hiliteBackColor>, C<::disabledColor>, C<::disabledBackColor>,
C<::light3DColor>, and C<::dark3DColor> properties. The C<ci::XXX> constants
are:

   ci::NormalText or ci::Fore
   ci::Normal or ci::Back
   ci::HiliteText
   ci::Hilite
   ci::DisabledText
   ci::Disabled
   ci::Light3DColor
   ci::Dark3DColor

The non-RGB C<cl::> constants, specific to the Prima::Widget color usage are
identical to their C<ci::> counterparts:

   cl::NormalText or cl::Fore
   cl::Normal or cl::Back
   cl::HiliteText
   cl::Hilite
   cl::DisabledText
   cl::Disabled
   cl::Light3DColor
   cl::Dark3DColor

See also: C<color>, C<backColor>, C<ColorChanged>

=item current BOOLEAN

If 1, the widget (or one of its children) is marked as the one to be selected
and possibly focused when the owner widget receives the C<select()> call. Only
one children widget can be current, or none at all.

See also: C<currentWidget>, C<selectable>, C<selected>, C<selectedWidget>, C<focused>

=item currentWidget OBJECT

Points to the children widget that is to be selected and possibly focused when
the owner widget receives the C<select()> call.

See also: C<current>, C<selectable>, C<selected>, C<selectedWidget>, C<focused>

=item cursorPos X_OFFSET Y_OFFSET

Specifies the lower left corner of the cursor

See also: C<cursorSize>, C<cursorVisible>

=item cursorSize WIDTH HEIGHT

Specifies width and height of the cursor

See also: C<cursorPos>, C<cursorVisible>

=item cursorVisible BOOLEAN

Specifies the cursor visibility flag. The default value is 0.

See also: C<cursorSize>, C<cursorPos>

=item dark3DColor COLOR

The color used to draw dark shades.

See also: C<light3DColor>, C<colorIndex>, C<ColorChanged>

=item designScale X_SCALE Y_SCALE

The width and height of the font that was used when the widget ( usually  a
dialog or a grouping widget ) was designed.

See also: C<scaleChildren>, C<width>, C<height>, C<size>, C<font>

=item disabledBackColor COLOR

The color to be used instead of the value of the C<::backColor> property when the widget
is in the disabled state.

See also: C<disabledColor>, C<colorIndex>, C<ColorChanged>

=item disabledColor COLOR

The color to be used instead of the value of the C<::color> property when the widget
is in the disabled state.

See also: C<disabledBackColor>, C<colorIndex>, C<ColorChanged>

=item dndAware 0 | 1 | FORMAT

To register the widget as a drop target, set its L</dndAware> property to
either 1, to mark that it will answer to all formats, or to a text string, in
which case the drop events will only be delivered if the DND clipboard contains
the data of the type FORMAT.

Default: 0

See also: C<Drag and Drop>

=item enabled BOOLEAN

Specifies if the widget can accept focus, the keyboard, and the mouse events.
The default value is 1, however, being 'enabled' does not automatically allow the
widget to become focused. Only the reverse is true - if enabled is 0, focusing can
never happen.

See also: C<responsive>, C<visible>, C<Enable>, C<Disable>

=item font %FONT

Manages the font context. Same syntax as in Prima::Drawable.
When changed initiates C<FontChanged> notification and repaints the widget.

See also: C<designScale>, C<FontChanged>, C<ColorChanged>

=item geometry INTEGER

Selects one of the available geometry managers. The corresponding
integer constants are:

   gt::GrowMode, gt::Default - the default grow-mode algorithm
   gt::Pack                  - Tk packer
   gt::Place                 - Tk placer

See C<growMode>, L<Prima::Widget::pack>, L<Prima::Widget::place>.

=item growMode MODE

Specifies the widget's behavior, when its owner is resized or moved.
MODE can be 0 ( default ) or a combination of the following constants:

=over

=item Basic constants

 gm::GrowLoX      the widget's left side is kept in constant
                  distance from its owner's right side
 gm::GrowLoY      the widget's bottom side is kept in constant
                  distance from its owner's top side
 gm::GrowHiX      the widget's right side is kept in constant
                  distance from its owner's right side
 gm::GrowHiY      the widget's top side is kept in constant
                  distance from its owner's top side
 gm::XCenter      the widget is kept in the center of its owner's
                  horizontal axis
 gm::YCenter      the widget is kept in the center of its owner's
                  vertical axis
 gm::DontCare     widgets origin is constant relative
                  to the screen

=item Derived or aliased constants

 gm::GrowAll      gm::GrowLoX|gm::GrowLoY|gm::GrowHiX|gm::GrowHiY
 gm::Center       gm::XCenter|gm::YCenter
 gm::Client       gm::GrowHiX|gm::GrowHiY
 gm::Right        gm::GrowLoX|gm::GrowHiY
 gm::Left         gm::GrowHiY
 gm::Floor        gm::GrowHiX

=back

See also: C<Move>, C<origin>

=item firstClick BOOLEAN

If 0, the widget ignores the first mouse click if the top-level window it
belongs to was not activated, so selecting such a widget with a mouse must take
two clicks.

Default: 1

See also: C<MouseDown>, C<selectable>, C<selected>, C<focused>,
C<selectingButtons>

=item focused BOOLEAN

On the get-call returns whether the widget possesses the input focus or not.
On the set-call sets the focus to the widget, ignoring the C<::selectable>
property.

See also: C<selectable>, C<selected>, C<selectedWidget>, C<KeyDown>

=item geomWidth, geomHeight, geomSize

The three properties that manage the geometry request size. Writing and reading
to the C<::geomWidth> and C<::geomHeight> properties is equivalent to doing the
same to the C<::geomSize> property. The properties are run-time only, and
behave differently under different circumstances:

=over

=item *

The properties can only be used after widget creation, they can not be set in
the creation profile, and their initial value is fetched from the C<::size>
property. Thus, setting the explicit size additionally sets the advised size
in case the widget is to be used with the Tk geometry managers.

=item *

Setting the properties under the C<gt::GrowMode> geometry manager also sets the
corresponding C<::width>, C<::height>, or C<::size> properties. When the
properties are read though, the widget size properties are not accessed, their
values are kept separately.

=item *

Setting the properties under Tk geometry managers causes the widget's size and
position to change according to the geometry manager policy.

=back

=item height

Maintains the height of the widget.

See also: C<width>, C<growMode>, C<Move>, C<Size>, C<get_virtual_size>,
C<sizeMax>, C<sizeMin>

=item helpContext STRING

A text string that binds the widget to the interactive help topic. STRING
format is defined as a POD link ( see L<perlpod> ) - "manpage/section", where
'manpage' is the file with POD content and 'section' is the topic inside the
manpage.

See also: C<help>

=item hiliteBackColor COLOR

The color to be used to draw the alternate background areas
with a higher contrast.

See also: C<hiliteColor>, C<colorIndex>, C<ColorChanged>

=item hiliteColor COLOR

The color to be used to draw the alternate foreground areas
with a higher contrast.

See also: C<hiliteBackColor>, C<colorIndex>, C<ColorChanged>

=item hint TEXT

A text string is shown under the mouse pointer if it is hovered over the widget
longer than the C<Prima::Application::hintPause> timeout. The text appears only if
the C<::showHint> is 1.

TEXT can also be a C<Prima::Drawable::Markup> object

See also: C<hintVisible>, C<showHint>, C<ownerHint>, C<ownerShowHint>

=item hintVisible BOOLEAN

Returns the hint visibility status when called in the get-form.  When called in
the set-form immediately turns on or off the hint label, disregarding the
timeouts. It does regard the mouse pointer location though and does not turn
on the hint label if the pointer is not immediately over the widget.

See also: C<hint>, C<showHint>, C<ownerHint>, C<ownerShowHint>

=item layered BOOLEAN

If set, requests the system to use the alpha transparency.  Depending on the
system and its configuration this request may or may not be granted.  The
actual status of the request success is returned by the C<is_surface_layered>
method.  See L<Prima::Image/Layering> for more details.

Default: false

Note: On Windows mouse events will not be delivered to the layered widget if
the pixel under the mouse pointer is fully transparent.

On X11 you need to run a composition manager, f.ex. I<compiz> or I<xcompmgr>.

On Darwin/XQuartz the alpha transparency is unavailable (2023).

=item left INTEGER

Maintains the left boundary of the widget. If changed does not affect the
widget width, however does so if called in the C<set()> method together with
the C<::right> property.

See also: C<bottom>, C<right>, C<top>, C<origin>, C<rect>,
C<growMode>, C<Move>

=item light3DColor COLOR

The color to draw light shades.

See also: C<dark3DColor>, C<colorIndex>, C<ColorChanged>

=item ownerBackColor BOOLEAN

If 1, the background color is synchronized with the owner's.
Automatically resets to 0 if the C<::backColor> property is set explicitly.

See also: C<ownerColor>, C<backColor>, C<colorIndex>

=item ownerColor BOOLEAN

If 1, the foreground color is synchronized with the owner's.
Automatically resets to 0 if the C<::color> property is set explicitly.

See also: C<ownerBackColor>, C<color>, C<colorIndex>

=item ownerFont BOOLEAN

If 1, the font is synchronized with the owner's.
Automatically resets to 0 if the C<::font> property is set explicitly.

See also: C<font>, C<FontChanged>

=item ownerHint BOOLEAN

If 1, the hint is synchronized with the owner's.
Automatically resets to 0 if the C<::hint> property is set explicitly.

See also: C<hint>, C<showHint>, C<hintVisible>, C<ownerShowHint>

=item ownerShowHint BOOLEAN

If 1, the show hint flag is synchronized with the owner's.
Automatically resets to 0 if the C<::showHint> property is set explicitly.

See also: C<hint>, C<showHint>, C<hintVisible>, C<ownerHint>

=item ownerPalette BOOLEAN

If 1, the palette array is synchronized with the owner's.
Automatically resets to 0 if the C<::palette> property is set explicitly.

See also: C<palette>

=item ownerSkin BOOLEAN

If 1, the C<skin> property is set to undef and thus will be synchronized with the owner's.
Automatically resets to 0 if the C<::skin> property is set explicitly.

See also: C<skin>

=item origin X Y

Maintains the left and bottom boundaries of the widget relative
to its owner ( or to the screen if the C<::clipOwner> property is 0 ).

See also: C<bottom>, C<right>, C<top>, C<left>, C<rect>,
C<growMode>, C<Move>

=item packInfo %OPTIONS

See L<Prima::Widget::pack>

=item palette [ @PALETTE ]

Manages the array of colors that are desired to be present in the system
palette, as close to the PALETTE as possible.  This property works only if the
graphic device allows palette operations. See L<Prima::Drawable/"palette">.

See also: C<ownerPalette>

=item parentHandle SYSTEM_WINDOW

If the SYSTEM_WINDOW is a valid system-dependent window handle then a widget
becomes the child of the window specified, given the widget's C<::clipOwner> is
0.  The parent window may belong to another application.

Default value is undef.

See also: C<clipOwner>

=item placeInfo %OPTIONS

See L<Prima::Widget::place>

=item pointer cr::XXX or ICON

Specifies the pointer icon by either one of the C<cr::XXX> constants or an
icon.  If the icon contains a hash variable C<__pointerHotSpot> with an array
of two integers, these integers will be treated as the pointer hot spot. In the
get-mode call, this variable is automatically assigned to an icon if the result
is an icon object.

See also: C<pointerHotSpot>, C<pointerIcon>, C<pointerType>

=item pointerHotSpot X_OFFSET Y_OFFSET

Specifies the hot spot coordinates of the pointer icon associated
with the widget.

See also: C<pointer>, C<pointerIcon>, C<pointerType>

=item pointerIcon ICON

Specifies the pointer icon associated with the widget.

See also: C<pointerHotSpot>, C<pointer>, C<pointerType>

=item pointerPos X_OFFSET Y_OFFSET

Specifies the mouse pointer coordinates relative to the widget's
coordinates.

See also: C<get_mouse_state>, C<screen_to_client>, C<client_to_screen>

=item pointerType TYPE

Specifies the type of the pointer associated with the widget.
The TYPE can accept one constant of the C<cr::XXX> constants:

   cr::Default                 same pointer type as owner's
   cr::Arrow                   arrow pointer
   cr::Text                    text entry cursor-like pointer
   cr::Wait                    hourglass
   cr::Size                    general size action pointer
   cr::Move                    general move action pointer
   cr::SizeWest, cr::SizeW     right-move action pointer
   cr::SizeEast, cr::SizeE     left-move action pointer
   cr::SizeWE                  general horizontal-move action pointer
   cr::SizeNorth, cr::SizeN    up-move action pointer
   cr::SizeSouth, cr::SizeS    down-move action pointer
   cr::SizeNS                  general vertical-move action pointer
   cr::SizeNW                  up-right move action pointer
   cr::SizeSE                  down-left move action pointer
   cr::SizeNE                  up-left move action pointer
   cr::SizeSW                  down-right move action pointer
   cr::Invalid                 invalid action pointer
   cr::DragNone                pointer for an invalid dragging target
   cr::DragCopy                pointer to indicate that a dnd::Copy action can be accepted
   cr::DragMove                pointer to indicate that a dnd::Move action can be accepted
   cr::DragLink                pointer to indicate that a dnd::Link action can be accepted
   cr::Crosshair               the crosshair pointer
   cr::UpArrow                 arrow directed upwards
   cr::QuestionArrow           question mark pointer
   cr::User                    user-defined icon

All constants except the C<cr::User> and the C<cr::Default> represent the
system-defined pointers, their icons, and hot spot offsets. C<cr::User> is a
constant that tells the system that an icon object was specified explicitly via
the C<::pointerIcon> property.  The C<cr::Default> constant tells that the
widget inherits its owner pointer type, no matter if is it a system-defined
pointer or a custom icon.

See also: C<pointerHotSpot>, C<pointerIcon>, C<pointer>

=item popup OBJECT

Manages a Prima::Popup object associated with the widget.  The purpose of the
popup object is to show the context menu when the user right-clicks or selects
the corresponding keyboard combination. Prima::Widget can host many popup
objects but only the one that is registered in the C<::popup> property will be
activated automatically.

The popup object can be destroyed safely; can be done either via a
C<popup(undef)> or a C<destroy()> call.

See also: C<Prima::Menu>, C<Popup>, C<Menu>,
C<popupItems>, C<popupColorIndex>, C<popupFont>

=item popupColorIndex INDEX, COLOR

Maintains eight color properties of the pop-up context menu, associated with
the widget. INDEX must be one of the C<ci::XXX> constants ( see C<::colorIndex>
property ).

See also: C<popupItems>, C<popupFont>, C<popup>

=item popupColor COLOR

Basic foreground color in the popup context menu color.

See also: C<popupItems>, C<popupColorIndex>, C<popupFont>, C<popup>

=item popupBackColor COLOR

Basic background color in the popup context menu color.

See also: C<popupItems>, C<popupColorIndex>, C<popupFont>, C<popup>

=item popupDark3DColor COLOR

The color for drawing dark shades in the popup context menu.

See also: C<popupItems>, C<popupColorIndex>, C<popupFont>, C<popup>

=item popupDisabledColor COLOR

The foreground color for the disabled items in the popup context menu.

See also: C<popupItems>, C<popupColorIndex>, C<popupFont>, C<popup>

=item popupDisabledBackColor COLOR

The background color for the disabled items in the popup context menu.

See also: C<popupItems>, C<popupColorIndex>, C<popupFont>, C<popup>

=item popupFont %FONT

Maintains the font of the pop-up context menu associated with the widget.

See also: C<popupItems>, C<popupColorIndex>, C<popup>

=item popupHiliteColor COLOR

The foreground color for the selected items in the popup context menu.

See also: C<popupItems>, C<popupColorIndex>, C<popupFont>, C<popup>

=item popupHiliteBackColor COLOR

The background color for the selected items in the popup context menu.

See also: C<popupItems>, C<popupColorIndex>, C<popupFont>, C<popup>

=item popupItems [ ITEM_LIST ]

Manages items of the Prima::Popup object associated with the widget.  The
ITEM_LIST format is the same as C<Prima::AbstractMenu::items> and is described in
L<Prima::Menu>.

See also: C<popup>, C<popupColorIndex>, C<popupFont>

=item popupLight3DColor COLOR

The color for drawing light shades in the popup context menu.

See also: C<popupItems>, C<popupColorIndex>, C<popupFont>, C<popup>

=item rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET Y_TOP_OFFSET

Maintains the rectangular boundaries of the widget relative
to its owner ( or to the screen if C<::clipOwner> is 0 ).

See also: C<bottom>, C<right>, C<top>, C<left>, C<origin>,
C<width>, C<height>, C<size>
C<growMode>, C<Move>, C<Size>, C<get_virtual_size>,
C<sizeMax>, C<sizeMin>

=item right INTEGER

Maintains the right boundary of the widget. If changed
does not affect the widget width, however does so if called
in the C<set()> method together with the C<::left> property.

See also: C<left>, C<bottom>, C<top>, C<origin>, C<rect>,
C<growMode>, C<Move>

=item scaleChildren BOOLEAN

If the widget has the C<::scaleChildren> property set to 1, then the
newly-created children widgets inserted in it will be scaled corresponding to
the value of its owner's C<::designScale> property, given that widget's
C<::designScale> is not C<undef> and the owner's is not [0,0].

Default: 1

See also: C<designScale>

=item selectable BOOLEAN

If 1, the widget can be granted focus by the toolkit or by the user.  The
C<select()> method checks if this property is set, and does not focus a widget
that has C<::selectable> set to 0.

Default: 0

See also: C<current>, C<currentWidget>, C<selected>, C<selectedWidget>, C<focused>

=item selected BOOLEAN

In the get-mode returns true if either the widget or one of its (grand-)
children is focused. In the set-mode either turns the system with no-focus
state ( if a value of 0 is given ) or re-sends input focus to itself or one of
the (grand-) children widgets down the C<::currentWidget> chain.

See also: C<current>, C<currentWidget>, C<selectable>, C<selectedWidget>, C<focused>

=item selectedWidget OBJECT

Points to the immediate child widget that has the value of the property C<::selected> set to 1.

See also: C<current>, C<currentWidget>, C<selectable>, C<selected>, C<focused>

=item selectingButtons FLAGS

The FLAGS is a combination of the C<mb::XXX> ( mouse button ) flags.  If the
widget receives a mouse click with the button that has the corresponding bit
set in C<::selectingButtons> then the C<select()> method is called.

Default: C<mb::Left>

See also: C<MouseDown>, C<firstClick>, C<selectable>, C<selected>, C<focused>

=item shape REGION

Maintains the non-rectangular shape of the widget.  In the set-mode REGION is
either a Prima::Image object with its 0 bits treated as transparent pixels and
1 bits as opaque pixels, or a Prima::Region object.  In the get-mode, it is
either undef or a Prima::Region object.

Successive only if the C<sv::ShapeExtension> value is true.

=item showHint BOOLEAN

If 1, the toolkit is allowed to show the hint label over the widget. The
C<::hint> property must contain a non-empty string text if the hint label is to
be shown.

The default value is 1.

See also: C<hint>, C<ownerShowHint>, C<hintVisible>, C<ownerHint>

=item size WIDTH HEIGHT

Maintains the width and height of the widget.

See also: C<width>, C<height>
C<growMode>, C<Move>, C<Size>, C<get_virtual_size>,
C<sizeMax>, C<sizeMin>

=item sizeMax WIDTH HEIGHT

Specifies the maximal size for the widget.

See also: C<width>, C<height>, C<size>
C<growMode>, C<Move>, C<Size>, C<get_virtual_size>,
C<sizeMin>

=item sizeMin WIDTH HEIGHT

Specifies the minimal size for the widget.

See also: C<width>, C<height>, C<size>
C<growMode>, C<Move>, C<Size>, C<get_virtual_size>,
C<sizeMax>

=item skin SCALAR

A generic scalar, is not used in the C<Prima::Widget> class implementation but is
designed to select the visual style of a widget, where the interpretation of
the property value will be up to the widget class itself. Many of the toolkit
widgets implement two skins, C<classic> and C<flat>.

Does not repaint the widget on the property change, however many of the toolkit
widgets do that.

If the C<ownerSkin> property value is 1 returns the skin of the owner.  When
is undef, sets the C<ownerSkin> property to 1, otherwise resets it to 0.

Note: this is not a symmetric property, as a C<< $self->skin($self->skin) >>
call is not idempotent.

=item syncPaint BOOLEAN

If 0, the C<Paint> request notifications are stacked until the event loop is
called. If 1, every time the widget surface gets invalidated the C<Paint>
notification is called.

Default: 0

See also: C<invalidate_rect>, C<repaint>, C<validate_rect>, C<Paint>

=item tabOrder INTEGER

Maintains the order in which the tab- and shift-tab key navigation algorithms
focus the sibling widgets. INTEGER is unique among the sibling widgets. In the
set-mode, if INTEGER the value is already taken by another widget, the latter
is assigned another unique value, but without the destruction of the internal
queue - the widgets with ::tabOrder greater than of the widget in question
receive new values too. The special value -1 is accepted as 'the end of list'
request in the set-call. A negative value is never returned in the get-call.

See also: C<tabStop>, C<next_tab>, C<selectable>, C<selected>, C<focused>

=item tabStop BOOLEAN

Specifies whether the widget is interested in the tab- and shift-tab key
navigation or not.

Default value is 1.

See also: C<tabOrder>, C<next_tab>, C<selectable>, C<selected>, C<focused>

=item text TEXT

A text string for generic purposes. Many Prima::Widget descendants use this
property heavily - buttons, labels, input lines, etc, but Prima::Widget itself
does not.

If the C<TEXT> is a reference to a string, it is treated as a markup string
and is compiled into a C<Prima::Drawable::Markup> object internally.

See L<Prima::Drawable::Markup>, F<examples/markup.pl>

=item top INTEGER

Maintains the upper boundary of the widget. If changed
does not affect the widget height, however does so if called
in the C<set()> method together with the C<::bottom> property.

See also: C<left>, C<right>, C<bottom>, C<origin>, C<rect>,
C<growMode>, C<Move>

=item transparent BOOLEAN

Specifies whether the background of the widget before it starts painting is of
any importance. If 1, the widget can gain a certain emulated transparency look if
it does not clear the background during the C<Paint> event.

Default value is 0

See also: C<Paint>, C<buffered>.

=item visible BOOLEAN

Specifies whether the widget is visible or not.
See L</"Visibility">.

See also: C<Show>, C<Hide>, C<showing>, C<exposed>

=item widgetClass CLASS

Maintains the integer value, designating the color class that is defined by the
system and is associated with Prima::Widget's eight basic color properties. The
CLASS can be one of the C<wc::XXX> constants:

   wc::Undef
   wc::Button
   wc::CheckBox
   wc::Combo
   wc::Dialog
   wc::Edit
   wc::InputLine
   wc::Label
   wc::ListBox
   wc::Menu
   wc::Popup
   wc::Radio
   wc::ScrollBar
   wc::Slider
   wc::Widget or wc::Custom
   wc::Window
   wc::Application

These constants are not associated with the toolkit classes but rather are a
wide shot to any possible native classes or widgets that the system may
implement and have different color defaults for.  Any Prima class can use any
of these constants in its C<::widgetClass> property.

See also: C<map_color>, C<colorIndex>

=item widgets @WIDGETS

In the get-mode returns the list of immediate children widgets (identical to
C<get_widgets>). In the set-mode accepts the set of widget profiles, as
C<insert> does, as a list or an array. This way it is possible to create a widget
hierarchy in a single call.

=item width WIDTH

Maintains the width of the widget.

See also: C<height> C<growMode>, C<Move>, C<Size>, C<get_virtual_size>,
C<sizeMax>, C<sizeMin>

=item x_centered BOOLEAN

A write-only property. Once set, the widget is centered on the horizontal
axis relative to its owner.

See also: C<centered>, C<y_centered>, C<growMode>, C<origin>, C<Move>.

=item y_centered BOOLEAN

A write-only property. Once set, the widget is centered on the vertical
axis relative to its owner.

See also: C<x_centered>, C<centered>, C<growMode>, C<origin>, C<Move>.

=back

=head2 Methods

=over

=item begin_drag [ DATA | %OPTIONS ]

Wrapper over the C<dnd_start> method that adds several aspects to the DND
session that the system doesn't offer. All of the input is contained in the
C<%OPTIONS> hash except when the case of a single-parameter call, when the DATA
scalar is treated either as C<< text => DATA >> or C<< image => DATA >>
depending on the C<DATA> type.

Returns -1 if a DND session cannot start, C<dnd::None> if it was canceled by
the user, or any other C<dnd::> constant when the DND receiver has selected and
successfully performed that action. For example, after a call to the
C<dnd_start> method that returned the C<dnd::Move> value the caller may remove
the data the user selected to move (C<Prima::InputLine> and C<Prima::Edit> do
exactly this).

In the C<wantarray> context also returns the widget that accepted the drop, if
that is a Prima widget. Check this before handling C<dnd::Move> actions that
require data to be deleted on the source, to not occasionally delete the
freshly transferred data. The C<begin_drag> method uses a special precaution
for this scenario and by default won't let the widget be both the sender and the
receiver ( see C<self_aware> below ).

The following input is recognized:

=over

=item actions INTEGER = dnd::Copy

A combination of the C<dnd::> constants, to tell a DND receiver if copying,
moving, and/or linking the data is allowed. The method fails on the invalid
C<actions> input.

=item format FORMAT, data INPUT

If set, the DND clipboard will contain a single entry of the C<INPUT> in the
C<FORMAT> format, where the format is either the standard C<Text> or C<Image>, or
one of the formats registered by the C<Clipboard::register_format> method.

If not set, the caller needs to fill the clipboard in advance, f.ex. to offer
data in more than one format.

=item image INPUT

Shortcut for C<< format => 'Image', data => $INPUT, preview => $INPUT >>

=item preview INPUT

If set, the mouse pointers sending feedback to the user will be visually
combined with either text or image, depending on whether C<INPUT> is a text
scalar or an image reference.

=item self_aware BOOLEAN = 1

If unset, the widget's C<dndAware> will be temporarily set to 0 to exclude a
possibility of an operation that may end in sending data to itself.

=item text INPUT

Shortcut for C<< format => 'Text', data => $INPUT, preview => $INPUT >>

=item track INTEGER = 5

If set, waits to start the DND process until the user moves the mouse
pointer away from the starting point further than C<track> pixels, which makes
sense if the method is to be called directly from a C<MouseDown> event handler.

If the drag did not happen because the user released the button or otherwise
marked that this is not a drag, -1 is returned. In that case, the caller should
continue to handle the C<MouseDown> event as if no drag session was ever started.

=back

=item bring_to_front

Sends the widget on top of all other sibling widgets

See also: C<insert_behind>, C<send_to_back>, C<ZOrderChanged>
,C<first>, C<next>, C<prev>, C<last>

=item can_close

Sends the C<Close> event and returns its flag value.  Windows that need to
abort a potential closing, for example when an editor asks the user if a
document needs to be saved, need to call the C<clear_event> method in the
C<Close> event handler.

See also: C<Close>, C<close>

=item client_to_screen @OFFSETS

Maps an array of X and Y integer offsets from the widget to the screen
coordinates.  Returns the mapped OFFSETS.

See also: C<screen_to_client>, C<clipOwner>

=item close

Calls C<can_close()>, and if successful, destroys the widget.
Returns the C<can_close()> result.

See also: C<can_close>, C<Close>

=item defocus

Alias for the C<focused(0)> call

See also: C<focus>, C<focused>, C<Enter>, C<Leave>

=item deselect

Alias for the C<selected(0)> call

See also: C<select>, C<selected>, C<Enter>, C<Leave>

=item dnd_start ACTIONS = dnd::Copy, USE_DEFAULT_POINTERS = 1

Starts a drag-and-drop session with a combination of the C<ACTIONS> allowed.
It is expected that the DND clipboard will be filled with the data that are
prepared to be sent to a DND receiver.

Returns -1 if a DND session cannot start, the C<dnd::None> constant if it was
canceled by the user or any other C<dnd::> constant when the DND receiver has
selected and successfully performed that action. For example, after a call to
the C<dnd_start> method returning C<dnd::Move>, the caller may remove the data
the user selected to move (C<Prima::InputLine> and C<Prima::Edit> do exactly
this).

Also returns the widget that accepted the drop, if that was the Prima widget within
the same program.

If the USE_DEFAULT_POINTERS flag is set the system will use default drag pointers.
Otherwise, it is expected that a C<DragResponse> action will change the mouse pointers
according to the current action, to give the user the visual feedback.

See C<begin_drag> for the wrapper over this method that extends this functionality.

See also: C<Drag and Drop>, C<DragQuery>, C<DragResponse>.

=item exposed

Returns the boolean value indicating whether the widget is at least partly
visible on the screen.  Never returns 1 if the widget's C<::visible> value is
0.

See also: C<visible>, C<showing>, C<Show>, C<Hide>

=item fetch_resource CLASS_NAME, NAME, CLASS_RESOURCE, RESOURCE, OWNER, RESOURCE_TYPE = fr::String

Returns a system-defined scalar of the resource, defined by the widget hierarchy,
its class, name, and owner. RESOURCE_TYPE can be one of the following type constants:

   fr::Color  - color resource
   fr::Font   - font resource
   fs::String - text string resource

These parameters are used to address the widget in its hierarchy before it is
created. The CLASS_NAME is the widget class string, NAME is the widget name.
CLASS_RESOURCE is the class of the resource, and RESOURCE is the resource name.

For example, resources 'color' and 'disabledColor' belong to the
resource class 'Foreground'.

=item first

Returns the first ( from bottom ) sibling widget in Z-order.

See also: C<last>, C<next>, C<prev>

=item focus

Alias for C<focused(1)> call

See also: C<defocus>, C<focused>, C<Enter>, C<Leave>

=item hide

Sets widget C<::visible> to 0.

See also: C<hide>, C<visible>, C<Show>, C<Hide>, C<showing>, C<exposed>

=item hide_cursor

Hides the cursor. If the C<hide_cursor()> method was called more than once then
the C<show_cursor> should also be called as many times to show the cursor back.

See also: C<show_cursor>, C<cursorVisible>

=item help

Starts the interactive help viewer session and requests it to open the link in
the C<::helpContext> string value.  The string value is combined from the
widget's owner C<::helpContext> strings if the latter is empty or begins with a
slash.  A special meaning is assigned to the empty string " " - the help() call
fails when such value is found to be the section component.  This feature can
be useful when a window or a dialog presents a standalone functionality in a
separate module, and the documentation is related more to the module than to an
embedding program. In such case the grouping widget holds C<::helpContext> as a
pod manpage name with the trailing slash, and its children widgets are assigned
C<::helpContext> to the topics without the manpage but with the leading slash
instead.  If the grouping widget has an empty string " " as the
C<::helpContext> then the help is unavailable for all the children widgets.

See also: C<helpContext>

=item insert CLASS, %PROFILE [[ CLASS, %PROFILE], ... ]

Creates one or more widgets with their C<owner> properties set to the caller
widget, and returns the list of the references to the newly created widgets.

Has two calling formats:

=over

=item Single widget

  $parent-> insert( 'Child::Class',
     name => 'child',
     ....
  );

=item Multiple widgets

  $parent-> insert(
    [
       'Child::Class1',
          name => 'child1',
          ....
    ],
    [
       'Child::Class2',
          name => 'child2',
          ....
    ],
  );

=back

=item insert_behind OBJECT

Sends the widget behind the OBJECT on Z-axis given that
the OBJECT is a sibling to the widget.

See also: C<bring_to_front>, C<send_to_back>, C<ZOrderChanged>
,C<first>, C<next>, C<prev>, C<last>

=item invalidate_rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET Y_TOP_OFFSET

Marks the rectangular area of the widget as 'invalid', triggering the re-painting
of the area. See L</"Graphic content">.

See also: C<validate_rect>, C<get_invalid_rect>, C<repaint>, C<Paint>,
C<syncPaint>, C<update_view>

=item is_surface_buffered

Returns true if the C<buffered> property is set and the buffering request was
granted.  The value is only valid inside the C<begin_paint/end_paint> bracket
and is always false otherwise.

See also: L</buffered>

=item is_surface_layered

Returns true if both the widget and its top-most parent are layered.
If the widget itself is top-most, i.e. a window, a non-clipOwner widget,
or a child to the application, then is the same as C<layered>.

See also: L</layered>

=item key_down CODE, KEY = kb::NoKey, MOD = 0, REPEAT = 1, POST = 0

The method sends or posts ( POST flag ) the simulated C<KeyDown> event
to the system. CODE, KEY, MOD, and REPEAT are the parameters
to be passed to the notification callbacks.

See also: C<key_up>, C<key_event>, C<KeyDown>

=item key_event COMMAND, CODE, KEY = kb::NoKey, MOD = 0, REPEAT = 1, POST = 0

The method sends or posts ( POST flag ) the simulated keyboard event to the
system. CODE, KEY, MOD and REPEAT are the parameters to be passed to an
eventual C<KeyDown> or C<KeyUp> notification.  COMMAND is allowed to be either
C<cm::KeyDown> or C<cm::KeyUp>.

See also: C<key_down>, C<key_up>, C<KeyDown>, C<KeyUp>

=item key_up CODE, KEY = kb::NoKey, MOD = 0, POST = 0

The method sends or posts ( POST flag ) the simulated C<KeyUp> event
to the system. CODE, KEY and MOD are the parameters
to be passed to the notification callbacks.

See also: C<key_down>, C<key_event>, C<KeyUp>

=item last

Returns the last ( the topmost ) sibling widget in Z-order.

See also: C<first>, C<next>, C<prev>

=item lock

Turns off the ability of the widget to re-paint itself.  If the C<lock> method
was called more than once, then the C<unlock> method should be called as many
times to re-enable the painting.  Returns the boolean success flag.

See also: C<unlock>, C<repaint>, C<Paint>, C<get_locked>

=item map_color COLOR

Translated combinations of the C<cl::XXX> and C<ci::XXX> constants to a 24-bit
RGB integer color value. If the COLOR is already in the RGB format, returns the
same value.

See also: C<colorIndex>

=item mouse_click BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, NTH = 0, POST = 0

The method sends or posts ( POST flag ) the simulated C<MouseClick> event
to the system. BUTTON, MOD, X, Y, and NTH are the parameters
to be passed to the notification callbacks.

See also: C<MouseDown>, C<MouseUp>, C<MouseWheel>,
C<MouseMove>, C<MouseEnter>, C<MouseLeave>

=item mouse_down BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, POST = 0

The method sends or posts ( POST flag ) the simulated C<MouseDown> event to the
system. BUTTON, MOD, X, and Y are the parameters to be passed to the
notification callbacks.

See also: C<MouseUp>, C<MouseWheel>, C<MouseClick>,
C<MouseMove>, C<MouseEnter>, C<MouseLeave>

=item mouse_enter MOD = 0, X = 0, Y = 0, POST = 0

The method sends or posts ( POST flag ) the simulated C<MouseEnter> event to
the system. MOD, X, and Y are the parameters to be passed to the notification
callbacks.

See also: C<MouseDown>, C<MouseUp>, C<MouseWheel>, C<MouseClick>,
C<MouseMove>, C<MouseLeave>

=item mouse_event COMMAND = cm::MouseDown, BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, NTH = 0, POST = 0

The method sends or posts ( POST flag ) the simulated mouse event to the
system. BUTTON, MOD, X, Y, and NTH are the parameters to be passed to an
eventual mouse notification.  COMMAND is allowed to be one of the C<cm::MouseDown>,
C<cm::MouseUp>, C<cm::MouseWheel>, C<cm::MouseClick>, C<cm::MouseMove>,
C<cm::MouseEnter>, C<cm::MouseLeave> constants.

See also: C<mouse_down>, C<mouse_up>, C<mouse_wheel>, C<mouse_click>,
C<mouse_move>, C<mouse_enter>, C<mouse_leave>, C<MouseDown>, C<MouseUp>,
C<MouseWheel>, C<MouseClick>, C<MouseMove>, C<MouseEnter>, C<MouseLeave>

=item mouse_leave

The method sends or posts ( POST flag ) the simulated C<MouseLeave> event to
the system.

See also: C<MouseDown>, C<MouseUp>, C<MouseWheel>, C<MouseClick>, C<MouseMove>,
C<MouseEnter>, C<MouseLeave>

=item mouse_move MOD = 0, X = 0, Y = 0, POST = 0

The method sends or posts ( POST flag ) the simulated C<MouseMove> event to the
system. MOD, X, and Y are the parameters to be passed to the notification
callbacks.

See also: C<MouseDown>, C<MouseUp>, C<MouseWheel>, C<MouseClick>,
C<MouseEnter>, C<MouseLeave>

=item mouse_up BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, POST = 0

The method sends or posts ( POST flag ) the simulated C<MouseUp> event to the
system. BUTTON, MOD, X, and Y are the parameters to be passed to the
notification callbacks.

See also: C<MouseDown>, C<MouseWheel>, C<MouseClick>, C<MouseMove>,
C<MouseEnter>, C<MouseLeave>

=item mouse_wheel MOD = 0, X = 0, Y = 0, INCR = 0, POST = 0

The method sends or posts ( POST flag ) the simulated C<MouseUp> event to the
system. MOD, X, Y, and INCR are the parameters to be passed to the notification
callbacks.

See also: C<MouseDown>, C<MouseUp>, C<MouseClick>,
C<MouseMove>, C<MouseEnter>, C<MouseLeave>

=item next

Returns the neighbor sibling widget, next ( above ) in the Z-order.  If none is
found, undef is returned.

See also: C<first>, C<last>, C<prev>

=item next_tab FORWARD = 1

Returns the next widget in the list of the sibling widgets sorted by
C<::tabOrder>.  FORWARD is the boolean lookup direction flag.  If none is found,
the first ( or the last, depending on the FORWARD flag ) widget is returned. Only
widgets with the C<::tabStop> value set to 1 participate in the scanning.

Also used by the internal keyboard navigation code.

See also: C<next_positional>, C<tabOrder>, C<tabStop>, C<selectable>

=item next_positional DELTA_X DELTA_Y

Returns the sibling, the (grand-)child of a sibling, or the (grand-)child widget
that matched best the direction specified by the DELTA_X and DELTA_Y integers.
Only one of these parameters may be zero; another parameter must be either 1 or
-1.

Also used by the internal keyboard navigation code.

See also: C<next_tab>, C<origin>

=item pack, packForget, packSlaves

See L<Prima::Widget::pack>

=item place, placeForget, placeSlaves

See L<Prima::Widget::place>

=item prev

Returns the neighbor sibling widget, previous ( below ) in the Z-order.  If
none is found, undef is returned.

See also: C<first>, C<last>, C<next>

=item repaint

Marks the whole widget area as 'invalid', triggering the re-painting of the
widget. See L</"Graphic content">.

See also: C<validate_rect>, C<get_invalid_rect>, C<invalidate_rect>, C<Paint>,
C<update_view>, C<syncPaint>

=item rect_bevel $CANVAS, @RECT, %OPTIONS

Draws a rectangular area, similar to one produced by the C<rect3d> method, over
C<@RECT> which is a 4-integer tuple (X1,Y1,X2,Y2). Uses the values of the
widget's C<light3DColor> and C<dark3DColor> properties. The following options
are recognized:

=over

=item fill COLOR

If set, the area is filled with COLOR, otherwise is left intact.

=item width INTEGER

The width of the border in pixels

=item concave BOOLEAN

If 1, draws a concave area, or a bulged area otherwise

=back

=item responsive

Returns the boolean flag indicating whether the widget and its owners have all
the C<::enabled> property value set 1 or not. Useful for the fast check if the
widget should respond to the user's actions.

See also: C<enabled>

=item screen_to_client @OFFSETS

Maps array of X and Y integer offsets from screen to widget coordinates.
Returns the mapped OFFSETS.

See also: C<client_to_screen>

=item scroll DELTA_X DELTA_Y %OPTIONS

Scrolls the graphic context area by DELTA_X and DELTA_Y pixels.
The OPTIONS is a hash that may contain the following optional parameters:

=over

=item clipRect [X1, Y1, X2, Y2]

The clipping area is confined by the X1, Y1, X2, Y2 rectangle.
If not specified, the clipping area covers the whole widget.
Only the bits covered by the clipRect are affected.
The bits scrolled from the outside of the rectangle to the inside
are invalidated; the bits scrolled from the inside of the rectangle to
the outside are not invalidated.

=item confineRect [X1, Y1, X2, Y2]

The scrolling area is confined by the X1, Y1, X2, Y2 rectangle.
If not specified, the scrolling area covers the whole widget.

=item withChildren BOOLEAN

If 1, the scrolling affects the eventual children widgets so that they also
change their positions to DELTA_X and DELTA_Y.

=back

Returns one of the following constants:

	scr::Error           - failure
	scr::NoExpose        - call resulted in no new exposed areas
	scr::Expose          - call resulted in new exposed areas, expect a repaint

Cannot be used inside the paint state.

See also: C<Paint>, C<get_invalid_rect>

=item select

Alias for C<selected(1)> call

See also: C<deselect>, C<selected>, C<Enter>, C<Leave>

=item send_to_back

Sends the widget to the bottom of all other sibling widgets

See also: C<insert_behind>, C<bring_to_front>, C<ZOrderChanged>
,C<first>, C<next>, C<prev>, C<last>

=item show

Sets the widget's C<::visible> property to 1.

See also: C<hide>, C<visible>, C<Show>, C<Hide>, C<showing>, C<exposed>

=item show_cursor

Shows the cursor. If the C<hide_cursor()> method was called more than once then
the C<show_cursor> should also be called as many times to show the cursor back.

See also: C<hide_cursor>, C<cursorVisible>

=item showing

Returns the boolean value indicating whether the widget and its owners
have all C<::visible> property set to 1 or not.

=item unlock

Turns on the ability of a widget to re-paint itself.  As many times the
C<lock()> method was called, as many times its counterpart, the C<unlock()>
method must be called to enable re-painting again.  After the last C<unlock()> is
called an implicit C<repaint()> call is issued.  Returns the boolean success flag.

See also: C<lock>, C<repaint>, C<Paint>, C<get_locked>

=item update_view

If any parts of the widget were marked as 'invalid' by either the
C<invalidate_rect()>, C<scroll>, or C<repaint()> calls, or by the exposure caused
by the window movements, then the C<Paint> notification is immediately called.  If
no parts are invalid, no action is performed.  If the widget has the
C<::syncPaint> property set to 1 the C<update_view()> is always a no-op call.

See also: C<invalidate_rect>, C<get_invalid_rect>, C<repaint>, C<Paint>,
C<syncPaint>, C<update_view>

=item validate_rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET Y_TOP_OFFSET

Reverses the effect of C<invalidate_rect()>, restoring the original, 'valid'
state of the widget area covered by the rectangular area passed. If the widget with
previously invalid areas was wholly validated by this method, no C<Paint>
notifications occur.

See also: C<invalidate_rect>, C<get_invalid_rect>, C<repaint>, C<Paint>,
C<syncPaint>, C<update_view>

=back

=head2 Get-methods

=over

=item get_default_font

Returns the default font for the Prima::Widget class.

See also: C<font>

=item get_default_popup_font

Returns the default font for the Prima::Popup class.

See also: C<font>

=item get_invalid_rect

Returns the rectangle encompassing the actual invalid region on the widget. If
the widget doesn't need to be repainted, the (0,0,0,0) tuple is returned.

See also: C<validate_rect>, C<invalidate_rect>, C<repaint>, C<Paint>,
C<syncPaint>, C<update_view>

=item get_handle

Returns the system handle for the widget

See also: C<get_parent_handle>, C<Window::get_client_handle>

=item get_locked

Returns 1 if the C<lock()> was called and all repaints are effectively blocked.

See also: C<lock>, C<unlock>

=item get_mouse_state

Returns a combination of the C<mb::XXX> constants that reflects the currently
pressed mouse buttons.

See also: C<pointerPos>, C<get_shift_state>

=item get_parent

Returns the widget that the caller widget boundaries get clipped to, or the
application object if the caller widget is top-level or has the clipOwner
property set to 1.

See also: C<clipOwner>

=item get_parent_handle

Returns the system handle for the parent of the widget, the window that belongs
to another program. Returns 0 if the widget's owner and parent are in the same
application and process space.

See also: C<get_handle>, C<clipOwner>

=item get_pointer_size

Returns two integers, the width and height of the icon, that the system accepts as
valid for the mouse pointer.  If the sizes of the icon exceed or are inferior
to the size the icon is then truncated or padded with transparency bits ( but
not stretched ).  Can be called with the class syntax as it returns the
system-wide value.

=item get_shift_state

Returns a combination of the C<km::XXX> constants that reflects the currently
pressed keyboard modifier buttons.

See also: C<get_shift_state>

=item get_virtual_size

Returns the virtual width and height of the widget.
See L</"Geometry">, Implicit size regulations.

See also: C<width>, C<height>, C<size>
C<growMode>, C<Move>, C<Size>, C<sizeMax>, C<sizeMin>

=item get_widgets

Returns the list of the children widgets.

=back

=head2 Events

=over

=item Change

A generic notification, is used for the Prima::Widget's descendants; the
Prima::Widget class itself neither calls nor uses the event.  Designed to be
called when an arbitrary major state of the widget is changed.

=item Click

A generic notification, is used for the Prima::Widget's descendants; Prima::Widget
itself neither calls nor uses the event.  Designed to be called when an
arbitrary major action for the widget is called.

=item Close

Triggered by the C<can_close()> and C<close()> functions.  If the event flag is
cleared during execution, these functions return the false value.

See also: C<close>, C<can_close>

=item ColorChanged INDEX

Called when one of the widget's color properties is changed, either by a direct
property change or by the system. INDEX is one of the C<ci::XXX> constants.

See also: C<colorIndex>

=item Disable

Triggered by a successful C<enabled(0)> call

See also: C<Enable>, C<enabled>, C<responsive>

=item DragBegin CLIPBOARD, ACTION, MOD, X, Y, COUNTERPART

Triggered on the receiver widget when the mouse pointer with a DND object
enters its screen boundaries.  C<CLIPBOARD> contains the DND data, 
C<ACTION> is a combination of the C<dnd::> constants that reflect the actions
the sender is ready to offer, C<MOD> is a combination of the modifier keys
(C<kb::>), and C<X> and C<Y> are the coordinates where the mouse pointer has
entered the widget. This event and the following C<DragOver> and C<DragEnd>
events occur only if the property C<dndAware> is set either to 1 or if
it matches the clipboard format that exists in the C<CLIPBOARD>.

C<COUNTERPART> is set to the Prima DND sender widget if the session was
initiated within the same program; is undef otherwise. 

See also: L</Drag and Drop>, C<DragOver>, C<DragEnd>

=item DragEnd CLIPBOARD, ACTION, MOD, X, Y, COUNTERPART, ANSWER

Triggered on the receiver widget when the user either drops or cancels the DND
session. In case of the canceled drop, C<CLIPBOARD> is set to C<undef> and
C<ACTION> to the C<dnd::None> constant. On a successful drop, the input data are
the same as in C<DragBegin> while the output data are expected to be stored in
the hashref C<ANSWER>, if any.  The following answers can be stored:

=over

=item allow BOOLEAN

Is pre-set to 1. If changed to 0, a signal will be sent to the sender that the drop
request is not accepted.

=item action INTEGER

A C<dnd::> constant (not a combination) to be returned to the sender with the action
the receiver has accepted, if any.

=back

C<COUNTERPART> is set to the Prima DND sender widget if the session was
initiated within the same program; is undef otherwise. 

See also: L</Drag and Drop>, C<DragBegin>, C<DragOver>

=item DragOver CLIPBOARD, ACTION, MOD, X, Y, COUNTERPART, ANSWER

Triggered on the received widget during the DND session.  The event is sent
repeatedly while the user drags the mouse pointer over the widget. The input
data are same as in C<DragBegin>, and output data are to be stored in hashref
C<ANSWER>, if any. The following answers can be stored:

=over

=item allow BOOLEAN

Is pre-set to 1. If the event handler changes it to 0, a response will be sent
to the sender that a drop action cannot happen with the input or location
provided.

=item action INTEGER

A C<dnd::> constant (not a combination) to be returned to the sender with the action
the receiver is ready to accept, if any.

=item pad X, Y, WIDTH, HEIGHT

If set, instructs the sender not to repeat C<DragOver> events that contain
the same input data, while the mouse pointer is within these geometrical limits.

=back

C<COUNTERPART> is the Prima DND sender widget, if the session is initiated
within the same program.

=item DragQuery MOD, COUNTERPART, ANSWER

Triggered on a sender DND widget when there was detected a change in the mouse
or modifier buttons, or the user pressed the C<Escape> key to cancel the DND
session.  The combination of the mouse and modifier buttons is stored in the
C<MOD> integer parameter.  The C<km::Escape> bit is set if the C<Escape> key
is pressed.

It is up to the event handler to decide whether to continue the drag session or
not.  If it is decided not to continue, the C<< $ANSWER->{allow} >> flag must
be set to 0.

Additionally, the C<< $ANSWER->{action} >> flag can be assigned a single
C<dnd::> constant to counter-propose the action to the sender. The proposal
will be typically based on the C<MOD> value, f.ex.  C<dnd::Move> if the CTRL
key was pressed.

Note: This action will only forward the change to the receiver on X11, but
it is advised to implement it anyway for the sake of portability.

C<COUNTERPART> is the Prima DND receiver widget, if the session is initiated
within the same program.

See also: L</Drag and Drop>, C<DragResponse>

=item DragResponse ALLOW, ACTION, COUNTERPART

Triggered on the sender DND widget when there was detected a change in the
mouse or modifier buttons, or when the mouse was moved from one DND target to
another.  The sender event handler is then presented with the new input,
collected from the interaction with the new target. There, the C<ALLOW> integer
parameter is set to a boolean value that shows whether the sender is allowed to
drop data or not. The C<ACTION> is the C<dnd::> constant with the action the
receiver has earlier agreed to accept, if any.

If the DND session was started without the option to update mouse pointers on
this event, the event handler should update the pointer itself. It is not
needed though to save and restore the mouse pointers before and after the DND
session, the C<begin_drag> method manages this.

C<COUNTERPART> is the Prima DND receiver widget, if the session is initiated
within the same program.

See also: L</Drag and Drop>, C<dnd_start>, C<begin_drag>.

=item Enable

Triggered by a successful C<enabled(1)> call

See also: C<Disable>, C<enabled>, C<responsive>

=item Enter

Called when the widget receives the input focus.

See also: C<Leave>, C<focused>, C<selected>

=item FontChanged

Called when the widget font is changed either by the direct property change
call or by the system.

See also: C<font>, C<ColorChanged>

=item Hide

Triggered by a successful C<visible(0)> call

See also: C<Show>, C<visible>, C<showing>, C<exposed>

=item Hint SHOW_FLAG

Called when the hint label is about to show or hide, depending on the SHOW_FLAG
parameter. The show or hide action is not executed if the event flag is cleared
in the event handler.

See also: C<showHint>, C<ownerShowHint>, C<hintVisible>, C<ownerHint>

=item KeyDown CODE, KEY, MOD, REPEAT

Sent to the focused widget when the user presses a key.  CODE contains an
eventual character code, KEY is one of the C<kb::XXX> constants, and MOD is a
combination of the modifier keys pressed when the event occurred ( the
C<km::XXX> constants ). REPEAT is an integer with the number of how many times
the key was pressed; usually, it is 1.  ( see C<::briefKeys> ).

The valid C<km::> constants are:

   km::Shift
   km::Ctrl
   km::Alt
   km::KeyPad
   km::DeadKey
   km::Unicode

The valid C<kb::> constants are grouped in several sets.  Some codes are
aliased, for example, C<kb::PgDn> and C<kb::PageDown> have the same value.

=over

=item Modifier keys

   kb::ShiftL   kb::ShiftR   kb::CtrlL      kb::CtrlR
   kb::AltL     kb::AltR     kb::MetaL      kb::MetaR
   kb::SuperL   kb::SuperR   kb::HyperL     kb::HyperR
   kb::CapsLock kb::NumLock  kb::ScrollLock kb::ShiftLock

=item Keys with character code defined

   kb::Backspace  kb::Tab    kb::Linefeed   kb::Enter
   kb::Return     kb::Escape kb::Esc        kb::Space


=item Function keys

   kb::F1 .. kb::F30
   kb::L1 .. kb::L10
   kb::R1 .. kb::R10

=item Other

   kb::Clear    kb::Pause   kb::SysRq  kb::SysReq
   kb::Delete   kb::Home    kb::Left   kb::Up
   kb::Right    kb::Down    kb::PgUp   kb::Prior
   kb::PageUp   kb::PgDn    kb::Next   kb::PageDown
   kb::End      kb::Begin   kb::Select kb::Print
   kb::PrintScr kb::Execute kb::Insert kb::Undo
   kb::Redo     kb::Menu    kb::Find   kb::Cancel
   kb::Help     kb::Break   kb::BackTab

=back

See also: C<KeyUp>, C<briefKeys>, C<key_down>, C<help>, C<popup>,
C<tabOrder>, C<tabStop>, C<accelTable>

=item KeyUp CODE, KEY, MOD

Sent to the focused widget when the user releases a key.  CODE contains an
eventual character code, KEY is one of the C<kb::XXX> constants, and MOD is a
combination of the modifier keys pressed when the event occurred ( C<km::XXX>).

See also: C<KeyDown>, C<key_up>

=item Leave

Called when the input focus is removed from the widget

See also: C<Enter>, C<focused>, C<selected>

=item Menu MENU VAR_NAME

Called before the user-navigated menu ( pop-up or pull-down ) is about to show
another level of submenu on the screen. MENU is a Prima::AbstractMenu
descendant, that is also a direct child to the widget. VAR_NAME is the name of
the menu item that is about to be shown.

Can be used for making dynamic changes in the menu structures, f.ex. enabling
or disabling clipboard commands if there is data in the clipboard that can be
pasted.

See also: C<popupItems>

=item MouseClick BUTTON, MOD, X, Y, NTH

Called when the mouse click ( a button is pressed, then released, within the
system-defined interval of time ) occurs in the widget area. BUTTON is one
of the C<mb::XXX> constants, MOD is a combination of the C<km::XXX> constants
that reflects the pressed modifier keys during the event, and X and Y are the mouse
pointer coordinates. NTH is an integer, set to 0 if it was a single click, and
to 2 and up if it was a double (triple, etc etc) click.

C<mb::XXX> constants are:

   mb::b1 or mb::Left
   mb::b2 or mb::Middle
   mb::b3 or mb::Right
   mb::b4
   mb::b5
   mb::b6
   mb::b7
   mb::b8

See also: C<MouseDown>, C<MouseUp>, C<MouseWheel>, C<MouseMove>, C<MouseEnter>,
C<MouseLeave>

=item MouseDown BUTTON, MOD, X, Y

Occurs when the user presses a mouse button on the widget.  BUTTON is one of
the C<mb::XXX> constants, MOD is a combination of the C<km::XXX> constants that
reflects the pressed modifier keys during the event, and X and Y are the mouse
pointer coordinates.

See also: C<MouseUp>, C<MouseClick>, C<MouseWheel>, C<MouseMove>,
C<MouseEnter>, C<MouseLeave>

=item MouseEnter MOD, X, Y

Occurs when the mouse pointer enters the area occupied by the widget.  MOD is a
combination of the C<km::XXX> constants that reflects the pressed modifier keys
during the event, and X and Y are the mouse pointer coordinates.

See also: C<MouseDown>, C<MouseUp>, C<MouseClick>, C<MouseWheel>, C<MouseMove>,
C<MouseLeave>

=item MouseLeave

Occurs when the mouse pointer leaves the area occupied by the widget.

See also: C<MouseDown>, C<MouseUp>, C<MouseClick>, C<MouseWheel>, C<MouseMove>,
C<MouseEnter>

=item MouseMove MOD, X, Y

Occurs when the mouse pointer moves over the widget.  MOD is a combination of
the C<km::XXX> constants that reflects the pressed modifier keys during the event,
and X and Y are the mouse pointer coordinates.

See also: C<MouseDown>, C<MouseUp>, C<MouseClick>, C<MouseWheel>,
C<MouseEnter>, C<MouseLeave>

=item MouseUp BUTTON, MOD, X, Y

Occurs when the user depresses a mouse button on the widget.  BUTTON is one of
the C<mb::XXX> constants, MOD is a combination of the C<km::XXX> constants that
reflects the pressed modifier keys during the event, X and Y are the mouse
pointer coordinates.

See also: C<MouseDown>, C<MouseClick>, C<MouseWheel>,
C<MouseMove>, C<MouseEnter>, C<MouseLeave>

=item MouseWheel MOD, X, Y, INCR

Occurs when the user rotates the mouse wheel on the widget.  MOD is a
combination of the C<km::XXX> constants that reflects the pressed modifier keys
during the event, INCR is the wheel movement, scaled by 120.  +120 is a step
upwards, and -120 is a step downwards.  Many of the consumer mice report the
wheel moves with a resolution of 120, the gamer mice may report a better
resolution.  An event handler should treat the scroll values as INCR/120 per
unit, for whatever the unit of movement might be, for example as lines of text,
slider ticks, etc.

The event handle may use different units if some MOD keys are pressed.  For
example, the C<Prima::SpinEdit> class has two different C<step> and C<pageStep>
properties, and it uses the value of the C<pageStep> property when the CTRL key
is pressed and the value of the C<step> property otherwise (see
L<Prima::Sliders> ).

See also: C<MouseDown>, C<MouseUp>, C<MouseClick>,
C<MouseMove>, C<MouseEnter>, C<MouseLeave>

=item Move OLD_X, OLD_Y, NEW_X, NEW_Y

Triggered when the widget changes its position relative to its parent, either
by one of the Prima::Widget methods or by the user.  OLD_X and OLD_Y are the old
coordinates of the widget, NEW_X and NEW_Y are the new ones.

See also: C<Size>, C<origin>, C<growMode>, C<centered>, C<clipOwner>

=item Paint CANVAS

Caused when the system calls for the refresh of the widget's graphic content.
CANVAS is the widget itself, use it to draw on ( see L<"Graphic content"> ).

See also: C<repaint>, C<syncPaint>, C<get_invalid_rect>, C<scroll>,
C<colorIndex>, C<font>

=item Popup BY_MOUSE, X, Y

Called by the system when the user presses the key or the mouse combination
defined for the execution of a context the pop-up menu.  By default executes the
associated Prima::Popup object if it is present. If the event flag is cleared
in the event handler then pop-up menu request is denied and the popup is not
shown.

See also: C<popup>

=item Setup

This message is posted right after the C<Create> notification and is delivered
to widgets from inside the event loop. Prima::Widget does not use it for
anything.

=item Show

Triggered by a successful C<visible(1)> call

See also: C<Show>, C<visible>, C<showing>, C<exposed>

=item Size OLD_WIDTH, OLD_HEIGHT, NEW_WIDTH, NEW_HEIGHT

Triggered when the widget changes its size, either by Prima::Widget methods or by
the user.  OLD_WIDTH and OLD_HEIGHT are the old sizes of the widget, and NEW_WIDTH
and NEW_HEIGHT are the new ones.

See also: C<Move>, C<origin>, C<size>, C<growMode>, C<sizeMax>, C<sizeMin>,
C<rect>, C<clipOwner>

=item SysHandle

Same as in C<Component> except that the following C<Widget> properties can also
trigger it:

L</clipOwner>, L</syncPaint>, L</layered>, L</transparent>

Handling of this event is generally needed only if the program relies on the
widget's system handle that is returned by the C<get_handle> method.

=item TranslateAccel CODE, KEY, MOD

A distributed version of the C<KeyDown> event. The event traverses all of the object
tree that the widget that received the original C<KeyDown> event
belongs to. Once the event flag is cleared, the iteration stops.

Used by the widgets that need to react to the keyboard input even if not
focused.

See also: C<KeyDown>

=item ZOrderChanged

Triggered when the widget's stacking order ( Z-order ) is changed either by one
of the Prima::Widget methods or by the user.

See also: C<bring_to_front>, C<insert_behind>, C<send_to_back>

=back

=head1 AUTHOR

Dmitry Karasik, E<lt>dmitry@karasik.eu.orgE<gt>.

=head1 SEE ALSO

L<Prima>, L<Prima::Object>, L<Prima::Drawable>.
