Prima

 view release on metacpan or  search on metacpan

pod/Prima/Widget.pod  view on Meta::CPAN

C<::hiliteColor>, C<::hiliteBackColor>, C<::light3DColor>, and
C<::dark3DColor>.  The 'disabled' color pair contains the values
that are expected to be used as foreground and background when
a widget is in the disabled state
( see API, C<::enabled> property ). The 'hilite' values
serve as the colors for representation of selection inside
a 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. Examples are selections
in the text widgets, or in the list boxes. The last pair,
C<::light3DColor> and C<::dark3DColor> is used for drawing
3D-looking outlines of a widget. The purpose of all these properties
is the adequate usage of the color settings, selected by the user using
system-specific tools, so the program written with the toolkit
would look not such different, and more or less conforming to the
user's color preferences.

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

Mapping from these constants to the RGB color representation
is used with C<map_color()> method. These C<cl::> constants alone
are sufficient for acquiring the default values, but the toolkit provides wider
functionality than this. The C<cl::> constants can be combined with
the C<wc::> constants, that represent standard widget class.
The widget class is implicitly used when single C<cl::> constant is used;
its value is read from the C<::widgetClass> property, unless
one of C<wc::> constants is combined with the non-RGB C<cl::> value. C<wc::>
constants are described in L</"API">; their usage can make
call of, for example, C<backColor( cl::Back)> on a button and on
an input line result in different colors, because the C<cl::Back>
is translated in the first case into C<cl::Back|wc::Button>, and
in another - C<cl::Back|wc::InputLine>.

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

=head1 Fonts

Prima::Widget does not change the handling of fonts - the
font selection inside and outside C<begin_paint()>/C<end_paint()>
is not different at all. A matter of difference is how
does Prima::Widget select the default font.

First, if the C<::ownerFont> property is set to 1,
then font of the owner is copied to the widget, and
is maintained all the time while the property is true.
If it is not, the default font values read from the system.

The default font metrics for a widget returned by C<get_default_font()>
method, that often deals with system-dependent and user-selected
preferences ( see L</"Additional resources"> ). Because a widget can host
an eventual Prima::Popup object, it contains
C<get_default_popup_font()> method, that returns the default font
for the popup objects. The dynamic popup font settings governed,
naturally, by the C<::popupFont> property. Prima::Window extends the
functionality to C<get_default_menu_font()> and the C<::menuFont> property.

Dynamic change of the font property results in the
C<FontChanged> notification.

=head1 Additional resources

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

=head2 Markup text

C<Prima::Drawable::Markup> provides text-like objects that can include font and
color change, and has a primitive image support. Since text methods of
C<Prima::Drawable> such as C<text_out>, C<get_text_width> etc can detect if a
text passed is actually a blessed object, and make a corresponding call on it,
the markup objects can be used transparently when rich text is needed, simply by
passing them to C<text> and 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 results of both 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 drawing methods on them.

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

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

treating a scalar reference to a text string as a sign that this is actually
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, set the
pointer icon to a jagged vertical line, or indicate a moving window
with a cross-arrow pointer.

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

NB: Not all systems allow the colored pointer icons. System value
under sv::ColorPointer index containing 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 reduced to the system limits.

In general, the C<::pointer> property is enough for these actions.
It discerns whether it has an icon or a constant passed, and
sets the appropriate 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 their
details in the L</"API"> sections.

Another property, which is present only in Prima::Application name space
is called C<::pointerVisible>, and governs the visibility of the pointer -
but for all widget instances at once.

=head2 Cursor

The cursor is a blinking rectangular area, indicating the
availability of the input focus in a widget. There can
be only one active cursor per a GUI
space, or none at all. Prima::Widget provides several
cursor properties: C<::cursorVisible>, C<::cursorPos>, and
C<::cursorSize>. There are also two methods, C<show_cursor()>
and C<hide_cursor()>, which are not the convenience shortcuts
but the functions accounting the cursor hide count. If C<hide_cursor()>
was called three times, then C<show_cursor()> must be called three times
as well for the cursor to become visible.

=head2 Hint

C<::hint> is a text string, that usually describes the widget's purpose
to the user in a brief manner. If the mouse pointer is hovered over the
widget longer than some timeout ( see Prima::Application::hintPause ),
then a label appears with the hint text, until the pointer is drawn away.
The hint behavior is governed by Prima::Application, but a widget
can do two additional things about hint: it can enable and disable
it by calling C<::showHint> property, and it can inherit the owner's
C<::hint> and C<::showHint> properties using C<::ownerHint>
and C<::ownerShowHint> properties. If, for example, C<::ownerHint>
is set to 1, then 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

The default functionality of Prima::Widget coexists with two kinds of the Prima::AbstractMenu
descendants - Prima::AccelTable and Prima::Popup ( Prima::Window
is also equipped with Prima::Menu reference). The C<::items> property of these objects
are accessible through C<::accelItems> and C<::popupItems>, whereas
the objects themselves - through C<::accelTable> and C<::popup>,
correspondingly. As mentioned in L</"User input">,
these objects hook the user keyboard input and call the programmer-defined
callback subroutine if the key stroke
equals to one of their table values. As for C<::accelTable>, its
function ends here. C<::popup> provides access to a context pop-up menu,
which can be invoked by either right-clicking or pressing a
system-dependent key combination. As a little customization,
the C<::popupColorIndex> and C<::popupFont> properties are introduced.
( C<::popupColorIndex> is multiplexed to C<::popupColor>,
C<::popupHiliteColor>, C<::popupHiliteBackColor>, etc etc
properties exactly like the C<::colorIndex> property ).

The font and color of a menu object might not always be writable (Win32).

The Prima::Window class provides equivalent methods for the menu bar, introducing
C<::menu>, C<::menuItems>, C<::menuColorIndex> ( with multiplexing ) and
C<::menuFont> properties.

=head2 User-specified resources

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

Unix version employs XRDB ( X resource database ), which is the
natural 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 a 'least common denominator', which is
colors and fonts. C<fetch_resource()> method is capable of returning
any of such settings, provided it's format is font, color or a string.
The method is rarely called directly.

The 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 C<fetch_resource()>
existing functionality, but it is believed that calling up the method
for the every property for the every widget created 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 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>

pod/Prima/Widget.pod  view on Meta::CPAN

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 a pointer icon, associated
with a widget.

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

=item pointerIcon ICON

Specifies the pointer icon, associated with a widget.

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

=item pointerPos X_OFFSET Y_OFFSET

Specifies the mouse pointer coordinates relative to 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.
TYPE can accept one constant of C<cr::XXX> set:

   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::User                    user-defined icon

All constants except C<cr::User> and C<cr::Default> present a system-defined
pointers, their icons and hot spot offsets. C<cr::User> is a sign that
an icon object was specified explicitly via C<::pointerIcon> property.
C<cr::Default> is a way to tell that a widget inherits its owner pointer type,
no matter 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 a widget.
The purpose of the popup object is to show a context menu
when the user right-clicks or selects the corresponding keyboard
combination. Prima::Widget can host many children objects,
Prima::Popup as well. But only the one that is set in
C<::popup> property will be activated automatically.

The popup object can be destroyed safely; its cancellation
can be done either via C<popup(undef)> or 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 a pop-up context menu,
associated with a widget. INDEX must be one of C<ci::XXX> constants
( see C<::colorIndex> property ).

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

=item popupColor COLOR

Basic foreground in a popup context menu color.

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

=item popupBackColor COLOR

Basic background in a popup context menu color.

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

=item popupDark3DColor COLOR

Color for drawing dark shadings in a popup context menu.

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

=item popupDisabledColor COLOR

Foreground color for disabled items in a popup context menu.

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

=item popupDisabledBackColor COLOR

Background color for disabled items in a popup context menu.

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

=item popupFont %FONT

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

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

=item popupHiliteColor COLOR

Foreground color for selected items in a popup context menu.

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

=item popupHiliteBackColor COLOR

Background color for selected items in a popup context menu.

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

=item popupItems [ ITEM_LIST ]

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

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

=item popupLight3DColor COLOR

Color for drawing light shadings in a 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 a widget relative
to its owner ( or to the screen if C<::clipOwner> is set to 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 a widget. If changed,
does not affect the widget width; but does so, if called
in C<set()> together with C<::left>.

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

=item scaleChildren BOOLEAN

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

Default is 1.

See also: C<designScale>

=item selectable BOOLEAN

If 1, a widget can be granted focus implicitly, or by means of
the user actions. C<select()> regards this property, and does not
focus a widget that has C<::selectable> set to 0.

Default value is 0

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

=item selected BOOLEAN

If called in get-mode, returns whether a widget or
one of its (grand-) children is focused. If in set-mode,
either simply turns the system with no-focus state ( if 0 ),
or sends input focus to itself or one of the widgets tracked down by
C<::currentWidget> chain.

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

=item selectedWidget OBJECT

Points to a child widget, that has property C<::selected> set to 1.

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

=item selectingButtons FLAGS

FLAGS is a combination of C<mb::XXX> ( mouse button ) flags.

pod/Prima/Widget.pod  view on Meta::CPAN

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

=item show_cursor

Shows the cursor. As many times C<hide_cursor()> was called,
as many time its counterpart C<show_cursor()> must be called
to reach the cursor's initial state.

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

=item showing

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

=item unlock

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

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

=item update_view

If any parts of a widget were marked as 'invalid' by
either C<invalidate_rect()> or C<repaint()> calls or the
exposure caused by window movements ( or any other),
then C<Paint> notification is immediately called.
If no parts are invalid, no action is performed.
If a widget has C<::syncPaint> set to 1,
C<update_view()> is always a no-operation 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 widget area covered by the rectangular area passed. If a 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 a Prima::Widget class.

See also: C<font>

=item get_default_popup_font

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

See also: C<font>

=item get_invalid_rect

Returns the result of successive calls C<invalidate_rect()>,
C<validate_rect()> and C<repaint()>, as a rectangular area
( four integers ) that cover all invalid regions in a widget.
If none found, (0,0,0,0) is returned.

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

=item get_handle

Returns a system handle for a widget

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

=item get_locked

Returns 1 if a widget is in C<lock()> - initiated repaint-blocked state.

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

=item get_mouse_state

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

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

=item get_parent

Returns the owner widget that clips the widget boundaries, or application
object if a widget is top-level.

See also: C<clipOwner>

=item get_parent_handle

Returns a system handle for a parent of a widget, a 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, width and height of a icon,
that the system accepts as valid for a pointer.
If the icon is supplied that is more or less than these values,
it is truncated or padded with transparency bits, but is not stretched.
Can be called with class syntax.

=item get_shift_state

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

pod/Prima/Widget.pod  view on Meta::CPAN

depending on SHOW_FLAG. The hint show or hide action
fails, if the event flag is cleared during execution.

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 C<kb::XXX>
constants, MOD is a combination of the modifier keys
pressed when the event occurred ( C<km::XXX> ). REPEAT
is 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, like, C<kb::PgDn> and C<kb::PageDown>.

=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 C<kb::XXX>
constants, 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 a 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 Prima::AbstractMenu
descendant, that children to a widget, and VAR_NAME
is the name of the menu item that is about to be shown.

Used for making changes in the menu structures dynamically.

See also: C<popupItems>

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

Called when a mouse click ( button is pressed, and then
released within system-defined interval of time ) is
happened in the widget area. BUTTON is one of C<mb::XXX>
constants, MOD is a combination of C<km::XXX> constants,
reflecting pressed modifier keys during the event,
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 mouse button on a widget.
BUTTON is one of C<mb::XXX> constants, MOD is a combination of
C<km::XXX> constants, reflecting the pressed modifier keys during the event,
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 is entered the area occupied by a widget
( without mouse button pressed ).
MOD is a combination of  C<km::XXX> constants, reflecting
the pressed modifier keys during the event,
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 is driven off the area
occupied by a widget ( without mouse button pressed ).

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

=item MouseMove MOD, X, Y

Occurs when the mouse pointer is transported over a widget.
MOD is a combination of  C<km::XXX> constants, reflecting
the pressed modifier keys during the event,
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 mouse button on a widget.
BUTTON is one of C<mb::XXX> constants, MOD is a combination of
C<km::XXX> constants, reflecting 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 mouse wheel on a widget.  MOD is a combination of
C<km::XXX> constants, reflecting the pressed modifier keys during the event,
INCR is the wheel movement, scaled by 120.  +120 is a step upwards, or -120
downwards.  For wheels which are discrete button clicks INCR is +/-120 but
other devices may give other amounts.  A widget should scroll by INCR/120 many
units, or partial unit, for whatever its unit of movement might be, such as
lines of text, slider ticks, etc.

A widget might like to vary its unit move according to the MOD keys.  For
example C<Prima::SpinEdit> has a C<step> and C<pageStep> and moves by
C<pageStep> when C<km::Ctrl> is held down (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 widget changes its position relative to
its parent, either by Prima::Widget methods or by the user.
OLD_X and OLD_Y are the old coordinates of
a 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 a graphic
context, associated with a widget. CANVAS is the widget itself,
however its usage instead of widget is recommended ( 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 a key or mouse
combination defined for a context pop-up menu execution.
By default executes the associated Prima::Popup object,
if it is present. If the event flag is cleared during the
execution of callbacks, the pop-up menu is not shown.

See also: C<popup>

=item Setup

This message is posted right after C<Create> notification,
and comes first from the event loop. Prima::Widget does not
use it.

=item Show

Triggered by a successive 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 widget changes its size,
either by Prima::Widget methods or by the user.
OLD_WIDTH and OLD_HEIGHT are the old extensions of
a widget, 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>, but introduces the following C<Widget> properties can trigger it:

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

This event will be only needed when the system handle (that can be acquired by
C<get_handle> ) is needed.

=item TranslateAccel CODE, KEY, MOD

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

Used for tracking keyboard events by out-of-focus widgets.

See also: C<KeyDown>

=item ZOrderChanged

Triggered when a widget changes its stacking order, or Z-order
among its siblings, either by 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>.