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 Markup text
922 "Prima::Drawable::Markup" provides text-like objects that can include
923 font and color change, and has a primitive image support. Since text
924 methods of "Prima::Drawable" such as "text_out", "get_text_width" etc
925 can detect if a text passed is actually a blessed object, and make a
926 corresponding call on it, the markup objects can be used transparently
927 when rich text is needed, simply by passing them to "text" and "hint"
928 properties.
929 There are two ways to construct a markup object: either directly:
931 Prima::Drawable::Markup->new( ... )
933 or using an imported method "M",
935 use Prima::Drawable::Markup q(M);
937 M '...';
938 where results of both can be directly set to almost any textual
940 property throughout the whole toolkit, provided that the classes are
941 not peeking inside the object but only calling drawing methods on them.
942 In addition to that, "Prima::Widget" and its descendants recognize a
944 third syntax
945 Widget->new( text => \ 'markup' )
947 treating a scalar reference to a text string as a sign that this is
949 actually the text to be compiled into a markup object.
950 Pointer
952 The mouse pointer is the shared resource, that can change its visual
953 representation when it hovers over different kinds of widgets. It is
954 usually a good practice for a text field, for example, set the pointer
955 icon to a jagged vertical line, or indicate a moving window with a
956 cross-arrowed pointer.
957 A widget can select either one of the predefined system pointers,
959 mapped by the "cr::XXX" constant set, or supply its own pointer icon of
960 an arbitrary size and color depth.
961 NB: Not all systems allow the colored pointer icons. System value under
963 sv::ColorPointer index containing a boolean value, whether the colored
964 icons are allowed or not. Also, the pointer icon size may have a limit:
965 check if sv::FixedPointerSize is non-zero, in which case the pointer
966 size will be reduced to the system limits.
967 In general, the "::pointer" property is enough for these actions. It
969 discerns whether it has an icon or a constant passed, and sets the
970 appropriate properties. These properties are also accessible
971 separately, although their usage is not encouraged, primarily because
972 of the tangled relationship between them. These properties are:
973 "::pointerType", "::pointerIcon", and "::pointerHotSpot". See their
974 details in the "API" sections.
975 Another property, which is present only in Prima::Application name
977 space is called "::pointerVisible", and governs the visibility of the
978 pointer - but for all widget instances at once.
979 Cursor
981 The cursor is a blinking rectangular area, indicating the availability
982 of the input focus in a widget. There can be only one active cursor per
983 a GUI space, or none at all. Prima::Widget provides several cursor
984 properties: "::cursorVisible", "::cursorPos", and "::cursorSize". There
985 are also two methods, "show_cursor()" and "hide_cursor()", which are
986 not the convenience shortcuts but the functions accounting the cursor
987 hide count. If "hide_cursor()" was called three times, then
988 "show_cursor()" must be called three times as well for the cursor to
989 become visible.
990 Hint
992 "::hint" is a text string, that usually describes the widget's purpose
993 to the user in a brief manner. If the mouse pointer is hovered over the
994 widget longer than some timeout ( see Prima::Application::hintPause ),
995 then a label appears with the hint text, until the pointer is drawn
996 away. The hint behavior is governed by Prima::Application, but a
997 widget can do two additional things about hint: it can enable and
998 disable it by calling "::showHint" property, and it can inherit the
999 owner's "::hint" and "::showHint" properties using "::ownerHint" and
1000 "::ownerShowHint" properties. If, for example, "::ownerHint" is set to
1001 1, then "::hint" value is automatically copied from the widget's owner,
1002 when it changes. If, however, the widget's "::hint" or "::showHint" are
1003 explicitly set, the owner link breaks automatically by setting
1004 "::ownerHint" or "::ownerShowHint" to 0.
1005 The widget can also operate the "::hintVisible" property, that shows or
1007 hides the hint label immediately, if the mouse pointer is inside the
1008 widget's boundaries.
1009 Menu objects
1011 The default functionality of Prima::Widget coexists with two kinds of
1012 the Prima::AbstractMenu descendants - Prima::AccelTable and
1013 Prima::Popup ( Prima::Window is also equipped with Prima::Menu
1014 reference). The "::items" property of these objects are accessible
1015 through "::accelItems" and "::popupItems", whereas the objects
1016 themselves - through "::accelTable" and "::popup", correspondingly. As
1017 mentioned in "User input", these objects hook the user keyboard input
1018 and call the programmer-defined callback subroutine if the key stroke
1019 equals to one of their table values. As for "::accelTable", its
1020 function ends here. "::popup" provides access to a context pop-up menu,
1021 which can be invoked by either right-clicking or pressing a system-
1022 dependent key combination. As a little customization, the
1023 "::popupColorIndex" and "::popupFont" properties are introduced. (
1024 "::popupColorIndex" is multiplexed to "::popupColor",
1025 "::popupHiliteColor", "::popupHiliteBackColor", etc etc properties
1026 exactly like the "::colorIndex" property ).
1027 The font and color of a menu object might not always be writable
1029 (Win32).
1030 The Prima::Window class provides equivalent methods for the menu bar,
1032 introducing "::menu", "::menuItems", "::menuColorIndex" ( with
1033 multiplexing ) and "::menuFont" properties.
1034 User-specified resources
1036 It is considered a good idea to incorporate the user preferences into
1037 the toolkit look-and-feel. Prima::Widget relies to the system-specific
1038 code that tries to map these preferences as close as possible to the
1039 toolkit paradigm.
1040 Unix version employs XRDB ( X resource database ), which is the natural
1042 way for the user to tell the preferences with fine granularity. Win32
1043 reads the setting that the user has to set interactively, using system
1044 tools. Nevertheless, the toolkit can not emulate all user settings that
1045 are available on the supported platforms; it rather takes a 'least
1046 common denominator', which is colors and fonts. "fetch_resource()"
1047 method is capable of returning any of such settings, provided it's
1048 format is font, color or a string. The method is rarely called
1049 directly.
1050 The appealing idea of making every widget property adjustable via the
1052 user-specified resources is not implemented in full. It can be
1053 accomplished up to a certain degree using "fetch_resource()" existing
1054 functionality, but it is believed that calling up the method for the
1055 every property for the every widget created is prohibitively expensive.
1056
1058 Properties
1059 accelItems [ ITEM_LIST ]
1060 Manages items of a Prima::AccelTable object associated with a
1061 widget. The ITEM_LIST format is same as
1062 "Prima::AbstractMenu::items" and is described in Prima::Menu.
1063 See also: "accelTable"
1065 accelTable OBJECT
1067 Manages a Prima::AccelTable object associated with a widget. The
1068 sole purpose of the accelTable object is to provide convenience
1069 mapping of key combinations to anonymous subroutines. Instead of
1070 writing an interface specifically for Prima::Widget, the existing
1071 interface of Prima::AbstractMenu was taken.
1072 The accelTable object can be destroyed safely; its cancellation can
1074 be done either via "accelTable(undef)" or "destroy()" call.
1075 Default value: undef
1077 See also: "accelItems"
1079 autoEnableChildren BOOLEAN
1081 If TRUE, all immediate children widgets maintain the same "enabled"
1082 state as the widget. This property is useful for the group-like
1083 widgets ( ComboBox, SpinEdit etc ), that employ their children for
1084 visual representation.
1085 Default value: 0
1087 backColor COLOR
1089 In widget paint state, reflects background color in the graphic
1090 context. In widget normal state, manages the basic background
1091 color. If changed, initiates "ColorChanged" notification and
1092 repaints the widget.
1093 See also: "color", "colorIndex", "ColorChanged"
1095 bottom INTEGER
1097 Maintains the lower boundary of a widget. If changed, does not
1098 affect the widget height; but does so, if called in "set()"
1099 together with "::top".
1100 See also: "left", "right", "top", "origin", "rect", "growMode",
1102 "Move"
1103 briefKeys BOOLEAN
1105 If 1, contracts the repetitive key press events into one
1106 notification, increasing REPEAT parameter of "KeyDown" callbacks.
1107 If 0, REPEAT parameter is always 1.
1108 Default value: 1
1110 See also: "KeyDown"
1112 buffered BOOLEAN
1114 If 1, a widget "Paint" callback draws not on the screen, but on the
1115 off-screen memory instead. The memory content is copied to the
1116 screen then. Used when complex drawing methods are used, or if
1117 output smoothness is desired.
1118 This behavior can not be always granted, however. If there is not
1120 enough memory, then widget draws in the usual manner.
1121 Default value: 0
1123 See also: "Paint"
1125 capture BOOLEAN, CLIP_OBJECT = undef
1127 Manipulates capturing of the mouse events. If 1, the mouse events
1128 are not passed to the widget the mouse pointer is over, but are
1129 redirected to the caller widget. The call for capture might not be
1130 always granted due the race conditions between programs.
1131 If CLIP_OBJECT widget is defined in set-mode call, the pointer
1133 movements are confined to CLIP_OBJECT inferior.
1134 See also: "MouseDown", "MouseUp", "MouseMove", "MouseWheel",
1136 "MouseClick".
1137 centered BOOLEAN
1139 A write-only property. Once set, widget is centered by X and Y axis
1140 relative to its owner.
1141 See also: "x_centered", "y_centered", "growMode", "origin", "Move".
1143 clipChildren BOOLEAN
1145 Affects the drawing mode when children widgets are present and
1146 obscuring the drawing area. If set, the children widgets are
1147 automatically added to the clipping area, and drawing over them
1148 will not happen. If unset, the painting can be done over the
1149 children widgets.
1150 Default: 1
1152 clipOwner BOOLEAN
1154 If 1, a widget is clipped by its owner boundaries. It is the
1155 default and expected behavior. If clipOwner is 0, a widget behaves
1156 differently: it does not clipped by the owner, it is not moved
1157 together with the parent, the origin offset is calculated not from
1158 the owner's coordinates but from the screen, and mouse events in a
1159 widget do not transgress to the top-level window decorations. In
1160 short, it itself becomes a top-level window, that, contrary to the
1161 one created from Prima::Window class, does not have any
1162 interference with system-dependent window stacking and positioning
1163 ( and any other ) policy, and is not ornamented by the window
1164 manager decorations.
1165 Default value: 1
1167 See "Parent-child relationship"
1169 See also: "Prima::Object" owner section, "parentHandle"
1171 color COLOR
1173 In widget paint state, reflects foreground color in the graphic
1174 context. In widget normal state, manages the basic foreground
1175 color. If changed, initiates "ColorChanged" notification and
1176 repaints the widget.
1177 See also: "backColor", "colorIndex", "ColorChanged"
1179 colorIndex INDEX, COLOR
1181 Manages the basic color properties indirectly, by accessing via
1182 "ci::XXX" constant. Is a complete alias for "::color",
1183 "::backColor", "::hiliteColor", "::hiliteBackColor",
1184 "::disabledColor", "::disabledBackColor", "::light3DColor", and
1185 "::dark3DColor" properties. The "ci::XXX" constants are:
1186 ci::NormalText or ci::Fore
1188 ci::Normal or ci::Back
1189 ci::HiliteText
1190 ci::Hilite
1191 ci::DisabledText
1192 ci::Disabled
1193 ci::Light3DColor
1194 ci::Dark3DColor
1195 The non-RGB "cl::" constants, specific to the Prima::Widget color
1197 usage are identical to their "ci::" counterparts:
1198 cl::NormalText or cl::Fore
1200 cl::Normal or cl::Back
1201 cl::HiliteText
1202 cl::Hilite
1203 cl::DisabledText
1204 cl::Disabled
1205 cl::Light3DColor
1206 cl::Dark3DColor
1207 See also: "color", "backColor", "ColorChanged"
1209 current BOOLEAN
1211 If 1, a widget (or one of its children) is marked as the one to be
1212 focused ( or selected) when the owner widget receives "select()"
1213 call. Within children widgets, only one or none at all can be
1214 marked as a current.
1215 See also: "currentWidget", "selectable", "selected",
1217 "selectedWidget", "focused"
1218 currentWidget OBJECT
1220 Points to a children widget, that is to be focused ( or selected)
1221 when the owner widget receives "select()" call.
1222 See also: "current", "selectable", "selected", "selectedWidget",
1224 "focused"
1225 cursorPos X_OFFSET Y_OFFSET
1227 Specifies the lower left corner of the cursor
1228 See also: "cursorSize", "cursorVisible"
1230 cursorSize WIDTH HEIGHT
1232 Specifies width and height of the cursor
1233 See also: "cursorPos", "cursorVisible"
1235 cursorVisible BOOLEAN
1237 Specifies cursor visibility flag. Default value is 0.
1238 See also: "cursorSize", "cursorPos"
1240 dark3DColor COLOR
1242 The color used to draw dark shades.
1243 See also: "light3DColor", "colorIndex", "ColorChanged"
1245 designScale X_SCALE Y_SCALE
1247 The width and height of a font, that was used when a widget (
1248 usually a dialog or a grouping widget ) was designed.
1249 See also: "scaleChildren", "width", "height", "size", "font"
1251 disabledBackColor COLOR
1253 The color used to substitute "::backColor" when a widget is in its
1254 disabled state.
1255 See also: "disabledColor", "colorIndex", "ColorChanged"
1257 disabledColor COLOR
1259 The color used to substitute "::color" when a widget is in its
1260 disabled state.
1261 See also: "disabledBackColor", "colorIndex", "ColorChanged"
1263 dndAware 0 | 1 | FORMAT
1265 To register a widget as a drop target, set its "dndAware" property
1266 to either 1, to mark that it will answer to all formats, or to a
1267 string, in which case drop events will only be delivered if the DND
1268 clipboard contains a format with that string.
1269 Default: 0
1271 See also: "Drag and Drop"
1273 enabled BOOLEAN
1275 Specifies if a widget can accept focus, keyboard and mouse events.
1276 Default value is 1, however, being 'enabled' does not automatically
1277 allow the widget become focused. Only the reverse is true - if
1278 enabled is 0, focusing can never happen.
1279 See also: "responsive", "visible", "Enable", "Disable"
1281 font %FONT
1283 Manages font context. Same syntax as in Prima::Drawable. If
1284 changed, initiates "FontChanged" notification and repaints the
1285 widget.
1286 See also: "designScale", "FontChanged", "ColorChanged"
1288 geometry INTEGER
1290 Selects one of the available geometry managers. The corresponding
1291 integer constants are:
1292 gt::GrowMode, gt::Default - the default grow-mode algorithm
1294 gt::Pack - Tk packer
1295 gt::Place - Tk placer
1296 See "growMode", Prima::Widget::pack, Prima::Widget::place.
1298 growMode MODE
1300 Specifies widget behavior, when its owner is resized or moved.
1301 MODE can be 0 ( default ) or a combination of the following
1302 constants:
1303 Basic constants
1305 gm::GrowLoX widget's left side is kept in constant
1306 distance from owner's right side
1307 gm::GrowLoY widget's bottom side is kept in constant
1308 distance from owner's top side
1309 gm::GrowHiX widget's right side is kept in constant
1310 distance from owner's right side
1311 gm::GrowHiY widget's top side is kept in constant
1312 distance from owner's top side
1313 gm::XCenter widget is kept in center on its owner's
1314 horizontal axis
1315 gm::YCenter widget is kept in center on its owner's
1316 vertical axis
1317 gm::DontCare widgets origin is maintained constant relative
1318 to the screen
1319 Derived or aliased constants
1321 gm::GrowAll gm::GrowLoX|gm::GrowLoY|gm::GrowHiX|gm::GrowHiY
1322 gm::Center gm::XCenter|gm::YCenter
1323 gm::Client gm::GrowHiX|gm::GrowHiY
1324 gm::Right gm::GrowLoX|gm::GrowHiY
1325 gm::Left gm::GrowHiY
1326 gm::Floor gm::GrowHiX
1327 See also: "Move", "origin"
1329 firstClick BOOLEAN
1331 If 0, a widget bypasses first mouse click on it, if the top-level
1332 window it belongs to was not activated, so selecting such a widget
1333 it takes two mouse clicks.
1334 Default value is 1
1336 See also: "MouseDown", "selectable", "selected", "focused",
1338 "selectingButtons"
1339 focused BOOLEAN
1341 Specifies whether a widget possesses the input focus or not.
1342 Disregards "::selectable" property on set-call.
1343 See also: "selectable", "selected", "selectedWidget", "KeyDown"
1345 geomWidth, geomHeight, geomSize
1347 Three properties that select geometry request size. Writing and
1348 reading to "::geomWidth" and "::geomHeight" is equivalent to
1349 "::geomSize". The properies are run-time only, and behave
1350 differently under different circumstances:
1351 • As the properties are run-time only, they can not be set in the
1353 profile, and their initial value is fetched from "::size"
1354 property. Thus, setting the explicit size is aditionally sets
1355 the advised size in case the widget is to be used with the Tk
1356 geometry managers.
1357 • Setting the properties under the "gt::GrowMode" geometry
1359 manager also sets the corresponding "::width", "::height", or
1360 "::size". When the properties are read, though, the real size
1361 properties are not read; the values are kept separately.
1362 • Setting the properties under Tk geometry managers cause widgets
1364 size and position changed according to the geometry manager
1365 policy.
1366 height
1368 Maintains the height of a widget.
1369 See also: "width", "growMode", "Move", "Size", "get_virtual_size",
1371 "sizeMax", "sizeMin"
1372 helpContext STRING
1374 A string that binds a widget, a logical part it plays with the
1375 application and an interactive help topic. STRING format is defined
1376 as POD link ( see perlpod ) - "manpage/section", where 'manpage' is
1377 the file with POD content and 'section' is the topic inside the
1378 manpage.
1379 See also: "help"
1381 hiliteBackColor COLOR
1383 The color used to draw alternate background areas with high
1384 contrast.
1385 See also: "hiliteColor", "colorIndex", "ColorChanged"
1387 hiliteColor COLOR
1389 The color used to draw alternate foreground areas with high
1390 contrast.
1391 See also: "hiliteBackColor", "colorIndex", "ColorChanged"
1393 hint TEXT
1395 A text, shown under mouse pointer if it is hovered over a widget
1396 longer than "Prima::Application::hintPause" timeout. The text shows
1397 only if the "::showHint" is 1.
1398 See also: "hintVisible", "showHint", "ownerHint", "ownerShowHint"
1400 hintVisible BOOLEAN
1402 If called in get-form, returns whether the hint label is shown or
1403 not. If in set-form, immediately turns on or off the hint label,
1404 disregarding the timeouts. It does regard the mouse pointer
1405 location, however, and does not turn on the hint label if the
1406 pointer is away.
1407 See also: "hint", "showHint", "ownerHint", "ownerShowHint"
1409 layered BOOLEAN
1411 If set, the widget will try to use alpha transparency available on
1412 the system. See "Layering" in Prima::Image for more details.
1413 Default: false
1415 See also: "is_surface_layered"
1417 Note: In Windows, mouse events will not be delivered to the layered
1419 widget if the pixel under the mouse pointer is fully transparent.
1420 In X11, you need to run a composition manager, f.ex. compiz or
1422 xcompmgr.
1423 left INTEGER
1425 Maintains the left boundary of a widget. If changed, does not
1426 affect the widget width; but does so, if called in "set()" together
1427 with "::right".
1428 See also: "bottom", "right", "top", "origin", "rect", "growMode",
1430 "Move"
1431 light3DColor COLOR
1433 The color used to draw light shades.
1434 See also: "dark3DColor", "colorIndex", "ColorChanged"
1436 ownerBackColor BOOLEAN
1438 If 1, the background color is synchronized with the owner's.
1439 Automatically set to 0 if "::backColor" property is explicitly set.
1440 See also: "ownerColor", "backColor", "colorIndex"
1442 ownerColor BOOLEAN
1444 If 1, the foreground color is synchronized with the owner's.
1445 Automatically set to 0 if "::color" property is explicitly set.
1446 See also: "ownerBackColor", "color", "colorIndex"
1448 ownerFont BOOLEAN
1450 If 1, the font is synchronized with the owner's. Automatically set
1451 to 0 if "::font" property is explicitly set.
1452 See also: "font", "FontChanged"
1454 ownerHint BOOLEAN
1456 If 1, the hint is synchronized with the owner's. Automatically set
1457 to 0 if "::hint" property is explicitly set.
1458 See also: "hint", "showHint", "hintVisible", "ownerShowHint"
1460 ownerShowHint BOOLEAN
1462 If 1, the show hint flag is synchronized with the owner's.
1463 Automatically set to 0 if "::showHint" property is explicitly set.
1464 See also: "hint", "showHint", "hintVisible", "ownerHint"
1466 ownerPalette BOOLEAN
1468 If 1, the palette array is synchronized with the owner's.
1469 Automatically set to 0 if "::palette" property is explicitly set.
1470 See also: "palette"
1472 origin X Y
1474 Maintains the left and bottom boundaries of a widget relative to
1475 its owner ( or to the screen if "::clipOwner" is set to 0 ).
1476 See also: "bottom", "right", "top", "left", "rect", "growMode",
1478 "Move"
1479 packInfo %OPTIONS
1481 See Prima::Widget::pack
1482 palette [ @PALETTE ]
1484 Specifies array of colors, that are desired to be present into the
1485 system palette, as close to the PALETTE as possible. This property
1486 works only if the graphic device allows palette operations. See
1487 "palette" in Prima::Drawable.
1488 See also: "ownerPalette"
1490 parentHandle SYSTEM_WINDOW
1492 If SYSTEM_WINDOW is a valid system-dependent window handle, then a
1493 widget becomes the child of the window specified, given the
1494 widget's "::clipOwner" is 0. The parent window can belong to
1495 another application.
1496 Default value is undef.
1498 See also: "clipOwner"
1500 placeInfo %OPTIONS
1502 See Prima::Widget::place
1503 pointer cr::XXX or ICON
1505 Specifies the pointer icon; discerns between "cr::XXX" constants
1506 and an icon. If an icon contains a hash variable "__pointerHotSpot"
1507 with an array of two integers, these integers will be treated as
1508 the pointer hot spot. In get-mode call, this variable is
1509 automatically assigned to an icon, if the result is an icon object.
1510 See also: "pointerHotSpot", "pointerIcon", "pointerType"
1512 pointerHotSpot X_OFFSET Y_OFFSET
1514 Specifies the hot spot coordinates of a pointer icon, associated
1515 with a widget.
1516 See also: "pointer", "pointerIcon", "pointerType"
1518 pointerIcon ICON
1520 Specifies the pointer icon, associated with a widget.
1521 See also: "pointerHotSpot", "pointer", "pointerType"
1523 pointerPos X_OFFSET Y_OFFSET
1525 Specifies the mouse pointer coordinates relative to widget's
1526 coordinates.
1527 See also: "get_mouse_state", "screen_to_client", "client_to_screen"
1529 pointerType TYPE
1531 Specifies the type of the pointer, associated with the widget.
1532 TYPE can accept one constant of "cr::XXX" set:
1533 cr::Default same pointer type as owner's
1535 cr::Arrow arrow pointer
1536 cr::Text text entry cursor-like pointer
1537 cr::Wait hourglass
1538 cr::Size general size action pointer
1539 cr::Move general move action pointer
1540 cr::SizeWest, cr::SizeW right-move action pointer
1541 cr::SizeEast, cr::SizeE left-move action pointer
1542 cr::SizeWE general horizontal-move action pointer
1543 cr::SizeNorth, cr::SizeN up-move action pointer
1544 cr::SizeSouth, cr::SizeS down-move action pointer
1545 cr::SizeNS general vertical-move action pointer
1546 cr::SizeNW up-right move action pointer
1547 cr::SizeSE down-left move action pointer
1548 cr::SizeNE up-left move action pointer
1549 cr::SizeSW down-right move action pointer
1550 cr::Invalid invalid action pointer
1551 cr::DragNone pointer for an invalid dragging target
1552 cr::DragCopy pointer to indicate that a dnd::Copy action can be accepted
1553 cr::DragMove pointer to indicate that a dnd::Move action can be accepted
1554 cr::DragLink pointer to indicate that a dnd::Link action can be accepted
1555 cr::User user-defined icon
1556 All constants except "cr::User" and "cr::Default" present a system-
1558 defined pointers, their icons and hot spot offsets. "cr::User" is a
1559 sign that an icon object was specified explicitly via
1560 "::pointerIcon" property. "cr::Default" is a way to tell that a
1561 widget inherits its owner pointer type, no matter is it a system-
1562 defined pointer or a custom icon.
1563 See also: "pointerHotSpot", "pointerIcon", "pointer"
1565 popup OBJECT
1567 Manages a Prima::Popup object associated with a widget. The
1568 purpose of the popup object is to show a context menu when the user
1569 right-clicks or selects the corresponding keyboard combination.
1570 Prima::Widget can host many children objects, Prima::Popup as well.
1571 But only the one that is set in "::popup" property will be
1572 activated automatically.
1573 The popup object can be destroyed safely; its cancellation can be
1575 done either via "popup(undef)" or "destroy()" call.
1576 See also: "Prima::Menu", "Popup", "Menu", "popupItems",
1578 "popupColorIndex", "popupFont"
1579 popupColorIndex INDEX, COLOR
1581 Maintains eight color properties of a pop-up context menu,
1582 associated with a widget. INDEX must be one of "ci::XXX" constants
1583 ( see "::colorIndex" property ).
1584 See also: "popupItems", "popupFont", "popup"
1586 popupColor COLOR
1588 Basic foreground in a popup context menu color.
1589 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1591 popupBackColor COLOR
1593 Basic background in a popup context menu color.
1594 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1596 popupDark3DColor COLOR
1598 Color for drawing dark shadings in a popup context menu.
1599 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1601 popupDisabledColor COLOR
1603 Foreground color for disabled items in a popup context menu.
1604 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1606 popupDisabledBackColor COLOR
1608 Background color for disabled items in a popup context menu.
1609 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1611 popupFont %FONT
1613 Maintains the font of a pop-up context menu, associated with a
1614 widget.
1615 See also: "popupItems", "popupColorIndex", "popup"
1617 popupHiliteColor COLOR
1619 Foreground color for selected items in a popup context menu.
1620 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1622 popupHiliteBackColor COLOR
1624 Background color for selected items in a popup context menu.
1625 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1627 popupItems [ ITEM_LIST ]
1629 Manages items of a Prima::Popup object associated with a widget.
1630 The ITEM_LIST format is same as "Prima::AbstractMenu::items" and is
1631 described in Prima::Menu.
1632 See also: "popup", "popupColorIndex", "popupFont"
1634 popupLight3DColor COLOR
1636 Color for drawing light shadings in a popup context menu.
1637 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1639 rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET Y_TOP_OFFSET
1641 Maintains the rectangular boundaries of a widget relative to its
1642 owner ( or to the screen if "::clipOwner" is set to 0 ).
1643 See also: "bottom", "right", "top", "left", "origin", "width",
1645 "height", "size" "growMode", "Move", "Size", "get_virtual_size",
1646 "sizeMax", "sizeMin"
1647 right INTEGER
1649 Maintains the right boundary of a widget. If changed, does not
1650 affect the widget width; but does so, if called in "set()" together
1651 with "::left".
1652 See also: "left", "bottom", "top", "origin", "rect", "growMode",
1654 "Move"
1655 scaleChildren BOOLEAN
1657 If a widget has "::scaleChildren" set to 1, then the newly-created
1658 children widgets inserted in it will be scaled corresponding to the
1659 owner's "::designScale", given that widget's "::designScale" is not
1660 "undef" and the owner's is not [0,0].
1661 Default is 1.
1663 See also: "designScale"
1665 selectable BOOLEAN
1667 If 1, a widget can be granted focus implicitly, or by means of the
1668 user actions. "select()" regards this property, and does not focus
1669 a widget that has "::selectable" set to 0.
1670 Default value is 0
1672 See also: "current", "currentWidget", "selected", "selectedWidget",
1674 "focused"
1675 selected BOOLEAN
1677 If called in get-mode, returns whether a widget or one of its
1678 (grand-) children is focused. If in set-mode, either simply turns
1679 the system with no-focus state ( if 0 ), or sends input focus to
1680 itself or one of the widgets tracked down by "::currentWidget"
1681 chain.
1682 See also: "current", "currentWidget", "selectable",
1684 "selectedWidget", "focused"
1685 selectedWidget OBJECT
1687 Points to a child widget, that has property "::selected" set to 1.
1688 See also: "current", "currentWidget", "selectable", "selected",
1690 "focused"
1691 selectingButtons FLAGS
1693 FLAGS is a combination of "mb::XXX" ( mouse button ) flags. If a
1694 widget receives a click with a mouse button, that has the
1695 corresponding bit set in "::selectingButtons", then "select()" is
1696 called.
1697 See also: "MouseDown", "firstClick", "selectable", "selected",
1699 "focused"
1700 shape REGION
1702 Maintains the non-rectangular shape of a widget. When setting,
1703 REGION is either a Prima::Image object, with 0 bits treated as
1704 transparent pixels, and 1 bits as opaque pixels, or a Prima::Region
1705 object. When getting, it is either undef or a Prima::Region
1706 object.
1707 Successive only if "sv::ShapeExtension" value is true.
1709 showHint BOOLEAN
1711 If 1, the toolkit is allowed to show the hint label over a widget.
1712 If 0, the display of the hint is forbidden. The "::hint" property
1713 must contain non-empty string as well, if the hint label must be
1714 shown.
1715 Default value is 1.
1717 See also: "hint", "ownerShowHint", "hintVisible", "ownerHint"
1719 size WIDTH HEIGHT
1721 Maintains the width and height of a widget.
1722 See also: "width", "height" "growMode", "Move", "Size",
1724 "get_virtual_size", "sizeMax", "sizeMin"
1725 sizeMax WIDTH HEIGHT
1727 Specifies the maximal size for a widget that it is allowed to
1728 accept.
1729 See also: "width", "height", "size" "growMode", "Move", "Size",
1731 "get_virtual_size", "sizeMin"
1732 sizeMin WIDTH HEIGHT
1734 Specifies the minimal size for a widget that it is allowed to
1735 accept.
1736 See also: "width", "height", "size" "growMode", "Move", "Size",
1738 "get_virtual_size", "sizeMax"
1739 syncPaint BOOLEAN
1741 If 0, the "Paint" request notifications are stacked until the event
1742 loop is called. If 1, every time the widget surface gets
1743 invalidated, the "Paint" notification is called.
1744 Default value is 0.
1746 See also: "invalidate_rect", "repaint", "validate_rect", "Paint"
1748 tabOrder INTEGER
1750 Maintains the order in which tab- and shift-tab- key navigation
1751 algorithms select the sibling widgets. INTEGER is unique among the
1752 sibling widgets. In set mode, if INTEGER value is already taken,
1753 the occupier is assigned another unique value, but without
1754 destruction of a queue - widgets with ::tabOrder greater than of
1755 the widget, receive their new values too. Special value -1 is
1756 accepted as 'the end of list' indicator; the negative value is
1757 never returned.
1758 See also: "tabStop", "next_tab", "selectable", "selected",
1760 "focused"
1761 tabStop BOOLEAN
1763 Specifies whether a widget is interested in tab- and shift-tab- key
1764 navigation or not.
1765 Default value is 1.
1767 See also: "tabOrder", "next_tab", "selectable", "selected",
1769 "focused"
1770 text TEXT
1772 A text string for generic purpose. Many Prima::Widget descendants
1773 use this property heavily - buttons, labels, input lines etc, but
1774 Prima::Widget itself does not.
1775 If "TEXT" is a reference to a string, it is translated as a markup
1777 string, and is compiled into a "Prima::Drawable::Markup" object
1778 internally.
1779 See Prima::Drawable::Markup, examples/markup.pl
1781 top INTEGER
1783 Maintains the upper boundary of a widget. If changed, does not
1784 affect the widget height; but does so, if called in "set()"
1785 together with "::bottom".
1786 See also: "left", "right", "bottom", "origin", "rect", "growMode",
1788 "Move"
1789 transparent BOOLEAN
1791 Specifies whether the background of a widget before it starts
1792 painting is of any importance. If 1, a widget can gain certain
1793 transparency look if it does not clear the background during
1794 "Paint" event.
1795 Default value is 0
1797 See also: "Paint", "buffered".
1799 visible BOOLEAN
1801 Specifies whether a widget is visible or not. See "Visibility".
1802 See also: "Show", "Hide", "showing", "exposed"
1804 widgetClass CLASS
1806 Maintains the integer value, designating the color class that is
1807 defined by the system and is associated with Prima::Widget eight
1808 basic color properties. CLASS can be one of "wc::XXX" constants:
1809 wc::Undef
1811 wc::Button
1812 wc::CheckBox
1813 wc::Combo
1814 wc::Dialog
1815 wc::Edit
1816 wc::InputLine
1817 wc::Label
1818 wc::ListBox
1819 wc::Menu
1820 wc::Popup
1821 wc::Radio
1822 wc::ScrollBar
1823 wc::Slider
1824 wc::Widget or wc::Custom
1825 wc::Window
1826 wc::Application
1827 These constants are not associated with the toolkit classes; any
1829 class can use any of these constants in "::widgetClass".
1830 See also: "map_color", "colorIndex"
1832 widgets @WIDGETS
1834 In get-mode, returns list of immediate children widgets (identical
1835 to "get_widgets"). In set-mode accepts set of widget profiles, as
1836 "insert" does, as a list or an array. This way it is possible to
1837 create widget hierarchy in a single call.
1838 width WIDTH
1840 Maintains the width of a widget.
1841 See also: "height" "growMode", "Move", "Size", "get_virtual_size",
1843 "sizeMax", "sizeMin"
1844 x_centered BOOLEAN
1846 A write-only property. Once set, widget is centered by the
1847 horizontal axis relative to its owner.
1848 See also: "centered", "y_centered", "growMode", "origin", "Move".
1850 y_centered BOOLEAN
1852 A write-only property. Once set, widget is centered by the vertical
1853 axis relative to its owner.
1854 See also: "x_centered", "centered", "growMode", "origin", "Move".
1856 Methods
1858 begin_drag [ DATA | %OPTIONS ]
1859 Wrapper over "dnd_start" that takes care of some DND session
1860 aspects other than the default system's. All input is contained in
1861 %OPTIONS hash, except for the case of a single-parameter call, in
1862 which case it is equivalent to "text => DATA" when "DATA" is a
1863 scalar, and to "image => DATA" when "DATA" is a reference.
1864 Returns -1 if a session cannot start, "dnd::None" if it was
1866 cancelled by the user, or any other "dnd::" constant when the DND
1867 receiver has selected and successfully performed that action. For
1868 example, after a call to "dnd_start" returning "dnd::Move"
1869 (depending on a context), the caller may remove the data the user
1870 selected to move ("Prima::InputLine" and "Prima::Edit" do exactly
1871 this).
1872 In "wantarray" context also returns the widget that accepted the
1874 drop, if that was a Prima widget. Check this before handling
1875 "dnd::Move" actions that require data to be deleted on the source,
1876 to not occasionally delete the freshly transferred data. The method
1877 uses a precaution for this scenario and by default won't let the
1878 widget to be both a sender and a receiver though ( see "self_aware"
1879 below ).
1880 The following input is recognized:
1882 actions INTEGER = dnd::Copy
1884 Combination of "dnd::" constants, to tell a DND receiver
1885 whether copying, moving, and/or linking of the data is allowed.
1886 The method fails on the invalid "actions" input.
1887 format FORMAT, data INPUT
1889 If set, the clipboard will be assigned to contain a single
1890 entry of "INPUT" of the "FORMAT" format, where format is either
1891 one of the standard "Text" or "Image", or one of the format
1892 registered by "Clipboard::register_format".
1893 If not set, the caller needs to fill the clipboard in advance,
1895 f.ex. to offer data in more than one format.
1896 image INPUT
1898 Shortcut for " format =" 'Image', data => $INPUT, preview =>
1899 $INPUT >
1900 preview INPUT
1902 If set, mouse pointers sending feedback to the user will be
1903 equipped with either text or image (depending on whether
1904 "INPUT" is a scalar or an image reference).
1905 self_aware BOOLEAN = 1
1907 If unset the widget's "dndAware" will be temporarily set to 0,
1908 to exclude a possibility of an operation that may end in
1909 sending data to itself.
1910 text INPUT
1912 Shortcut for " format =" 'Text', data => $INPUT, preview =>
1913 $INPUT >
1914 track INTEGER = 5
1916 When set, waits with starting the DND process until the user
1917 moves the pointer from the starting point further than "track"
1918 pixels, which makes sense if the method to be called directly
1919 from a "MouseDown" event handler.
1920 If the drag did not happen because the user released the button
1922 or otherwise marked that this is not a drag, -1 is returned. In
1923 that case, the caller should continue to handle "MouseDown"
1924 event as if no drag sesssion was ever started.
1925 bring_to_front
1927 Sends a widget on top of all other siblings widgets
1928 See also: "insert_behind", "send_to_back", "ZOrderChanged"
1930 ,"first", "next", "prev", "last"
1931 can_close
1933 Sends "Close" message, and returns its boolean exit state.
1934 See also: "Close", "close"
1936 client_to_screen @OFFSETS
1938 Maps array of X and Y integer offsets from widget to screen
1939 coordinates. Returns the mapped OFFSETS.
1940 See also: "screen_to_client", "clipOwner"
1942 close
1944 Calls "can_close()", and if successful, destroys a widget. Returns
1945 the "can_close()" result.
1946 See also: "can_close", "Close"
1948 defocus
1950 Alias for focused(0) call
1951 See also: "focus", "focused", "Enter", "Leave"
1953 deselect
1955 Alias for selected(0) call
1956 See also: "select", "selected", "Enter", "Leave"
1958 dnd_start ACTIONS = dnd::Copy, USE_DEFAULT_POINTERS = 1
1960 Starts a drag and drop session with a combination of "ACTIONS"
1961 allowed. It is expected that a DND clipboard will be filled with
1962 data that are prepared to be sent to a DND receiver.
1963 Returns -1 if a session cannot start, "dnd::None" if it was
1965 cancelled by the user, or any other "dnd::" constant when the DND
1966 receiver has selected and successfully performed that action. For
1967 example, after a call to "dnd_start" returning "dnd::Move"
1968 (depending on a context), the called may remove the data the user
1969 selected to move ("Prima::InputLine" and "Prima::Edit" do exactly
1970 this).
1971 Also returns the widget that accepted the drop, if that was a Prima
1973 widget within the same program.
1974 If USE_DEFAULT_POINTERS is set, then the system will use default
1976 drag pointers. Otherwise it is expected that a "DragResponse"
1977 action will change them according to current action, to give the
1978 user a visual feedback.
1979 See "begin_drag" for a wrapper over this method that handles also
1981 for other DND aspects.
1982 See also: "Drag and Drop", "DragQuery", "DragResponse".
1984 exposed
1986 Returns a boolean value, indicating whether a widget is at least
1987 partly visible on the screen. Never returns 1 if a widget has
1988 "::visible" set to 0.
1989 See also: "visible", "showing", "Show", "Hide"
1991 fetch_resource CLASS_NAME, NAME, CLASS_RESOURCE, RESOURCE, OWNER,
1993 RESOURCE_TYPE = fr::String
1994 Returns a system-defined scalar of resource, defined by the widget
1995 hierarchy, its class, name and owner. RESOURCE_TYPE can be one of
1996 type qualificators:
1997 fr::Color - color resource
1999 fr::Font - font resource
2000 fs::String - text string resource
2001 Such a number of the parameters is used because the method can be
2003 called before a widget is created. CLASS_NAME is widget class
2004 string, NAME is widget name. CLASS_RESOURCE is class of resource,
2005 and RESOURCE is the resource name.
2006 For example, resources 'color' and 'disabledColor' belong to the
2008 resource class 'Foreground'.
2009 first
2011 Returns the first ( from bottom ) sibling widget in Z-order.
2012 See also: "last", "next", "prev"
2014 focus
2016 Alias for focused(1) call
2017 See also: "defocus", "focused", "Enter", "Leave"
2019 hide
2021 Sets widget "::visible" to 0.
2022 See also: "hide", "visible", "Show", "Hide", "showing", "exposed"
2024 hide_cursor
2026 Hides the cursor. As many times "hide_cursor()" was called, as many
2027 time its counterpart "show_cursor()" must be called to reach the
2028 cursor's initial state.
2029 See also: "show_cursor", "cursorVisible"
2031 help
2033 Starts an interactive help viewer opened on "::helpContext" string
2034 value.
2035 The string value is combined from the widget's owner
2037 "::helpContext" strings if the latter is empty or begins with a
2038 slash. A special meaning is assigned to an empty string " " - the
2039 help() call fails when such value is found to be the section
2040 component. This feature can be useful when a window or a dialog
2041 presents a standalone functionality in a separate module, and the
2042 documentation is related more to the module than to an embedding
2043 program. In such case, the grouping widget holds "::helpContext" as
2044 a pod manpage name with a trailing slash, and its children widgets
2045 are assigned "::helpContext" to the topics without the manpage but
2046 the leading slash instead. If the grouping widget has an empty
2047 string " " as "::helpContext" then the help is forced to be
2048 unavailable for all the children widgets.
2049 See also: "helpContext"
2051 insert CLASS, %PROFILE [[ CLASS, %PROFILE], ... ]
2053 Creates one or more widgets with "owner" property set to the caller
2054 widget, and returns the list of references to the newly created
2055 widgets.
2056 Has two calling formats:
2058 Single widget
2060 $parent-> insert( 'Child::Class',
2061 name => 'child',
2062 ....
2063 );
2064 Multiple widgets
2066 $parent-> insert(
2067 [
2068 'Child::Class1',
2069 name => 'child1',
2070 ....
2071 ],
2072 [
2073 'Child::Class2',
2074 name => 'child2',
2075 ....
2076 ],
2077 );
2078 insert_behind OBJECT
2080 Sends a widget behind the OBJECT on Z-axis, given that the OBJECT
2081 is a sibling to the widget.
2082 See also: "bring_to_front", "send_to_back", "ZOrderChanged"
2084 ,"first", "next", "prev", "last"
2085 invalidate_rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET
2087 Y_TOP_OFFSET
2088 Marks the rectangular area of a widget as 'invalid', so re-painting
2089 of the area happens. See "Graphic content".
2090 See also: "validate_rect", "get_invalid_rect", "repaint", "Paint",
2092 "syncPaint", "update_view"
2093 is_surface_layered
2095 Returns true if both the widget and it's top-most parent are
2096 layered. If the widget itself is top-most, i.e. a window, a non-
2097 clipOwner widget, or a child to application, then is the same as
2098 "layered".
2099 See also: "layered"
2101 key_down CODE, KEY = kb::NoKey, MOD = 0, REPEAT = 1, POST = 0
2103 The method sends or posts ( POST flag ) simulated "KeyDown" event
2104 to the system. CODE, KEY, MOD and REPEAT are the parameters to be
2105 passed to the notification callbacks.
2106 See also: "key_up", "key_event", "KeyDown"
2108 key_event COMMAND, CODE, KEY = kb::NoKey, MOD = 0, REPEAT = 1, POST = 0
2110 The method sends or posts ( POST flag ) simulated keyboard event to
2111 the system. CODE, KEY, MOD and REPEAT are the parameters to be
2112 passed to an eventual "KeyDown" or "KeyUp" notifications. COMMAND
2113 is allowed to be either "cm::KeyDown" or "cm::KeyUp".
2114 See also: "key_down", "key_up", "KeyDown", "KeyUp"
2116 key_up CODE, KEY = kb::NoKey, MOD = 0, POST = 0
2118 The method sends or posts ( POST flag ) simulated "KeyUp" event to
2119 the system. CODE, KEY and MOD are the parameters to be passed to
2120 the notification callbacks.
2121 See also: "key_down", "key_event", "KeyUp"
2123 last
2125 Returns the last ( the topmost ) sibling widget in Z-order.
2126 See also: "first", "next", "prev"
2128 lock
2130 Turns off the ability of a widget to re-paint itself. As many
2131 times "lock()" was called, as may times its counterpart, "unlock()"
2132 must be called to enable re-painting again. Returns a boolean
2133 success flag.
2134 See also: "unlock", "repaint", "Paint", "get_locked"
2136 map_color COLOR
2138 Transforms "cl::XXX" and "ci::XXX" combinations into RGB color
2139 representation and returns the result. If COLOR is already in RGB
2140 format, no changes are made.
2141 See also: "colorIndex"
2143 mouse_click BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, DBL_CLICK = 0,
2145 POST = 0
2146 The method sends or posts ( POST flag ) simulated "MouseClick"
2147 event to the system. BUTTON, MOD, X, Y, and DBL_CLICK are the
2148 parameters to be passed to the notification callbacks.
2149 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseMove",
2151 "MouseEnter", "MouseLeave"
2152 mouse_down BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, POST = 0
2154 The method sends or posts ( POST flag ) simulated "MouseDown" event
2155 to the system. BUTTON, MOD, X, and Y are the parameters to be
2156 passed to the notification callbacks.
2157 See also: "MouseUp", "MouseWheel", "MouseClick", "MouseMove",
2159 "MouseEnter", "MouseLeave"
2160 mouse_enter MOD = 0, X = 0, Y = 0, POST = 0
2162 The method sends or posts ( POST flag ) simulated "MouseEnter"
2163 event to the system. MOD, X, and Y are the parameters to be passed
2164 to the notification callbacks.
2165 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseClick",
2167 "MouseMove", "MouseLeave"
2168 mouse_event COMMAND = cm::MouseDown, BUTTON = mb::Left, MOD = 0, X = 0,
2170 Y = 0, DBL_CLICK = 0, POST = 0
2171 The method sends or posts ( POST flag ) simulated mouse event to
2172 the system. BUTTON, MOD, X, Y and DBL_CLICK are the parameters to
2173 be passed to an eventual mouse notifications. COMMAND is allowed
2174 to be one of "cm::MouseDown", "cm::MouseUp", "cm::MouseWheel",
2175 "cm::MouseClick", "cm::MouseMove", "cm::MouseEnter",
2176 "cm::MouseLeave" constants.
2177 See also: "mouse_down", "mouse_up", "mouse_wheel", "mouse_click",
2179 "mouse_move", "mouse_enter", "mouse_leave", "MouseDown", "MouseUp",
2180 "MouseWheel", "MouseClick", "MouseMove", "MouseEnter", "MouseLeave"
2181 mouse_leave
2183 The method sends or posts ( POST flag ) simulated "MouseLeave"
2184 event to the system.
2185 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseClick",
2187 "MouseMove", "MouseEnter", "MouseLeave"
2188 mouse_move MOD = 0, X = 0, Y = 0, POST = 0
2190 The method sends or posts ( POST flag ) simulated "MouseMove" event
2191 to the system. MOD, X, and Y are the parameters to be passed to the
2192 notification callbacks.
2193 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseClick",
2195 "MouseEnter", "MouseLeave"
2196 mouse_up BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, POST = 0
2198 The method sends or posts ( POST flag ) simulated "MouseUp" event
2199 to the system. BUTTON, MOD, X, and Y are the parameters to be
2200 passed to the notification callbacks.
2201 See also: "MouseDown", "MouseWheel", "MouseClick", "MouseMove",
2203 "MouseEnter", "MouseLeave"
2204 mouse_wheel MOD = 0, X = 0, Y = 0, INCR = 0, POST = 0
2206 The method sends or posts ( POST flag ) simulated "MouseUp" event
2207 to the system. MOD, X, Y and INCR are the parameters to be passed
2208 to the notification callbacks.
2209 See also: "MouseDown", "MouseUp", "MouseClick", "MouseMove",
2211 "MouseEnter", "MouseLeave"
2212 next
2214 Returns the neighbor sibling widget, next ( above ) in Z-order. If
2215 none found, undef is returned.
2216 See also: "first", "last", "prev"
2218 next_tab FORWARD = 1
2220 Returns the next widget in the sorted by "::tabOrder" list of
2221 sibling widgets. FORWARD is a boolean lookup direction flag. If
2222 none found, the first ( or the last, depending on FORWARD flag )
2223 widget is returned. Only widgets with "::tabStop" set to 1
2224 participate.
2225 Also used by the internal keyboard navigation code.
2227 See also: "next_positional", "tabOrder", "tabStop", "selectable"
2229 next_positional DELTA_X DELTA_Y
2231 Returns a sibling, (grand-)child of a sibling or (grand-)child
2232 widget, that matched best the direction specified by DELTA_X and
2233 DELTA_Y. At one time, only one of these parameters can be zero;
2234 another parameter must be either 1 or -1.
2235 Also used by the internal keyboard navigation code.
2237 See also: "next_tab", "origin"
2239 pack, packForget, packSlaves
2241 See Prima::Widget::pack
2242 place, placeForget, placeSlaves
2244 See Prima::Widget::place
2245 prev
2247 Returns the neighbor sibling widget, previous ( below ) in Z-order.
2248 If none found, undef is returned.
2249 See also: "first", "last", "next"
2251 repaint
2253 Marks the whole widget area as 'invalid', so re-painting of the
2254 area happens. See "Graphic content".
2255 See also: "validate_rect", "get_invalid_rect", "invalidate_rect",
2257 "Paint", "update_view", "syncPaint"
2258 rect_bevel $CANVAS, @RECT, %OPTIONS
2260 Draws a rectangular area, similar to produced by "rect3d" over
2261 @RECT that is 4-integer coordinates of the area, but implicitly
2262 using widget's "light3DColor" and "dark3DColor" properties' values.
2263 The following options are recognized:
2264 fill COLOR
2266 If set, the area is filled with COLOR, ortherwise is left
2267 intact.
2268 width INTEGER
2270 Width of the border in pixels
2271 concave BOOLEAN
2273 If 1, draw a concave area, bulged otherwise
2274 responsive
2276 Returns a boolean flag, indicating whether a widget and its owners
2277 have all "::enabled" 1 or not. Useful for fast check if a widget
2278 should respond to the user actions.
2279 See also: "enabled"
2281 screen_to_client @OFFSETS
2283 Maps array of X and Y integer offsets from screen to widget
2284 coordinates. Returns the mapped OFFSETS.
2285 See also: "client_to_screen"
2287 scroll DELTA_X DELTA_Y %OPTIONS
2289 Scrolls the graphic context area by DELTA_X and DELTA_Y pixels.
2290 OPTIONS is hash, that contains optional parameters to the scrolling
2291 procedure:
2292 clipRect [X1, Y1, X2, Y2]
2294 The clipping area is confined by X1, Y1, X2, Y2 rectangular
2295 area. If not specified, the clipping area covers the whole
2296 widget. Only the bits, covered by clipRect are affected. Bits
2297 scrolled from the outside of the rectangle to the inside are
2298 painted; bits scrolled from the inside of the rectangle to the
2299 outside are not painted.
2300 confineRect [X1, Y1, X2, Y2]
2302 The scrolling area is confined by X1, Y1, X2, Y2 rectangular
2303 area. If not specified, the scrolling area covers the whole
2304 widget.
2305 withChildren BOOLEAN
2307 If 1, the scrolling performs with the eventual children widgets
2308 change their positions to DELTA_X and DELTA_Y as well.
2309 Returns one of the following constants:
2311 scr::Error - failure
2313 scr::NoExpose - call resulted in no new exposed areas
2314 scr::Expose - call resulted in new exposed areas, expect a repaint
2315 Cannot be used inside paint state.
2317 See also: "Paint", "get_invalid_rect"
2319 select
2321 Alias for selected(1) call
2322 See also: "deselect", "selected", "Enter", "Leave"
2324 send_to_back
2326 Sends a widget at bottom of all other siblings widgets
2327 See also: "insert_behind", "bring_to_front", "ZOrderChanged"
2329 ,"first", "next", "prev", "last"
2330 show
2332 Sets widget "::visible" to 1.
2333 See also: "hide", "visible", "Show", "Hide", "showing", "exposed"
2335 show_cursor
2337 Shows the cursor. As many times "hide_cursor()" was called, as many
2338 time its counterpart "show_cursor()" must be called to reach the
2339 cursor's initial state.
2340 See also: "hide_cursor", "cursorVisible"
2342 showing
2344 Returns a boolean value, indicating whether the widget and its
2345 owners have all "::visible" 1 or not.
2346 unlock
2348 Turns on the ability of a widget to re-paint itself. As many times
2349 "lock()" was called, as may times its counterpart, "unlock()" must
2350 be called to enable re-painting again. When last "unlock()" is
2351 called, an implicit "repaint()" call is made. Returns a boolean
2352 success flag.
2353 See also: "lock", "repaint", "Paint", "get_locked"
2355 update_view
2357 If any parts of a widget were marked as 'invalid' by either
2358 "invalidate_rect()" or "repaint()" calls or the exposure caused by
2359 window movements ( or any other), then "Paint" notification is
2360 immediately called. If no parts are invalid, no action is
2361 performed. If a widget has "::syncPaint" set to 1, "update_view()"
2362 is always a no-operation call.
2363 See also: "invalidate_rect", "get_invalid_rect", "repaint",
2365 "Paint", "syncPaint", "update_view"
2366 validate_rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET Y_TOP_OFFSET
2368 Reverses the effect of "invalidate_rect()", restoring the original,
2369 'valid' state of widget area covered by the rectangular area
2370 passed. If a widget with previously invalid areas was wholly
2371 validated by this method, no "Paint" notifications occur.
2372 See also: "invalidate_rect", "get_invalid_rect", "repaint",
2374 "Paint", "syncPaint", "update_view"
2375 Get-methods
2377 get_default_font
2378 Returns the default font for a Prima::Widget class.
2379 See also: "font"
2381 get_default_popup_font
2383 Returns the default font for a Prima::Popup class.
2384 See also: "font"
2386 get_invalid_rect
2388 Returns the result of successive calls "invalidate_rect()",
2389 "validate_rect()" and "repaint()", as a rectangular area ( four
2390 integers ) that cover all invalid regions in a widget. If none
2391 found, (0,0,0,0) is returned.
2392 See also: "validate_rect", "invalidate_rect", "repaint", "Paint",
2394 "syncPaint", "update_view"
2395 get_handle
2397 Returns a system handle for a widget
2398 See also: "get_parent_handle", "Window::get_client_handle"
2400 get_locked
2402 Returns 1 if a widget is in "lock()" - initiated repaint-blocked
2403 state.
2404 See also: "lock", "unlock"
2406 get_mouse_state
2408 Returns a combination of "mb::XXX" constants, reflecting the
2409 currently pressed mouse buttons.
2410 See also: "pointerPos", "get_shift_state"
2412 get_parent
2414 Returns the owner widget that clips the widget boundaries, or
2415 application object if a widget is top-level.
2416 See also: "clipOwner"
2418 get_parent_handle
2420 Returns a system handle for a parent of a widget, a window that
2421 belongs to another program. Returns 0 if the widget's owner and
2422 parent are in the same application and process space.
2423 See also: "get_handle", "clipOwner"
2425 get_pointer_size
2427 Returns two integers, width and height of a icon, that the system
2428 accepts as valid for a pointer. If the icon is supplied that is
2429 more or less than these values, it is truncated or padded with
2430 transparency bits, but is not stretched. Can be called with class
2431 syntax.
2432 get_shift_state
2434 Returns a combination of "km::XXX" constants, reflecting the
2435 currently pressed keyboard modificator buttons.
2436 See also: "get_shift_state"
2438 get_virtual_size
2440 Returns virtual width and height of a widget. See "Geometry",
2441 Implicit size regulations.
2442 See also: "width", "height", "size" "growMode", "Move", "Size",
2444 "sizeMax", "sizeMin"
2445 get_widgets
2447 Returns list of children widgets.
2448 Events
2450 Change
2451 Generic notification, used for Prima::Widget descendants;
2452 Prima::Widget itself neither calls not uses the event. Designed to
2453 be called when an arbitrary major state of a widget is changed.
2454 Click
2456 Generic notification, used for Prima::Widget descendants;
2457 Prima::Widget itself neither calls not uses the event. Designed to
2458 be called when an arbitrary major action for a widget is called.
2459 Close
2461 Triggered by "can_close()" and "close()" functions. If the event
2462 flag is cleared during execution, these functions fail.
2463 See also: "close", "can_close"
2465 ColorChanged INDEX
2467 Called when one of widget's color properties is changed, either by
2468 direct property change or by the system. INDEX is one of "ci::XXX"
2469 constants.
2470 See also: "colorIndex"
2472 Disable
2474 Triggered by a successive enabled(0) call
2475 See also: "Enable", "enabled", "responsive"
2477 DragBegin CLIPBOARD, ACTION, MOD, X, Y, COUNTERPART
2479 Triggered on a receiver widget when a mouse with a DND object
2480 enters it. "CLIPBOARD" contains the DND data, "ACTION" is a
2481 combination of "dnd::" constants, the actions the sender is ready
2482 to offer, "MOD" is a combination of modifier keys ("kb::"), and "X"
2483 and "Y" are coordinates where the mouse has entered the widget.
2484 This event, and the following "DragOver" and "DragEnd" events are
2485 happening only if the property "dndAware" is set either to 1, or if
2486 it matches a clipboard format that exists in "CLIPBOARD".
2487 "COUNTERPART" is the Prima DND sender widget, if the session is
2489 initiated within the same program.
2490 See also: "Drag and Drop", "DragOver", "DragEnd"
2492 DragEnd CLIPBOARD, ACTION, MOD, X, Y, COUNTERPART, ANSWER
2494 Triggered on a received widget when the user either drops or
2495 cancels the DND session. In case of a cancelled drop, "CLIPBOARD"
2496 is set to "undef" and "ACTION" to "dnd::None". On a successful
2497 drop, input data are same as on "DragBegin", and output data are to
2498 be stored in hashref "ANSWER", if any. The following answers can
2499 be stored:
2500 allow BOOLEAN
2502 Is pre-set to 1. If changed to 0, a signal will be send to the
2503 sender that a drop is not accepted.
2504 action INTEGER
2506 A "dnd::" constant (not a combination) to be returned to the
2507 sender with the action the receiver has accepted, if any.
2508 "COUNTERPART" is the Prima DND sender widget, if the session is
2510 initiated within the same program.
2511 See also: "Drag and Drop", "DragBegin", "DragOver"
2513 DragOver CLIPBOARD, ACTION, MOD, X, Y, COUNTERPART, ANSWER
2515 Triggered on a received widget when a mouse with a DND moves within
2516 the widget. Input data are same as on "DragBegin", and output data
2517 are to be stored in hashref "ANSWER", if any. The following answers
2518 can be stored:
2519 allow BOOLEAN
2521 Is pre-set to 1. If changed to 0, a signal will be send to the
2522 sender that a drop action cannot happen with the input
2523 provided.
2524 action INTEGER
2526 A "dnd::" constant (not a combination) to be returned to the
2527 sender with the action the receiver is ready to accept, if any.
2528 pad X, Y, WIDTH, HEIGHT
2530 If set, instructs the sender not to repeat "DragOver" events
2531 that contains same input data, while the mouse pointer is
2532 within these geometrical limits.
2533 "COUNTERPART" is the Prima DND sender widget, if the session is
2535 initiated within the same program.
2536 DragQuery MOD, ANSWERS, COUNTERPART
2538 Triggered on a sender DND widget when there was detected a change
2539 in mouse or modifier buttons, or the user pressed "Escape" key to
2540 cancel the DND session. The combination of mouse and modifier
2541 buttons is stored in "MOD" integer, together with a special
2542 "km::Escape" constant for the "Escape" key.
2543 It is up to this event to decide whether to continue the drag
2545 session or not, and if it is decided not to continue,
2546 "$answer-"{allow}> must be set to 0.
2547 Additionally, "$answer-"{action}> can be set to select a single
2549 "dnd::" action that will be used to propose to the receiver a
2550 single concrete action based on the "MOD" value (f.ex. a
2551 "dnd::Move" if a control modifier was pressed).
2552 Note: This action will only forward the change to the receiver on
2554 X11, but it is advised to implement it anyway for portability.
2555 "COUNTERPART" is the Prima DND receiver widget, if within the same
2557 program.
2558 See also: "Drag and Drop", "DragResponse"
2560 DragResponse ALLOW, ACTION, COUNTERPART
2562 Triggered on a sender DND widget when there was detected a change
2563 in mouse or modifier buttons, or the mouse was moved from one DND
2564 target to another. The sender event is then presented with the new
2565 input, collected from interaction with the new target; there,
2566 "ALLOW" is set to a boolean value whether the sender is allowed to
2567 drop data, and "ACTION" is a "dnd::" constant with the action the
2568 receiver has agreed to accept, if any.
2569 If the drag and drop session was told not to update mouse pointers
2571 on such event, the handle should update the pointer in this
2572 callback. It is not needed though to save and restore mouse
2573 pointers before and after the DND session.
2574 "COUNTERPART" is the Prima DND receiver widget, if within the same
2576 program. See also: "Drag and Drop", "dnd_start", "begin_drag".
2577 Enable
2579 Triggered by a successive enabled(1) call
2580 See also: "Disable", "enabled", "responsive"
2582 Enter
2584 Called when a widget receives the input focus.
2585 See also: "Leave", "focused", "selected"
2587 FontChanged
2589 Called when a widget font is changed either by direct property
2590 change or by the system.
2591 See also: "font", "ColorChanged"
2593 Hide
2595 Triggered by a successive visible(0) call
2596 See also: "Show", "visible", "showing", "exposed"
2598 Hint SHOW_FLAG
2600 Called when the hint label is about to show or hide, depending on
2601 SHOW_FLAG. The hint show or hide action fails, if the event flag is
2602 cleared during execution.
2603 See also: "showHint", "ownerShowHint", "hintVisible", "ownerHint"
2605 KeyDown CODE, KEY, MOD, REPEAT
2607 Sent to the focused widget when the user presses a key. CODE
2608 contains an eventual character code, KEY is one of "kb::XXX"
2609 constants, MOD is a combination of the modificator keys pressed
2610 when the event occurred ( "km::XXX" ). REPEAT is how many times the
2611 key was pressed; usually it is 1. ( see "::briefKeys" ).
2612 The valid "km::" constants are:
2614 km::Shift
2616 km::Ctrl
2617 km::Alt
2618 km::KeyPad
2619 km::DeadKey
2620 km::Unicode
2621 The valid "kb::" constants are grouped in several sets. Some codes
2623 are aliased, like, "kb::PgDn" and "kb::PageDown".
2624 Modificator keys
2626 kb::ShiftL kb::ShiftR kb::CtrlL kb::CtrlR
2627 kb::AltL kb::AltR kb::MetaL kb::MetaR
2628 kb::SuperL kb::SuperR kb::HyperL kb::HyperR
2629 kb::CapsLock kb::NumLock kb::ScrollLock kb::ShiftLock
2630 Keys with character code defined
2632 kb::Backspace kb::Tab kb::Linefeed kb::Enter
2633 kb::Return kb::Escape kb::Esc kb::Space
2634 Function keys
2636 kb::F1 .. kb::F30
2637 kb::L1 .. kb::L10
2638 kb::R1 .. kb::R10
2639 Other
2641 kb::Clear kb::Pause kb::SysRq kb::SysReq
2642 kb::Delete kb::Home kb::Left kb::Up
2643 kb::Right kb::Down kb::PgUp kb::Prior
2644 kb::PageUp kb::PgDn kb::Next kb::PageDown
2645 kb::End kb::Begin kb::Select kb::Print
2646 kb::PrintScr kb::Execute kb::Insert kb::Undo
2647 kb::Redo kb::Menu kb::Find kb::Cancel
2648 kb::Help kb::Break kb::BackTab
2649 See also: "KeyUp", "briefKeys", "key_down", "help", "popup",
2651 "tabOrder", "tabStop", "accelTable"
2652 KeyUp CODE, KEY, MOD
2654 Sent to the focused widget when the user releases a key. CODE
2655 contains an eventual character code, KEY is one of "kb::XXX"
2656 constants, MOD is a combination of the modificator keys pressed
2657 when the event occurred ( "km::XXX" ).
2658 See also: "KeyDown", "key_up"
2660 Leave
2662 Called when the input focus is removed from a widget
2663 See also: "Enter", "focused", "selected"
2665 Menu MENU VAR_NAME
2667 Called before the user-navigated menu ( pop-up or pull-down ) is
2668 about to show another level of submenu on the screen. MENU is
2669 Prima::AbstractMenu descendant, that children to a widget, and
2670 VAR_NAME is the name of the menu item that is about to be shown.
2671 Used for making changes in the menu structures dynamically.
2673 See also: "popupItems"
2675 MouseClick BUTTON, MOD, X, Y, DOUBLE_CLICK
2677 Called when a mouse click ( button is pressed, and then released
2678 within system-defined interval of time ) is happened in the widget
2679 area. BUTTON is one of "mb::XXX" constants, MOD is a combination of
2680 "km::XXX" constants, reflecting pressed modificator keys during the
2681 event, X and Y are the mouse pointer coordinates. DOUBLE_CLICK is a
2682 boolean flag, set to 1 if it was a double click, 0 if a single.
2683 "mb::XXX" constants are:
2685 mb::b1 or mb::Left
2687 mb::b2 or mb::Middle
2688 mb::b3 or mb::Right
2689 mb::b4
2690 mb::b5
2691 mb::b6
2692 mb::b7
2693 mb::b8
2694 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseMove",
2696 "MouseEnter", "MouseLeave"
2697 MouseDown BUTTON, MOD, X, Y
2699 Occurs when the user presses mouse button on a widget. BUTTON is
2700 one of "mb::XXX" constants, MOD is a combination of "km::XXX"
2701 constants, reflecting the pressed modificator keys during the
2702 event, X and Y are the mouse pointer coordinates.
2703 See also: "MouseUp", "MouseClick", "MouseWheel", "MouseMove",
2705 "MouseEnter", "MouseLeave"
2706 MouseEnter MOD, X, Y
2708 Occurs when the mouse pointer is entered the area occupied by a
2709 widget ( without mouse button pressed ). MOD is a combination of
2710 "km::XXX" constants, reflecting the pressed modificator keys during
2711 the event, X and Y are the mouse pointer coordinates.
2712 See also: "MouseDown", "MouseUp", "MouseClick", "MouseWheel",
2714 "MouseMove", "MouseLeave"
2715 MouseLeave
2717 Occurs when the mouse pointer is driven off the area occupied by a
2718 widget ( without mouse button pressed ).
2719 See also: "MouseDown", "MouseUp", "MouseClick", "MouseWheel",
2721 "MouseMove", "MouseEnter"
2722 MouseMove MOD, X, Y
2724 Occurs when the mouse pointer is transported over a widget. MOD is
2725 a combination of "km::XXX" constants, reflecting the pressed
2726 modificator keys during the event, X and Y are the mouse pointer
2727 coordinates.
2728 See also: "MouseDown", "MouseUp", "MouseClick", "MouseWheel",
2730 "MouseEnter", "MouseLeave"
2731 MouseUp BUTTON, MOD, X, Y
2733 Occurs when the user depresses mouse button on a widget. BUTTON is
2734 one of "mb::XXX" constants, MOD is a combination of "km::XXX"
2735 constants, reflecting the pressed modificator keys during the
2736 event, X and Y are the mouse pointer coordinates.
2737 See also: "MouseDown", "MouseClick", "MouseWheel", "MouseMove",
2739 "MouseEnter", "MouseLeave"
2740 MouseWheel MOD, X, Y, INCR
2742 Occurs when the user rotates mouse wheel on a widget. MOD is a
2743 combination of "km::XXX" constants, reflecting the pressed
2744 modificator keys during the event, INCR is the wheel movement,
2745 scaled by 120. +120 is a step upwards, or -120 downwards. For
2746 wheels which are discrete button clicks INCR is +/-120 but other
2747 devices may give other amounts. A widget should scroll by INCR/120
2748 many units, or partial unit, for whatever its unit of movement
2749 might be, such as lines of text, slider ticks, etc.
2750 A widget might like to vary its unit move according to the MOD
2752 keys. For example "Prima::SpinEdit" has a "step" and "pageStep"
2753 and moves by "pageStep" when "km::Ctrl" is held down (see
2754 Prima::Sliders).
2755 See also: "MouseDown", "MouseUp", "MouseClick", "MouseMove",
2757 "MouseEnter", "MouseLeave"
2758 Move OLD_X, OLD_Y, NEW_X, NEW_Y
2760 Triggered when widget changes its position relative to its parent,
2761 either by Prima::Widget methods or by the user. OLD_X and OLD_Y
2762 are the old coordinates of a widget, NEW_X and NEW_Y are the new
2763 ones.
2764 See also: "Size", "origin", "growMode", "centered", "clipOwner"
2766 Paint CANVAS
2768 Caused when the system calls for the refresh of a graphic context,
2769 associated with a widget. CANVAS is the widget itself, however its
2770 usage instead of widget is recommended ( see "Graphic content" ).
2771 See also: "repaint", "syncPaint", "get_invalid_rect", "scroll",
2773 "colorIndex", "font"
2774 Popup BY_MOUSE, X, Y
2776 Called by the system when the user presses a key or mouse
2777 combination defined for a context pop-up menu execution. By
2778 default executes the associated Prima::Popup object, if it is
2779 present. If the event flag is cleared during the execution of
2780 callbacks, the pop-up menu is not shown.
2781 See also: "popup"
2783 Setup
2785 This message is posted right after "Create" notification, and comes
2786 first from the event loop. Prima::Widget does not use it.
2787 Show
2789 Triggered by a successive visible(1) call
2790 See also: "Show", "visible", "showing", "exposed"
2792 Size OLD_WIDTH, OLD_HEIGHT, NEW_WIDTH, NEW_HEIGHT
2794 Triggered when widget changes its size, either by Prima::Widget
2795 methods or by the user. OLD_WIDTH and OLD_HEIGHT are the old
2796 extensions of a widget, NEW_WIDTH and NEW_HEIGHT are the new ones.
2797 See also: "Move", "origin", "size", "growMode", "sizeMax",
2799 "sizeMin", "rect", "clipOwner"
2800 SysHandle
2802 Same as in "Component", but introduces the following "Widget"
2803 properties can trigger it:
2804 "clipOwner", "syncPaint", "layered", "transparent"
2806 This event will be only needed when the system handle (that can be
2808 acquired by "get_handle" ) is needed.
2809 TranslateAccel CODE, KEY, MOD
2811 A distributed "KeyDown" event. Traverses all the object tree that
2812 the widget which received original "KeyDown" event belongs to. Once
2813 the event flag is cleared, the iteration stops.
2814 Used for tracking keyboard events by out-of-focus widgets.
2816 See also: "KeyDown"
2818 ZOrderChanged
2820 Triggered when a widget changes its stacking order, or Z-order
2821 among its siblings, either by Prima::Widget methods or by the user.
2822 See also: "bring_to_front", "insert_behind", "send_to_back"
2824
2826 Dmitry Karasik, <dmitry@karasik.eu.org>.
2827
2829 Prima, Prima::Object, Prima::Drawable.
2830perl v5.34.0 2021-07-22 pod::Prima::Widget(3)