pod::Prima::Widget(3)

📦

version 1.74000 · 5 versions

1.74000 · opensuse-leap 16.0 (latest)
1.74 · epel 9
1.76 · fedora 43
1.78 · fedora 44
1.77 · fedora 44

okay bestie, this is pod::Prima::Widget(3) from User Contributed Perl Documentation — the window-management manual, and it's genuinely iconic 💅

🌸 NAME 🌸

Prima::Widget — window management, no cap.

✨ 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, and it 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. It's giving "whole window system, but make it a Perl object" ✨

💖 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. Literally the main character energy of the toolkit 🫶

🛠️ 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 ). Slay a whole batch of widgets in one go 🎀

$owner-> insert( 'Prima::Widget',
   name => 'Widget',
   size => [ 20, 10],
   onMouseClick => sub { print "click\n"; },
);

These two examples produce identical results. fr fr.

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. lowkey important, bestie ⚠️

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 ). order matters, and the toolkit is handling it 💅

🎨 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. Two paths, same screen, pick your vibe 🌈

✨ 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. this is the assignment, bestie 🫶

An example of the Paint notification handler could be a simple one 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. same energy, different spelling ✨

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. not me getting an empty clip rect 😭

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. draw less, slay more 💅

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. boundaries are boundaries, bestie 🚧

🖌️ 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. whole screen canvas? main character behavior 🌈

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. choose your fighter 🎀

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. last unlock said "and I took that personally" 💀💅

🌈 Geometry 🌈

Okay bestie, geometry time — and no cap, this part is lowkey the whole vibe of how widgets sit and slay on screen. ✨

🎀 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, and the 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 is the 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 of the 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.
insert_behind() — sets a widget behind another widget.

Changes to Z-order trigger the ZOrderChanged notification. 💅

💖 Parent-child relationship 💖

okay so by default, if a widget is the child of another widget or a window, it gets clipped by its owner’s boundaries and it moves together with its owner when the owner changes position. In this setup, the child’s owner is also its parent. 💅

A widget must always have an owner, but not necessarily a parent. The ::clipOwner property is 1 by default; set it to 0 and the widget switches into parent-less mode. That means it is neither clipped nor moved together with its parent. The widget becomes parent-less, or, more strictly speaking, the screen becomes its parent. Also, 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. ✨

You can get the same result if a widget is inserted in the application object that 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 up the possibility for 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.

bestie, this is the “living in someone else’s window” situation — cute in theory, but you gotta be ready for it to vanish at any moment 😭

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 it 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 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 triggers 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 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. iconic behavior, honestly 💖

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 with the window and 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 ⌨️

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, 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. 🎮✨

Okay so the event-driven input is the more-or-less natural way of communicating with the user, bestie. When the user presses a key or moves the mouse, a system event occurs and triggers the notification in one or more widgets. Polling gives you the immediate state of the input devices. It’s rarely chosen, mostly because its usability is limited, and because the info it provides gets passed to the notification callbacks anyway. Simulated input is literally a little more than a notify() call with specifically crafted parameters. It interacts with the system by sending the event through the system API, so input emulation can be more similar to real user actions. The simulated input functions let notifications be called right away, or be post'ed, delaying the notification until the next invocation of the event loop.

⌨️ Keyboard ⌨️

✨ Event-driven ✨

Keyboard input generates several notifications, and the main characters are KeyDown and KeyUp — no cap. Both have almost the same list of parameters (see the API) containing the keycode, the modifier keys (if any) that were pressed, and an eventual character code. The algorithms that extract the meaning of the key — like discerning between character keys 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 also at the Prima::Edit and Prima::InputLine modules, the classes that use keyboard input extensively.

But in short: the keycode is one of the kb::XXX constants (like kb::F10, kb::Esc), and the key modifier value is a combination of the km::XXX constants (km::Ctrl, km::Shift). The notable exception is the kb::None constant, which hints that there is a character code present in the event. Some other kb::XXX-marked keys have a character code as well, and it is up to the 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, to decide what type of key combination the user pressed.

The KeyDown event also has 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 introducing the repeat value makes the code too complicated, you may consider setting the ::briefKeys property to 0. ::briefKeys is a boolean property and is 1 by default. If it is set to 0, it guarantees that the repeat value will always be 1, but that comes at 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 user input, even while being out of focus. A notable example is 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 you to declare hotkeys in the Menu definitions. So if a descendant of the Prima::AbstractMenu class is in the widget’s children tree hierarchy, Prima checks 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 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 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, and MouseLeave.

The notifications from the first set respond to 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 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 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, which 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 for 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, you 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 their 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 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.

okay so the DragOver and DragEnd callbacks are literally your chance to either allow or deny data and select an action (if there’s more than one allowed by the other application) to proceed with. To do that, set appropriate values in the {allow} and {action} fields of the last hashref parameter that is sent to these event handlers. Also, your program can respond to DragOver by setting the {pad} rectangle — that caches the last answer and tells 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 ✨

Okay so the resources that Prima::Widget totally operates but that aren’t, like, strictly bound to the widget concept all get gathered here. This section gives you the lowdown on pointer, cursor, hint, menus, and user-specified resources. Bestie, it’s giving “misc but iconic.” 💅

🎀 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. Obsessed, honestly. ✨

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. Respect the boundaries, periodt. 🫶

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. Cute, right? 🎀

🖱️ 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. Main character energy for the cursor, honestly. 👑

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. No cap, the system said “bestie, we’re resizing.” 😭

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. Group chat for the whole app, basically. 💬

⌨️ 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. It’s a whole vibe check — do not lose count, bestie. 💀

💬 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 way that inheritance just snaps is so dramatic, honestly. 😭

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. Very “you’re in my zone, here’s the tea.” 🍵

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. Slay, context menu. 🖱️✨

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. It’s giving menu bar main character energy. 👑

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. Not me side-eyeing Win32, but okay. 🙈

🌸 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. Respecting the user’s vibe is highkey important. 💖

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. And honestly, bestie, that would be a lot. 😭

🌈 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 it’s 1, the widget is clipped by its owner boundaries. That’s the default and the expected behavior, no cap. 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. iconic behavior tbh.

See also: backColor, colorIndex, ColorChanged

colorIndex INDEX, COLOR — manages the basic color properties indirectly by accessing them via the ci::XXX constants. It is a complete alias for the ::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. main character energy, but only one at a time 💅

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.

🌟 Methods 🌟

begin_drag [ DATA | %OPTIONS ] — a wrapper over the dnd_start method that adds several aspects to the DND session that the system doesn't offer 🫶. All of the input lives in the %OPTIONS hash, except in 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 wantarray context it also returns the widget that accepted the drop, if that's a Prima widget 👀. Check this before handling dnd::Move actions that require data to be deleted on the source, so you don't 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 👑 main character energy fr

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

can_close — sends the Close event and returns its flag value 📨. Windows that need to abort a potential closing — for example when an editor asks the user if a document needs to be saved — need to call the clear_event method in the Close event handler.

🎀 Get-methods 🎀

Getters!! The "just tell me the value already" squad, we love them 💖

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

🌈 Events 🌈

Change — A generic notification, is used for the Prima::Widget's descendants; the Prima::Widget class itself neither calls nor uses the event. Designed to be called when an arbitrary major state of the widget is changed.
Click — A generic notification, is used for the Prima::Widget's descendants; Prima::Widget itself neither calls nor uses the event. Designed to be called when an arbitrary major action for the widget is called. (Yes, it's the sibling of Change — same energy, different occasion ✨)
Close — Triggered by the can_close() and close() functions. If the event flag is cleared during execution, these functions return the false value — so you can literally veto the close, main character move 💅

Paint CANVAS

okay so this one fires when the system calls for the refresh of the widget's graphic content. CANVAS is literally the widget itself, so use it to draw on (see Graphic content).

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

bestie, this is called by the system when the user presses the key or the mouse combination defined for execution of a context pop-up menu. By default it executes the associated Prima::Popup object if it is present.

If the event flag is cleared in the event handler, then the pop-up menu request is denied and the popup is not shown. no cap, that's the whole vibe check right there.

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