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.

See also: accelTable

accelTable OBJECT

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

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

Default value: undef

See also: accelItems

autoEnableChildren BOOLEAN

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

Default value: 0

backColor COLOR

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

See also: color, colorIndex, ColorChanged

bottom INTEGER

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

See also: left, right, top, origin, rect, growMode, Move

briefKeys BOOLEAN

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

Default value: 1

See also: KeyDown

buffered BOOLEAN

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

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

Default value: 0

See also: Paint, "is_surface_buffered".

capture BOOLEAN, CLIP_OBJECT = undef

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

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

See also: MouseDown, MouseUp, MouseMove, MouseWheel, MouseClick.

centered BOOLEAN

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

See also: x_centered, y_centered, growMode, origin, Move.

clipChildren BOOLEAN

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

Default: 1

clipOwner BOOLEAN

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

Default value: 1

See "Parent-child relationship"

See also: Prima::Object owner section, parentHandle

color COLOR

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

See also: backColor, colorIndex, ColorChanged

colorIndex INDEX, COLOR

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

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

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

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

See also: color, backColor, ColorChanged

current BOOLEAN

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

See also: currentWidget, selectable, selected, selectedWidget, focused

currentWidget OBJECT

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

See also: current, selectable, selected, selectedWidget, focused

cursorPos X_OFFSET Y_OFFSET

Specifies the lower left corner of the cursor

See also: cursorSize, cursorVisible

cursorSize WIDTH HEIGHT

Specifies width and height of the cursor

See also: cursorPos, cursorVisible

cursorVisible BOOLEAN

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

See also: cursorSize, cursorPos

dark3DColor COLOR

The color used to draw dark shades.

See also: light3DColor, colorIndex, ColorChanged

designScale X_SCALE Y_SCALE

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

See also: scaleChildren, width, height, size, font

disabledBackColor COLOR

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

See also: disabledColor, colorIndex, ColorChanged

disabledColor COLOR

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

See also: disabledBackColor, colorIndex, ColorChanged

dndAware 0 | 1 | FORMAT

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

Default: 0

See also: Drag and Drop

enabled BOOLEAN

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

See also: responsive, visible, Enable, Disable

font %FONT

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

See also: designScale, FontChanged, ColorChanged

geometry INTEGER

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

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

See growMode, Prima::Widget::pack, Prima::Widget::place.

growMode MODE

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

Basic constants
 gm::GrowLoX      the widget's left side is kept in constant
                  distance from its owner's right side
 gm::GrowLoY      the widget's bottom side is kept in constant
                  distance from its owner's top side
 gm::GrowHiX      the widget's right side is kept in constant
                  distance from its owner's right side
 gm::GrowHiY      the widget's top side is kept in constant
                  distance from its owner's top side
 gm::XCenter      the widget is kept in the center of its owner's
                  horizontal axis
 gm::YCenter      the widget is kept in the center of its owner's
                  vertical axis
 gm::DontCare     widgets origin is constant relative
                  to the screen
Derived or aliased constants
 gm::GrowAll      gm::GrowLoX|gm::GrowLoY|gm::GrowHiX|gm::GrowHiY
 gm::Center       gm::XCenter|gm::YCenter
 gm::Client       gm::GrowHiX|gm::GrowHiY
 gm::Right        gm::GrowLoX|gm::GrowHiY
 gm::Left         gm::GrowHiY
 gm::Floor        gm::GrowHiX

See also: Move, origin

firstClick BOOLEAN

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

Default: 1

See also: MouseDown, selectable, selected, focused, selectingButtons

focused BOOLEAN

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

See also: selectable, selected, selectedWidget, KeyDown

geomWidth, geomHeight, geomSize

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

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

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

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

height

Maintains the height of the widget.

See also: width, growMode, Move, Size, get_virtual_size, sizeMax, sizeMin

helpContext STRING

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

See also: help

hiliteBackColor COLOR

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

See also: hiliteColor, colorIndex, ColorChanged

hiliteColor COLOR

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

See also: hiliteBackColor, colorIndex, ColorChanged

hint TEXT

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

TEXT can also be a Prima::Drawable::Markup object

See also: hintVisible, showHint, ownerHint, ownerShowHint

hintVisible BOOLEAN

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

See also: hint, showHint, ownerHint, ownerShowHint

layered BOOLEAN

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

Default: false

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

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

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

left INTEGER

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

See also: bottom, right, top, origin, rect, growMode, Move

light3DColor COLOR

The color to draw light shades.

See also: dark3DColor, colorIndex, ColorChanged

ownerBackColor BOOLEAN

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

See also: ownerColor, backColor, colorIndex

ownerColor BOOLEAN

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

See also: ownerBackColor, color, colorIndex

ownerFont BOOLEAN

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

See also: font, FontChanged

ownerHint BOOLEAN

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

See also: hint, showHint, hintVisible, ownerShowHint

ownerShowHint BOOLEAN

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

See also: hint, showHint, hintVisible, ownerHint

ownerPalette BOOLEAN

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

See also: palette

ownerSkin BOOLEAN

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

See also: skin

origin X Y

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

See also: bottom, right, top, left, rect, growMode, Move

packInfo %OPTIONS

See Prima::Widget::pack

palette [ @PALETTE ]

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

See also: ownerPalette

parentHandle SYSTEM_WINDOW

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

Default value is undef.

See also: clipOwner

placeInfo %OPTIONS

See Prima::Widget::place

pointer cr::XXX or ICON

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

See also: pointerHotSpot, pointerIcon, pointerType

pointerHotSpot X_OFFSET Y_OFFSET

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

See also: pointer, pointerIcon, pointerType

pointerIcon ICON

Specifies the pointer icon associated with the widget.

See also: pointerHotSpot, pointer, pointerType

pointerPos X_OFFSET Y_OFFSET

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

See also: get_mouse_state, screen_to_client, client_to_screen

pointerType TYPE

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

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

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

See also: pointerHotSpot, pointerIcon, pointer

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

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

See also: Prima::Menu, Popup, Menu, popupItems, popupColorIndex, popupFont

popupColorIndex INDEX, COLOR

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

See also: popupItems, popupFont, popup

popupColor COLOR

Basic foreground color in the popup context menu color.

See also: popupItems, popupColorIndex, popupFont, popup

popupBackColor COLOR

Basic background color in the popup context menu color.

See also: popupItems, popupColorIndex, popupFont, popup

popupDark3DColor COLOR

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

See also: popupItems, popupColorIndex, popupFont, popup

popupDisabledColor COLOR

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

See also: popupItems, popupColorIndex, popupFont, popup

popupDisabledBackColor COLOR

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

See also: popupItems, popupColorIndex, popupFont, popup

popupFont %FONT

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

See also: popupItems, popupColorIndex, popup

popupHiliteColor COLOR

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

See also: popupItems, popupColorIndex, popupFont, popup

popupHiliteBackColor COLOR

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

See also: popupItems, popupColorIndex, popupFont, popup

popupItems [ ITEM_LIST ]

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

See also: popup, popupColorIndex, popupFont

popupLight3DColor COLOR

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

See also: popupItems, popupColorIndex, popupFont, popup

rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET Y_TOP_OFFSET

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

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

right INTEGER

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

See also: left, bottom, top, origin, rect, growMode, Move

scaleChildren BOOLEAN

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

Default: 1

See also: designScale

selectable BOOLEAN

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

Default: 0

See also: current, currentWidget, selected, selectedWidget, focused

selected BOOLEAN

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

See also: current, currentWidget, selectable, selectedWidget, focused

selectedWidget OBJECT

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

See also: current, currentWidget, selectable, selected, focused

selectingButtons FLAGS

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

Default: mb::Left

See also: MouseDown, firstClick, selectable, selected, focused

shape REGION

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

Successive only if the sv::ShapeExtension value is true.

showHint BOOLEAN

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

The default value is 1.

See also: hint, ownerShowHint, hintVisible, ownerHint

size WIDTH HEIGHT

Maintains the width and height of the widget.

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

sizeMax WIDTH HEIGHT

Specifies the maximal size for the widget.

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

sizeMin WIDTH HEIGHT

Specifies the minimal size for the widget.

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

skin SCALAR

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

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

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

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

syncPaint BOOLEAN

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

Default: 0

See also: invalidate_rect, repaint, validate_rect, Paint

tabOrder INTEGER

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

See also: tabStop, next_tab, selectable, selected, focused

tabStop BOOLEAN

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

Default value is 1.

See also: tabOrder, next_tab, selectable, selected, focused

text TEXT

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

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

See Prima::Drawable::Markup, examples/markup.pl

top INTEGER

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

See also: left, right, bottom, origin, rect, growMode, Move

transparent BOOLEAN

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

Default value is 0

See also: Paint, buffered.

visible BOOLEAN

Specifies whether the widget is visible or not. See "Visibility".

See also: Show, Hide, showing, exposed

widgetClass CLASS

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

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

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

See also: map_color, colorIndex

widgets @WIDGETS

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

width WIDTH

Maintains the width of the widget.

See also: height growMode, Move, Size, get_virtual_size, sizeMax, sizeMin

x_centered BOOLEAN

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

See also: centered, y_centered, growMode, origin, Move.

y_centered BOOLEAN

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

See also: x_centered, centered, growMode, origin, Move.

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.

See also: Close, close

client_to_screen @OFFSETS

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

See also: screen_to_client, clipOwner

close

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

See also: can_close, Close

defocus

Alias for the focused(0) call

See also: focus, focused, Enter, Leave

deselect

Alias for the selected(0) call

See also: select, selected, Enter, Leave

dnd_start ACTIONS = dnd::Copy, USE_DEFAULT_POINTERS = 1

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

Returns -1 if a DND session cannot start, the dnd::None constant 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 returning dnd::Move, the caller may remove the data the user selected to move (Prima::InputLine and Prima::Edit do exactly this).

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

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

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

See also: Drag and Drop, DragQuery, DragResponse.

exposed

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

See also: visible, showing, Show, Hide

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

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

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

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

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

first

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

See also: last, next, prev

focus

Alias for focused(1) call

See also: defocus, focused, Enter, Leave

hide

Sets widget ::visible to 0.

See also: hide, visible, Show, Hide, showing, exposed

hide_cursor

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

See also: show_cursor, cursorVisible

help

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

See also: helpContext

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

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

Has two calling formats:

Single widget
  $parent-> insert( 'Child::Class',
     name => 'child',
     ....
  );
Multiple widgets
  $parent-> insert(
    [
       'Child::Class1',
          name => 'child1',
          ....
    ],
    [
       'Child::Class2',
          name => 'child2',
          ....
    ],
  );
insert_behind OBJECT

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

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

invalidate_rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET Y_TOP_OFFSET

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

See also: validate_rect, get_invalid_rect, repaint, Paint, syncPaint, update_view

is_surface_buffered

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

See also: "buffered"

is_surface_layered

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

See also: "layered"

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

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

See also: key_up, key_event, KeyDown

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

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

See also: key_down, key_up, KeyDown, KeyUp

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

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

See also: key_down, key_event, KeyUp

last

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

See also: first, next, prev

lock

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

See also: unlock, repaint, Paint, get_locked

map_color COLOR

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

See also: colorIndex

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

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

See also: MouseDown, MouseUp, MouseWheel, MouseMove, MouseEnter, MouseLeave

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

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

See also: MouseUp, MouseWheel, MouseClick, MouseMove, MouseEnter, MouseLeave

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

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

See also: MouseDown, MouseUp, MouseWheel, MouseClick, MouseMove, MouseLeave

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

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

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

mouse_leave

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

See also: MouseDown, MouseUp, MouseWheel, MouseClick, MouseMove, MouseEnter, MouseLeave

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

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

See also: MouseDown, MouseUp, MouseWheel, MouseClick, MouseEnter, MouseLeave

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

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

See also: MouseDown, MouseWheel, MouseClick, MouseMove, MouseEnter, MouseLeave

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

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

See also: MouseDown, MouseUp, MouseClick, MouseMove, MouseEnter, MouseLeave

next

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

See also: first, last, prev

next_tab FORWARD = 1

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

Also used by the internal keyboard navigation code.

See also: next_positional, tabOrder, tabStop, selectable

next_positional DELTA_X DELTA_Y

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

Also used by the internal keyboard navigation code.

See also: next_tab, origin

pack, packForget, packSlaves

See Prima::Widget::pack

place, placeForget, placeSlaves

See Prima::Widget::place

prev

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

See also: first, last, next

repaint

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

See also: validate_rect, get_invalid_rect, invalidate_rect, Paint, update_view, syncPaint

rect_bevel $CANVAS, @RECT, %OPTIONS

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

fill COLOR

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

width INTEGER

The width of the border in pixels

concave BOOLEAN

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

responsive

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

See also: enabled

screen_to_client @OFFSETS

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

See also: client_to_screen

scroll DELTA_X DELTA_Y %OPTIONS

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

clipRect [X1, Y1, X2, Y2]

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

confineRect [X1, Y1, X2, Y2]

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

withChildren BOOLEAN

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

Returns one of the following constants:

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

Cannot be used inside the paint state.

See also: Paint, get_invalid_rect

select

Alias for selected(1) call

See also: deselect, selected, Enter, Leave

send_to_back

Sends the widget to the bottom of all other sibling widgets

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

show

Sets the widget's ::visible property to 1.

See also: hide, visible, Show, Hide, showing, exposed

show_cursor

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

See also: hide_cursor, cursorVisible

showing

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

unlock

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

See also: lock, repaint, Paint, get_locked

update_view

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

See also: invalidate_rect, get_invalid_rect, repaint, Paint, syncPaint, update_view

validate_rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET Y_TOP_OFFSET

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

See also: invalidate_rect, get_invalid_rect, repaint, Paint, syncPaint, update_view

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.

See also: close, can_close

ColorChanged INDEX

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

See also: colorIndex

Disable

Triggered by a successful enabled(0) call

See also: Enable, enabled, responsive

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

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

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

See also: "Drag and Drop", DragOver, DragEnd

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

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

allow BOOLEAN

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

action INTEGER

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

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

See also: "Drag and Drop", DragBegin, DragOver

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

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

allow BOOLEAN

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

action INTEGER

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

pad X, Y, WIDTH, HEIGHT

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

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

DragQuery MOD, COUNTERPART, ANSWER

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

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

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

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

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

See also: "Drag and Drop", DragResponse

DragResponse ALLOW, ACTION, COUNTERPART

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

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

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

See also: "Drag and Drop", dnd_start, begin_drag.

Enable

Triggered by a successful enabled(1) call

See also: Disable, enabled, responsive

Enter

Called when the widget receives the input focus.

See also: Leave, focused, selected

FontChanged

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

See also: font, ColorChanged

Hide

Triggered by a successful visible(0) call

See also: Show, visible, showing, exposed

Hint SHOW_FLAG

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

See also: showHint, ownerShowHint, hintVisible, ownerHint

KeyDown CODE, KEY, MOD, REPEAT

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

The valid km:: constants are:

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

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

Modifier keys
   kb::ShiftL   kb::ShiftR   kb::CtrlL      kb::CtrlR
   kb::AltL     kb::AltR     kb::MetaL      kb::MetaR
   kb::SuperL   kb::SuperR   kb::HyperL     kb::HyperR
   kb::CapsLock kb::NumLock  kb::ScrollLock kb::ShiftLock
Keys with character code defined
   kb::Backspace  kb::Tab    kb::Linefeed   kb::Enter
   kb::Return     kb::Escape kb::Esc        kb::Space
Function keys
   kb::F1 .. kb::F30
   kb::L1 .. kb::L10
   kb::R1 .. kb::R10
Other
   kb::Clear    kb::Pause   kb::SysRq  kb::SysReq
   kb::Delete   kb::Home    kb::Left   kb::Up
   kb::Right    kb::Down    kb::PgUp   kb::Prior
   kb::PageUp   kb::PgDn    kb::Next   kb::PageDown
   kb::End      kb::Begin   kb::Select kb::Print
   kb::PrintScr kb::Execute kb::Insert kb::Undo
   kb::Redo     kb::Menu    kb::Find   kb::Cancel
   kb::Help     kb::Break   kb::BackTab

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

KeyUp CODE, KEY, MOD

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

See also: KeyDown, key_up

Leave

Called when the input focus is removed from the widget

See also: Enter, focused, selected

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

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

See also: popupItems

MouseClick BUTTON, MOD, X, Y, NTH

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

mb::XXX constants are:

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

See also: MouseDown, MouseUp, MouseWheel, MouseMove, MouseEnter, MouseLeave

MouseDown BUTTON, MOD, X, Y

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

See also: MouseUp, MouseClick, MouseWheel, MouseMove, MouseEnter, MouseLeave

MouseEnter MOD, X, Y

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

See also: MouseDown, MouseUp, MouseClick, MouseWheel, MouseMove, MouseLeave

MouseLeave

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

See also: MouseDown, MouseUp, MouseClick, MouseWheel, MouseMove, MouseEnter

MouseMove MOD, X, Y

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

See also: MouseDown, MouseUp, MouseClick, MouseWheel, MouseEnter, MouseLeave

MouseUp BUTTON, MOD, X, Y

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

See also: MouseDown, MouseClick, MouseWheel, MouseMove, MouseEnter, MouseLeave

MouseWheel MOD, X, Y, INCR

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

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

See also: MouseDown, MouseUp, MouseClick, MouseMove, MouseEnter, MouseLeave

Move OLD_X, OLD_Y, NEW_X, NEW_Y

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

See also: Size, origin, growMode, centered, clipOwner

Paint CANVAS

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

See also: repaint, syncPaint, get_invalid_rect, scroll, colorIndex, font

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

See also: popup

Setup

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

Show

Triggered by a successful visible(1) call

See also: Show, visible, showing, exposed

Size OLD_WIDTH, OLD_HEIGHT, NEW_WIDTH, NEW_HEIGHT

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

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

SysHandle

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

"clipOwner", "syncPaint", "layered", "transparent"

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

TranslateAccel CODE, KEY, MOD

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

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

See also: KeyDown

ZOrderChanged

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

See also: bring_to_front, insert_behind, send_to_back

AUTHOR

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

SEE ALSO

Prima, Prima::Object, Prima::Drawable.