1pod::Prima::Widget(3) User Contributed Perl Documentationpod::Prima::Widget(3)
2
6 Prima::Widget - window management
7
9 # create a widget
10 my $widget = Prima::Widget-> new(
11 size => [ 200, 200],
12 color => cl::Green,
13 visible => 0,
14 onPaint => sub {
15 my ($self,$canvas) = @_;
16 $canvas-> clear;
17 $canvas-> text_out( "Hello world!", 10, 10);
18 },
19 );
20 # manipulate the widget
22 $widget-> origin( 10, 10);
23 $widget-> show;
24
26 Prima::Widget is a descendant of Prima::Component, a class, especially
27 crafted to reflect and govern properties of a system-dependent window,
28 such as its position, hierarchy, outlook etc. Prima::Widget is mapped
29 into the screen space as a rectangular area, with distinct boundaries,
30 pointer and sometimes cursor, and a user-selectable input focus.
31
33 Prima::Widget class and its descendants are used widely throughout the
34 toolkit, and, indeed provide almost all its user interaction and input-
35 output. The notification system, explained in Prima::Object, is
36 employed in Prima::Widget heavily, providing the programmer with
37 unified access to the system-generated events, that occur when the user
38 moves windows, clicks the mouse, types the keyboard, etc. Descendants
39 of Prima::Widget use the internal, the direct method of overriding the
40 notifications, whereas end programs tend to use the toolkit widgets
41 equipped with anonymous subroutines ( see Prima::Object for the
42 details).
43 The class functionality is much more extensive comparing to the other
45 built-in classes, and therefore the explanations are grouped in several
46 topics.
47
49 The widget creation syntax is the same as for the other Prima objects:
50 Prima::Widget-> create(
52 name => 'Widget',
53 size => [ 20, 10],
54 onMouseClick => sub { print "click\n"; },
55 owner => $owner,
56 );
57 In the real life, a widget must be almost always explicitly told about
59 its owner. The owner object is either a Prima::Widget descendant, in
60 which case the widget is drawn inside its inferior, or the application
61 object, and in the latter case a widget becomes top-level. This is the
62 reason why the "insert" syntax is much more often used, as it is more
63 illustrative and is more convenient for creating several widgets in one
64 call ( see Prima::Object ).
65 $owner-> insert( 'Prima::Widget',
67 name => 'Widget',
68 size => [ 20, 10],
69 onMouseClick => sub { print "click\n"; },
70 );
71 These two examples produce identical results.
73 As a descendant of Prima::Component, Prima::Widget sends "Create"
75 notification when created ( more precisely, after its init stage is
76 finished. See Prima::Object for details). This notification is called
77 and processed within "create()" call. In addition, another notification
78 "Setup" is sent after the widget is created. This message is posted, so
79 it is called within "create()" but processed in the application event
80 loop. This means that the execution time of "Setup" is uncertain, as it
81 is with all posted messages; its delivery time is system-dependent, so
82 its use must be considered with care.
83 After a widget is created, it is usually asked to render its content,
85 provided that the widget is visible. This request is delivered by means
86 of "Paint" notification.
87 When the life time of a widget is over, its method "destroy()" is
89 called, often implicitly. If a widget gets destroyed because its owner
90 also does, it is guaranteed that the children widgets will be destroyed
91 first, and the owner afterwards. In such situation, widget can operate
92 with a limited functionality both on itself and its owners ( see
93 Prima::Object, Creation section ).
94
96 A widget can use two different ways for representing its graphic
97 content to the user. The first method is event-driven, when the "Paint"
98 notification arrives, notifying the widget that it must re-paint
99 itself. The second is the 'direct' method, when the widget generates
100 graphic output unconditionally.
101 Event-driven rendering
103 A notification responsible for widget repainting is "Paint". It
104 provides a single ( besides the widget itself ) parameter, an object,
105 where the drawing is performed. In an event-driven call, it is always
106 equals to the widget. However, if a custom mechanism should be used
107 that directly calls, for example,
108 $widget-> notify('Paint', $some_other_widget);
110 for whatever purpose, it is recommended ( not required, though ), to
112 use this parameter, not the widget itself for painting and drawing
113 calls.
114 The example of "Paint" callback is quite simple:
116 Prima::Widget-> create(
118 ...
119 onPaint => sub {
120 my ( $self, $canvas) = @_;
121 $canvas-> clear;
122 $canvas-> text_out("Clicked $self->{clicked} times", 10, 10);
123 },
124 onMouseClick => sub {
125 $_[0]-> {clicked}++;
126 $_[0]-> repaint;
127 },
128 );
129 The example uses several important features of the event-driven
131 mechanism. First, no "begin_paint()"/"end_paint()" brackets are used
132 within the callback. These are called implicitly. Second, when the
133 custom refresh of the widget's graphic content is needed, no code like
134 "notify(q(Paint))" is used - "repaint()" method is used instead. It
135 must be noted, that the actual execution of "Paint" callbacks might or
136 might not occur inside the "repaint()" call. This behavior is governed
137 by the "::syncPaint" property. "repaint()" marks the whole widget's
138 area to be refreshed, or invalidates the area. For the finer gradation
139 of the area that should be repainted, "invalidate_rect()" and
140 "validate_rect()" pair of functions is used. Thus,
141 $x-> repaint()
143 code is a mere alias to
145 $x-> invalidate_rect( 0, 0, $x-> size);
147 call. It must be realized, that the area, passed to "invalidate_rect()"
149 only in its ideal ( but a quite often ) execution case will be
150 pertained as a clipping rectangle when a widget executes its "Paint"
151 notification. The user and system interactions can result in
152 exposition of other parts of a widget ( like, moving windows over a
153 widget ), and the resulting clipping rectangle can be different from
154 the one that was passed to "invalidate_rect()". Moreover, the clipping
155 rectangle can become empty as the result of these influences, and the
156 notification will not be called at all.
157 Invalid rectangle is presented differently inside and outside the
159 drawing mode. The first, returned by "::clipRect", employs inclusive-
160 inclusive coordinates, whereas "invalidate_rect()", "validate_rect()"
161 and "get_invalid_rect()" - inclusive-exclusive coordinates. The ideal
162 case exemplifies the above said:
163 $x-> onPaint( sub {
165 my @c = $_[0]-> clipRect;
166 print "clip rect:@c\n";
167 });
168 $x-> invalidate_rect( 10, 10, 20, 20);
169 ...
170 clip rect: 10 10 19 19
171 As noted above, "::clipRect" property is set to the clipping rectangle
173 of the widget area that is needed to be refreshed, and an event handler
174 code can take advantage of this information, increasing the efficiency
175 of the painting procedure.
176 Further assignments of "::clipRect" property do not make possible over-
178 painting on the screen area that lies outside the original clipping
179 region. This is also valid for all paint operations, however since the
180 original clipping rectangle is the full area of a canvas, this rule is
181 implicit and unnecessary, because whatever large the clipping rectangle
182 is, drawing and painting cannot be performed outside the physical
183 boundaries of the canvas.
184 Direct rendering
186 The direct rendering, contrary to the event-driven, is initiated by the
187 program, not by the system. If a programmer wishes to paint over a
188 widget immediately, then "begin_paint()" is called, and, if successful,
189 the part of the screen occupied by the widget is accessible to the
190 drawing and painting routines.
191 This method is useful, for example, for graphic demonstration programs,
193 that draw continuously without any input. Another field is the screen
194 drawing, which is performed with Prima::Application class, that does
195 not have "Paint" notification. Application's graphic canvas represents
196 the whole screen, allowing over-drawing the graphic content of other
197 programs.
198 The event-driven rendering method adds implicit
200 "begin_paint()"/"end_paint()" brackets ( plus some system-dependent
201 actions ) and is a convenience version of the direct rendering.
202 Sometimes, however, the changes needed to be made to a widget's graphic
203 context are so insignificant, so the direct rendering method is
204 preferable, because of the cleaner and terser code. As an example might
205 serve a simple progress bar, that draws a simple colored bar. The
206 event-driven code would be ( in short, omitting many details ) as such:
207 $bar = Widget-> create(
209 width => 100,
210 onPaint => sub {
211 my ( $self, $canvas) = @_;
212 $canvas-> color( cl::Blue);
213 $canvas-> bar( 0, 0, $self-> {progress}, $self-> height);
214 $canvas-> color( cl::Back);
215 $canvas-> bar( $self-> {progress}, 0, $self-> size);
216 },
217 );
218 ...
219 $bar-> {progress} += 10;
220 $bar-> repaint;
221 # or, more efficiently, ( but clumsier )
222 # $bar-> invalidate_rect( $bar->{progress}-10, 0,
223 # $bar->{progress}, $bar-> height);
224 And the direct driven:
226 $bar = Widget-> create( width => 100 );
228 ...
229 $bar-> begin_paint;
230 $bar-> color( cl::Blue);
231 $bar-> bar( $progress, 0, $progress + 10, $bar-> height);
232 $bar-> end_paint;
233 $progress += 10;
234 The pros and contras are obvious: the event-driven rendered widget
236 correctly represents the status after an eventual repaint, for example
237 when the user sweeps a window over the progress bar widget. The direct
238 method cannot be that smart, but if the status bar is an insignificant
239 part of the program, the trade-off of the functionality in favor to the
240 code simplicity might be preferred.
241 Both methods can be effectively disabled using the paint locking
243 mechanism. The "lock()" and "unlock()" methods can be called several
244 times, stacking the requests. This feature is useful because many
245 properties implicitly call "repaint()", and if several of these
246 properties activate in a row, the unnecessary redrawing of the widget
247 can be avoided. The drawback is that the last "unlock()" call triggers
248 "repaint()" unconditionally.
249
251 Basic properties
252 A widget always has its position and size determined, even if it is not
253 visible on the screen. Prima::Widget provides several properties with
254 overlapping functionality, that govern the geometry of a widget. The
255 base properties are "::origin" and "::size", and the derived are
256 "::left", "::bottom", "::right", "::top", "::width", "::height" and
257 "::rect". "::origin" and "::size" operate with two integers, "::rect"
258 with four, others with one integer value.
259 As the Prima toolkit coordinate space begins in the lower bottom
261 corner, the combination of "::left" and "::bottom" is same as
262 "::origin", and combination of "::left", "::bottom", "::right" and
263 "::top" - same as "::rect".
264 When a widget is moved or resized, correspondingly two notifications
266 occur: "Move" and "Size". The parameters to both are old and new
267 position and size. The notifications occur irrespectable to whether the
268 geometry change was issued by the program itself or by the user.
269 Implicit size regulations
271 Concerning the size of a widget, two additional two-integer properties
272 exist, "::sizeMin" and "::sizeMax", that constrain the extension of a
273 widget in their boundaries. The direct call that assigns values to the
274 size properties that lie outside "::sizeMin" and "::sizeMax"
275 boundaries, will fail - the widget extension will be adjusted to the
276 boundary values, not to the specified ones.
277 Change to widget's position and size can occur not only by an explicit
279 call to one of the geometry properties. The toolkit contains implicit
280 rules, that can move and resize a widget corresponding to the flags,
281 given to the "::growMode" property. The exact meaning of the "gm::XXX"
282 flags is not given here ( see description to "::growMode" in API
283 section ), but in short, it is possible with simple means to maintain
284 widget's size and position regarding its owner, when the latter is
285 resized. By default, and the default behavior corresponds to
286 "::growMode" 0, widget does not change neither its size nor position
287 when its owner is resized. It stays always in 'the left bottom corner'.
288 When, for example, a widget is expected to stay in 'the right bottom
289 corner', or 'the left top corner', the "gm::GrowLoX" and "gm::GrowLoY"
290 values must be used, correspondingly. When a widget is expected to
291 cover, for example, its owner's lower part and change its width in
292 accord with the owner's, ( a horizontal scroll bar in an editor window
293 is the example), the "gm::GrowHiX" value must be used.
294 When this implicit size change does occur, the "::sizeMin" and
296 "::sizeMax" do take their part as well - they still do not allow the
297 widget's size to exceed their boundaries. However, this algorithm has a
298 problem, that is illustrated by the following setup. Imagine a widget
299 with size-dependent "::growMode" ( with "gm::GrowHiX" or "gm::GrowHiY"
300 bits set ) that must maintain certain relation between the owner's size
301 and its own. If the implicit size change would depend on the actual
302 widget size, derived as a result from the previous implicit size
303 action, then its size (and probably position) will be incorrect after
304 an attempt is made to change the widget's size to values outside the
305 size boundaries.
306 Example: child widget has width 100, growMode set to "gm::GrowHiX" and
308 sizeMin set to (95, 95). Its owner has width 200. If the owner widget
309 changes gradually its width from 200 to 190 and then back, the
310 following width table emerges:
311 Owner Child
313 Initial state 200 100
314 Shrink 195 -5 95
315 Shrink 190 -5 95 - as it can not be less than 95.
316 Grow 195 +5 100
317 Grow 200 +5 105
318 That effect would exist if the differential-size algorithm would be
320 implemented, - the owner changes width by 5, and the child does the
321 same. The situation is fixed by introducing the virtual size term.
322 The "::size" property is derived from virtual size, and as "::size"
323 cannot exceed the size boundaries, virtual size can. It can even
324 accept the negative values. With this intermediate stage added, the
325 correct picture occurs:
326 Owner Child's Child's
328 virtual width width
329 Initial state 200 100 100
330 Shrink 195 -5 95 95
331 Shrink 190 -5 90 95
332 Grow 195 +5 95 95
333 Grow 200 +5 100 100
334 Geometry managers
336 The concept of geometry managers is imported from Tk, which in turn is
337 a port of Tcl-Tk. The idea behind it is that a widget size and position
338 is governed by one of the managers, which operate depending on the
339 specific options given to the widget. The selection is operated by
340 "::geometry" property, and is one of "gt::XXX" constants. The native (
341 and the default ) geometry manager is the described above grow-mode
342 algorithm ( "gt::GrowMode" ). The currently implemented Tk managers are
343 packer ( "gt::Pack" ) and placer ( "gt::Place"). Each has its own set
344 of options and methods, and their manuals are provided separately in
345 Prima::Widget::pack and Prima::Widget::place ( the manpages are also
346 imported from Tk ).
347 Another concept that comes along with geometry managers is the
349 'geometry request size'. It is realized as a two-integer property
350 "::geomSize", which reflects the size deduced by some intrinsic widget
351 knowledge. The idea is that "::geomSize" it is merely a request to a
352 geometry manager, whereas the latter changes "::size" accordingly. For
353 example, a button might set its 'intrinsic' width in accord with the
354 width of text string displayed in it. If the default width for such a
355 button is not overridden, it is assigned with such a width. By default,
356 under "gt::GrowMode" geometry manager, setting "::geomSize" ( and its
357 two semi-alias properties "::geomWidth" and "::geomHeight" ) also
358 changes the actual widget size.Moreover, when the size is passed to the
359 Widget initialization code, "::size" properties are used to initialize
360 "::geomSize". Such design minimizes the confusion between the two
361 properties, and also minimizes the direct usage of "::geomSize",
362 limiting it for selecting advisory size in widget internal code.
363 The geometry request size is useless under "gt::GrowMode" geometry
365 manager, but Tk managers use it extensively.
366 Relative coordinates
368 Another geometry issue, or rather a programming technique must be
369 mentioned - the relative coordinates. It is the well-known problem,
370 when a dialog window, developed with one font looks garbled on another
371 system with another font. The relative coordinates solve that problem;
372 the solution is to use the "::designScale" two-integer property, the
373 width and height of the font, that was used when the dialog window was
374 designed. With this property supplied, the position and size supplied
375 when a widget is actually created, are transformed in proportion
376 between the designed and the actual font metrics.
377 The relative coordinates can be used only when passing the geometry
379 properties values, and only before the creation stage, before a widget
380 is created, because the scaling calculations perform in
381 Prima::Widget::"profile_check_in()" method.
382 In order to employ the relative coordinates scheme, the owner ( or the
384 dialog ) widget must set its "::designScale" to the font metrics and
385 "::scaleChildren" property to 1. Widgets, created with owner that
386 meets these requirements, participate in the relative coordinates
387 scheme. If a widget must be excluded from the relative geometry
388 applications, either the owner's property "::scaleChildren" must be set
389 to 0, or the widget's "::designScale" must be set to "undef". As the
390 default "::designScale" value is "undef", no default implicit relative
391 geometry schemes are applied.
392 The "::designScale" property is auto-inherited; its value is copied to
394 the children widgets, unless the explicit "::designScale" was given
395 during the widget's creation. This is used when such a child widget
396 serves as an owner for some other grand-children widgets; the
397 inheritance scheme allows the grand- ( grand- etc ) children to
398 participate in the relative geometry scheme.
399 Note: it is advised to test such applications with the Prima::Stress
401 module, which assigns a random font as the default, so the testing
402 phase does not involve tweaking of the system settings.
403
405 In case when two widgets overlap, one of these is drawn in full,
406 whereas the another only partly. Prima::Widget provides management of
407 the Z-axis ordering, but since Z-ordering paradigm can hardly be fit
408 into the properties scheme, the toolkit uses methods instead.
409 A widget can use four query methods: "first()", "last()", "next()", and
411 "prev()". These return, correspondingly, the first and the last widgets
412 in Z-order stack, and the direct neighbors of a widget ( $widget->
413 next-> prev always equals to the $widget itself, given that $widget->
414 next exists ).
415 The last widget is the topmost one, the one that is drawn fully. The
417 first is the most obscured one, given that all the widgets overlap.
418 Z-order can also be changed at runtime ( but not during widget's
420 creation). There are three methods: "bring_to_front()", that sets the
421 widget last in the order, making it topmost, "send_to_back()", that
422 does the reverse, and "insert_behind()", that sets a widget behind the
423 another widget, passed as an argument.
424 Changes to Z-order trigger "ZOrderChanged" notification.
426
428 By default, if a widget is a child to a widget or a window, it
429 maintains two features: it is clipped by its owner's boundaries and is
430 moved together as the owner widget moves, i.e. a child is inferior to
431 its parent. However, a widget without a parent still does have a valid
432 owner. Instead of implementing parent property, the "::clipOwner"
433 property was devised. It is 1 by default, and if it is 1, then owner of
434 a widget is its parent, at the same time. However, when it is 0, many
435 things change. The widget is neither clipped nor moved together with
436 its parent. The widget become parentless, or, more strictly speaking,
437 the screen becomes its parent. Moreover, the widget's origin offset is
438 calculated then not from the owner's coordinates but from the screen,
439 and mouse events in the widget do not transgress implicitly to the
440 owner's top-level window eventual decorations.
441 The same results are produced if a widget is inserted in the
443 application object, which does not have screen visualization. A widget
444 that belongs to the application object, can not reset its "::clipOwner"
445 value to 1.
446 The "::clipOwner" property opens a possibility for the toolkit widgets
448 to live inside other programs' windows. If the "::parentHandle" is
449 changed from its default "undef" value to a valid system window handle,
450 the widget becomes child to this window, which can belong to any
451 application residing on the same display. This option is dangerous,
452 however: normally widgets never get destroyed by no reason. A top-level
453 window is never destroyed before its "Close" notification grants the
454 destruction. The case with "::parentHandle" is special, because a
455 widget, inserted into an alien application, must be prepared to be
456 destroyed at any moment. It is recommended to use prior knowledge about
457 such the application, and, even better, use one or another inter-
458 process communication scheme to interact with it.
459 A widget does not need to undertake anything special to become an
461 'owner'. Any widget, that was set in "::owner" property on any other
462 widget, becomes an owner automatically. Its "get_widgets()" method
463 returns non-empty widget list. "get_widgets()" serves same purpose as
464 Prima::Component::"get_components()", but returns only Prima::Widget
465 descendants.
466 A widget can change its owner at any moment. The "::owner" property is
468 both readable and writable, and if a widget is visible during the owner
469 change, it is immediately appeared under different coordinates and
470 different clipping condition after the property change, given that its
471 "::clipOwner" is set to 1.
472
474 A widget is created visible by default. Visible means that it is shown
475 on the screen if it is not shadowed by other widgets or windows. The
476 visibility is governed by the "::visible" property, and its two
477 convenience aliases, "show()" and "hide()".
478 When a widget is invisible, its geometry is not discarded; the widget
480 pertains its position and size, and is subject to all previously
481 discussed implicit sizing issues. When change to "::visible" property
482 is made, the screen is not updated immediately, but in the next event
483 loop invocation, because uncovering of the underlying area of a hidden
484 widget, and repainting of a new-shown widget both depend onto the
485 event-driven rendering functionality. If the graphic content must be
486 updated, "update_view()" must be called, but there's a problem. It is
487 obvious that if a widget is shown, the only content to be updated is
488 its own. When a widget becomes hidden, it may uncover more than one
489 widget, depending on the geometry, so it is unclear what widgets must
490 be updated. For the practical reasons, it is enough to get one event
491 loop passed, by calling "yield()" method of the $::application object.
492 The other notifications may pass here as well, however.
493 There are other kinds of visibility. A widget might be visible, but one
495 of its owners might not. Or, a widget and its owners might be visible,
496 but they might be over-shadowed by the other windows. These conditions
497 are returned by "showing()" and "exposed()" functions, correspondinly.
498 These return boolean values corresponding to the condition described.
499 So, if a widget is 'exposed', it is 'showing' and 'visible';
500 "exposed()" returns always 0 if a widget is either not 'showing' or not
501 'visible'. If a widget is 'showing', then it is always 'visible'.
502 "showing()" returns always 0 if a widget is invisible.
503 Visibility changes trigger "Hide" and "Show" notifications.
505
507 One of the key points of any GUI is that only one window at a time can
508 possess a focus. The widget is focused, if the user's keyboard input is
509 directed to it. The toolkit adds another layer in the focusing scheme,
510 as often window managers do, highlighting the decorations of a top-
511 level window over a window with the input focus.
512 Prima::Widget property "::focused" governs the focused state of a
514 widget. It is sometimes too powerful to be used. Its more often
515 substitutes, "::selected" and "::current" properties provide more
516 respect to widget hierarchy.
517 "::selected" property sets focus to a widget if it is allowed to be
519 focused, by the usage of the "::selectable" property. With this
520 granted, the focus is passed to the widget or to the one of its (
521 grand-) children. So to say, when 'selecting' a window with a text
522 field by clicking on a window, one does not expect the window itself to
523 be focused, but the text field. To achieve this goal and reduce
524 unnecessary coding, the "::current" property is introduced. With all
525 equal conditions, a widget that is 'current' gets precedence in getting
526 selected over widgets that are not 'current'.
527 De-selecting, in its turn, leaves the system in such a state when no
529 window has input focus. There are two convenience shortcuts "select()"
530 and "deselect()" defined, aliased to selected(1) and selected(0),
531 correspondingly.
532 As within the GUI space, there can be only one 'focused' widget, so
534 within the single widget space, there can be only one 'current' widget.
535 A widget can be marked as a current by calling "::current" ( or,
536 identically, "::currentWidget" on the owner widget ). The
537 reassignments are performed automatically when a widget is focused.
538 The reverse is also true: if a widget is explicitly marked as
539 'current', and belongs to the widget tree with the focus in one of its
540 widgets, then the focus passed to the 'current' widget, or down to its
541 hierarchy if it is not selectable.
542 These relations between current widget pointer and focus allow the
544 toolkit easily implement the focusing hierarchy. The focused widget is
545 always on the top of the chain of its owner widgets, each of whose is a
546 'current' widget. If, for example, a window that contains a widget that
547 contains a focused button, become un-focused, and then user selects the
548 window again, then the button will become focused automatically.
549 Changes to focus produce "Enter" and "Leave" notifications.
551 Below discussed mouse- and keyboard- driven focusing schemes. Note
553 that all of these work via "::selected", and do not focus the widgets
554 with "::selectable" property set to 0.
555 Mouse-aided focusing
557 Typically, when the user clicks the left mouse button on a widget, the
558 latter becomes focused. One can note that not all widgets become
559 focused after the mouse click - scroll bars are the examples. Another
560 kind of behavior is the described above window with the text field -
561 clicking mouse on a window focuses a text field.
562 Prima::Widget has the "::selectingButtons" property, a combination of
564 mb::XXX ( mouse buttons ) flags. If the bits corresponding to the
565 buttons are set, then click of this button will automatically call
566 ::selected(1) ( not ::focused(1) ).
567 Another boolean property, "::firstClick" determines the behavior when
569 the mouse button action is up to focus a widget, but the widget's top-
570 level window is not active. The default value of "::firstClick" is 1,
571 but if set otherwise, the user must click twice to a widget to get it
572 focused. The property does not influence anything if the top-level
573 window was already active when the click event occured.
574 Due to different GUI designs, it is hardly possibly to force selection
576 of one top-level window when the click was on the another. The window
577 manager or the OS can interfere, although this does not always happen,
578 and produces different results on different platforms. Since the
579 primary goal of the toolkit is portability, such functionality must be
580 considered with care. Moreover, when the user selects a window by
581 clicking not on the toolkit-created widgets, but on the top-level
582 window decorations, it is not possible to discern the case from any
583 other kind of focusing.
584 Keyboard focusing
586 The native way to navigate between the toolkit widgets are tab- and
587 arrow- navigation. The tab ( and its reverse, shift-tab ) key
588 combinations circulate the focus between the widgets in same top-level
589 group ( but not inside the same owner widget group ). The arrow keys,
590 if the focused widget is not interested in these keystrokes, move the
591 focus in the specified direction, if it is possible. The methods that
592 provide the navigations are available and called "next_tab()" and
593 "next_positional()", correspondingly ( see API for the details).
594 When "next_positional()" operates with the geometry of the widgets,
596 "next_tab()" uses the "::tabStop" and "::tabOrder" properties.
597 "::tabStop", the boolean property, set to 1 by default, tells if a
598 widget is willing to participate in tab-aided focus circulation. If it
599 doesn't, "next_tab()" never uses it in its iterations. "::tabOrder"
600 value is an integer, unique within the sibling widgets ( sharing same
601 owner ) list, and is used as simple tag when the next tab-focus
602 candidate is picked up. The default "::tabOrder" value is -1, which
603 changes automatically after widget creation to a unique value.
604
606 The toolkit responds to the two basic means of the user input - the
607 keyboard and the mouse. Below described three aspects of the input
608 handling - the event-driven, the polling and the simulated input
609 issues. The event-driven input is the more or less natural way of
610 communicating with the user, so when the user presses the key or moves
611 the mouse, a system event occurs and triggers the notification in one
612 or more widgets. Polling methods provide the immediate state of the
613 input devices; the polling is rarely employed, primarily because of its
614 limited usability, and because the information it provides is passed to
615 the notification callbacks anyway. The simulated input is little more
616 than "notify()" call with specifically crafted parameters. It interacts
617 with the system, so the emulation can gain the higher level of
618 similarity to the user actions. The simulated input functions allow the
619 notifications to be called right away, or post it, delaying the
620 notification until the next event loop invocation.
621 Keyboard
623 Event-driven
624 Keyboard input generates several notifications, where the most
625 important are "KeyDown" and "KeyUp". Both have almost the same list
626 of parameters ( see API ), that contain the key code, its modifiers
627 ( if any ) that were pressed and an eventual character code. The
628 algorithms that extract the meaning of the key, for example,
629 discretion between character and functional keys etc are not
630 described here. The reader is advised to look at Prima::KeySelector
631 module, which provides convenience functions for keyboard input
632 values transformations, and to the Prima::Edit and Prima::InputLine
633 modules, the classes that use extensively the keyboard input. But
634 in short, the key code is one of the "kb::XXX" ( like, kb::F10,
635 kb::Esc ) constants, and the modifier value is a combination of the
636 "km::XXX" ( km::Ctrl, km::Shift) constants. The notable exception
637 is kb::None value, which hints that the character code is of value.
638 Some other "kb::XXX"-marked keys have the character code as well,
639 and it is up to a programmer how to treat these combinations. It is
640 advised, however, to look at the key code first, and then to the
641 character code.
642 "KeyDown" event has also the repeat integer parameter, that shows
644 the repetitive count how many times the key was pressed. Usually
645 it is 1, but if a widget was not able to get its portion of events
646 between the key presses, its value can be higher. If a code
647 doesn't check for this parameter, some keyboard input may be lost.
648 If the code will be too much complicated by introducing the repeat-
649 value, one may consider setting the "::briefKeys" property to 0.
650 "::briefKeys", the boolean property, is 1 by default. If set to 0,
651 it guarantees that the repeat value will always be 1, but with the
652 price of certain under-optimization. If the core "KeyDown"
653 processing code sees repeat value greater than 1, it simply calls
654 the notification again.
655 Along with these two notifications, the "TranslateAccel" event is
657 generated after "KeyDown", if the focused widget is not interested
658 in the key event. Its usage covers the needs of the other widgets
659 that are willing to read the user input, even being out of focus.
660 A notable example can be a button with a hot key, that reacts on
661 the key press when the focus is elsewhere within its top-level
662 window. "TranslateAccel" has same parameters as "KeyDown", except
663 the REPEAT parameter.
664 Such out-of-focus input is also used with built-in menu keys
666 translations. If a descendant of Prima::AbstractMenu is in the
667 reach of the widget tree hierarchy, then it is checked whether it
668 contains some hot keys that match the user input. See Prima::Menu
669 for the details. In particular, Prima::Widget has "::accelTable"
670 property, a mere slot for an object that contains a table of hot
671 keys mappings to custom subroutines.
672 Polling
674 The polling function for the keyboard is limited to the modifier
675 keys only. "get_shift_state()" method returns the press state of
676 the modifier keys, a combination of "km::XXX" constants.
677 Simulated input
679 There are two methods, corresponding to the major notifications -
680 "key_up()" and "key_down()", that accept the same parameters as the
681 "KeyUp" and "KeyDown" notifications do, plus the POST boolean flag.
682 See "API" for details.
683 These methods are convenience wrappers for "key_event()" method,
685 which is never used directly.
686 Mouse
688 Event-driven
689 Mouse notifications are send in response when the user moves the
690 mouse, or presses and releases mouse buttons. The notifications
691 are logically grouped in two sets, the first contains "MouseDown",
692 "MouseUp", "MouseClick", and "MouseWheel", and the second -
693 "MouseMove", "MouseEnter", end "MouseLeave".
694 The first set deals with button actions. Pressing, de-pressing,
696 clicking ( and double-clicking ), the turn of mouse wheel
697 correspond to the four notifications. The notifications are sent
698 together with the mouse pointer coordinates, the button that was
699 touched, and the eventual modifier keys that were pressed. In
700 addition, "MouseClick" provides the boolean flag if the click was
701 single or double, and "MouseWheel" the wheel turn amount. These
702 notifications occur when the mouse event occurs within the
703 geometrical bounds of a widget, with one notable exception, when a
704 widget is in capture mode. If the "::capture" is set to 1, then
705 these events are sent to the widget even if the mouse pointer is
706 outside, and not sent to the widgets and windows that reside under
707 the pointer.
708 The second set deals with the pointer movements. When the pointer
710 passes over a widget, it receives first "MouseEnter", then series
711 of "MouseMove", and finally "MouseLeave". "MouseMove" and
712 "MouseEnter" notifications provide X,Y-coordinates and modificator
713 keys; "MouseLeave" passes no parameters.
714 Polling
716 The mouse input polling procedures are "get_mouse_state()" method,
717 that returns combination of "mb::XXX" constants, and the
718 "::pointerPos" two-integer property that reports the current
719 position of the mouse pointer.
720 Simulated input
722 There are five methods, corresponding to the mouse events -
723 "mouse_up()", "mouse_down()", "mouse_click()", "mouse_wheel()" and
724 "mouse_move()", that accept the same parameters as their event
725 counterparts do, plus the POST boolean flag. See "API" for details.
726 These methods are convenience wrappers for "mouse_event()" method,
728 which is never used directly.
729 Drag and drop
731 Widgets can participate in full drag and drop sessions with other
732 applications and itself, with very few restrictions. See below how to
733 use this functionality.
734 Data exchange
736 Prima defines a special clipboard object that serves as an exchange
737 point whenever data is to be either sent or received. In order to
738 either offer to, or choose from, many formats of another DND
739 client, use that clipboard to operate with standard
740 open/fetch/store/close methods (see more at Prima::Clipboard).
741 The clipboard can be accessed at any time by calling "
743 $::application-" get_dnd_clipboard >, however during handling of
744 dropping events it will stay read-only.
745 To successfully exchange data with other applictions, one may
747 investigate results of "$clipboard-> get_formats(1)" to see what
748 types of data the selected application can exchange. With a high
749 probability many programs can exchange text and image in a system-
750 dependent format, however it is also common to see applications to
751 exchange data in format names that match their MIME description.
752 For example Prima supports image formats like "image/bmp" out of
753 the box, and "text/plain" on X11, that are selected automatically
754 when operating with pseudo-formats "Text" or "Image". Other MIME
755 formats like f.ex. "text/html" are not known to Prima, but can be
756 exchanged quite easily; one needs to register that format first
757 using "Clipbpard::register_format", once, and then it is ready for
758 exachange.
759 Dragging
761 To initiate the drag, first fill the DND clipboard with data to be
762 exchanged, using one or more formats, then call either "start_dnd".
763 Alternatively, call "begin_drag", a wrapper method that can set up
764 clipboard data itself. See their documentation for more details.
765 During the dragging, the sender will receive "DragQuery" and
767 "DragResponse" events, in order to decide whether the drag session
768 must continue or stop depending on the user input, and reflect that
769 back to the user. Traditionally, mouse cursors are changed to show
770 whether an application will receive a drop, and if yes, what action
771 (copy, move, or link) it will participate in. Prima will try its
772 best to either use system cursors, or synthesise ones that are
773 informative enough; if that is not sufficient, one may present own
774 cursor schema (see f.ex how "begin_drag" is implemented).
775 Dropping
777 To register a widget as a drop target, set its "dndAware" property
778 to either 1, to mark that it will answer to all formats, or to a
779 string, in which case drop events will only be delivered if the DND
780 clipboard contains a format with that string.
781 Thereafter, when the user will initiate a DND session and will move
783 mouse pointer over the widget, it will receive a "DragBegin" event,
784 then series of "DragOver" events, and finally a "DragEnd" event
785 with a flag telling whether the user chose to drop the data or
786 cancel the session.
787 The "DragOver" and "DragEnd" callbacks have a chance to either
789 allow or deny data, and select an action (if there are more than
790 one allowed by the other application) to proceed with. To do so,
791 set appropriate values to "{allow}" and "{action}" in the last
792 hashref parameter that is sent to these event handlers.
793 Additionally, "DragOver" can set a "{pad}" rectangle that will
794 cache the last answer and will tell the system not to send repeated
795 event with same input while the mouse pointer stays in the same
796 rectangle.
797 Portability
799 X11 and Win32 are rather identical in how they are handing a DND
800 session from the user's perspective. The only difference that is
801 significant to Prima here is whether the sender or the receiver is
802 responsible to select an action for available list of actions, when
803 the user presses modifier keys, like CTRL or SHIFT.
804 On X11, it is the sender that contols that aspect, and tells the
806 receiver what action at any given moment the user chose, by
807 responding to a "DragQuery" event. On Win32, it is the receiver
808 that selects an action from the list on each "DragOver" event,
809 depending on modifier keys pressed by the user; Windows recommends
810 to adhere to the standard scheme where CTRL mark "dnd::Move"
811 action, and SHIFT the "dnd::Link", but that is up to the receiver.
812 Thus, to write an effective portable program, assume that your
814 program may control the actions both as sender and as a receiver;
815 Prima system-dependent code will make sure that there will be no
816 ambiguities on the input. F.ex. a sender on Win32 will never be
817 presented with a combination of several "dnd::" constants inside a
818 "DragQuery" event, and a X11 receiver will similarly never be
819 presented with such combination inside "DragOver". However, a
820 portable program must be prepared to select and return a DND action
821 in either callback.
822 Additionally, a X11 non-Prima receiver, when presented with a
824 multiple choice of actions, may ask the user what action to select,
825 or cancel the session altogether. This is okay and is expected by
826 the user.
827
829 Prima::Drawable deals only with such color values, that can be
830 unambiguously decomposed to their red, green and blue components.
831 Prima::Widget extends the range of the values acceptable by its color
832 properties, introducing the color schemes. The color can be set
833 indirectly, without prior knowledge of what is its RGB value. There are
834 several constants defined in "cl::" name space, that correspond to the
835 default values of different color properties of a widget.
836 Prima::Widget revises the usage of "::color" and "::backColor", the
838 properties inherited from Prima::Drawable. Their values are widget's
839 'foreground' and 'background' colors, in addition to their function as
840 template values. Moreover, their dynamic change induces the repainting
841 of a widget, and they can be inherited from the owner. The inheritance
842 is governed by properties "::ownerColor" and "::ownerBackColor". While
843 these are true, changes to owner "::color" or "::backColor" copied
844 automatically to a widget. Once the widget's "::color" or "::backColor"
845 are explicitly set, the owner link breaks automatically by setting
846 "::ownerColor" or "::ownerBackColor" to 0.
847 In addition to these two color properties, Prima::Widget introduces six
849 others. These are "::disabledColor", "::disabledBackColor",
850 "::hiliteColor", "::hiliteBackColor", "::light3DColor", and
851 "::dark3DColor". The 'disabled' color pair contains the values that
852 are expected to be used as foreground and background when a widget is
853 in the disabled state ( see API, "::enabled" property ). The 'hilite'
854 values serve as the colors for representation of selection inside a
855 widget. Selection may be of any kind, and some widgets do not provide
856 any. But for those that do, the 'hilite' color values provide distinct
857 alternative colors. Examples are selections in the text widgets, or in
858 the list boxes. The last pair, "::light3DColor" and "::dark3DColor" is
859 used for drawing 3D-looking outlines of a widget. The purpose of all
860 these properties is the adequate usage of the color settings, selected
861 by the user using system-specific tools, so the program written with
862 the toolkit would look not such different, and more or less conformant
863 to the user's color preferences.
864 The additional "cl::" constants, mentioned above, represent these eight
866 color properties. These named correspondingly, cl::NormalText,
867 cl::Normal, cl::HiliteText, cl::Hilite, cl::DisabledText, cl::Disabled,
868 cl::Light3DColor and cl::Dark3DColor. cl::NormalText is alias to
869 cl::Fore, and cl::Normal - to cl::Back. Another constant set, "ci::"
870 can be used with the "::colorIndex" property, a multiplexer for all
871 eight color properties. "ci::" constants mimic their non-RGB "cl::"
872 counterparts, so the call "hiliteBackColor(cl::Red)" is equal to
873 "colorIndex(ci::Hilite, cl::Red)".
874 Mapping from these constants to the RGB color representation is used
876 with "map_color()" method. These "cl::" constants alone are sufficient
877 for acquiring the default values, but the toolkit provides wider
878 functionality than this. The "cl::" constants can be combined with the
879 "wc::" constants, that represent standard widget class. The widget
880 class is implicitly used when single "cl::" constant is used; its value
881 is read from the "::widgetClass" property, unless one of "wc::"
882 constants is combined with the non-RGB "cl::" value. "wc::" constants
883 are described in "API"; their usage can make call of, for example,
884 "backColor( cl::Back)" on a button and on an input line result in
885 different colors, because the "cl::Back" is translated in the first
886 case into "cl::Back|wc::Button", and in another -
887 "cl::Back|wc::InputLine".
888 Dynamic change of the color properties result in the "ColorChanged"
890 notification.
891
893 Prima::Widget does not change the handling of fonts - the font
894 selection inside and outside "begin_paint()"/"end_paint()" is not
895 different at all. A matter of difference is how does Prima::Widget
896 select the default font.
897 First, if the "::ownerFont" property is set to 1, then font of the
899 owner is copied to the widget, and is maintained all the time while the
900 property is true. If it is not, the default font values read from the
901 system.
902 The default font metrics for a widget returned by "get_default_font()"
904 method, that often deals with system-dependent and user-selected
905 preferences ( see "Additional resources" ). Because a widget can host
906 an eventual Prima::Popup object, it contains "get_default_popup_font()"
907 method, that returns the default font for the popup objects. The
908 dynamic popup font settings governed, naturally, by the "::popupFont"
909 property. Prima::Window extends the functionality to
910 "get_default_menu_font()" and the "::menuFont" property.
911 Dynamic change of the font property results in the "FontChanged"
913 notification.
914
916 The resources, operated via Prima::Widget class but not that strictly
917 bound to the widget concept, are gathered in this section. The section
918 includes overview of pointer, cursor, hint, menu objects and user-
919 specified resources.
920 Pointer
922 The mouse pointer is the shared resource, that can change its visual
923 representation when it hovers over different kinds of widgets. It is
924 usually a good practice for a text field, for example, set the pointer
925 icon to a jagged vertical line, or indicate a moving window with a
926 cross-arrowed pointer.
927 A widget can select either one of the predefined system pointers,
929 mapped by the "cr::XXX" constant set, or supply its own pointer icon of
930 an arbitrary size and color depth.
931 NB: Not all systems allow the colored pointer icons. System value under
933 sv::ColorPointer index containing a boolean value, whether the colored
934 icons are allowed or not. Also, the pointer icon size may have a limit:
935 check if sv::FixedPointerSize is non-zero, in which case the pointer
936 size will be reduced to the system limits.
937 In general, the "::pointer" property is enough for these actions. It
939 discerns whether it has an icon or a constant passed, and sets the
940 appropriate properties. These properties are also accessible
941 separately, although their usage is not encouraged, primarily because
942 of the tangled relationship between them. These properties are:
943 "::pointerType", "::pointerIcon", and "::pointerHotSpot". See their
944 details in the "API" sections.
945 Another property, which is present only in Prima::Application name
947 space is called "::pointerVisible", and governs the visibility of the
948 pointer - but for all widget instances at once.
949 Cursor
951 The cursor is a blinking rectangular area, indicating the availability
952 of the input focus in a widget. There can be only one active cursor per
953 a GUI space, or none at all. Prima::Widget provides several cursor
954 properties: "::cursorVisible", "::cursorPos", and "::cursorSize". There
955 are also two methods, "show_cursor()" and "hide_cursor()", which are
956 not the convenience shortcuts but the functions accounting the cursor
957 hide count. If "hide_cursor()" was called three times, then
958 "show_cursor()" must be called three times as well for the cursor to
959 become visible.
960 Hint
962 "::hint" is a text string, that usually describes the widget's purpose
963 to the user in a brief manner. If the mouse pointer is hovered over the
964 widget longer than some timeout ( see Prima::Application::hintPause ),
965 then a label appears with the hint text, until the pointer is drawn
966 away. The hint behavior is governed by Prima::Application, but a
967 widget can do two additional things about hint: it can enable and
968 disable it by calling "::showHint" property, and it can inherit the
969 owner's "::hint" and "::showHint" properties using "::ownerHint" and
970 "::ownerShowHint" properties. If, for example, "::ownerHint" is set to
971 1, then "::hint" value is automatically copied from the widget's owner,
972 when it changes. If, however, the widget's "::hint" or "::showHint" are
973 explicitly set, the owner link breaks automatically by setting
974 "::ownerHint" or "::ownerShowHint" to 0.
975 The widget can also operate the "::hintVisible" property, that shows or
977 hides the hint label immediately, if the mouse pointer is inside the
978 widget's boundaries.
979 Menu objects
981 The default functionality of Prima::Widget coexists with two kinds of
982 the Prima::AbstractMenu descendants - Prima::AccelTable and
983 Prima::Popup ( Prima::Window is also equipped with Prima::Menu
984 reference). The "::items" property of these objects are accessible
985 through "::accelItems" and "::popupItems", whereas the objects
986 themselves - through "::accelTable" and "::popup", correspondingly. As
987 mentioned in "User input", these objects hook the user keyboard input
988 and call the programmer-defined callback subroutine if the key stroke
989 equals to one of their table values. As for "::accelTable", its
990 function ends here. "::popup" provides access to a context pop-up menu,
991 which can be invoked by either right-clicking or pressing a system-
992 dependent key combination. As a little customization, the
993 "::popupColorIndex" and "::popupFont" properties are introduced. (
994 "::popupColorIndex" is multiplexed to "::popupColor",
995 "::popupHiliteColor", "::popupHiliteBackColor", etc etc properties
996 exactly like the "::colorIndex" property ).
997 The font and color of a menu object might not always be writable
999 (Win32).
1000 The Prima::Window class provides equivalent methods for the menu bar,
1002 introducing "::menu", "::menuItems", "::menuColorIndex" ( with
1003 multiplexing ) and "::menuFont" properties.
1004 User-specified resources
1006 It is considered a good idea to incorporate the user preferences into
1007 the toolkit look-and-feel. Prima::Widget relies to the system-specific
1008 code that tries to map these preferences as close as possible to the
1009 toolkit paradigm.
1010 Unix version employs XRDB ( X resource database ), which is the natural
1012 way for the user to tell the preferences with fine granularity. Win32
1013 reads the setting that the user has to set interactively, using system
1014 tools. Nevertheless, the toolkit can not emulate all user settings that
1015 are available on the supported platforms; it rather takes a 'least
1016 common denominator', which is colors and fonts. "fetch_resource()"
1017 method is capable of returning any of such settings, provided it's
1018 format is font, color or a string. The method is rarely called
1019 directly.
1020 The appealing idea of making every widget property adjustable via the
1022 user-specified resources is not implemented in full. It can be
1023 accomplished up to a certain degree using "fetch_resource()" existing
1024 functionality, but it is believed that calling up the method for the
1025 every property for the every widget created is prohibitively expensive.
1026
1028 Properties
1029 accelItems [ ITEM_LIST ]
1030 Manages items of a Prima::AccelTable object associated with a
1031 widget. The ITEM_LIST format is same as
1032 "Prima::AbstractMenu::items" and is described in Prima::Menu.
1033 See also: "accelTable"
1035 accelTable OBJECT
1037 Manages a Prima::AccelTable object associated with a widget. The
1038 sole purpose of the accelTable object is to provide convenience
1039 mapping of key combinations to anonymous subroutines. Instead of
1040 writing an interface specifically for Prima::Widget, the existing
1041 interface of Prima::AbstractMenu was taken.
1042 The accelTable object can be destroyed safely; its cancellation can
1044 be done either via "accelTable(undef)" or "destroy()" call.
1045 Default value: undef
1047 See also: "accelItems"
1049 autoEnableChildren BOOLEAN
1051 If TRUE, all immediate children widgets maintain the same "enabled"
1052 state as the widget. This property is useful for the group-like
1053 widgets ( ComboBox, SpinEdit etc ), that employ their children for
1054 visual representation.
1055 Default value: 0
1057 backColor COLOR
1059 In widget paint state, reflects background color in the graphic
1060 context. In widget normal state, manages the basic background
1061 color. If changed, initiates "ColorChanged" notification and
1062 repaints the widget.
1063 See also: "color", "colorIndex", "ColorChanged"
1065 bottom INTEGER
1067 Maintains the lower boundary of a widget. If changed, does not
1068 affect the widget height; but does so, if called in "set()"
1069 together with "::top".
1070 See also: "left", "right", "top", "origin", "rect", "growMode",
1072 "Move"
1073 briefKeys BOOLEAN
1075 If 1, contracts the repetitive key press events into one
1076 notification, increasing REPEAT parameter of "KeyDown" callbacks.
1077 If 0, REPEAT parameter is always 1.
1078 Default value: 1
1080 See also: "KeyDown"
1082 buffered BOOLEAN
1084 If 1, a widget "Paint" callback draws not on the screen, but on the
1085 off-screen memory instead. The memory content is copied to the
1086 screen then. Used when complex drawing methods are used, or if
1087 output smoothness is desired.
1088 This behavior can not be always granted, however. If there is not
1090 enough memory, then widget draws in the usual manner.
1091 Default value: 0
1093 See also: "Paint"
1095 capture BOOLEAN, CLIP_OBJECT = undef
1097 Manipulates capturing of the mouse events. If 1, the mouse events
1098 are not passed to the widget the mouse pointer is over, but are
1099 redirected to the caller widget. The call for capture might not be
1100 always granted due the race conditions between programs.
1101 If CLIP_OBJECT widget is defined in set-mode call, the pointer
1103 movements are confined to CLIP_OBJECT inferior.
1104 See also: "MouseDown", "MouseUp", "MouseMove", "MouseWheel",
1106 "MouseClick".
1107 centered BOOLEAN
1109 A write-only property. Once set, widget is centered by X and Y axis
1110 relative to its owner.
1111 See also: "x_centered", "y_centered", "growMode", "origin", "Move".
1113 clipChildren BOOLEAN
1115 Affects the drawing mode when children widgets are present and
1116 obscuring the drawing area. If set, the children widgets are
1117 automatically added to the clipping area, and drawing over them
1118 will not happen. If unset, the painting can be done over the
1119 children widgets.
1120 Default: 1
1122 clipOwner BOOLEAN
1124 If 1, a widget is clipped by its owner boundaries. It is the
1125 default and expected behavior. If clipOwner is 0, a widget behaves
1126 differently: it does not clipped by the owner, it is not moved
1127 together with the parent, the origin offset is calculated not from
1128 the owner's coordinates but from the screen, and mouse events in a
1129 widget do not transgress to the top-level window decorations. In
1130 short, it itself becomes a top-level window, that, contrary to the
1131 one created from Prima::Window class, does not have any
1132 interference with system-dependent window stacking and positioning
1133 ( and any other ) policy, and is not ornamented by the window
1134 manager decorations.
1135 Default value: 1
1137 See "Parent-child relationship"
1139 See also: "Prima::Object" owner section, "parentHandle"
1141 color COLOR
1143 In widget paint state, reflects foreground color in the graphic
1144 context. In widget normal state, manages the basic foreground
1145 color. If changed, initiates "ColorChanged" notification and
1146 repaints the widget.
1147 See also: "backColor", "colorIndex", "ColorChanged"
1149 colorIndex INDEX, COLOR
1151 Manages the basic color properties indirectly, by accessing via
1152 "ci::XXX" constant. Is a complete alias for "::color",
1153 "::backColor", "::hiliteColor", "::hiliteBackColor",
1154 "::disabledColor", "::disabledBackColor", "::light3DColor", and
1155 "::dark3DColor" properties. The "ci::XXX" constants are:
1156 ci::NormalText or ci::Fore
1158 ci::Normal or ci::Back
1159 ci::HiliteText
1160 ci::Hilite
1161 ci::DisabledText
1162 ci::Disabled
1163 ci::Light3DColor
1164 ci::Dark3DColor
1165 The non-RGB "cl::" constants, specific to the Prima::Widget color
1167 usage are identical to their "ci::" counterparts:
1168 cl::NormalText or cl::Fore
1170 cl::Normal or cl::Back
1171 cl::HiliteText
1172 cl::Hilite
1173 cl::DisabledText
1174 cl::Disabled
1175 cl::Light3DColor
1176 cl::Dark3DColor
1177 See also: "color", "backColor", "ColorChanged"
1179 current BOOLEAN
1181 If 1, a widget (or one of its children) is marked as the one to be
1182 focused ( or selected) when the owner widget receives "select()"
1183 call. Within children widgets, only one or none at all can be
1184 marked as a current.
1185 See also: "currentWidget", "selectable", "selected",
1187 "selectedWidget", "focused"
1188 currentWidget OBJECT
1190 Points to a children widget, that is to be focused ( or selected)
1191 when the owner widget receives "select()" call.
1192 See also: "current", "selectable", "selected", "selectedWidget",
1194 "focused"
1195 cursorPos X_OFFSET Y_OFFSET
1197 Specifies the lower left corner of the cursor
1198 See also: "cursorSize", "cursorVisible"
1200 cursorSize WIDTH HEIGHT
1202 Specifies width and height of the cursor
1203 See also: "cursorPos", "cursorVisible"
1205 cursorVisible BOOLEAN
1207 Specifies cursor visibility flag. Default value is 0.
1208 See also: "cursorSize", "cursorPos"
1210 dark3DColor COLOR
1212 The color used to draw dark shades.
1213 See also: "light3DColor", "colorIndex", "ColorChanged"
1215 designScale X_SCALE Y_SCALE
1217 The width and height of a font, that was used when a widget (
1218 usually a dialog or a grouping widget ) was designed.
1219 See also: "scaleChildren", "width", "height", "size", "font"
1221 disabledBackColor COLOR
1223 The color used to substitute "::backColor" when a widget is in its
1224 disabled state.
1225 See also: "disabledColor", "colorIndex", "ColorChanged"
1227 disabledColor COLOR
1229 The color used to substitute "::color" when a widget is in its
1230 disabled state.
1231 See also: "disabledBackColor", "colorIndex", "ColorChanged"
1233 dndAware 0 | 1 | FORMAT
1235 To register a widget as a drop target, set its "dndAware" property
1236 to either 1, to mark that it will answer to all formats, or to a
1237 string, in which case drop events will only be delivered if the DND
1238 clipboard contains a format with that string.
1239 Default: 0
1241 See also: "Drag and Drop"
1243 enabled BOOLEAN
1245 Specifies if a widget can accept focus, keyboard and mouse events.
1246 Default value is 1, however, being 'enabled' does not automatically
1247 allow the widget become focused. Only the reverse is true - if
1248 enabled is 0, focusing can never happen.
1249 See also: "responsive", "visible", "Enable", "Disable"
1251 font %FONT
1253 Manages font context. Same syntax as in Prima::Drawable. If
1254 changed, initiates "FontChanged" notification and repaints the
1255 widget.
1256 See also: "designScale", "FontChanged", "ColorChanged"
1258 geometry INTEGER
1260 Selects one of the available geometry managers. The corresponding
1261 integer constants are:
1262 gt::GrowMode, gt::Default - the default grow-mode algorithm
1264 gt::Pack - Tk packer
1265 gt::Place - Tk placer
1266 See "growMode", Prima::Widget::pack, Prima::Widget::place.
1268 growMode MODE
1270 Specifies widget behavior, when its owner is resized or moved.
1271 MODE can be 0 ( default ) or a combination of the following
1272 constants:
1273 Basic constants
1275 gm::GrowLoX widget's left side is kept in constant
1276 distance from owner's right side
1277 gm::GrowLoY widget's bottom side is kept in constant
1278 distance from owner's top side
1279 gm::GrowHiX widget's right side is kept in constant
1280 distance from owner's right side
1281 gm::GrowHiY widget's top side is kept in constant
1282 distance from owner's top side
1283 gm::XCenter widget is kept in center on its owner's
1284 horizontal axis
1285 gm::YCenter widget is kept in center on its owner's
1286 vertical axis
1287 gm::DontCare widgets origin is maintained constant relative
1288 to the screen
1289 Derived or aliased constants
1291 gm::GrowAll gm::GrowLoX|gm::GrowLoY|gm::GrowHiX|gm::GrowHiY
1292 gm::Center gm::XCenter|gm::YCenter
1293 gm::Client gm::GrowHiX|gm::GrowHiY
1294 gm::Right gm::GrowLoX|gm::GrowHiY
1295 gm::Left gm::GrowHiY
1296 gm::Floor gm::GrowHiX
1297 See also: "Move", "origin"
1299 firstClick BOOLEAN
1301 If 0, a widget bypasses first mouse click on it, if the top-level
1302 window it belongs to was not activated, so selecting such a widget
1303 it takes two mouse clicks.
1304 Default value is 1
1306 See also: "MouseDown", "selectable", "selected", "focused",
1308 "selectingButtons"
1309 focused BOOLEAN
1311 Specifies whether a widget possesses the input focus or not.
1312 Disregards "::selectable" property on set-call.
1313 See also: "selectable", "selected", "selectedWidget", "KeyDown"
1315 geomWidth, geomHeight, geomSize
1317 Three properties that select geometry request size. Writing and
1318 reading to "::geomWidth" and "::geomHeight" is equivalent to
1319 "::geomSize". The properies are run-time only, and behave
1320 differently under different circumstances:
1321 · As the properties are run-time only, they can not be set in the
1323 profile, and their initial value is fetched from "::size"
1324 property. Thus, setting the explicit size is aditionally sets
1325 the advised size in case the widget is to be used with the Tk
1326 geometry managers.
1327 · Setting the properties under the "gt::GrowMode" geometry
1329 manager also sets the corresponding "::width", "::height", or
1330 "::size". When the properties are read, though, the real size
1331 properties are not read; the values are kept separately.
1332 · Setting the properties under Tk geometry managers cause widgets
1334 size and position changed according to the geometry manager
1335 policy.
1336 height
1338 Maintains the height of a widget.
1339 See also: "width", "growMode", "Move", "Size", "get_virtual_size",
1341 "sizeMax", "sizeMin"
1342 helpContext STRING
1344 A string that binds a widget, a logical part it plays with the
1345 application and an interactive help topic. STRING format is defined
1346 as POD link ( see perlpod ) - "manpage/section", where 'manpage' is
1347 the file with POD content and 'section' is the topic inside the
1348 manpage.
1349 See also: "help"
1351 hiliteBackColor COLOR
1353 The color used to draw alternate background areas with high
1354 contrast.
1355 See also: "hiliteColor", "colorIndex", "ColorChanged"
1357 hiliteColor COLOR
1359 The color used to draw alternate foreground areas with high
1360 contrast.
1361 See also: "hiliteBackColor", "colorIndex", "ColorChanged"
1363 hint TEXT
1365 A text, shown under mouse pointer if it is hovered over a widget
1366 longer than "Prima::Application::hintPause" timeout. The text shows
1367 only if the "::showHint" is 1.
1368 See also: "hintVisible", "showHint", "ownerHint", "ownerShowHint"
1370 hintVisible BOOLEAN
1372 If called in get-form, returns whether the hint label is shown or
1373 not. If in set-form, immediately turns on or off the hint label,
1374 disregarding the timeouts. It does regard the mouse pointer
1375 location, however, and does not turn on the hint label if the
1376 pointer is away.
1377 See also: "hint", "showHint", "ownerHint", "ownerShowHint"
1379 layered BOOLEAN
1381 If set, the widget will try to use alpha transparency available on
1382 the system. See "Layering" in Prima::Image for more details.
1383 Default: false
1385 See also: "is_surface_layered"
1387 Note: In Windows, mouse events will not be delivered to the layered
1389 widget if the pixel under the mouse pointer is fully transparent.
1390 In X11, you need to run a composition manager, f.ex. compiz or
1392 xcompmgr.
1393 left INTEGER
1395 Maintains the left boundary of a widget. If changed, does not
1396 affect the widget width; but does so, if called in "set()" together
1397 with "::right".
1398 See also: "bottom", "right", "top", "origin", "rect", "growMode",
1400 "Move"
1401 light3DColor COLOR
1403 The color used to draw light shades.
1404 See also: "dark3DColor", "colorIndex", "ColorChanged"
1406 ownerBackColor BOOLEAN
1408 If 1, the background color is synchronized with the owner's.
1409 Automatically set to 0 if "::backColor" property is explicitly set.
1410 See also: "ownerColor", "backColor", "colorIndex"
1412 ownerColor BOOLEAN
1414 If 1, the foreground color is synchronized with the owner's.
1415 Automatically set to 0 if "::color" property is explicitly set.
1416 See also: "ownerBackColor", "color", "colorIndex"
1418 ownerFont BOOLEAN
1420 If 1, the font is synchronized with the owner's. Automatically set
1421 to 0 if "::font" property is explicitly set.
1422 See also: "font", "FontChanged"
1424 ownerHint BOOLEAN
1426 If 1, the hint is synchronized with the owner's. Automatically set
1427 to 0 if "::hint" property is explicitly set.
1428 See also: "hint", "showHint", "hintVisible", "ownerShowHint"
1430 ownerShowHint BOOLEAN
1432 If 1, the show hint flag is synchronized with the owner's.
1433 Automatically set to 0 if "::showHint" property is explicitly set.
1434 See also: "hint", "showHint", "hintVisible", "ownerHint"
1436 ownerPalette BOOLEAN
1438 If 1, the palette array is synchronized with the owner's.
1439 Automatically set to 0 if "::palette" property is explicitly set.
1440 See also: "palette"
1442 origin X Y
1444 Maintains the left and bottom boundaries of a widget relative to
1445 its owner ( or to the screen if "::clipOwner" is set to 0 ).
1446 See also: "bottom", "right", "top", "left", "rect", "growMode",
1448 "Move"
1449 packInfo %OPTIONS
1451 See Prima::Widget::pack
1452 palette [ @PALETTE ]
1454 Specifies array of colors, that are desired to be present into the
1455 system palette, as close to the PALETTE as possible. This property
1456 works only if the graphic device allows palette operations. See
1457 "palette" in Prima::Drawable.
1458 See also: "ownerPalette"
1460 parentHandle SYSTEM_WINDOW
1462 If SYSTEM_WINDOW is a valid system-dependent window handle, then a
1463 widget becomes the child of the window specified, given the
1464 widget's "::clipOwner" is 0. The parent window can belong to
1465 another application.
1466 Default value is undef.
1468 See also: "clipOwner"
1470 placeInfo %OPTIONS
1472 See Prima::Widget::place
1473 pointer cr::XXX or ICON
1475 Specifies the pointer icon; discerns between "cr::XXX" constants
1476 and an icon. If an icon contains a hash variable "__pointerHotSpot"
1477 with an array of two integers, these integers will be treated as
1478 the pointer hot spot. In get-mode call, this variable is
1479 automatically assigned to an icon, if the result is an icon object.
1480 See also: "pointerHotSpot", "pointerIcon", "pointerType"
1482 pointerHotSpot X_OFFSET Y_OFFSET
1484 Specifies the hot spot coordinates of a pointer icon, associated
1485 with a widget.
1486 See also: "pointer", "pointerIcon", "pointerType"
1488 pointerIcon ICON
1490 Specifies the pointer icon, associated with a widget.
1491 See also: "pointerHotSpot", "pointer", "pointerType"
1493 pointerPos X_OFFSET Y_OFFSET
1495 Specifies the mouse pointer coordinates relative to widget's
1496 coordinates.
1497 See also: "get_mouse_state", "screen_to_client", "client_to_screen"
1499 pointerType TYPE
1501 Specifies the type of the pointer, associated with the widget.
1502 TYPE can accept one constant of "cr::XXX" set:
1503 cr::Default same pointer type as owner's
1505 cr::Arrow arrow pointer
1506 cr::Text text entry cursor-like pointer
1507 cr::Wait hourglass
1508 cr::Size general size action pointer
1509 cr::Move general move action pointer
1510 cr::SizeWest, cr::SizeW right-move action pointer
1511 cr::SizeEast, cr::SizeE left-move action pointer
1512 cr::SizeWE general horizontal-move action pointer
1513 cr::SizeNorth, cr::SizeN up-move action pointer
1514 cr::SizeSouth, cr::SizeS down-move action pointer
1515 cr::SizeNS general vertical-move action pointer
1516 cr::SizeNW up-right move action pointer
1517 cr::SizeSE down-left move action pointer
1518 cr::SizeNE up-left move action pointer
1519 cr::SizeSW down-right move action pointer
1520 cr::Invalid invalid action pointer
1521 cr::User user-defined icon
1522 All constants except "cr::User" and "cr::Default" present a system-
1524 defined pointers, their icons and hot spot offsets. "cr::User" is a
1525 sign that an icon object was specified explicitly via
1526 "::pointerIcon" property. "cr::Default" is a way to tell that a
1527 widget inherits its owner pointer type, no matter is it a system-
1528 defined pointer or a custom icon.
1529 See also: "pointerHotSpot", "pointerIcon", "pointer"
1531 popup OBJECT
1533 Manages a Prima::Popup object associated with a widget. The
1534 purpose of the popup object is to show a context menu when the user
1535 right-clicks or selects the corresponding keyboard combination.
1536 Prima::Widget can host many children objects, Prima::Popup as well.
1537 But only the one that is set in "::popup" property will be
1538 activated automatically.
1539 The popup object can be destroyed safely; its cancellation can be
1541 done either via "popup(undef)" or "destroy()" call.
1542 See also: "Prima::Menu", "Popup", "Menu", "popupItems",
1544 "popupColorIndex", "popupFont"
1545 popupColorIndex INDEX, COLOR
1547 Maintains eight color properties of a pop-up context menu,
1548 associated with a widget. INDEX must be one of "ci::XXX" constants
1549 ( see "::colorIndex" property ).
1550 See also: "popupItems", "popupFont", "popup"
1552 popupColor COLOR
1554 Basic foreground in a popup context menu color.
1555 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1557 popupBackColor COLOR
1559 Basic background in a popup context menu color.
1560 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1562 popupDark3DColor COLOR
1564 Color for drawing dark shadings in a popup context menu.
1565 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1567 popupDisabledColor COLOR
1569 Foreground color for disabled items in a popup context menu.
1570 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1572 popupDisabledBackColor COLOR
1574 Background color for disabled items in a popup context menu.
1575 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1577 popupFont %FONT
1579 Maintains the font of a pop-up context menu, associated with a
1580 widget.
1581 See also: "popupItems", "popupColorIndex", "popup"
1583 popupHiliteColor COLOR
1585 Foreground color for selected items in a popup context menu.
1586 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1588 popupHiliteBackColor COLOR
1590 Background color for selected items in a popup context menu.
1591 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1593 popupItems [ ITEM_LIST ]
1595 Manages items of a Prima::Popup object associated with a widget.
1596 The ITEM_LIST format is same as "Prima::AbstractMenu::items" and is
1597 described in Prima::Menu.
1598 See also: "popup", "popupColorIndex", "popupFont"
1600 popupLight3DColor COLOR
1602 Color for drawing light shadings in a popup context menu.
1603 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1605 rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET Y_TOP_OFFSET
1607 Maintains the rectangular boundaries of a widget relative to its
1608 owner ( or to the screen if "::clipOwner" is set to 0 ).
1609 See also: "bottom", "right", "top", "left", "origin", "width",
1611 "height", "size" "growMode", "Move", "Size", "get_virtual_size",
1612 "sizeMax", "sizeMin"
1613 right INTEGER
1615 Maintains the right boundary of a widget. If changed, does not
1616 affect the widget width; but does so, if called in "set()" together
1617 with "::left".
1618 See also: "left", "bottom", "top", "origin", "rect", "growMode",
1620 "Move"
1621 scaleChildren BOOLEAN
1623 If a widget has "::scaleChildren" set to 1, then the newly-created
1624 children widgets inserted in it will be scaled corresponding to the
1625 owner's "::designScale", given that widget's "::designScale" is not
1626 "undef" and the owner's is not [0,0].
1627 Default is 1.
1629 See also: "designScale"
1631 selectable BOOLEAN
1633 If 1, a widget can be granted focus implicitly, or by means of the
1634 user actions. "select()" regards this property, and does not focus
1635 a widget that has "::selectable" set to 0.
1636 Default value is 0
1638 See also: "current", "currentWidget", "selected", "selectedWidget",
1640 "focused"
1641 selected BOOLEAN
1643 If called in get-mode, returns whether a widget or one of its
1644 (grand-) children is focused. If in set-mode, either simply turns
1645 the system with no-focus state ( if 0 ), or sends input focus to
1646 itself or one of the widgets tracked down by "::currentWidget"
1647 chain.
1648 See also: "current", "currentWidget", "selectable",
1650 "selectedWidget", "focused"
1651 selectedWidget OBJECT
1653 Points to a child widget, that has property "::selected" set to 1.
1654 See also: "current", "currentWidget", "selectable", "selected",
1656 "focused"
1657 selectingButtons FLAGS
1659 FLAGS is a combination of "mb::XXX" ( mouse button ) flags. If a
1660 widget receives a click with a mouse button, that has the
1661 corresponding bit set in "::selectingButtons", then "select()" is
1662 called.
1663 See also: "MouseDown", "firstClick", "selectable", "selected",
1665 "focused"
1666 shape REGION
1668 Maintains the non-rectangular shape of a widget. When setting,
1669 REGION is either a Prima::Image object, with 0 bits treated as
1670 transparent pixels, and 1 bits as opaque pixels, or a Prima::Region
1671 object. When getting, it is either undef or a Prima::Region
1672 object.
1673 Successive only if "sv::ShapeExtension" value is true.
1675 showHint BOOLEAN
1677 If 1, the toolkit is allowed to show the hint label over a widget.
1678 If 0, the display of the hint is forbidden. The "::hint" property
1679 must contain non-empty string as well, if the hint label must be
1680 shown.
1681 Default value is 1.
1683 See also: "hint", "ownerShowHint", "hintVisible", "ownerHint"
1685 size WIDTH HEIGHT
1687 Maintains the width and height of a widget.
1688 See also: "width", "height" "growMode", "Move", "Size",
1690 "get_virtual_size", "sizeMax", "sizeMin"
1691 sizeMax WIDTH HEIGHT
1693 Specifies the maximal size for a widget that it is allowed to
1694 accept.
1695 See also: "width", "height", "size" "growMode", "Move", "Size",
1697 "get_virtual_size", "sizeMin"
1698 sizeMin WIDTH HEIGHT
1700 Specifies the minimal size for a widget that it is allowed to
1701 accept.
1702 See also: "width", "height", "size" "growMode", "Move", "Size",
1704 "get_virtual_size", "sizeMax"
1705 syncPaint BOOLEAN
1707 If 0, the "Paint" request notifications are stacked until the event
1708 loop is called. If 1, every time the widget surface gets
1709 invalidated, the "Paint" notification is called.
1710 Default value is 0.
1712 See also: "invalidate_rect", "repaint", "validate_rect", "Paint"
1714 tabOrder INTEGER
1716 Maintains the order in which tab- and shift-tab- key navigation
1717 algorithms select the sibling widgets. INTEGER is unique among the
1718 sibling widgets. In set mode, if INTEGER value is already taken,
1719 the occupier is assigned another unique value, but without
1720 destruction of a queue - widgets with ::tabOrder greater than of
1721 the widget, receive their new values too. Special value -1 is
1722 accepted as 'the end of list' indicator; the negative value is
1723 never returned.
1724 See also: "tabStop", "next_tab", "selectable", "selected",
1726 "focused"
1727 tabStop BOOLEAN
1729 Specifies whether a widget is interested in tab- and shift-tab- key
1730 navigation or not.
1731 Default value is 1.
1733 See also: "tabOrder", "next_tab", "selectable", "selected",
1735 "focused"
1736 text TEXT
1738 A text string for generic purpose. Many Prima::Widget descendants
1739 use this property heavily - buttons, labels, input lines etc, but
1740 Prima::Widget itself does not.
1741 top INTEGER
1743 Maintains the upper boundary of a widget. If changed, does not
1744 affect the widget height; but does so, if called in "set()"
1745 together with "::bottom".
1746 See also: "left", "right", "bottom", "origin", "rect", "growMode",
1748 "Move"
1749 transparent BOOLEAN
1751 Specifies whether the background of a widget before it starts
1752 painting is of any importance. If 1, a widget can gain certain
1753 transparency look if it does not clear the background during
1754 "Paint" event.
1755 Default value is 0
1757 See also: "Paint", "buffered".
1759 visible BOOLEAN
1761 Specifies whether a widget is visible or not. See "Visibility".
1762 See also: "Show", "Hide", "showing", "exposed"
1764 widgetClass CLASS
1766 Maintains the integer value, designating the color class that is
1767 defined by the system and is associated with Prima::Widget eight
1768 basic color properties. CLASS can be one of "wc::XXX" constants:
1769 wc::Undef
1771 wc::Button
1772 wc::CheckBox
1773 wc::Combo
1774 wc::Dialog
1775 wc::Edit
1776 wc::InputLine
1777 wc::Label
1778 wc::ListBox
1779 wc::Menu
1780 wc::Popup
1781 wc::Radio
1782 wc::ScrollBar
1783 wc::Slider
1784 wc::Widget or wc::Custom
1785 wc::Window
1786 wc::Application
1787 These constants are not associated with the toolkit classes; any
1789 class can use any of these constants in "::widgetClass".
1790 See also: "map_color", "colorIndex"
1792 widgets @WIDGETS
1794 In get-mode, returns list of immediate children widgets (identical
1795 to "get_widgets"). In set-mode accepts set of widget profiles, as
1796 "insert" does, as a list or an array. This way it is possible to
1797 create widget hierarchy in a single call.
1798 width WIDTH
1800 Maintains the width of a widget.
1801 See also: "height" "growMode", "Move", "Size", "get_virtual_size",
1803 "sizeMax", "sizeMin"
1804 x_centered BOOLEAN
1806 A write-only property. Once set, widget is centered by the
1807 horizontal axis relative to its owner.
1808 See also: "centered", "y_centered", "growMode", "origin", "Move".
1810 y_centered BOOLEAN
1812 A write-only property. Once set, widget is centered by the vertical
1813 axis relative to its owner.
1814 See also: "x_centered", "centered", "growMode", "origin", "Move".
1816 Methods
1818 begin_drag [ DATA | %OPTIONS ]
1819 Wrapper over "dnd_start" that takes care of some DND session
1820 aspects other than the default system's. All input is contained in
1821 %OPTIONS hash, except for the case of a single-parameter call, in
1822 which case it is equivalent to "text => DATA" when "DATA" is a
1823 scalar, and to "image => DATA" when "DATA" is a reference.
1824 Returns -1 if a session cannot start, "dnd::None" if it was
1826 cancelled by the user, or any other "dnd::" constant when the DND
1827 receiver has selected and successfully performed that action. For
1828 example, after a call to "dnd_start" returning "dnd::Move"
1829 (depending on a context), the caller may remove the data the user
1830 selected to move ("Prima::InputLine" and "Prima::Edit" do exactly
1831 this).
1832 In "wantarray" context also returns the widget that accepted the
1834 drop, if that was a Prima widget. Check this before handling
1835 "dnd::Move" actions that require data to be deleted on the source,
1836 to not occasionally delete the freshly transferred data. The method
1837 uses a precaution for this scenario and by default won't let the
1838 widget to be both a sender and a receiver though ( see "self_aware"
1839 below ).
1840 The following input is recognized:
1842 actions INTEGER = dnd::Copy
1844 Combination of "dnd::" constants, to tell a DND receiver
1845 whether copying, moving, and/or linking of the data is allowed.
1846 The method fails on the invalid "actions" input.
1847 format FORMAT, data INPUT
1849 If set, the clipboard will be assigned to contain a single
1850 entry of "INPUT" of the "FORMAT" format, where format is either
1851 one of the standard "Text" or "Image", or one of the format
1852 registered by "Clipboard::register_format".
1853 If not set, the caller needs to fill the clipboard in advance,
1855 f.ex. to offer data in more than one format.
1856 image INPUT
1858 Shortcut for " format =" 'Image', data => $INPUT, preview =>
1859 $INPUT >
1860 preview INPUT
1862 If set, mouse pointers sending feedback to the user will be
1863 equipped with either text or image (depending on whether
1864 "INPUT" is a scalar or an image reference).
1865 self_aware BOOLEAN = 1
1867 If unset the widget's "dndAware" will be temporarily set to 0,
1868 to exclude a possibility of an operation that may end in
1869 sending data to itself.
1870 text INPUT
1872 Shortcut for " format =" 'Text', data => $INPUT, preview =>
1873 $INPUT >
1874 track INTEGER = 5
1876 When set, waits with starting the DND process until the user
1877 moves the pointer from the starting point further than "track"
1878 pixels, which makes sense if the method to be called directly
1879 from a "MouseDown" event handler.
1880 If the drag did not happen because the user released the button
1882 or otherwise marked that this is not a drag, -1 is returned. In
1883 that case, the caller should continue to handle "MouseDown"
1884 event as if no drag sesssion was ever started.
1885 bring_to_front
1887 Sends a widget on top of all other siblings widgets
1888 See also: "insert_behind", "send_to_back", "ZOrderChanged"
1890 ,"first", "next", "prev", "last"
1891 can_close
1893 Sends "Close" message, and returns its boolean exit state.
1894 See also: "Close", "close"
1896 client_to_screen @OFFSETS
1898 Maps array of X and Y integer offsets from widget to screen
1899 coordinates. Returns the mapped OFFSETS.
1900 See also: "screen_to_client", "clipOwner"
1902 close
1904 Calls "can_close()", and if successful, destroys a widget. Returns
1905 the "can_close()" result.
1906 See also: "can_close", "Close"
1908 defocus
1910 Alias for focused(0) call
1911 See also: "focus", "focused", "Enter", "Leave"
1913 deselect
1915 Alias for selected(0) call
1916 See also: "select", "selected", "Enter", "Leave"
1918 dnd_start ACTIONS = dnd::Copy, USE_DEFAULT_POINTERS = 1
1920 Starts a drag and drop session with a combination of "ACTIONS"
1921 allowed. It is expected that a DND clipboard will be filled with
1922 data that are prepared to be sent to a DND receiver.
1923 Returns -1 if a session cannot start, "dnd::None" if it was
1925 cancelled by the user, or any other "dnd::" constant when the DND
1926 receiver has selected and successfully performed that action. For
1927 example, after a call to "dnd_start" returning "dnd::Move"
1928 (depending on a context), the called may remove the data the user
1929 selected to move ("Prima::InputLine" and "Prima::Edit" do exactly
1930 this).
1931 Also returns the widget that accepted the drop, if that was a Prima
1933 widget within the same program.
1934 If USE_DEFAULT_POINTERS is set, then the system will use default
1936 drag pointers. Otherwise it is expected that a "DragResponse"
1937 action will change them according to current action, to give the
1938 user a visual feedback.
1939 See "begin_drag" for a wrapper over this method that handles also
1941 for other DND aspects.
1942 See also: "Drag and Drop", "DragQuery", "DragResponse".
1944 exposed
1946 Returns a boolean value, indicating whether a widget is at least
1947 partly visible on the screen. Never returns 1 if a widget has
1948 "::visible" set to 0.
1949 See also: "visible", "showing", "Show", "Hide"
1951 fetch_resource CLASS_NAME, NAME, CLASS_RESOURCE, RESOURCE, OWNER,
1953 RESOURCE_TYPE = fr::String
1954 Returns a system-defined scalar of resource, defined by the widget
1955 hierarchy, its class, name and owner. RESOURCE_TYPE can be one of
1956 type qualificators:
1957 fr::Color - color resource
1959 fr::Font - font resource
1960 fs::String - text string resource
1961 Such a number of the parameters is used because the method can be
1963 called before a widget is created. CLASS_NAME is widget class
1964 string, NAME is widget name. CLASS_RESOURCE is class of resource,
1965 and RESOURCE is the resource name.
1966 For example, resources 'color' and 'disabledColor' belong to the
1968 resource class 'Foreground'.
1969 first
1971 Returns the first ( from bottom ) sibling widget in Z-order.
1972 See also: "last", "next", "prev"
1974 focus
1976 Alias for focused(1) call
1977 See also: "defocus", "focused", "Enter", "Leave"
1979 hide
1981 Sets widget "::visible" to 0.
1982 See also: "hide", "visible", "Show", "Hide", "showing", "exposed"
1984 hide_cursor
1986 Hides the cursor. As many times "hide_cursor()" was called, as many
1987 time its counterpart "show_cursor()" must be called to reach the
1988 cursor's initial state.
1989 See also: "show_cursor", "cursorVisible"
1991 help
1993 Starts an interactive help viewer opened on "::helpContext" string
1994 value.
1995 The string value is combined from the widget's owner
1997 "::helpContext" strings if the latter is empty or begins with a
1998 slash. A special meaning is assigned to an empty string " " - the
1999 help() call fails when such value is found to be the section
2000 component. This feature can be useful when a window or a dialog
2001 presents a standalone functionality in a separate module, and the
2002 documentation is related more to the module than to an embedding
2003 program. In such case, the grouping widget holds "::helpContext" as
2004 a pod manpage name with a trailing slash, and its children widgets
2005 are assigned "::helpContext" to the topics without the manpage but
2006 the leading slash instead. If the grouping widget has an empty
2007 string " " as "::helpContext" then the help is forced to be
2008 unavailable for all the children widgets.
2009 See also: "helpContext"
2011 insert CLASS, %PROFILE [[ CLASS, %PROFILE], ... ]
2013 Creates one or more widgets with "owner" property set to the caller
2014 widget, and returns the list of references to the newly created
2015 widgets.
2016 Has two calling formats:
2018 Single widget
2020 $parent-> insert( 'Child::Class',
2021 name => 'child',
2022 ....
2023 );
2024 Multiple widgets
2026 $parent-> insert(
2027 [
2028 'Child::Class1',
2029 name => 'child1',
2030 ....
2031 ],
2032 [
2033 'Child::Class2',
2034 name => 'child2',
2035 ....
2036 ],
2037 );
2038 insert_behind OBJECT
2040 Sends a widget behind the OBJECT on Z-axis, given that the OBJECT
2041 is a sibling to the widget.
2042 See also: "bring_to_front", "send_to_back", "ZOrderChanged"
2044 ,"first", "next", "prev", "last"
2045 invalidate_rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET
2047 Y_TOP_OFFSET
2048 Marks the rectangular area of a widget as 'invalid', so re-painting
2049 of the area happens. See "Graphic content".
2050 See also: "validate_rect", "get_invalid_rect", "repaint", "Paint",
2052 "syncPaint", "update_view"
2053 is_surface_layered
2055 Returns true if both the widget and it's top-most parent are
2056 layered. If the widget itself is top-most, i.e. a window, a non-
2057 clipOwner widget, or a child to application, then is the same as
2058 "layered".
2059 See also: "layered"
2061 key_down CODE, KEY = kb::NoKey, MOD = 0, REPEAT = 1, POST = 0
2063 The method sends or posts ( POST flag ) simulated "KeyDown" event
2064 to the system. CODE, KEY, MOD and REPEAT are the parameters to be
2065 passed to the notification callbacks.
2066 See also: "key_up", "key_event", "KeyDown"
2068 key_event COMMAND, CODE, KEY = kb::NoKey, MOD = 0, REPEAT = 1, POST = 0
2070 The method sends or posts ( POST flag ) simulated keyboard event to
2071 the system. CODE, KEY, MOD and REPEAT are the parameters to be
2072 passed to an eventual "KeyDown" or "KeyUp" notifications. COMMAND
2073 is allowed to be either "cm::KeyDown" or "cm::KeyUp".
2074 See also: "key_down", "key_up", "KeyDown", "KeyUp"
2076 key_up CODE, KEY = kb::NoKey, MOD = 0, POST = 0
2078 The method sends or posts ( POST flag ) simulated "KeyUp" event to
2079 the system. CODE, KEY and MOD are the parameters to be passed to
2080 the notification callbacks.
2081 See also: "key_down", "key_event", "KeyUp"
2083 last
2085 Returns the last ( the topmost ) sibling widget in Z-order.
2086 See also: "first", "next", "prev"
2088 lock
2090 Turns off the ability of a widget to re-paint itself. As many
2091 times "lock()" was called, as may times its counterpart, "unlock()"
2092 must be called to enable re-painting again. Returns a boolean
2093 success flag.
2094 See also: "unlock", "repaint", "Paint", "get_locked"
2096 map_color COLOR
2098 Transforms "cl::XXX" and "ci::XXX" combinations into RGB color
2099 representation and returns the result. If COLOR is already in RGB
2100 format, no changes are made.
2101 See also: "colorIndex"
2103 mouse_click BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, DBL_CLICK = 0,
2105 POST = 0
2106 The method sends or posts ( POST flag ) simulated "MouseClick"
2107 event to the system. BUTTON, MOD, X, Y, and DBL_CLICK are the
2108 parameters to be passed to the notification callbacks.
2109 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseMove",
2111 "MouseEnter", "MouseLeave"
2112 mouse_down BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, POST = 0
2114 The method sends or posts ( POST flag ) simulated "MouseDown" event
2115 to the system. BUTTON, MOD, X, and Y are the parameters to be
2116 passed to the notification callbacks.
2117 See also: "MouseUp", "MouseWheel", "MouseClick", "MouseMove",
2119 "MouseEnter", "MouseLeave"
2120 mouse_enter MOD = 0, X = 0, Y = 0, POST = 0
2122 The method sends or posts ( POST flag ) simulated "MouseEnter"
2123 event to the system. MOD, X, and Y are the parameters to be passed
2124 to the notification callbacks.
2125 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseClick",
2127 "MouseMove", "MouseLeave"
2128 mouse_event COMMAND = cm::MouseDown, BUTTON = mb::Left, MOD = 0, X = 0,
2130 Y = 0, DBL_CLICK = 0, POST = 0
2131 The method sends or posts ( POST flag ) simulated mouse event to
2132 the system. BUTTON, MOD, X, Y and DBL_CLICK are the parameters to
2133 be passed to an eventual mouse notifications. COMMAND is allowed
2134 to be one of "cm::MouseDown", "cm::MouseUp", "cm::MouseWheel",
2135 "cm::MouseClick", "cm::MouseMove", "cm::MouseEnter",
2136 "cm::MouseLeave" constants.
2137 See also: "mouse_down", "mouse_up", "mouse_wheel", "mouse_click",
2139 "mouse_move", "mouse_enter", "mouse_leave", "MouseDown", "MouseUp",
2140 "MouseWheel", "MouseClick", "MouseMove", "MouseEnter", "MouseLeave"
2141 mouse_leave
2143 The method sends or posts ( POST flag ) simulated "MouseLeave"
2144 event to the system.
2145 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseClick",
2147 "MouseMove", "MouseEnter", "MouseLeave"
2148 mouse_move MOD = 0, X = 0, Y = 0, POST = 0
2150 The method sends or posts ( POST flag ) simulated "MouseMove" event
2151 to the system. MOD, X, and Y are the parameters to be passed to the
2152 notification callbacks.
2153 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseClick",
2155 "MouseEnter", "MouseLeave"
2156 mouse_up BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, POST = 0
2158 The method sends or posts ( POST flag ) simulated "MouseUp" event
2159 to the system. BUTTON, MOD, X, and Y are the parameters to be
2160 passed to the notification callbacks.
2161 See also: "MouseDown", "MouseWheel", "MouseClick", "MouseMove",
2163 "MouseEnter", "MouseLeave"
2164 mouse_wheel MOD = 0, X = 0, Y = 0, INCR = 0, POST = 0
2166 The method sends or posts ( POST flag ) simulated "MouseUp" event
2167 to the system. MOD, X, Y and INCR are the parameters to be passed
2168 to the notification callbacks.
2169 See also: "MouseDown", "MouseUp", "MouseClick", "MouseMove",
2171 "MouseEnter", "MouseLeave"
2172 next
2174 Returns the neighbor sibling widget, next ( above ) in Z-order. If
2175 none found, undef is returned.
2176 See also: "first", "last", "prev"
2178 next_tab FORWARD = 1
2180 Returns the next widget in the sorted by "::tabOrder" list of
2181 sibling widgets. FORWARD is a boolean lookup direction flag. If
2182 none found, the first ( or the last, depending on FORWARD flag )
2183 widget is returned. Only widgets with "::tabStop" set to 1
2184 participate.
2185 Also used by the internal keyboard navigation code.
2187 See also: "next_positional", "tabOrder", "tabStop", "selectable"
2189 next_positional DELTA_X DELTA_Y
2191 Returns a sibling, (grand-)child of a sibling or (grand-)child
2192 widget, that matched best the direction specified by DELTA_X and
2193 DELTA_Y. At one time, only one of these parameters can be zero;
2194 another parameter must be either 1 or -1.
2195 Also used by the internal keyboard navigation code.
2197 See also: "next_tab", "origin"
2199 pack, packForget, packSlaves
2201 See Prima::Widget::pack
2202 place, placeForget, placeSlaves
2204 See Prima::Widget::place
2205 prev
2207 Returns the neighbor sibling widget, previous ( below ) in Z-order.
2208 If none found, undef is returned.
2209 See also: "first", "last", "next"
2211 repaint
2213 Marks the whole widget area as 'invalid', so re-painting of the
2214 area happens. See "Graphic content".
2215 See also: "validate_rect", "get_invalid_rect", "invalidate_rect",
2217 "Paint", "update_view", "syncPaint"
2218 rect_bevel $CANVAS, @RECT, %OPTIONS
2220 Draws a rectangular area, similar to produced by "rect3d" over
2221 @RECT that is 4-integer coordinates of the area, but implicitly
2222 using widget's "light3DColor" and "dark3DColor" properties' values.
2223 The following options are recognized:
2224 fill COLOR
2226 If set, the area is filled with COLOR, ortherwise is left
2227 intact.
2228 width INTEGER
2230 Width of the border in pixels
2231 concave BOOLEAN
2233 If 1, draw a concave area, bulged otherwise
2234 responsive
2236 Returns a boolean flag, indicating whether a widget and its owners
2237 have all "::enabled" 1 or not. Useful for fast check if a widget
2238 should respond to the user actions.
2239 See also: "enabled"
2241 screen_to_client @OFFSETS
2243 Maps array of X and Y integer offsets from screen to widget
2244 coordinates. Returns the mapped OFFSETS.
2245 See also: "client_to_screen"
2247 scroll DELTA_X DELTA_Y %OPTIONS
2249 Scrolls the graphic context area by DELTA_X and DELTA_Y pixels.
2250 OPTIONS is hash, that contains optional parameters to the scrolling
2251 procedure:
2252 clipRect [X1, Y1, X2, Y2]
2254 The clipping area is confined by X1, Y1, X2, Y2 rectangular
2255 area. If not specified, the clipping area covers the whole
2256 widget. Only the bits, covered by clipRect are affected. Bits
2257 scrolled from the outside of the rectangle to the inside are
2258 painted; bits scrolled from the inside of the rectangle to the
2259 outside are not painted.
2260 confineRect [X1, Y1, X2, Y2]
2262 The scrolling area is confined by X1, Y1, X2, Y2 rectangular
2263 area. If not specified, the scrolling area covers the whole
2264 widget.
2265 withChildren BOOLEAN
2267 If 1, the scrolling performs with the eventual children widgets
2268 change their positions to DELTA_X and DELTA_Y as well.
2269 Cannot be used inside paint state.
2271 See also: "Paint", "get_invalid_rect"
2273 select
2275 Alias for selected(1) call
2276 See also: "deselect", "selected", "Enter", "Leave"
2278 send_to_back
2280 Sends a widget at bottom of all other siblings widgets
2281 See also: "insert_behind", "bring_to_front", "ZOrderChanged"
2283 ,"first", "next", "prev", "last"
2284 show
2286 Sets widget "::visible" to 1.
2287 See also: "hide", "visible", "Show", "Hide", "showing", "exposed"
2289 show_cursor
2291 Shows the cursor. As many times "hide_cursor()" was called, as many
2292 time its counterpart "show_cursor()" must be called to reach the
2293 cursor's initial state.
2294 See also: "hide_cursor", "cursorVisible"
2296 showing
2298 Returns a boolean value, indicating whether the widget and its
2299 owners have all "::visible" 1 or not.
2300 unlock
2302 Turns on the ability of a widget to re-paint itself. As many times
2303 "lock()" was called, as may times its counterpart, "unlock()" must
2304 be called to enable re-painting again. When last "unlock()" is
2305 called, an implicit "repaint()" call is made. Returns a boolean
2306 success flag.
2307 See also: "lock", "repaint", "Paint", "get_locked"
2309 update_view
2311 If any parts of a widget were marked as 'invalid' by either
2312 "invalidate_rect()" or "repaint()" calls or the exposure caused by
2313 window movements ( or any other), then "Paint" notification is
2314 immediately called. If no parts are invalid, no action is
2315 performed. If a widget has "::syncPaint" set to 1, "update_view()"
2316 is always a no-operation call.
2317 See also: "invalidate_rect", "get_invalid_rect", "repaint",
2319 "Paint", "syncPaint", "update_view"
2320 validate_rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET Y_TOP_OFFSET
2322 Reverses the effect of "invalidate_rect()", restoring the original,
2323 'valid' state of widget area covered by the rectangular area
2324 passed. If a widget with previously invalid areas was wholly
2325 validated by this method, no "Paint" notifications occur.
2326 See also: "invalidate_rect", "get_invalid_rect", "repaint",
2328 "Paint", "syncPaint", "update_view"
2329 Get-methods
2331 get_default_font
2332 Returns the default font for a Prima::Widget class.
2333 See also: "font"
2335 get_default_popup_font
2337 Returns the default font for a Prima::Popup class.
2338 See also: "font"
2340 get_invalid_rect
2342 Returns the result of successive calls "invalidate_rect()",
2343 "validate_rect()" and "repaint()", as a rectangular area ( four
2344 integers ) that cover all invalid regions in a widget. If none
2345 found, (0,0,0,0) is returned.
2346 See also: "validate_rect", "invalidate_rect", "repaint", "Paint",
2348 "syncPaint", "update_view"
2349 get_handle
2351 Returns a system handle for a widget
2352 See also: "get_parent_handle", "Window::get_client_handle"
2354 get_locked
2356 Returns 1 if a widget is in "lock()" - initiated repaint-blocked
2357 state.
2358 See also: "lock", "unlock"
2360 get_mouse_state
2362 Returns a combination of "mb::XXX" constants, reflecting the
2363 currently pressed mouse buttons.
2364 See also: "pointerPos", "get_shift_state"
2366 get_parent
2368 Returns the owner widget that clips the widget boundaries, or
2369 application object if a widget is top-level.
2370 See also: "clipOwner"
2372 get_parent_handle
2374 Returns a system handle for a parent of a widget, a window that
2375 belongs to another program. Returns 0 if the widget's owner and
2376 parent are in the same application and process space.
2377 See also: "get_handle", "clipOwner"
2379 get_pointer_size
2381 Returns two integers, width and height of a icon, that the system
2382 accepts as valid for a pointer. If the icon is supplied that is
2383 more or less than these values, it is truncated or padded with
2384 transparency bits, but is not stretched. Can be called with class
2385 syntax.
2386 get_shift_state
2388 Returns a combination of "km::XXX" constants, reflecting the
2389 currently pressed keyboard modificator buttons.
2390 See also: "get_shift_state"
2392 get_virtual_size
2394 Returns virtual width and height of a widget. See "Geometry",
2395 Implicit size regulations.
2396 See also: "width", "height", "size" "growMode", "Move", "Size",
2398 "sizeMax", "sizeMin"
2399 get_widgets
2401 Returns list of children widgets.
2402 Events
2404 Change
2405 Generic notification, used for Prima::Widget descendants;
2406 Prima::Widget itself neither calls not uses the event. Designed to
2407 be called when an arbitrary major state of a widget is changed.
2408 Click
2410 Generic notification, used for Prima::Widget descendants;
2411 Prima::Widget itself neither calls not uses the event. Designed to
2412 be called when an arbitrary major action for a widget is called.
2413 Close
2415 Triggered by "can_close()" and "close()" functions. If the event
2416 flag is cleared during execution, these functions fail.
2417 See also: "close", "can_close"
2419 ColorChanged INDEX
2421 Called when one of widget's color properties is changed, either by
2422 direct property change or by the system. INDEX is one of "ci::XXX"
2423 constants.
2424 See also: "colorIndex"
2426 Disable
2428 Triggered by a successive enabled(0) call
2429 See also: "Enable", "enabled", "responsive"
2431 DragBegin CLIPBOARD, ACTION, MOD, X, Y, COUNTERPART
2433 Triggered on a receiver widget when a mouse with a DND object
2434 enters it. "CLIPBOARD" contains the DND data, "ACTION" is a
2435 combination of "dnd::" constants, the actions the sender is ready
2436 to offer, "MOD" is a combination of modifier keys ("kb::"), and "X"
2437 and "Y" are coordinates where the mouse has entered the widget.
2438 This event, and the following "DragOver" and "DragEnd" events are
2439 happening only if the property "dndAware" is set either to 1, or if
2440 it matches a clipboard format that exists in "CLIPBOARD".
2441 "COUNTERPART" is the Prima DND sender widget, if the session is
2443 initiated within the same program.
2444 See also: "Drag and Drop", "DragOver", "DragEnd"
2446 DragEnd CLIPBOARD, ACTION, MOD, X, Y, COUNTERPART, ANSWER
2448 Triggered on a received widget when the user either drops or
2449 cancels the DND session. In case of a cancelled drop, "CLIPBOARD"
2450 is set to "undef" and "ACTION" to "dnd::None". On a successful
2451 drop, input data are same as on "DragBegin", and output data are to
2452 be stored in hashref "ANSWER", if any. The following answers can
2453 be stored:
2454 allow BOOLEAN
2456 Is pre-set to 1. If changed to 0, a signal will be send to the
2457 sender that a drop is not accepted.
2458 action INTEGER
2460 A "dnd::" constant (not a combination) to be returned to the
2461 sender with the action the receiver has accepted, if any.
2462 "COUNTERPART" is the Prima DND sender widget, if the session is
2464 initiated within the same program.
2465 See also: "Drag and Drop", "DragBegin", "DragOver"
2467 DragOver CLIPBOARD, ACTION, MOD, X, Y, COUNTERPART, ANSWER
2469 Triggered on a received widget when a mouse with a DND moves within
2470 the widget. Input data are same as on "DragBegin", and output data
2471 are to be stored in hashref "ANSWER", if any. The following answers
2472 can be stored:
2473 allow BOOLEAN
2475 Is pre-set to 1. If changed to 0, a signal will be send to the
2476 sender that a drop action cannot happen with the input
2477 provided.
2478 action INTEGER
2480 A "dnd::" constant (not a combination) to be returned to the
2481 sender with the action the receiver is ready to accept, if any.
2482 pad X, Y, WIDTH, HEIGHT
2484 If set, instructs the sender not to repeat "DragOver" events
2485 that contains same input data, while the mouse pointer is
2486 within these geometrical limits.
2487 "COUNTERPART" is the Prima DND sender widget, if the session is
2489 initiated within the same program.
2490 DragQuery MOD, ANSWERS, COUNTERPART
2492 Triggered on a sender DND widget when there was detected a change
2493 in mouse or modifier buttons, or the user pressed "Escape" key to
2494 cancel the DND session. The combination of mouse and modifier
2495 buttons is stored in "MOD" integer, together with a special
2496 "km::Escape" constant for the "Escape" key.
2497 It is up to this event to decide whether to continue the drag
2499 session or not, and if it is decided not to continue,
2500 "$answer-"{allow}> must be set to 0.
2501 Additionally, "$answer-"{action}> can be set to select a single
2503 "dnd::" action that will be used to propose to the receiver a
2504 single concrete action based on the "MOD" value (f.ex. a
2505 "dnd::Move" if a control modifier was pressed).
2506 Note: This action will only forward the change to the receiver on
2508 X11, but it is advised to implement it anyway for portability.
2509 "COUNTERPART" is the Prima DND receiver widget, if within the same
2511 program.
2512 See also: "Drag and Drop", "DragResponse"
2514 DragResponse ALLOW, ACTION, COUNTERPART
2516 Triggered on a sender DND widget when there was detected a change
2517 in mouse or modifier buttons, or the mouse was moved from one DND
2518 target to another. The sender event is then presented with the new
2519 input, collected from interaction with the new target; there,
2520 "ALLOW" is set to a boolean value whether the sender is allowed to
2521 drop data, and "ACTION" is a "dnd::" constant with the action the
2522 receiver has agreed to accept, if any.
2523 If the drag and drop session was told not to update mouse pointers
2525 on such event, the handle should update the pointer in this
2526 callback. It is not needed though to save and restore mouse
2527 pointers before and after the DND session.
2528 "COUNTERPART" is the Prima DND receiver widget, if within the same
2530 program. See also: "Drag and Drop", "dnd_start", "begin_drag".
2531 Enable
2533 Triggered by a successive enabled(1) call
2534 See also: "Disable", "enabled", "responsive"
2536 Enter
2538 Called when a widget receives the input focus.
2539 See also: "Leave", "focused", "selected"
2541 FontChanged
2543 Called when a widget font is changed either by direct property
2544 change or by the system.
2545 See also: "font", "ColorChanged"
2547 Hide
2549 Triggered by a successive visible(0) call
2550 See also: "Show", "visible", "showing", "exposed"
2552 Hint SHOW_FLAG
2554 Called when the hint label is about to show or hide, depending on
2555 SHOW_FLAG. The hint show or hide action fails, if the event flag is
2556 cleared during execution.
2557 See also: "showHint", "ownerShowHint", "hintVisible", "ownerHint"
2559 KeyDown CODE, KEY, MOD, REPEAT
2561 Sent to the focused widget when the user presses a key. CODE
2562 contains an eventual character code, KEY is one of "kb::XXX"
2563 constants, MOD is a combination of the modificator keys pressed
2564 when the event occurred ( "km::XXX" ). REPEAT is how many times the
2565 key was pressed; usually it is 1. ( see "::briefKeys" ).
2566 The valid "km::" constants are:
2568 km::Shift
2570 km::Ctrl
2571 km::Alt
2572 km::KeyPad
2573 km::DeadKey
2574 km::Unicode
2575 The valid "kb::" constants are grouped in several sets. Some codes
2577 are aliased, like, "kb::PgDn" and "kb::PageDown".
2578 Modificator keys
2580 kb::ShiftL kb::ShiftR kb::CtrlL kb::CtrlR
2581 kb::AltL kb::AltR kb::MetaL kb::MetaR
2582 kb::SuperL kb::SuperR kb::HyperL kb::HyperR
2583 kb::CapsLock kb::NumLock kb::ScrollLock kb::ShiftLock
2584 Keys with character code defined
2586 kb::Backspace kb::Tab kb::Linefeed kb::Enter
2587 kb::Return kb::Escape kb::Esc kb::Space
2588 Function keys
2590 kb::F1 .. kb::F30
2591 kb::L1 .. kb::L10
2592 kb::R1 .. kb::R10
2593 Other
2595 kb::Clear kb::Pause kb::SysRq kb::SysReq
2596 kb::Delete kb::Home kb::Left kb::Up
2597 kb::Right kb::Down kb::PgUp kb::Prior
2598 kb::PageUp kb::PgDn kb::Next kb::PageDown
2599 kb::End kb::Begin kb::Select kb::Print
2600 kb::PrintScr kb::Execute kb::Insert kb::Undo
2601 kb::Redo kb::Menu kb::Find kb::Cancel
2602 kb::Help kb::Break kb::BackTab
2603 See also: "KeyUp", "briefKeys", "key_down", "help", "popup",
2605 "tabOrder", "tabStop", "accelTable"
2606 KeyUp CODE, KEY, MOD
2608 Sent to the focused widget when the user releases a key. CODE
2609 contains an eventual character code, KEY is one of "kb::XXX"
2610 constants, MOD is a combination of the modificator keys pressed
2611 when the event occurred ( "km::XXX" ).
2612 See also: "KeyDown", "key_up"
2614 Leave
2616 Called when the input focus is removed from a widget
2617 See also: "Enter", "focused", "selected"
2619 Menu MENU VAR_NAME
2621 Called before the user-navigated menu ( pop-up or pull-down ) is
2622 about to show another level of submenu on the screen. MENU is
2623 Prima::AbstractMenu descendant, that children to a widget, and
2624 VAR_NAME is the name of the menu item that is about to be shown.
2625 Used for making changes in the menu structures dynamically.
2627 See also: "popupItems"
2629 MouseClick BUTTON, MOD, X, Y, DOUBLE_CLICK
2631 Called when a mouse click ( button is pressed, and then released
2632 within system-defined interval of time ) is happened in the widget
2633 area. BUTTON is one of "mb::XXX" constants, MOD is a combination of
2634 "km::XXX" constants, reflecting pressed modificator keys during the
2635 event, X and Y are the mouse pointer coordinates. DOUBLE_CLICK is a
2636 boolean flag, set to 1 if it was a double click, 0 if a single.
2637 "mb::XXX" constants are:
2639 mb::b1 or mb::Left
2641 mb::b2 or mb::Middle
2642 mb::b3 or mb::Right
2643 mb::b4
2644 mb::b5
2645 mb::b6
2646 mb::b7
2647 mb::b8
2648 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseMove",
2650 "MouseEnter", "MouseLeave"
2651 MouseDown BUTTON, MOD, X, Y
2653 Occurs when the user presses mouse button on a widget. BUTTON is
2654 one of "mb::XXX" constants, MOD is a combination of "km::XXX"
2655 constants, reflecting the pressed modificator keys during the
2656 event, X and Y are the mouse pointer coordinates.
2657 See also: "MouseUp", "MouseClick", "MouseWheel", "MouseMove",
2659 "MouseEnter", "MouseLeave"
2660 MouseEnter MOD, X, Y
2662 Occurs when the mouse pointer is entered the area occupied by a
2663 widget ( without mouse button pressed ). MOD is a combination of
2664 "km::XXX" constants, reflecting the pressed modificator keys during
2665 the event, X and Y are the mouse pointer coordinates.
2666 See also: "MouseDown", "MouseUp", "MouseClick", "MouseWheel",
2668 "MouseMove", "MouseLeave"
2669 MouseLeave
2671 Occurs when the mouse pointer is driven off the area occupied by a
2672 widget ( without mouse button pressed ).
2673 See also: "MouseDown", "MouseUp", "MouseClick", "MouseWheel",
2675 "MouseMove", "MouseEnter"
2676 MouseMove MOD, X, Y
2678 Occurs when the mouse pointer is transported over a widget. MOD is
2679 a combination of "km::XXX" constants, reflecting the pressed
2680 modificator keys during the event, X and Y are the mouse pointer
2681 coordinates.
2682 See also: "MouseDown", "MouseUp", "MouseClick", "MouseWheel",
2684 "MouseEnter", "MouseLeave"
2685 MouseUp BUTTON, MOD, X, Y
2687 Occurs when the user depresses mouse button on a widget. BUTTON is
2688 one of "mb::XXX" constants, MOD is a combination of "km::XXX"
2689 constants, reflecting the pressed modificator keys during the
2690 event, X and Y are the mouse pointer coordinates.
2691 See also: "MouseDown", "MouseClick", "MouseWheel", "MouseMove",
2693 "MouseEnter", "MouseLeave"
2694 MouseWheel MOD, X, Y, INCR
2696 Occurs when the user rotates mouse wheel on a widget. MOD is a
2697 combination of "km::XXX" constants, reflecting the pressed
2698 modificator keys during the event, INCR is the wheel movement,
2699 scaled by 120. +120 is a step upwards, or -120 downwards. For
2700 wheels which are discrete button clicks INCR is +/-120 but other
2701 devices may give other amounts. A widget should scroll by INCR/120
2702 many units, or partial unit, for whatever its unit of movement
2703 might be, such as lines of text, slider ticks, etc.
2704 A widget might like to vary its unit move according to the MOD
2706 keys. For example "Prima::SpinEdit" has a "step" and "pageStep"
2707 and moves by "pageStep" when "km::Ctrl" is held down (see
2708 Prima::Sliders).
2709 See also: "MouseDown", "MouseUp", "MouseClick", "MouseMove",
2711 "MouseEnter", "MouseLeave"
2712 Move OLD_X, OLD_Y, NEW_X, NEW_Y
2714 Triggered when widget changes its position relative to its parent,
2715 either by Prima::Widget methods or by the user. OLD_X and OLD_Y
2716 are the old coordinates of a widget, NEW_X and NEW_Y are the new
2717 ones.
2718 See also: "Size", "origin", "growMode", "centered", "clipOwner"
2720 Paint CANVAS
2722 Caused when the system calls for the refresh of a graphic context,
2723 associated with a widget. CANVAS is the widget itself, however its
2724 usage instead of widget is recommended ( see "Graphic content" ).
2725 See also: "repaint", "syncPaint", "get_invalid_rect", "scroll",
2727 "colorIndex", "font"
2728 Popup BY_MOUSE, X, Y
2730 Called by the system when the user presses a key or mouse
2731 combination defined for a context pop-up menu execution. By
2732 default executes the associated Prima::Popup object, if it is
2733 present. If the event flag is cleared during the execution of
2734 callbacks, the pop-up menu is not shown.
2735 See also: "popup"
2737 Setup
2739 This message is posted right after "Create" notification, and comes
2740 first from the event loop. Prima::Widget does not use it.
2741 Show
2743 Triggered by a successive visible(1) call
2744 See also: "Show", "visible", "showing", "exposed"
2746 Size OLD_WIDTH, OLD_HEIGHT, NEW_WIDTH, NEW_HEIGHT
2748 Triggered when widget changes its size, either by Prima::Widget
2749 methods or by the user. OLD_WIDTH and OLD_HEIGHT are the old
2750 extensions of a widget, NEW_WIDTH and NEW_HEIGHT are the new ones.
2751 See also: "Move", "origin", "size", "growMode", "sizeMax",
2753 "sizeMin", "rect", "clipOwner"
2754 SysHandle
2756 Same as in "Component", but introduces the following "Widget"
2757 properties can trigger it:
2758 "clipOwner", "syncPaint", "layered", "transparent"
2760 This event will be only needed when the system handle (that can be
2762 acquired by "get_handle" ) is needed.
2763 TranslateAccel CODE, KEY, MOD
2765 A distributed "KeyDown" event. Traverses all the object tree that
2766 the widget which received original "KeyDown" event belongs to. Once
2767 the event flag is cleared, the iteration stops.
2768 Used for tracking keyboard events by out-of-focus widgets.
2770 See also: "KeyDown"
2772 ZOrderChanged
2774 Triggered when a widget changes its stacking order, or Z-order
2775 among its siblings, either by Prima::Widget methods or by the user.
2776 See also: "bring_to_front", "insert_behind", "send_to_back"
2778
2780 Dmitry Karasik, <dmitry@karasik.eu.org>.
2781
2783 Prima, Prima::Object, Prima::Drawable.
2784perl v5.32.0 2020-07-28 pod::Prima::Widget(3)