Prima::Widget - window management
# 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;
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.
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.
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 ).
insert
$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.
Create
new()
Setup
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.
Paint
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 ).
destroy()
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.
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
begin_paint()
end_paint()
notify(q(Paint))
repaint()
::syncPaint
invalidate_rect()
validate_rect()
$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.
invalidate_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:
::clipRect
begin_paint
end_paint
get_invalid_rect()
$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.
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.
$::application
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.
lock()
unlock()
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.
::origin
::size
::left
::bottom
::right
::top
::width
::height
::rect
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.
Move
Size
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.
::sizeMin
::sizeMax
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.
::growMode
gm::XXX
gm::GrowLoX
gm::GrowLoY
gm::GrowHiX
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
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 ).
::geometry
gt::XXX
gt::GrowMode
gt::Pack
gt::Place
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.
::geomSize
::geomWidth
::geomHeight
The geometry request size is useless under the gt::GrowMode geometry manager, but Tk managers use it extensively.
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.
::designScale
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.
profile_check_in()
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.
::scaleChildren
undef
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.
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.
first()
last()
next()
prev()
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
bring_to_front()
send_to_back()
insert_behind()
Changes to Z-order trigger the ZOrderChanged notification.
ZOrderChanged
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.
::clipOwner
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.
::parentHandle
Close
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.
::owner
get_widgets()
Prima::Component::get_components()
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.
Widgets are created visible by default. The visibility status is managed by the ::visible property, and its two convenience alias methods, show() and hide().
::visible
show()
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.
update_view()
yield()
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.
showing()
exposed()
Change to the visibility status trigger the Hide and Show notifications.
Hide
Show
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.
::focused
::selected
::current
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'.
::selectable
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.
select()
deselect()
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.
::currentWidget
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.
Enter
Leave
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.
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.
::selectingButtons
::selected(1)
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.
::firstClick
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.
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).
next_tab()
next_positional()
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.
::tabStop
::tabOrder
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.
notify()
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.
KeyDown
KeyUp
kb::XXX
km::XXX
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.
::briefKeys
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.
TranslateAccel
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.
::accelTable
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.
get_shift_state()
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.
key_up()
key_down()
key_event()
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.
MouseUp
MouseClick
MouseWheel
MouseMove
MouseEnter
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.
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.
get_mouse_state()
mb::XXX
::pointerPos
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.
mouse_up()
mouse_down()
mouse_click()
mouse_wheel()
mouse_move()
These methods are convenience wrappers for the mouse_event() method that is never used directly.
mouse_event()
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.
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.
$::application-
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.
$clipboard-> get_formats(1)
image/bmp
text/plain
Text
Image
text/html
Clipboard::register_format
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).
begin_drag
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.
DragOver
DragEnd
{allow}
{action}
{pad}
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.
DragQuery
dnd::Move
dnd::Link
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.
dnd::
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.
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.
::color
::backColor
::ownerColor
::ownerBackColor
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.
::disabledColor
::disabledBackColor
::hiliteColor
::hiliteBackColor
::light3DColor
::dark3DColor
::enabled
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).
cl::
ci::
::colorIndex
hiliteBackColor(cl::Red)
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".
map_color
wc::
::widgetClass
backColor( cl::Back)
cl::Back
cl::Back|wc::Button
cl::Back|wc::InputLine
Dynamic changes of the color properties result in the ColorChanged notification.
ColorChanged
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.
::ownerFont
get_default_font
get_default_popup_font
::popupFont
get_default_menu_font
::menuFont
Dynamic changes to the font property result in the FontChanged notification.
FontChanged
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.
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.
Prima::Drawable::Markup
Prima::Drawable
text_out
get_text_width
text
hint
There are two ways to construct a markup object: either directly:
Prima::Drawable::Markup->new( ... )
or using an imported method M,
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:
Prima::Widget
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.
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.
cr::XXX
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.
::pointer
::pointerType
::pointerIcon
::pointerHotSpot
Another property called Prima::Application::pointerVisible manages the visibility of the mouse pointer for all widgets at once.
Prima::Application::pointerVisible
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.
::cursorVisible
::cursorPos
::cursorSize
show_cursor()
hide_cursor()
::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.
::hint
::showHint
::ownerHint
::ownerShowHint
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.
::hintVisible
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.
::popup
::menu
::items
::accelItems
::popupItems
::menuItems
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.
::popupColorIndex
::popupColor
::popupHiliteColor
::popupHiliteBackColor
::menuColorIndex
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.
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.
fetch_resource()
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.
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.
Prima::AbstractMenu::items
See also: accelTable
accelTable
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.
accelTable(undef)
Default value: undef
See also: accelItems
accelItems
If TRUE, all immediate children widgets maintain the same enabled state as the widget. This property is useful for group-like widgets ( ComboBox,
enabled
Default value: 0
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
color
colorIndex
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.
set()
See also: left, right, top, origin, rect, growMode, Move
left
right
top
origin
rect
growMode
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
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.
is_surface_buffered
See also: Paint, "is_surface_buffered".
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.
MouseDown
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.
x_centered
y_centered
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
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.
See "Parent-child relationship"
See also: Prima::Object owner section, parentHandle
Prima::Object
parentHandle
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
backColor
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::XXX
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
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
selectable
selected
selectedWidget
focused
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
current
Specifies the lower left corner of the cursor
See also: cursorSize, cursorVisible
cursorSize
cursorVisible
Specifies width and height of the cursor
See also: cursorPos, cursorVisible
cursorPos
Specifies the cursor visibility flag. The default value is 0.
See also: cursorSize, cursorPos
The color used to draw dark shades.
See also: light3DColor, colorIndex, ColorChanged
light3DColor
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
scaleChildren
width
height
size
font
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
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
disabledBackColor
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
Drag and Drop
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
responsive
visible
Enable
Disable
Manages the font context. Same syntax as in Prima::Drawable. When changed initiates FontChanged notification and repaints the widget.
See also: designScale, FontChanged, ColorChanged
designScale
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.
Specifies the widget's behavior, when its owner is resized or moved. MODE can be 0 ( default ) or a combination of the following 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
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
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.
See also: MouseDown, selectable, selected, focused, selectingButtons
selectingButtons
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
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.
Maintains the height of the widget.
See also: width, growMode, Move, Size, get_virtual_size, sizeMax, sizeMin
get_virtual_size
sizeMax
sizeMin
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
help
The color to be used to draw the alternate background areas with a higher contrast.
See also: hiliteColor, colorIndex, ColorChanged
hiliteColor
The color to be used to draw the alternate foreground areas with a higher contrast.
See also: hiliteBackColor, colorIndex, ColorChanged
hiliteBackColor
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.
Prima::Application::hintPause
TEXT can also be a Prima::Drawable::Markup object
See also: hintVisible, showHint, ownerHint, ownerShowHint
hintVisible
showHint
ownerHint
ownerShowHint
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
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.
is_surface_layered
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).
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
bottom
The color to draw light shades.
See also: dark3DColor, colorIndex, ColorChanged
dark3DColor
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
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
ownerBackColor
If 1, the font is synchronized with the owner's. Automatically resets to 0 if the ::font property is set explicitly.
::font
See also: font, FontChanged
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
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
If 1, the palette array is synchronized with the owner's. Automatically resets to 0 if the ::palette property is set explicitly.
::palette
See also: palette
palette
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.
skin
::skin
See also: skin
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
See Prima::Widget::pack
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
ownerPalette
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
clipOwner
See Prima::Widget::place
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.
__pointerHotSpot
See also: pointerHotSpot, pointerIcon, pointerType
pointerHotSpot
pointerIcon
pointerType
Specifies the hot spot coordinates of the pointer icon associated with the widget.
See also: pointer, pointerIcon, pointerType
pointer
Specifies the pointer icon associated with the widget.
See also: pointerHotSpot, pointer, pointerType
Specifies the mouse pointer coordinates relative to the widget's coordinates.
See also: get_mouse_state, screen_to_client, client_to_screen
get_mouse_state
screen_to_client
client_to_screen
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.
cr::User
cr::Default
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.
popup(undef)
See also: Prima::Menu, Popup, Menu, popupItems, popupColorIndex, popupFont
Prima::Menu
Popup
Menu
popupItems
popupColorIndex
popupFont
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
popup
Basic foreground color in the popup context menu color.
See also: popupItems, popupColorIndex, popupFont, popup
Basic background color in the popup context menu color.
The color for drawing dark shades in the popup context menu.
The foreground color for the disabled items in the popup context menu.
The background color for the disabled items in the popup context menu.
Maintains the font of the pop-up context menu associated with the widget.
See also: popupItems, popupColorIndex, popup
The foreground color for the selected items in the popup context menu.
The background color for the selected items in the popup context menu.
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
The color for drawing light shades in the popup context menu.
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
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
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].
See also: designScale
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.
See also: current, currentWidget, selected, selectedWidget, focused
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
Points to the immediate child widget that has the value of the property ::selected set to 1.
See also: current, currentWidget, selectable, selected, focused
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
mb::Left
See also: MouseDown, firstClick, selectable, selected, focused
firstClick
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.
sv::ShapeExtension
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
Maintains the width and height of the widget.
See also: width, height growMode, Move, Size, get_virtual_size, sizeMax, sizeMin
Specifies the maximal size for the widget.
See also: width, height, size growMode, Move, Size, get_virtual_size, sizeMin
Specifies the minimal size for the widget.
See also: width, height, size growMode, Move, Size, get_virtual_size, sizeMax
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.
classic
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.
ownerSkin
Note: this is not a symmetric property, as a $self->skin($self->skin) call is not idempotent.
$self->skin($self->skin)
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.
See also: invalidate_rect, repaint, validate_rect, Paint
repaint
validate_rect
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
next_tab
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
tabOrder
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.
TEXT
See Prima::Drawable::Markup, examples/markup.pl
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
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.
buffered
Specifies whether the widget is visible or not. See "Visibility".
See also: Show, Hide, showing, exposed
showing
exposed
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::XXX
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
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.
get_widgets
Maintains the width of the widget.
See also: height growMode, Move, Size, get_virtual_size, sizeMax, sizeMin
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.
centered
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.
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.
dnd_start
%OPTIONS
text => DATA
image => DATA
DATA
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).
dnd::None
Prima::InputLine
Prima::Edit
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 ).
wantarray
self_aware
The following input is recognized:
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.
actions
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.
INPUT
FORMAT
If not set, the caller needs to fill the clipboard in advance, f.ex. to offer data in more than one format.
Shortcut for format => 'Image', data => $INPUT, preview => $INPUT
format => 'Image', data => $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.
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.
dndAware
Shortcut for format => 'Text', data => $INPUT, preview => $INPUT
format => 'Text', data => $INPUT, preview => $INPUT
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.
track
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.
Sends the widget on top of all other sibling widgets
See also: insert_behind, send_to_back, ZOrderChanged ,first, next, prev, last
insert_behind
send_to_back
first
next
prev
last
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.
clear_event
See also: Close, close
close
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
Calls can_close(), and if successful, destroys the widget. Returns the can_close() result.
can_close()
See also: can_close, Close
can_close
Alias for the focused(0) call
focused(0)
See also: focus, focused, Enter, Leave
focus
Alias for the selected(0) call
selected(0)
See also: select, selected, Enter, Leave
select
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.
ACTIONS
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.
DragResponse
See begin_drag for the wrapper over this method that extends this functionality.
See also: Drag and Drop, DragQuery, DragResponse.
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
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'.
Returns the first ( from bottom ) sibling widget in Z-order.
See also: last, next, prev
Alias for focused(1) call
focused(1)
See also: defocus, focused, Enter, Leave
defocus
Sets widget ::visible to 0.
See also: hide, visible, Show, Hide, showing, exposed
hide
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.
show_cursor
See also: show_cursor, cursorVisible
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.
::helpContext
See also: helpContext
helpContext
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.
owner
Has two calling formats:
$parent-> insert( 'Child::Class', name => 'child', .... );
$parent-> insert( [ 'Child::Class1', name => 'child1', .... ], [ 'Child::Class2', name => 'child2', .... ], );
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
bring_to_front
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
get_invalid_rect
syncPaint
update_view
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.
begin_paint/end_paint
See also: "buffered"
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.
layered
See also: "layered"
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_up
key_event
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.
cm::KeyDown
cm::KeyUp
See also: key_down, key_up, KeyDown, KeyUp
key_down
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
Returns the last ( the topmost ) sibling widget in Z-order.
See also: first, next, prev
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.
lock
unlock
See also: unlock, repaint, Paint, get_locked
get_locked
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.
cl::XXX
See also: colorIndex
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
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
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
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.
cm::MouseDown
cm::MouseUp
cm::MouseWheel
cm::MouseClick
cm::MouseMove
cm::MouseEnter
cm::MouseLeave
See also: mouse_down, mouse_up, mouse_wheel, mouse_click, mouse_move, mouse_enter, mouse_leave, MouseDown, MouseUp, MouseWheel, MouseClick, MouseMove, MouseEnter, MouseLeave
mouse_down
mouse_up
mouse_wheel
mouse_click
mouse_move
mouse_enter
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
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
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
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
Returns the neighbor sibling widget, next ( above ) in the Z-order. If none is found, undef is returned.
See also: first, last, prev
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
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.
See also: next_tab, origin
Returns the neighbor sibling widget, previous ( below ) in the Z-order. If none is found, undef is returned.
See also: first, last, next
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
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:
rect3d
@RECT
If set, the area is filled with COLOR, otherwise is left intact.
The width of the border in pixels
If 1, draws a concave area, or a bulged area otherwise
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
Maps array of X and Y integer offsets from screen to widget coordinates. Returns the mapped OFFSETS.
See also: client_to_screen
Scrolls the graphic context area by DELTA_X and DELTA_Y pixels. The OPTIONS is a hash that may contain the following optional parameters:
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.
The scrolling area is confined by the X1, Y1, X2, Y2 rectangle. If not specified, the scrolling area covers the whole widget.
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
Alias for selected(1) call
selected(1)
See also: deselect, selected, Enter, Leave
deselect
Sends the widget to the bottom of all other sibling widgets
See also: insert_behind, bring_to_front, ZOrderChanged ,first, next, prev, last
Sets the widget's ::visible property to 1.
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
hide_cursor
Returns the boolean value indicating whether the widget and its owners have all ::visible property set to 1 or not.
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
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.
scroll
See also: invalidate_rect, get_invalid_rect, repaint, Paint, syncPaint, update_view
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.
Returns the default font for the Prima::Widget class.
See also: font
Returns the default font for the Prima::Popup class.
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
Returns the system handle for the widget
See also: get_parent_handle, Window::get_client_handle
get_parent_handle
Window::get_client_handle
Returns 1 if the lock() was called and all repaints are effectively blocked.
See also: lock, unlock
Returns a combination of the mb::XXX constants that reflects the currently pressed mouse buttons.
See also: pointerPos, get_shift_state
pointerPos
get_shift_state
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.
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_handle
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.
Returns a combination of the km::XXX constants that reflects the currently pressed keyboard modifier buttons.
See also: get_shift_state
Returns the virtual width and height of the widget. See "Geometry", Implicit size regulations.
See also: width, height, size growMode, Move, Size, sizeMax, sizeMin
Returns the list of the children widgets.
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.
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.
Triggered by the can_close() and close() functions. If the event flag is cleared during execution, these functions return the false value.
close()
See also: close, can_close
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.
Triggered by a successful enabled(0) call
enabled(0)
See also: Enable, enabled, responsive
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.
CLIPBOARD
ACTION
MOD
kb::
X
Y
COUNTERPART is set to the Prima DND sender widget if the session was initiated within the same program; is undef otherwise.
COUNTERPART
See also: "Drag and Drop", DragOver, DragEnd
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:
DragBegin
ANSWER
Is pre-set to 1. If changed to 0, a signal will be sent to the sender that the drop request is not accepted.
A dnd:: constant (not a combination) to be returned to the sender with the action the receiver has accepted, if any.
See also: "Drag and Drop", DragBegin, DragOver
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:
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.
A dnd:: constant (not a combination) to be returned to the sender with the action the receiver is ready to accept, if any.
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.
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.
Escape
km::Escape
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.
$ANSWER->{allow}
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.
$ANSWER->{action}
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
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.
ALLOW
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.
See also: "Drag and Drop", dnd_start, begin_drag.
Triggered by a successful enabled(1) call
enabled(1)
See also: Disable, enabled, responsive
Called when the widget receives the input focus.
See also: Leave, focused, selected
Called when the widget font is changed either by the direct property change call or by the system.
See also: font, ColorChanged
Triggered by a successful visible(0) call
visible(0)
See also: Show, visible, showing, exposed
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
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::
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.
kb::PgDn
kb::PageDown
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
kb::Backspace kb::Tab kb::Linefeed kb::Enter kb::Return kb::Escape kb::Esc kb::Space
kb::F1 .. kb::F30 kb::L1 .. kb::L10 kb::R1 .. kb::R10
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
briefKeys
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
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
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
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
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
Occurs when the mouse pointer leaves the area occupied by the widget.
See also: MouseDown, MouseUp, MouseClick, MouseWheel, MouseMove, MouseEnter
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
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
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 ).
Prima::SpinEdit
step
pageStep
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
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
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.
Triggered by a successful visible(1) call
visible(1)
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
Same as in Component except that the following Widget properties can also trigger it:
Component
Widget
"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.
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.
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
Dmitry Karasik, <dmitry@karasik.eu.org>.
Prima, Prima::Object, Prima::Drawable.
To install Prima, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Prima
CPAN shell
perl -MCPAN -e shell install Prima
For more information on module installation, please visit the detailed CPAN module installation guide.