NAME

Prima::Widget - window management

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;

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.

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

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 insert syntax is preferred, as it is more illustrative and is more convenient for creating several widgets in one call ( see 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 Create notification while being created ( more precisely, after its init stage is finished. See Prima::Object for details). This notification is called and processed within the new() method. Another notification Setup is sent after the widget finishes the creation process. This message is posted though, i e it is invoked within the new() method but is processed inside the application event loop. This means that the moment when the 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 Paint notification.

When the lifetime of the widget is over, its method 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 Prima::Object, the Creation section ).

Graphic content

There are two ways graphics can be displayed in a widget. The first is the event-driven method when the 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.

Event-driven rendering

When the system decides that a widget needs to update its graphics it sends the Paint notification to the program. The notification has a single ( besides the widget itself ) parameter, referred to as 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 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 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 begin_paint()/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 notify(q(Paint)) is needed - the repaint() method is used instead. Note that the execution of Paint callbacks may or may not occur inside the repaint() call. This behavior is managed by the ::syncPaint property. A call to repaint() marks the whole widget's area to be refreshed, or invalidates the area. For the finer access to the area that should be repainted, the functions invalidate_rect() and 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 invalidate_rect() method will be accessible as the clipping rectangle inside the 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 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 ::clipRect property is used. Inside the Paint call (or, strictly speaking, inside the begin_paint/end_paint brackets) the rectangle is measured in the inclusive-inclusive coordinates, whereas the invalidate_rect(), validate_rect(), and 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 ::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 ::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.

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 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 $::application object, that does not have the 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 lock() and unlock() methods can be called several times, counting the requests. This feature is useful because many properties implicitly call 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 unlock() call triggers the repaint() method unconditionally.

Geometry

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 ::origin and ::size, and the derived ones are ::left, ::bottom, ::right, ::top, ::width, ::height, and ::rect. ::origin and ::size operate on two integers, ::rect on four, others on one integer value.

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

When widgets are moved or resized, two notifications may occur, correspondingly, Move and 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.

Implicit size regulations

There exist two other properties that regulate widget size, ::sizeMin and ::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 ::sizeMin and ::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 ::growMode property accepts a set of gm::XXX flags that encode this behavior. The exact meaning of the gm::XXX flags is not given here ( see the description to ::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 ::growMode property is 0, so widgets don't change either their size or position on these occasions. A widget with ::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 gm::GrowLoX and 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 gm::GrowHiX value must be used.

When such implicit size change occurs, the ::sizeMin and ::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 ::growMode set to 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 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 virtual size . The ::size property is derived from the virtual size, but while ::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

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 managers, and each manager has its own set of properties. One can select the manager by assigning the ::geometry property one the of gt::XXX constants. The native ( and the default ) geometry manager is the described above grow-mode algorithm ( gt::GrowMode). The currently implemented Tk managers are packer ( gt::Pack ) and placer ( gt::Place). Each has its own set of options and methods, and their manuals are provided separately in Prima::Widget::pack and 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 ::geomSize, which reflects the size deduced by some intrinsic widget knowledge. The idea is that ::geomSize is merely a request to a geometry manager, whereas the latter changes ::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 gt::GrowMode geometry manager, setting ::geomSize ( and its two semi-alias properties ::geomWidth and ::geomHeight ) also changes the actual widget size. Moreover, when the size is passed to the Widget initialization code, the ::size property is used to initialize ::geomSize. Such design minimizes the confusion between the two properties, and also minimizes the direct usage of ::geomSize, limiting it to selecting the advisory size in the internal code.

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

Relative coordinates

Another geometry issue, or rather a programming technique, must be mentioned - the 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 ::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::profile_check_in() method.

To use the relative coordinates technique the owner ( or the dialog ) widget must set its ::designScale property to the font metrics, and the ::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 ::scaleChildren must be set to 0, or the widget's ::designScale must be set to undef. As the default ::designScale value is undef, no implicit relative geometry schemes are applied by default.

The ::designScale property is automatically propagated to the children widgets, unless the explicit ::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 Prima::Stress for more.

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 Z-axis ordering, with these four methods: first(), last(), next(), and 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 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: bring_to_front() sends the widget to the top of the stack, send_to_back() sends it to the bottom, and insert_behind() sets a widget behind another widget

Changes to Z-order trigger the ZOrderChanged notification.

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 ::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 ::clipOwner value set to 0, and it cannot be changed.

The ::clipOwner property opens a possibility for the toolkit widgets to live inside other programs' windows. The ::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 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 ::owner property of another widget, becomes an owner of the latter automatically. The get_widgets() method returns the list of these children widgets, similar to the Prima::Component::get_components() method, but returns only Prima::Widget descendant objects.

Widgets can change their owner at any moment. The ::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 ::clipOwner property is set to 1.

Visibility

Widgets are created visible by default. The visibility status is managed by the ::visible property, and its two convenience alias methods, show() and 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 ::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 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 yield() method on the $::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 showing() and exposed() functions, correspondingly. So, if a widget is 'exposed', it is 'showing' and 'visible'; the 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'. showing() always returns 0 if a widget is invisible.

Change to the visibility status trigger the Hide and Show notifications.

Focus

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

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

The ::selected property sets focus to a widget only if it is allowed to be focused, by consulting with the value of the ::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 ::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 select() and 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 ::current property or the owner widget's ::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 Enter and Leave notifications.

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

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 ::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 ::selected(1) on the widget that received the mouse click.

Another boolean property ::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 ::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.

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 next_tab() and next_positional() ( see API for the details).

The 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 next_tab() method uses the ::tabStop and ::tabOrder properties for this. The boolean property ::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 next_tab() never returns that widget as a candidate to be selected. The value of the ::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 ::tabOrder value is -1, which changes to a unique value automatically after the widget creation.

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 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 post'ed, delaying the notification until the next invocation of the event loop.

Keyboard

Event-driven

Keyboard input generates several notifications, where the most important are the KeyDown and 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 kb::XXX ( like, kb::F10, kb::Esc ) constants and the key modifier value is a combination of the 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 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 KeyDown event has also the 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 ::briefKeys property to 0. ::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 KeyDown processing code sees a repeat value greater than 1, it simply calls the notification again.

Along with these two notifications, the TranslateAccel event is generated after 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. TranslateAccel has the same parameters as 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 Prima::Menu for the details. In particular, Prima::Widget has the ::accelTable property, a mere slot for an object that contains a table of hotkeys mapped to the custom subroutines.

Polling

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

Simulated input

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

Mouse

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>, MouseUp, MouseClick, and MouseWheel notifications, and the second of MouseMove, MouseEnter, end 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 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 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 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 MouseEnter event, then a series of MouseMove events, and finally the MouseLeave event. The MouseMove and MouseEnter notifications provide the X,Y-coordinates and the eventual modifier keys; MouseLeave provides no parameters.

Polling

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

Simulated input

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

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

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.

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 Prima::Clipboard). The DND clipboard can be accessed at any time by calling the $::application- get_dnd_clipboard > method.

To successfully exchange data with other applications, one should investigate the results of a $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 image/bmp out of the box, and text/plain on X11, which are selected automatically when operating with pseudo-formats Text or Image. Other MIME formats like f.ex. text/html are not known to Prima, but can be exchanged quite easily; the program only needs to register these formats by calling the Clipboard::register_format method at the start of the program.

Dragging

To begin a dragging session first fill the DND clipboard with data to be exchanged, using one or more formats, then call the "start_dnd" method. Alternatively, call "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 "DragQuery" and "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 begin_drag is implemented).

Dropping

To register a widget as a drop target, set its "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 "DragBegin" event, then a series of the "DragOver" events, and finally a "DragEnd" event with a flag telling whether the user chose to drop the data to the widget or cancel the session.

The DragOver and 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 {allow} and the {action} fields in the last hashref parameter that is sent to these event handlers. Additionally, the program can respond to the DragOver by setting the {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.

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 DragQuery event. On Win32, it is the receiver that selects an action from the list on each DragOver event, depending on the modifier keys pressed by the user; Win32 recommends adhering to the standard scheme where the CTRL key means the dnd::Move action, and the SHIFT key the 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 dnd:: constants inside a DragQuery event, and the X11 receiver will similarly never be presented with such combination inside 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.

Colors

Prima::Widget extends the functionality of ::color and ::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 ::ownerColor and ::ownerBackColor. If these are set to 1 then changes to the owner's properties ::color or ::backColor are copied automatically to the widget. Once the widget's ::color or ::backColor is explicitly set, the owner link breaks automatically by setting ::ownerColor or ::ownerBackColor to 0.

In addition to these two existing color properties, Prima::Widget introduces six others. These are: ::disabledColor, ::disabledBackColor, ::hiliteColor, ::hiliteBackColor, ::light3DColor, and ::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, ::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, ::light3DColor and ::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 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, ci:: can be used with the ::colorIndex property, a multiplexer method for all the eight color properties. ci:: constants mimic their non-RGB cl:: counterparts, so that a call to hiliteBackColor(cl::Red) is equal to colorIndex(ci::Hilite, cl::Red).

The map_color translates these special constants to the 24-bit RGB integer values. The 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 cl:: constants can be combined with the wc:: constants, that represent the standard widget classes. If the color property was assigned with a cl:: constant not combined with a wc:: constant, the widget class value is read from the ::widgetClass property. Thus a call to, for example, backColor( cl::Back) on a button and an input line may result in different colors because the cl::Back is translated in the first case to cl::Back|wc::Button, and in another to cl::Back|wc::InputLine. The wc:: constants are described in "API".

Dynamic changes of the color properties result in the ColorChanged notification.

Fonts

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

Dynamic changes to the font property result in the FontChanged notification.

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.

Markup text

The 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 Prima::Drawable that handle text output such as text_out, and 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 text and the hint properties.

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

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

or using an imported method 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 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.

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 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 ::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: ::pointerType, ::pointerIcon, and ::pointerHotSpot. See the details in the "API" sections.

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

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: ::cursorVisible, ::cursorPos, and ::cursorSize. There are also two methods, show_cursor() and hide_cursor() that govern the cursor visibility. Note: If the hide_cursor() method was called three times, then show_cursor() must be called three times as well for the cursor to become visible.

Hints

::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 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 ::showHint property, and it can inherit the owner's ::hint and ::showHint properties using the ::ownerHint and ::ownerShowHint properties. If, for example, the widgets' ::ownerHint property is set to 1, then the ::hint value is automatically copied from the widget's owner when it changes. If, however, the widget's ::hint or ::showHint are explicitly set, the owner link breaks automatically by setting ::ownerHint or ::ownerShowHint to 0.

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

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 ::accelTable, ::popup, and ::menu properties. Also the ::items property of these objects can also be accessed via the ::accelItems, ::popupItems, and ::menuItems properties. As mentioned in "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. ::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 ::popupColorIndex and ::popupFont properties. The multiplexer method ::popupColorIndex can be also used to access the ::popupColor, ::popupHiliteColor, ::popupHiliteBackColor, etc properties exactly like the ::colorIndex property. The Prima::Window class provides equivalent methods for the menu bar, introducing ::menu, ::menuItems, ::menuColorIndex, and ::menuFont properties.

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

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 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 fetch_resource() method, but it is believed that calling the method for every property on every widget is prohibitively expensive.

API

Properties

accelItems [ ITEM_LIST ]

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

Methods

begin_drag [ DATA | %OPTIONS ]

Wrapper over the 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 %OPTIONS hash except when the case of a single-parameter call, when the DATA scalar is treated either as text => DATA or image => DATA depending on the DATA type.

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

In the wantarray context also returns the widget that accepted the drop, if that is a Prima widget. Check this before handling dnd::Move actions that require data to be deleted on the source, to not occasionally delete the freshly transferred data. The 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 self_aware below ).

The following input is recognized:

actions INTEGER = dnd::Copy

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

format FORMAT, data INPUT

If set, the DND clipboard will contain a single entry of the INPUT in the FORMAT format, where the format is either the standard Text or Image, or one of the formats registered by the 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.

image INPUT

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

preview INPUT

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

self_aware BOOLEAN = 1

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

text INPUT

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

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 track pixels, which makes sense if the method is to be called directly from a 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 MouseDown event as if no drag session was ever started.

bring_to_front

Sends the widget on top of all other sibling widgets

See also: insert_behind, send_to_back, ZOrderChanged ,first, next, prev, last

can_close

Sends the 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 clear_event method in the Close event handler.

Get-methods

get_default_font

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

Events

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.

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.

Close

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

AUTHOR

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

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)