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.

Menu objects¶

Prima::Widget objects may have a special relationship with registered object instances of the Prima::AccelTable and Prima::Popup class ( for Prima::Window this is also valid for Prima::Menu objects ). The registration and/or automatic creation of these objects can happen by using the "::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.
See also: "font"
get_default_popup_font: Returns the default font for the Prima::Popup class.
See also: "font"
get_invalid_rect: Returns the rectangle encompassing the actual invalid region on the widget. If the widget doesn't need to be repainted, the (0,0,0,0) tuple is returned.
See also: "validate_rect", "invalidate_rect", "repaint", "Paint", "syncPaint", "update_view"
get_handle: Returns the system handle for the widget
See also: "get_parent_handle", "Window::get_client_handle"
get_locked: Returns 1 if the lock() was called and all repaints are effectively blocked.
See also: "lock", "unlock"
get_mouse_state: Returns a combination of the "mb::XXX" constants that reflects the currently pressed mouse buttons.
See also: "pointerPos", "get_shift_state"
get_parent: Returns the widget that the caller widget boundaries get clipped to, or the application object if the caller widget is top-level or has the clipOwner property set to 1.
See also: "clipOwner"
get_parent_handle: Returns the system handle for the parent of the widget, the window that belongs to another program. Returns 0 if the widget's owner and parent are in the same application and process space.
See also: "get_handle", "clipOwner"
get_pointer_size: Returns two integers, the width and height of the icon, that the system accepts as valid for the mouse pointer. If the sizes of the icon exceed or are inferior to the size the icon is then truncated or padded with transparency bits ( but not stretched ). Can be called with the class syntax as it returns the system-wide value.
get_shift_state: Returns a combination of the "km::XXX" constants that reflects the currently pressed keyboard modifier buttons.
See also: "get_shift_state"
get_virtual_size: Returns the virtual width and height of the widget. See "Geometry", Implicit size regulations.
See also: "width", "height", "size" "growMode", "Move", "Size", "sizeMax", "sizeMin"
get_widgets: Returns the list of the children widgets.

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

Source file:	pod::Prima::Widget.3pm.en.gz (from perl-Prima 1.72000-1.1)
Source last updated:	2024-03-08T20:56:17Z
Converted to HTML:	2024-05-01T01:42:22Z