Prima

 view release on metacpan or  search on metacpan

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

=back

=head2 Mouse

=over

=item Event-driven

Mouse notifications are send in response when the user
moves the mouse, or presses and releases mouse buttons.
The notifications are logically grouped in two sets, the first contains
C<MouseDown>, C<MouseUp>, C<MouseClick>, and C<MouseWheel>, and the second -
C<MouseMove>, C<MouseEnter>, end C<MouseLeave>.

The first set deals with button actions. Pressing, de-pressing, clicking
( and double-clicking ), the turn of mouse wheel correspond to the four
notifications. The notifications are sent together with the mouse pointer coordinates,
the button that was touched, and the eventual modifier keys that were pressed.
In addition, C<MouseClick> provides the boolean flag if the click was single or double,
and C<MouseWheel> the wheel turn amount. These notifications occur
when the mouse event occurs within the geometrical bounds of a widget,
with one notable exception, when a widget is in I<capture> mode.
If the C<::capture> is set to 1, then these events are sent to the widget even
if the mouse pointer is outside, and not sent to the widgets and windows
that reside under the pointer.

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

=item Polling

The mouse input polling procedures are C<get_mouse_state()> method,
that returns combination of C<mb::XXX> constants, and the C<::pointerPos>
two-integer property that reports the current position of the mouse pointer.

=item Simulated input

There are five methods, corresponding to the mouse events -
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 C<mouse_event()>
method, which is never used directly.

=back

=head2 Drag and drop

Widgets can participate in full drag and drop sessions with other applications
and itself, 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 point
whenever data is to be either sent or received. In order to either offer to, or
choose from, many formats of another DND client, use that clipboard to operate
with standard open/fetch/store/close methods (see more at L<Prima::Clipboard>).

The clipboard can be accessed at any time by calling C< $::application->
get_dnd_clipboard >, however during handling of dropping events it will stay
read-only.

To successfully exchange data with other applications, one may investigate
results of C<< $clipboard-> get_formats(1) >> to see what types of data the
selected application can exchange. With a high probability many programs can
exchange text and image in a system-dependent format, however it is also common
to see applications to exchange data in format names that match their MIME
description. For example Prima supports image formats like C<image/bmp> out of
the box, and C<text/plain> on X11, that 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;
one needs to register that format first using C<Clipboard::register_format>,
once, and then it is ready for exchange.

=item Dragging

To initiate the drag, first fill the DND clipboard with data to be exchanged,
using one or more formats, then call either L</start_dnd>. Alternatively, call
L</begin_drag>, a wrapper method that can set up clipboard data itself. See
their documentation for more details.

During the dragging, the sender will receive L</DragQuery> and L</DragResponse> events,
in order to decide whether the drag session must continue or stop depending on
the user input, and reflect that back to the user. Traditionally, mouse cursors
are changed to show whether an application will receive a drop, and if yes,
what action (copy, move, or link) it will participate in. Prima will try its best
to either use system cursors, or synthesize ones that are informative enough;
if that is not sufficient, one may present own cursor 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 all formats, or to a string, in which case
drop events will only be delivered if the DND clipboard contains a format with
that string.

Thereafter, when the user will initiate a DND session and will move mouse
pointer over the widget, it will receive a L</DragBegin> event, then series of
L</DragOver> events, and finally a L</DragEnd> event with a flag telling whether
the user chose to drop the data or cancel the session.

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

=item Portability

X11 and Win32 are rather identical in how they are handing a DND session from
the user's perspective. The only difference that is significant to Prima here
is whether the sender or the receiver is responsible to select an action for
available list of actions, when the user presses 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 modifier keys pressed by the user; Windows
recommends to adhere to the standard scheme where CTRL mark C<dnd::Move> action,
and SHIFT the C<dnd::Link>, but that is up to the receiver. 

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

Additionally, a X11 non-Prima receiver, when presented with a multiple choice
of actions, may ask the user what action to select, or cancel the session
altogether. This is okay and is expected by the user.

=back

=head1 Color schemes

Prima::Drawable deals only with such color values, that
can be unambiguously decomposed to their red, green and blue components.
Prima::Widget extends the range of the values acceptable by
its color properties, introducing the color schemes.
The color can be set indirectly, without prior knowledge
of what is its RGB value. There are several
constants defined in C<cl::> name space, that correspond to the
default values of different color properties of a widget.

Prima::Widget revises the usage of C<::color> and C<::backColor>,
the properties inherited from Prima::Drawable. Their values
are widget's 'foreground' and 'background' colors,
in addition to their function as template values. Moreover, their dynamic change
induces the repainting of a widget, and they can be inherited

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

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

=item currentWidget OBJECT

Points to a children widget, that is to
be focused ( or selected) when the owner widget receives 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 cursor visibility flag. 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 a font, that was used when
a 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 used to substitute C<::backColor> when a widget
is in its disabled state.

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

=item disabledColor COLOR

The color used to substitute C<::color> when a widget
is in its disabled state.

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

=item dndAware 0 | 1 | FORMAT

To register a 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 string, in which case
drop events will only be delivered if the DND clipboard contains a format with
that string.

Default: 0

See also: C<Drag and Drop>

=item enabled BOOLEAN

Specifies if a widget can accept focus, keyboard and mouse events.
Default value is 1, however, being 'enabled' does not automatically
allow the widget 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 font context. Same syntax as in Prima::Drawable.
If 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 widget 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      widget's left side is kept in constant
                  distance from owner's right side
 gm::GrowLoY      widget's bottom side is kept in constant
                  distance from owner's top side
 gm::GrowHiX      widget's right side is kept in constant
                  distance from owner's right side
 gm::GrowHiY      widget's top side is kept in constant
                  distance from owner's top side
 gm::XCenter      widget is kept in center on its owner's
                  horizontal axis
 gm::YCenter      widget is kept in center on its owner's
                  vertical axis
 gm::DontCare     widgets origin is maintained constant relative
                  to the screen

=item Derived or aliased constants

 gm::GrowAll      gm::GrowLoX|gm::GrowLoY|gm::GrowHiX|gm::GrowHiY

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

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, widget is centered by 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, widget is centered by 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 C<dnd_start> that takes care of some DND session aspects other
than the default system's. All input is contained in C<%OPTIONS> hash, except
for the case of a single-parameter call, in which case it is equivalent to C<<
text => DATA >> when C<DATA> is a scalar, and to C<< image => DATA >> when C<DATA>
is a reference.

Returns -1 if a 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 C<dnd_start>
returning C<dnd::Move> (depending on a context), the caller may remove the data
the user selected to move (C<Prima::InputLine> and C<Prima::Edit> do exactly
this).

In C<wantarray> context also returns the widget that accepted the drop, if that
was 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 method uses a precaution for this scenario and by
default won't let the widget to be both a sender and a receiver though ( see
C<self_aware> below ).

The following input is recognized:

=over

=item actions INTEGER = dnd::Copy

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

=item format FORMAT, data INPUT

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

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, mouse pointers sending feedback to the user will be equipped with
either text or image (depending on whether C<INPUT> is a 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

When set, waits with starting the DND process until the user moves the pointer
from the starting point further than C<track> pixels, which makes sense if the method
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 C<MouseDown> event as if no drag session was ever started.

=back

=item bring_to_front

Sends a widget on top of all other siblings widgets

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

=item can_close

Sends C<Close> message, and returns its boolean exit state.

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

=item client_to_screen @OFFSETS

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

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

=item close

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

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

=item defocus

Alias for C<focused(0)> call

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

=item deselect

Alias for 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 C<ACTIONS> allowed.  It is
expected that a DND clipboard will be filled with data that are prepared to be
sent to a DND receiver.

Returns -1 if a 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 C<dnd_start>
returning C<dnd::Move> (depending on a context), the called 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 a Prima widget within
the same program.

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

See C<begin_drag> for a wrapper over this method that handles also for other
DND aspects.

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

=item exposed

Returns a boolean value, indicating whether a widget
is at least partly visible on the screen.
Never returns 1 if a widget has C<::visible> set to 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 resource, defined by the widget hierarchy,
its class, name and owner. RESOURCE_TYPE can be one of type constants:

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

Such a number of the parameters is used because the method
can be called before a widget is created.
CLASS_NAME is widget class string, NAME is widget name.
CLASS_RESOURCE is class of 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

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

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 list of children widgets.

=back

=head2 Events

=over

=item Change

Generic notification, used for Prima::Widget descendants;
Prima::Widget itself neither calls not uses the event.
Designed to be called when an arbitrary major state of
a widget is changed.

=item Click

Generic notification, used for Prima::Widget descendants;
Prima::Widget itself neither calls not uses the event.
Designed to be called when an arbitrary major action
for a widget is called.

=item Close

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

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

=item ColorChanged INDEX

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

See also: C<colorIndex>

=item Disable

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

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

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

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

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

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

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

Triggered on a received widget when the user either drops or cancels the DND
session. In case of a canceled drop, C<CLIPBOARD> is set to C<undef> and
C<ACTION> to C<dnd::None>. On a successful drop, input data are same as on
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 changed to 0, a signal will be send to the sender that a drop
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 the Prima DND sender widget, if the session is initiated within
the same program.

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

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

Triggered on a received widget when a mouse with a DND moves within the widget.
Input data are same as on 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 changed to 0, a signal will be send to the sender that a drop
action cannot happen with the input 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 contains 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.