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 called,
89 often implicitly. If a widget gets destroyed because its owner also
90 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 within
132 the callback. These are called implicitly. Second, when the custom
133 refresh of the widget's graphic content is needed, no code like
134 "notify(q(Paint))" is used - repaint() method is used instead. It must
135 be noted, that the actual execution of "Paint" callbacks might or might
136 not occur inside the repaint() call. This behavior is governed by the
137 "::syncPaint" property. repaint() marks the whole widget's area to be
138 refreshed, or invalidates the area. For the finer gradation of the area
139 that should be repainted, invalidate_rect() and validate_rect() pair of
140 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() and
161 get_invalid_rect() - inclusive-exclusive coordinates. The ideal case
162 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 actions
201 ) and is a convenience version of the direct rendering. Sometimes,
202 however, the changes needed to be made to a widget's graphic context
203 are so insignificant, so the direct rendering method is preferable,
204 because of the cleaner and terser code. As an example might serve a
205 simple progress bar, that draws a simple colored bar. The event-driven
206 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 times,
244 stacking the requests. This feature is useful because many properties
245 implicitly call repaint(), and if several of these properties activate
246 in a row, the unnecessary redrawing of the widget can be avoided. The
247 drawback is that the last unlock() call triggers repaint()
248 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 irrespective 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 does
422 the reverse, and insert_behind(), that sets a widget behind the another
423 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 parent-less, 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, correspondingly.
498 These return boolean values corresponding to the condition described.
499 So, if a widget is 'exposed', it is 'showing' and 'visible'; exposed()
500 returns always 0 if a widget is either not 'showing' or not 'visible'.
501 If a widget is 'showing', then it is always 'visible'. showing()
502 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 occurred.
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 navigation 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 the
676 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 modifier
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 applications, 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 "Clipboard::register_format", once, and then it is ready for
758 exchange.
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 synthesize 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 controls 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 conforming
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 different
895 at all. A matter of difference is how does Prima::Widget select the
896 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-arrow 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 not
986 the convenience shortcuts but the functions accounting the cursor hide
987 count. If hide_cursor() was called three times, then show_cursor() must
988 be called three times as well for the cursor to become visible.
989 Hint
991 "::hint" is a text string, that usually describes the widget's purpose
992 to the user in a brief manner. If the mouse pointer is hovered over the
993 widget longer than some timeout ( see Prima::Application::hintPause ),
994 then a label appears with the hint text, until the pointer is drawn
995 away. The hint behavior is governed by Prima::Application, but a
996 widget can do two additional things about hint: it can enable and
997 disable it by calling "::showHint" property, and it can inherit the
998 owner's "::hint" and "::showHint" properties using "::ownerHint" and
999 "::ownerShowHint" properties. If, for example, "::ownerHint" is set to
1000 1, then "::hint" value is automatically copied from the widget's owner,
1001 when it changes. If, however, the widget's "::hint" or "::showHint" are
1002 explicitly set, the owner link breaks automatically by setting
1003 "::ownerHint" or "::ownerShowHint" to 0.
1004 The widget can also operate the "::hintVisible" property, that shows or
1006 hides the hint label immediately, if the mouse pointer is inside the
1007 widget's boundaries.
1008 Menu objects
1010 The default functionality of Prima::Widget coexists with two kinds of
1011 the Prima::AbstractMenu descendants - Prima::AccelTable and
1012 Prima::Popup ( Prima::Window is also equipped with Prima::Menu
1013 reference). The "::items" property of these objects are accessible
1014 through "::accelItems" and "::popupItems", whereas the objects
1015 themselves - through "::accelTable" and "::popup", correspondingly. As
1016 mentioned in "User input", these objects hook the user keyboard input
1017 and call the programmer-defined callback subroutine if the key stroke
1018 equals to one of their table values. As for "::accelTable", its
1019 function ends here. "::popup" provides access to a context pop-up menu,
1020 which can be invoked by either right-clicking or pressing a system-
1021 dependent key combination. As a little customization, the
1022 "::popupColorIndex" and "::popupFont" properties are introduced. (
1023 "::popupColorIndex" is multiplexed to "::popupColor",
1024 "::popupHiliteColor", "::popupHiliteBackColor", etc etc properties
1025 exactly like the "::colorIndex" property ).
1026 The font and color of a menu object might not always be writable
1028 (Win32).
1029 The Prima::Window class provides equivalent methods for the menu bar,
1031 introducing "::menu", "::menuItems", "::menuColorIndex" ( with
1032 multiplexing ) and "::menuFont" properties.
1033 User-specified resources
1035 It is considered a good idea to incorporate the user preferences into
1036 the toolkit look-and-feel. Prima::Widget relies to the system-specific
1037 code that tries to map these preferences as close as possible to the
1038 toolkit paradigm.
1039 Unix version employs XRDB ( X resource database ), which is the natural
1041 way for the user to tell the preferences with fine granularity. Win32
1042 reads the setting that the user has to set interactively, using system
1043 tools. Nevertheless, the toolkit can not emulate all user settings that
1044 are available on the supported platforms; it rather takes a 'least
1045 common denominator', which is colors and fonts. fetch_resource() method
1046 is capable of returning any of such settings, provided it's format is
1047 font, color or a string. The method is rarely called directly.
1048 The appealing idea of making every widget property adjustable via the
1050 user-specified resources is not implemented in full. It can be
1051 accomplished up to a certain degree using fetch_resource() existing
1052 functionality, but it is believed that calling up the method for the
1053 every property for the every widget created is prohibitively expensive.
1054
1056 Properties
1057 accelItems [ ITEM_LIST ]
1058 Manages items of a Prima::AccelTable object associated with a
1059 widget. The ITEM_LIST format is same as
1060 "Prima::AbstractMenu::items" and is described in Prima::Menu.
1061 See also: "accelTable"
1063 accelTable OBJECT
1065 Manages a Prima::AccelTable object associated with a widget. The
1066 sole purpose of the accelTable object is to provide convenience
1067 mapping of key combinations to anonymous subroutines. Instead of
1068 writing an interface specifically for Prima::Widget, the existing
1069 interface of Prima::AbstractMenu was taken.
1070 The accelTable object can be destroyed safely; its cancellation can
1072 be done either via accelTable(undef) or destroy() call.
1073 Default value: undef
1075 See also: "accelItems"
1077 autoEnableChildren BOOLEAN
1079 If TRUE, all immediate children widgets maintain the same "enabled"
1080 state as the widget. This property is useful for the group-like
1081 widgets ( ComboBox, SpinEdit etc ), that employ their children for
1082 visual representation.
1083 Default value: 0
1085 backColor COLOR
1087 In widget paint state, reflects background color in the graphic
1088 context. In widget normal state, manages the basic background
1089 color. If changed, initiates "ColorChanged" notification and
1090 repaints the widget.
1091 See also: "color", "colorIndex", "ColorChanged"
1093 bottom INTEGER
1095 Maintains the lower boundary of a widget. If changed, does not
1096 affect the widget height; but does so, if called in set() together
1097 with "::top".
1098 See also: "left", "right", "top", "origin", "rect", "growMode",
1100 "Move"
1101 briefKeys BOOLEAN
1103 If 1, contracts the repetitive key press events into one
1104 notification, increasing REPEAT parameter of "KeyDown" callbacks.
1105 If 0, REPEAT parameter is always 1.
1106 Default value: 1
1108 See also: "KeyDown"
1110 buffered BOOLEAN
1112 If 1, a widget "Paint" callback draws not on the screen, but on the
1113 off-screen memory instead. The memory content is copied to the
1114 screen then. Used when complex drawing methods are used, or if
1115 output smoothness is desired.
1116 This behavior can not be always granted, however. If there is not
1118 enough memory, then widget draws in the usual manner.
1119 Default value: 0
1121 See also: "Paint"
1123 capture BOOLEAN, CLIP_OBJECT = undef
1125 Manipulates capturing of the mouse events. If 1, the mouse events
1126 are not passed to the widget the mouse pointer is over, but are
1127 redirected to the caller widget. The call for capture might not be
1128 always granted due the race conditions between programs.
1129 If CLIP_OBJECT widget is defined in set-mode call, the pointer
1131 movements are confined to CLIP_OBJECT inferior.
1132 See also: "MouseDown", "MouseUp", "MouseMove", "MouseWheel",
1134 "MouseClick".
1135 centered BOOLEAN
1137 A write-only property. Once set, widget is centered by X and Y axis
1138 relative to its owner.
1139 See also: "x_centered", "y_centered", "growMode", "origin", "Move".
1141 clipChildren BOOLEAN
1143 Affects the drawing mode when children widgets are present and
1144 obscuring the drawing area. If set, the children widgets are
1145 automatically added to the clipping area, and drawing over them
1146 will not happen. If unset, the painting can be done over the
1147 children widgets.
1148 Default: 1
1150 clipOwner BOOLEAN
1152 If 1, a widget is clipped by its owner boundaries. It is the
1153 default and expected behavior. If clipOwner is 0, a widget behaves
1154 differently: it does not clipped by the owner, it is not moved
1155 together with the parent, the origin offset is calculated not from
1156 the owner's coordinates but from the screen, and mouse events in a
1157 widget do not transgress to the top-level window decorations. In
1158 short, it itself becomes a top-level window, that, contrary to the
1159 one created from Prima::Window class, does not have any
1160 interference with system-dependent window stacking and positioning
1161 ( and any other ) policy, and is not ornamented by the window
1162 manager decorations.
1163 Default value: 1
1165 See "Parent-child relationship"
1167 See also: "Prima::Object" owner section, "parentHandle"
1169 color COLOR
1171 In widget paint state, reflects foreground color in the graphic
1172 context. In widget normal state, manages the basic foreground
1173 color. If changed, initiates "ColorChanged" notification and
1174 repaints the widget.
1175 See also: "backColor", "colorIndex", "ColorChanged"
1177 colorIndex INDEX, COLOR
1179 Manages the basic color properties indirectly, by accessing via
1180 "ci::XXX" constant. Is a complete alias for "::color",
1181 "::backColor", "::hiliteColor", "::hiliteBackColor",
1182 "::disabledColor", "::disabledBackColor", "::light3DColor", and
1183 "::dark3DColor" properties. The "ci::XXX" constants are:
1184 ci::NormalText or ci::Fore
1186 ci::Normal or ci::Back
1187 ci::HiliteText
1188 ci::Hilite
1189 ci::DisabledText
1190 ci::Disabled
1191 ci::Light3DColor
1192 ci::Dark3DColor
1193 The non-RGB "cl::" constants, specific to the Prima::Widget color
1195 usage are identical to their "ci::" counterparts:
1196 cl::NormalText or cl::Fore
1198 cl::Normal or cl::Back
1199 cl::HiliteText
1200 cl::Hilite
1201 cl::DisabledText
1202 cl::Disabled
1203 cl::Light3DColor
1204 cl::Dark3DColor
1205 See also: "color", "backColor", "ColorChanged"
1207 current BOOLEAN
1209 If 1, a widget (or one of its children) is marked as the one to be
1210 focused ( or selected) when the owner widget receives select()
1211 call. Within children widgets, only one or none at all can be
1212 marked as a current.
1213 See also: "currentWidget", "selectable", "selected",
1215 "selectedWidget", "focused"
1216 currentWidget OBJECT
1218 Points to a children widget, that is to be focused ( or selected)
1219 when the owner widget receives select() call.
1220 See also: "current", "selectable", "selected", "selectedWidget",
1222 "focused"
1223 cursorPos X_OFFSET Y_OFFSET
1225 Specifies the lower left corner of the cursor
1226 See also: "cursorSize", "cursorVisible"
1228 cursorSize WIDTH HEIGHT
1230 Specifies width and height of the cursor
1231 See also: "cursorPos", "cursorVisible"
1233 cursorVisible BOOLEAN
1235 Specifies cursor visibility flag. Default value is 0.
1236 See also: "cursorSize", "cursorPos"
1238 dark3DColor COLOR
1240 The color used to draw dark shades.
1241 See also: "light3DColor", "colorIndex", "ColorChanged"
1243 designScale X_SCALE Y_SCALE
1245 The width and height of a font, that was used when a widget (
1246 usually a dialog or a grouping widget ) was designed.
1247 See also: "scaleChildren", "width", "height", "size", "font"
1249 disabledBackColor COLOR
1251 The color used to substitute "::backColor" when a widget is in its
1252 disabled state.
1253 See also: "disabledColor", "colorIndex", "ColorChanged"
1255 disabledColor COLOR
1257 The color used to substitute "::color" when a widget is in its
1258 disabled state.
1259 See also: "disabledBackColor", "colorIndex", "ColorChanged"
1261 dndAware 0 | 1 | FORMAT
1263 To register a widget as a drop target, set its "dndAware" property
1264 to either 1, to mark that it will answer to all formats, or to a
1265 string, in which case drop events will only be delivered if the DND
1266 clipboard contains a format with that string.
1267 Default: 0
1269 See also: "Drag and Drop"
1271 enabled BOOLEAN
1273 Specifies if a widget can accept focus, keyboard and mouse events.
1274 Default value is 1, however, being 'enabled' does not automatically
1275 allow the widget become focused. Only the reverse is true - if
1276 enabled is 0, focusing can never happen.
1277 See also: "responsive", "visible", "Enable", "Disable"
1279 font %FONT
1281 Manages font context. Same syntax as in Prima::Drawable. If
1282 changed, initiates "FontChanged" notification and repaints the
1283 widget.
1284 See also: "designScale", "FontChanged", "ColorChanged"
1286 geometry INTEGER
1288 Selects one of the available geometry managers. The corresponding
1289 integer constants are:
1290 gt::GrowMode, gt::Default - the default grow-mode algorithm
1292 gt::Pack - Tk packer
1293 gt::Place - Tk placer
1294 See "growMode", Prima::Widget::pack, Prima::Widget::place.
1296 growMode MODE
1298 Specifies widget behavior, when its owner is resized or moved.
1299 MODE can be 0 ( default ) or a combination of the following
1300 constants:
1301 Basic constants
1303 gm::GrowLoX widget's left side is kept in constant
1304 distance from owner's right side
1305 gm::GrowLoY widget's bottom side is kept in constant
1306 distance from owner's top side
1307 gm::GrowHiX widget's right side is kept in constant
1308 distance from owner's right side
1309 gm::GrowHiY widget's top side is kept in constant
1310 distance from owner's top side
1311 gm::XCenter widget is kept in center on its owner's
1312 horizontal axis
1313 gm::YCenter widget is kept in center on its owner's
1314 vertical axis
1315 gm::DontCare widgets origin is maintained constant relative
1316 to the screen
1317 Derived or aliased constants
1319 gm::GrowAll gm::GrowLoX|gm::GrowLoY|gm::GrowHiX|gm::GrowHiY
1320 gm::Center gm::XCenter|gm::YCenter
1321 gm::Client gm::GrowHiX|gm::GrowHiY
1322 gm::Right gm::GrowLoX|gm::GrowHiY
1323 gm::Left gm::GrowHiY
1324 gm::Floor gm::GrowHiX
1325 See also: "Move", "origin"
1327 firstClick BOOLEAN
1329 If 0, a widget bypasses first mouse click on it, if the top-level
1330 window it belongs to was not activated, so selecting such a widget
1331 it takes two mouse clicks.
1332 Default value is 1
1334 See also: "MouseDown", "selectable", "selected", "focused",
1336 "selectingButtons"
1337 focused BOOLEAN
1339 Specifies whether a widget possesses the input focus or not.
1340 Disregards "::selectable" property on set-call.
1341 See also: "selectable", "selected", "selectedWidget", "KeyDown"
1343 geomWidth, geomHeight, geomSize
1345 Three properties that select geometry request size. Writing and
1346 reading to "::geomWidth" and "::geomHeight" is equivalent to
1347 "::geomSize". The properties are run-time only, and behave
1348 differently under different circumstances:
1349 • As the properties are run-time only, they can not be set in the
1351 profile, and their initial value is fetched from "::size"
1352 property. Thus, setting the explicit size is additionally sets
1353 the advised size in case the widget is to be used with the Tk
1354 geometry managers.
1355 • Setting the properties under the "gt::GrowMode" geometry
1357 manager also sets the corresponding "::width", "::height", or
1358 "::size". When the properties are read, though, the real size
1359 properties are not read; the values are kept separately.
1360 • Setting the properties under Tk geometry managers cause widgets
1362 size and position changed according to the geometry manager
1363 policy.
1364 height
1366 Maintains the height of a widget.
1367 See also: "width", "growMode", "Move", "Size", "get_virtual_size",
1369 "sizeMax", "sizeMin"
1370 helpContext STRING
1372 A string that binds a widget, a logical part it plays with the
1373 application and an interactive help topic. STRING format is defined
1374 as POD link ( see perlpod ) - "manpage/section", where 'manpage' is
1375 the file with POD content and 'section' is the topic inside the
1376 manpage.
1377 See also: "help"
1379 hiliteBackColor COLOR
1381 The color used to draw alternate background areas with high
1382 contrast.
1383 See also: "hiliteColor", "colorIndex", "ColorChanged"
1385 hiliteColor COLOR
1387 The color used to draw alternate foreground areas with high
1388 contrast.
1389 See also: "hiliteBackColor", "colorIndex", "ColorChanged"
1391 hint TEXT
1393 A text, shown under mouse pointer if it is hovered over a widget
1394 longer than "Prima::Application::hintPause" timeout. The text shows
1395 only if the "::showHint" is 1.
1396 See also: "hintVisible", "showHint", "ownerHint", "ownerShowHint"
1398 hintVisible BOOLEAN
1400 If called in get-form, returns whether the hint label is shown or
1401 not. If in set-form, immediately turns on or off the hint label,
1402 disregarding the timeouts. It does regard the mouse pointer
1403 location, however, and does not turn on the hint label if the
1404 pointer is away.
1405 See also: "hint", "showHint", "ownerHint", "ownerShowHint"
1407 layered BOOLEAN
1409 If set, the widget will try to use alpha transparency available on
1410 the system. See "Layering" in Prima::Image for more details.
1411 Default: false
1413 See also: "is_surface_layered"
1415 Note: In Windows, mouse events will not be delivered to the layered
1417 widget if the pixel under the mouse pointer is fully transparent.
1418 In X11, you need to run a composition manager, f.ex. compiz or
1420 xcompmgr.
1421 left INTEGER
1423 Maintains the left boundary of a widget. If changed, does not
1424 affect the widget width; but does so, if called in set() together
1425 with "::right".
1426 See also: "bottom", "right", "top", "origin", "rect", "growMode",
1428 "Move"
1429 light3DColor COLOR
1431 The color used to draw light shades.
1432 See also: "dark3DColor", "colorIndex", "ColorChanged"
1434 ownerBackColor BOOLEAN
1436 If 1, the background color is synchronized with the owner's.
1437 Automatically set to 0 if "::backColor" property is explicitly set.
1438 See also: "ownerColor", "backColor", "colorIndex"
1440 ownerColor BOOLEAN
1442 If 1, the foreground color is synchronized with the owner's.
1443 Automatically set to 0 if "::color" property is explicitly set.
1444 See also: "ownerBackColor", "color", "colorIndex"
1446 ownerFont BOOLEAN
1448 If 1, the font is synchronized with the owner's. Automatically set
1449 to 0 if "::font" property is explicitly set.
1450 See also: "font", "FontChanged"
1452 ownerHint BOOLEAN
1454 If 1, the hint is synchronized with the owner's. Automatically set
1455 to 0 if "::hint" property is explicitly set.
1456 See also: "hint", "showHint", "hintVisible", "ownerShowHint"
1458 ownerShowHint BOOLEAN
1460 If 1, the show hint flag is synchronized with the owner's.
1461 Automatically set to 0 if "::showHint" property is explicitly set.
1462 See also: "hint", "showHint", "hintVisible", "ownerHint"
1464 ownerPalette BOOLEAN
1466 If 1, the palette array is synchronized with the owner's.
1467 Automatically set to 0 if "::palette" property is explicitly set.
1468 See also: "palette"
1470 ownerSkin BOOLEAN
1472 If 1, the "skin" property is set to undef and thus will be
1473 synchronized with the owner's. Automatically set to 0 if the
1474 "skin" property is explicitly set.
1475 See also: "skin"
1477 origin X Y
1479 Maintains the left and bottom boundaries of a widget relative to
1480 its owner ( or to the screen if "::clipOwner" is set to 0 ).
1481 See also: "bottom", "right", "top", "left", "rect", "growMode",
1483 "Move"
1484 packInfo %OPTIONS
1486 See Prima::Widget::pack
1487 palette [ @PALETTE ]
1489 Specifies array of colors, that are desired to be present into the
1490 system palette, as close to the PALETTE as possible. This property
1491 works only if the graphic device allows palette operations. See
1492 "palette" in Prima::Drawable.
1493 See also: "ownerPalette"
1495 parentHandle SYSTEM_WINDOW
1497 If SYSTEM_WINDOW is a valid system-dependent window handle, then a
1498 widget becomes the child of the window specified, given the
1499 widget's "::clipOwner" is 0. The parent window can belong to
1500 another application.
1501 Default value is undef.
1503 See also: "clipOwner"
1505 placeInfo %OPTIONS
1507 See Prima::Widget::place
1508 pointer cr::XXX or ICON
1510 Specifies the pointer icon; discerns between "cr::XXX" constants
1511 and an icon. If an icon contains a hash variable "__pointerHotSpot"
1512 with an array of two integers, these integers will be treated as
1513 the pointer hot spot. In get-mode call, this variable is
1514 automatically assigned to an icon, if the result is an icon object.
1515 See also: "pointerHotSpot", "pointerIcon", "pointerType"
1517 pointerHotSpot X_OFFSET Y_OFFSET
1519 Specifies the hot spot coordinates of a pointer icon, associated
1520 with a widget.
1521 See also: "pointer", "pointerIcon", "pointerType"
1523 pointerIcon ICON
1525 Specifies the pointer icon, associated with a widget.
1526 See also: "pointerHotSpot", "pointer", "pointerType"
1528 pointerPos X_OFFSET Y_OFFSET
1530 Specifies the mouse pointer coordinates relative to widget's
1531 coordinates.
1532 See also: "get_mouse_state", "screen_to_client", "client_to_screen"
1534 pointerType TYPE
1536 Specifies the type of the pointer, associated with the widget.
1537 TYPE can accept one constant of "cr::XXX" set:
1538 cr::Default same pointer type as owner's
1540 cr::Arrow arrow pointer
1541 cr::Text text entry cursor-like pointer
1542 cr::Wait hourglass
1543 cr::Size general size action pointer
1544 cr::Move general move action pointer
1545 cr::SizeWest, cr::SizeW right-move action pointer
1546 cr::SizeEast, cr::SizeE left-move action pointer
1547 cr::SizeWE general horizontal-move action pointer
1548 cr::SizeNorth, cr::SizeN up-move action pointer
1549 cr::SizeSouth, cr::SizeS down-move action pointer
1550 cr::SizeNS general vertical-move action pointer
1551 cr::SizeNW up-right move action pointer
1552 cr::SizeSE down-left move action pointer
1553 cr::SizeNE up-left move action pointer
1554 cr::SizeSW down-right move action pointer
1555 cr::Invalid invalid action pointer
1556 cr::DragNone pointer for an invalid dragging target
1557 cr::DragCopy pointer to indicate that a dnd::Copy action can be accepted
1558 cr::DragMove pointer to indicate that a dnd::Move action can be accepted
1559 cr::DragLink pointer to indicate that a dnd::Link action can be accepted
1560 cr::User user-defined icon
1561 All constants except "cr::User" and "cr::Default" present a system-
1563 defined pointers, their icons and hot spot offsets. "cr::User" is a
1564 sign that an icon object was specified explicitly via
1565 "::pointerIcon" property. "cr::Default" is a way to tell that a
1566 widget inherits its owner pointer type, no matter is it a system-
1567 defined pointer or a custom icon.
1568 See also: "pointerHotSpot", "pointerIcon", "pointer"
1570 popup OBJECT
1572 Manages a Prima::Popup object associated with a widget. The
1573 purpose of the popup object is to show a context menu when the user
1574 right-clicks or selects the corresponding keyboard combination.
1575 Prima::Widget can host many children objects, Prima::Popup as well.
1576 But only the one that is set in "::popup" property will be
1577 activated automatically.
1578 The popup object can be destroyed safely; its cancellation can be
1580 done either via popup(undef) or destroy() call.
1581 See also: "Prima::Menu", "Popup", "Menu", "popupItems",
1583 "popupColorIndex", "popupFont"
1584 popupColorIndex INDEX, COLOR
1586 Maintains eight color properties of a pop-up context menu,
1587 associated with a widget. INDEX must be one of "ci::XXX" constants
1588 ( see "::colorIndex" property ).
1589 See also: "popupItems", "popupFont", "popup"
1591 popupColor COLOR
1593 Basic foreground in a popup context menu color.
1594 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1596 popupBackColor COLOR
1598 Basic background in a popup context menu color.
1599 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1601 popupDark3DColor COLOR
1603 Color for drawing dark shadings in a popup context menu.
1604 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1606 popupDisabledColor COLOR
1608 Foreground color for disabled items in a popup context menu.
1609 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1611 popupDisabledBackColor COLOR
1613 Background color for disabled items in a popup context menu.
1614 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1616 popupFont %FONT
1618 Maintains the font of a pop-up context menu, associated with a
1619 widget.
1620 See also: "popupItems", "popupColorIndex", "popup"
1622 popupHiliteColor COLOR
1624 Foreground color for selected items in a popup context menu.
1625 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1627 popupHiliteBackColor COLOR
1629 Background color for selected items in a popup context menu.
1630 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1632 popupItems [ ITEM_LIST ]
1634 Manages items of a Prima::Popup object associated with a widget.
1635 The ITEM_LIST format is same as "Prima::AbstractMenu::items" and is
1636 described in Prima::Menu.
1637 See also: "popup", "popupColorIndex", "popupFont"
1639 popupLight3DColor COLOR
1641 Color for drawing light shadings in a popup context menu.
1642 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1644 rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET Y_TOP_OFFSET
1646 Maintains the rectangular boundaries of a widget relative to its
1647 owner ( or to the screen if "::clipOwner" is set to 0 ).
1648 See also: "bottom", "right", "top", "left", "origin", "width",
1650 "height", "size" "growMode", "Move", "Size", "get_virtual_size",
1651 "sizeMax", "sizeMin"
1652 right INTEGER
1654 Maintains the right boundary of a widget. If changed, does not
1655 affect the widget width; but does so, if called in set() together
1656 with "::left".
1657 See also: "left", "bottom", "top", "origin", "rect", "growMode",
1659 "Move"
1660 scaleChildren BOOLEAN
1662 If a widget has "::scaleChildren" set to 1, then the newly-created
1663 children widgets inserted in it will be scaled corresponding to the
1664 owner's "::designScale", given that widget's "::designScale" is not
1665 "undef" and the owner's is not [0,0].
1666 Default is 1.
1668 See also: "designScale"
1670 selectable BOOLEAN
1672 If 1, a widget can be granted focus implicitly, or by means of the
1673 user actions. select() regards this property, and does not focus a
1674 widget that has "::selectable" set to 0.
1675 Default value is 0
1677 See also: "current", "currentWidget", "selected", "selectedWidget",
1679 "focused"
1680 selected BOOLEAN
1682 If called in get-mode, returns whether a widget or one of its
1683 (grand-) children is focused. If in set-mode, either simply turns
1684 the system with no-focus state ( if 0 ), or sends input focus to
1685 itself or one of the widgets tracked down by "::currentWidget"
1686 chain.
1687 See also: "current", "currentWidget", "selectable",
1689 "selectedWidget", "focused"
1690 selectedWidget OBJECT
1692 Points to a child widget, that has property "::selected" set to 1.
1693 See also: "current", "currentWidget", "selectable", "selected",
1695 "focused"
1696 selectingButtons FLAGS
1698 FLAGS is a combination of "mb::XXX" ( mouse button ) flags. If a
1699 widget receives a click with a mouse button, that has the
1700 corresponding bit set in "::selectingButtons", then select() is
1701 called.
1702 See also: "MouseDown", "firstClick", "selectable", "selected",
1704 "focused"
1705 shape REGION
1707 Maintains the non-rectangular shape of a widget. When setting,
1708 REGION is either a Prima::Image object, with 0 bits treated as
1709 transparent pixels, and 1 bits as opaque pixels, or a Prima::Region
1710 object. When getting, it is either undef or a Prima::Region
1711 object.
1712 Successive only if "sv::ShapeExtension" value is true.
1714 showHint BOOLEAN
1716 If 1, the toolkit is allowed to show the hint label over a widget.
1717 If 0, the display of the hint is forbidden. The "::hint" property
1718 must contain non-empty string as well, if the hint label must be
1719 shown.
1720 Default value is 1.
1722 See also: "hint", "ownerShowHint", "hintVisible", "ownerHint"
1724 size WIDTH HEIGHT
1726 Maintains the width and height of a widget.
1727 See also: "width", "height" "growMode", "Move", "Size",
1729 "get_virtual_size", "sizeMax", "sizeMin"
1730 sizeMax WIDTH HEIGHT
1732 Specifies the maximal size for a widget that it is allowed to
1733 accept.
1734 See also: "width", "height", "size" "growMode", "Move", "Size",
1736 "get_virtual_size", "sizeMin"
1737 sizeMin WIDTH HEIGHT
1739 Specifies the minimal size for a widget that it is allowed to
1740 accept.
1741 See also: "width", "height", "size" "growMode", "Move", "Size",
1743 "get_virtual_size", "sizeMax"
1744 skin SCALAR
1746 A generic scalar not used in "Prima::Widget" but designated to
1747 select the visual style of a widget, where the interpretation of
1748 the property value will be up to the widget class itself. Many of
1749 the toolkit widgets implement two skins, "classic" and "flat".
1750 Also, does not repaint the widget on change, but again, many of the
1751 toolkit widgets do that.
1752 If "ownerSkin" is 1, returns the skin of the owner. When set to
1754 undef, sets the "ownerSkin" property to 1, otherwise to 0. Note:
1755 this is therefore not an symetric property, as a
1756 "$self->skin($self->skin)" is not an idempotent call.
1757 syncPaint BOOLEAN
1759 If 0, the "Paint" request notifications are stacked until the event
1760 loop is called. If 1, every time the widget surface gets
1761 invalidated, the "Paint" notification is called.
1762 Default value is 0.
1764 See also: "invalidate_rect", "repaint", "validate_rect", "Paint"
1766 tabOrder INTEGER
1768 Maintains the order in which tab- and shift-tab- key navigation
1769 algorithms select the sibling widgets. INTEGER is unique among the
1770 sibling widgets. In set mode, if INTEGER value is already taken,
1771 the occupier is assigned another unique value, but without
1772 destruction of a queue - widgets with ::tabOrder greater than of
1773 the widget, receive their new values too. Special value -1 is
1774 accepted as 'the end of list' indicator; the negative value is
1775 never returned.
1776 See also: "tabStop", "next_tab", "selectable", "selected",
1778 "focused"
1779 tabStop BOOLEAN
1781 Specifies whether a widget is interested in tab- and shift-tab- key
1782 navigation or not.
1783 Default value is 1.
1785 See also: "tabOrder", "next_tab", "selectable", "selected",
1787 "focused"
1788 text TEXT
1790 A text string for generic purpose. Many Prima::Widget descendants
1791 use this property heavily - buttons, labels, input lines etc, but
1792 Prima::Widget itself does not.
1793 If "TEXT" is a reference to a string, it is translated as a markup
1795 string, and is compiled into a "Prima::Drawable::Markup" object
1796 internally.
1797 See Prima::Drawable::Markup, examples/markup.pl
1799 top INTEGER
1801 Maintains the upper boundary of a widget. If changed, does not
1802 affect the widget height; but does so, if called in set() together
1803 with "::bottom".
1804 See also: "left", "right", "bottom", "origin", "rect", "growMode",
1806 "Move"
1807 transparent BOOLEAN
1809 Specifies whether the background of a widget before it starts
1810 painting is of any importance. If 1, a widget can gain certain
1811 transparency look if it does not clear the background during
1812 "Paint" event.
1813 Default value is 0
1815 See also: "Paint", "buffered".
1817 visible BOOLEAN
1819 Specifies whether a widget is visible or not. See "Visibility".
1820 See also: "Show", "Hide", "showing", "exposed"
1822 widgetClass CLASS
1824 Maintains the integer value, designating the color class that is
1825 defined by the system and is associated with Prima::Widget eight
1826 basic color properties. CLASS can be one of "wc::XXX" constants:
1827 wc::Undef
1829 wc::Button
1830 wc::CheckBox
1831 wc::Combo
1832 wc::Dialog
1833 wc::Edit
1834 wc::InputLine
1835 wc::Label
1836 wc::ListBox
1837 wc::Menu
1838 wc::Popup
1839 wc::Radio
1840 wc::ScrollBar
1841 wc::Slider
1842 wc::Widget or wc::Custom
1843 wc::Window
1844 wc::Application
1845 These constants are not associated with the toolkit classes; any
1847 class can use any of these constants in "::widgetClass".
1848 See also: "map_color", "colorIndex"
1850 widgets @WIDGETS
1852 In get-mode, returns list of immediate children widgets (identical
1853 to "get_widgets"). In set-mode accepts set of widget profiles, as
1854 "insert" does, as a list or an array. This way it is possible to
1855 create widget hierarchy in a single call.
1856 width WIDTH
1858 Maintains the width of a widget.
1859 See also: "height" "growMode", "Move", "Size", "get_virtual_size",
1861 "sizeMax", "sizeMin"
1862 x_centered BOOLEAN
1864 A write-only property. Once set, widget is centered by the
1865 horizontal axis relative to its owner.
1866 See also: "centered", "y_centered", "growMode", "origin", "Move".
1868 y_centered BOOLEAN
1870 A write-only property. Once set, widget is centered by the vertical
1871 axis relative to its owner.
1872 See also: "x_centered", "centered", "growMode", "origin", "Move".
1874 Methods
1876 begin_drag [ DATA | %OPTIONS ]
1877 Wrapper over "dnd_start" that takes care of some DND session
1878 aspects other than the default system's. All input is contained in
1879 %OPTIONS hash, except for the case of a single-parameter call, in
1880 which case it is equivalent to "text => DATA" when "DATA" is a
1881 scalar, and to "image => DATA" when "DATA" is a reference.
1882 Returns -1 if a session cannot start, "dnd::None" if it was
1884 canceled by the user, or any other "dnd::" constant when the DND
1885 receiver has selected and successfully performed that action. For
1886 example, after a call to "dnd_start" returning "dnd::Move"
1887 (depending on a context), the caller may remove the data the user
1888 selected to move ("Prima::InputLine" and "Prima::Edit" do exactly
1889 this).
1890 In "wantarray" context also returns the widget that accepted the
1892 drop, if that was a Prima widget. Check this before handling
1893 "dnd::Move" actions that require data to be deleted on the source,
1894 to not occasionally delete the freshly transferred data. The method
1895 uses a precaution for this scenario and by default won't let the
1896 widget to be both a sender and a receiver though ( see "self_aware"
1897 below ).
1898 The following input is recognized:
1900 actions INTEGER = dnd::Copy
1902 Combination of "dnd::" constants, to tell a DND receiver
1903 whether copying, moving, and/or linking of the data is allowed.
1904 The method fails on the invalid "actions" input.
1905 format FORMAT, data INPUT
1907 If set, the clipboard will be assigned to contain a single
1908 entry of "INPUT" of the "FORMAT" format, where format is either
1909 one of the standard "Text" or "Image", or one of the format
1910 registered by "Clipboard::register_format".
1911 If not set, the caller needs to fill the clipboard in advance,
1913 f.ex. to offer data in more than one format.
1914 image INPUT
1916 Shortcut for " format =" 'Image', data => $INPUT, preview =>
1917 $INPUT >
1918 preview INPUT
1920 If set, mouse pointers sending feedback to the user will be
1921 equipped with either text or image (depending on whether
1922 "INPUT" is a scalar or an image reference).
1923 self_aware BOOLEAN = 1
1925 If unset the widget's "dndAware" will be temporarily set to 0,
1926 to exclude a possibility of an operation that may end in
1927 sending data to itself.
1928 text INPUT
1930 Shortcut for " format =" 'Text', data => $INPUT, preview =>
1931 $INPUT >
1932 track INTEGER = 5
1934 When set, waits with starting the DND process until the user
1935 moves the pointer from the starting point further than "track"
1936 pixels, which makes sense if the method to be called directly
1937 from a "MouseDown" event handler.
1938 If the drag did not happen because the user released the button
1940 or otherwise marked that this is not a drag, -1 is returned. In
1941 that case, the caller should continue to handle "MouseDown"
1942 event as if no drag session was ever started.
1943 bring_to_front
1945 Sends a widget on top of all other siblings widgets
1946 See also: "insert_behind", "send_to_back", "ZOrderChanged"
1948 ,"first", "next", "prev", "last"
1949 can_close
1951 Sends "Close" message, and returns its boolean exit state.
1952 See also: "Close", "close"
1954 client_to_screen @OFFSETS
1956 Maps array of X and Y integer offsets from widget to screen
1957 coordinates. Returns the mapped OFFSETS.
1958 See also: "screen_to_client", "clipOwner"
1960 close
1962 Calls can_close(), and if successful, destroys a widget. Returns
1963 the can_close() result.
1964 See also: "can_close", "Close"
1966 defocus
1968 Alias for focused(0) call
1969 See also: "focus", "focused", "Enter", "Leave"
1971 deselect
1973 Alias for selected(0) call
1974 See also: "select", "selected", "Enter", "Leave"
1976 dnd_start ACTIONS = dnd::Copy, USE_DEFAULT_POINTERS = 1
1978 Starts a drag and drop session with a combination of "ACTIONS"
1979 allowed. It is expected that a DND clipboard will be filled with
1980 data that are prepared to be sent to a DND receiver.
1981 Returns -1 if a session cannot start, "dnd::None" if it was
1983 canceled by the user, or any other "dnd::" constant when the DND
1984 receiver has selected and successfully performed that action. For
1985 example, after a call to "dnd_start" returning "dnd::Move"
1986 (depending on a context), the called may remove the data the user
1987 selected to move ("Prima::InputLine" and "Prima::Edit" do exactly
1988 this).
1989 Also returns the widget that accepted the drop, if that was a Prima
1991 widget within the same program.
1992 If USE_DEFAULT_POINTERS is set, then the system will use default
1994 drag pointers. Otherwise it is expected that a "DragResponse"
1995 action will change them according to current action, to give the
1996 user a visual feedback.
1997 See "begin_drag" for a wrapper over this method that handles also
1999 for other DND aspects.
2000 See also: "Drag and Drop", "DragQuery", "DragResponse".
2002 exposed
2004 Returns a boolean value, indicating whether a widget is at least
2005 partly visible on the screen. Never returns 1 if a widget has
2006 "::visible" set to 0.
2007 See also: "visible", "showing", "Show", "Hide"
2009 fetch_resource CLASS_NAME, NAME, CLASS_RESOURCE, RESOURCE, OWNER,
2011 RESOURCE_TYPE = fr::String
2012 Returns a system-defined scalar of resource, defined by the widget
2013 hierarchy, its class, name and owner. RESOURCE_TYPE can be one of
2014 type constants:
2015 fr::Color - color resource
2017 fr::Font - font resource
2018 fs::String - text string resource
2019 Such a number of the parameters is used because the method can be
2021 called before a widget is created. CLASS_NAME is widget class
2022 string, NAME is widget name. CLASS_RESOURCE is class of resource,
2023 and RESOURCE is the resource name.
2024 For example, resources 'color' and 'disabledColor' belong to the
2026 resource class 'Foreground'.
2027 first
2029 Returns the first ( from bottom ) sibling widget in Z-order.
2030 See also: "last", "next", "prev"
2032 focus
2034 Alias for focused(1) call
2035 See also: "defocus", "focused", "Enter", "Leave"
2037 hide
2039 Sets widget "::visible" to 0.
2040 See also: "hide", "visible", "Show", "Hide", "showing", "exposed"
2042 hide_cursor
2044 Hides the cursor. As many times hide_cursor() was called, as many
2045 time its counterpart show_cursor() must be called to reach the
2046 cursor's initial state.
2047 See also: "show_cursor", "cursorVisible"
2049 help
2051 Starts an interactive help viewer opened on "::helpContext" string
2052 value.
2053 The string value is combined from the widget's owner
2055 "::helpContext" strings if the latter is empty or begins with a
2056 slash. A special meaning is assigned to an empty string " " - the
2057 help() call fails when such value is found to be the section
2058 component. This feature can be useful when a window or a dialog
2059 presents a standalone functionality in a separate module, and the
2060 documentation is related more to the module than to an embedding
2061 program. In such case, the grouping widget holds "::helpContext" as
2062 a pod manpage name with a trailing slash, and its children widgets
2063 are assigned "::helpContext" to the topics without the manpage but
2064 the leading slash instead. If the grouping widget has an empty
2065 string " " as "::helpContext" then the help is forced to be
2066 unavailable for all the children widgets.
2067 See also: "helpContext"
2069 insert CLASS, %PROFILE [[ CLASS, %PROFILE], ... ]
2071 Creates one or more widgets with "owner" property set to the caller
2072 widget, and returns the list of references to the newly created
2073 widgets.
2074 Has two calling formats:
2076 Single widget
2078 $parent-> insert( 'Child::Class',
2079 name => 'child',
2080 ....
2081 );
2082 Multiple widgets
2084 $parent-> insert(
2085 [
2086 'Child::Class1',
2087 name => 'child1',
2088 ....
2089 ],
2090 [
2091 'Child::Class2',
2092 name => 'child2',
2093 ....
2094 ],
2095 );
2096 insert_behind OBJECT
2098 Sends a widget behind the OBJECT on Z-axis, given that the OBJECT
2099 is a sibling to the widget.
2100 See also: "bring_to_front", "send_to_back", "ZOrderChanged"
2102 ,"first", "next", "prev", "last"
2103 invalidate_rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET
2105 Y_TOP_OFFSET
2106 Marks the rectangular area of a widget as 'invalid', so re-painting
2107 of the area happens. See "Graphic content".
2108 See also: "validate_rect", "get_invalid_rect", "repaint", "Paint",
2110 "syncPaint", "update_view"
2111 is_surface_layered
2113 Returns true if both the widget and it's top-most parent are
2114 layered. If the widget itself is top-most, i.e. a window, a non-
2115 clipOwner widget, or a child to application, then is the same as
2116 "layered".
2117 See also: "layered"
2119 key_down CODE, KEY = kb::NoKey, MOD = 0, REPEAT = 1, POST = 0
2121 The method sends or posts ( POST flag ) simulated "KeyDown" event
2122 to the system. CODE, KEY, MOD and REPEAT are the parameters to be
2123 passed to the notification callbacks.
2124 See also: "key_up", "key_event", "KeyDown"
2126 key_event COMMAND, CODE, KEY = kb::NoKey, MOD = 0, REPEAT = 1, POST = 0
2128 The method sends or posts ( POST flag ) simulated keyboard event to
2129 the system. CODE, KEY, MOD and REPEAT are the parameters to be
2130 passed to an eventual "KeyDown" or "KeyUp" notifications. COMMAND
2131 is allowed to be either "cm::KeyDown" or "cm::KeyUp".
2132 See also: "key_down", "key_up", "KeyDown", "KeyUp"
2134 key_up CODE, KEY = kb::NoKey, MOD = 0, POST = 0
2136 The method sends or posts ( POST flag ) simulated "KeyUp" event to
2137 the system. CODE, KEY and MOD are the parameters to be passed to
2138 the notification callbacks.
2139 See also: "key_down", "key_event", "KeyUp"
2141 last
2143 Returns the last ( the topmost ) sibling widget in Z-order.
2144 See also: "first", "next", "prev"
2146 lock
2148 Turns off the ability of a widget to re-paint itself. As many
2149 times lock() was called, as may times its counterpart, unlock()
2150 must be called to enable re-painting again. Returns a boolean
2151 success flag.
2152 See also: "unlock", "repaint", "Paint", "get_locked"
2154 map_color COLOR
2156 Transforms "cl::XXX" and "ci::XXX" combinations into RGB color
2157 representation and returns the result. If COLOR is already in RGB
2158 format, no changes are made.
2159 See also: "colorIndex"
2161 mouse_click BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, NTH = 0, POST = 0
2163 The method sends or posts ( POST flag ) simulated "MouseClick"
2164 event to the system. BUTTON, MOD, X, Y, and NTH are the parameters
2165 to be passed to the notification callbacks.
2166 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseMove",
2168 "MouseEnter", "MouseLeave"
2169 mouse_down BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, POST = 0
2171 The method sends or posts ( POST flag ) simulated "MouseDown" event
2172 to the system. BUTTON, MOD, X, and Y are the parameters to be
2173 passed to the notification callbacks.
2174 See also: "MouseUp", "MouseWheel", "MouseClick", "MouseMove",
2176 "MouseEnter", "MouseLeave"
2177 mouse_enter MOD = 0, X = 0, Y = 0, POST = 0
2179 The method sends or posts ( POST flag ) simulated "MouseEnter"
2180 event to the system. MOD, X, and Y are the parameters to be passed
2181 to the notification callbacks.
2182 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseClick",
2184 "MouseMove", "MouseLeave"
2185 mouse_event COMMAND = cm::MouseDown, BUTTON = mb::Left, MOD = 0, X = 0,
2187 Y = 0, DBL_CLICK = 0, POST = 0
2188 The method sends or posts ( POST flag ) simulated mouse event to
2189 the system. BUTTON, MOD, X, Y and DBL_CLICK are the parameters to
2190 be passed to an eventual mouse notifications. COMMAND is allowed
2191 to be one of "cm::MouseDown", "cm::MouseUp", "cm::MouseWheel",
2192 "cm::MouseClick", "cm::MouseMove", "cm::MouseEnter",
2193 "cm::MouseLeave" constants.
2194 See also: "mouse_down", "mouse_up", "mouse_wheel", "mouse_click",
2196 "mouse_move", "mouse_enter", "mouse_leave", "MouseDown", "MouseUp",
2197 "MouseWheel", "MouseClick", "MouseMove", "MouseEnter", "MouseLeave"
2198 mouse_leave
2200 The method sends or posts ( POST flag ) simulated "MouseLeave"
2201 event to the system.
2202 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseClick",
2204 "MouseMove", "MouseEnter", "MouseLeave"
2205 mouse_move MOD = 0, X = 0, Y = 0, POST = 0
2207 The method sends or posts ( POST flag ) simulated "MouseMove" event
2208 to the system. MOD, X, and Y are the parameters to be passed to the
2209 notification callbacks.
2210 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseClick",
2212 "MouseEnter", "MouseLeave"
2213 mouse_up BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, POST = 0
2215 The method sends or posts ( POST flag ) simulated "MouseUp" event
2216 to the system. BUTTON, MOD, X, and Y are the parameters to be
2217 passed to the notification callbacks.
2218 See also: "MouseDown", "MouseWheel", "MouseClick", "MouseMove",
2220 "MouseEnter", "MouseLeave"
2221 mouse_wheel MOD = 0, X = 0, Y = 0, INCR = 0, POST = 0
2223 The method sends or posts ( POST flag ) simulated "MouseUp" event
2224 to the system. MOD, X, Y and INCR are the parameters to be passed
2225 to the notification callbacks.
2226 See also: "MouseDown", "MouseUp", "MouseClick", "MouseMove",
2228 "MouseEnter", "MouseLeave"
2229 next
2231 Returns the neighbor sibling widget, next ( above ) in Z-order. If
2232 none found, undef is returned.
2233 See also: "first", "last", "prev"
2235 next_tab FORWARD = 1
2237 Returns the next widget in the sorted by "::tabOrder" list of
2238 sibling widgets. FORWARD is a boolean lookup direction flag. If
2239 none found, the first ( or the last, depending on FORWARD flag )
2240 widget is returned. Only widgets with "::tabStop" set to 1
2241 participate.
2242 Also used by the internal keyboard navigation code.
2244 See also: "next_positional", "tabOrder", "tabStop", "selectable"
2246 next_positional DELTA_X DELTA_Y
2248 Returns a sibling, (grand-)child of a sibling or (grand-)child
2249 widget, that matched best the direction specified by DELTA_X and
2250 DELTA_Y. At one time, only one of these parameters can be zero;
2251 another parameter must be either 1 or -1.
2252 Also used by the internal keyboard navigation code.
2254 See also: "next_tab", "origin"
2256 pack, packForget, packSlaves
2258 See Prima::Widget::pack
2259 place, placeForget, placeSlaves
2261 See Prima::Widget::place
2262 prev
2264 Returns the neighbor sibling widget, previous ( below ) in Z-order.
2265 If none found, undef is returned.
2266 See also: "first", "last", "next"
2268 repaint
2270 Marks the whole widget area as 'invalid', so re-painting of the
2271 area happens. See "Graphic content".
2272 See also: "validate_rect", "get_invalid_rect", "invalidate_rect",
2274 "Paint", "update_view", "syncPaint"
2275 rect_bevel $CANVAS, @RECT, %OPTIONS
2277 Draws a rectangular area, similar to produced by "rect3d" over
2278 @RECT that is 4-integer coordinates of the area, but implicitly
2279 using widget's "light3DColor" and "dark3DColor" properties' values.
2280 The following options are recognized:
2281 fill COLOR
2283 If set, the area is filled with COLOR, otherwise is left
2284 intact.
2285 width INTEGER
2287 Width of the border in pixels
2288 concave BOOLEAN
2290 If 1, draw a concave area, bulged otherwise
2291 responsive
2293 Returns a boolean flag, indicating whether a widget and its owners
2294 have all "::enabled" 1 or not. Useful for fast check if a widget
2295 should respond to the user actions.
2296 See also: "enabled"
2298 screen_to_client @OFFSETS
2300 Maps array of X and Y integer offsets from screen to widget
2301 coordinates. Returns the mapped OFFSETS.
2302 See also: "client_to_screen"
2304 scroll DELTA_X DELTA_Y %OPTIONS
2306 Scrolls the graphic context area by DELTA_X and DELTA_Y pixels.
2307 OPTIONS is hash, that contains optional parameters to the scrolling
2308 procedure:
2309 clipRect [X1, Y1, X2, Y2]
2311 The clipping area is confined by X1, Y1, X2, Y2 rectangular
2312 area. If not specified, the clipping area covers the whole
2313 widget. Only the bits, covered by clipRect are affected. Bits
2314 scrolled from the outside of the rectangle to the inside are
2315 painted; bits scrolled from the inside of the rectangle to the
2316 outside are not painted.
2317 confineRect [X1, Y1, X2, Y2]
2319 The scrolling area is confined by X1, Y1, X2, Y2 rectangular
2320 area. If not specified, the scrolling area covers the whole
2321 widget.
2322 withChildren BOOLEAN
2324 If 1, the scrolling performs with the eventual children widgets
2325 change their positions to DELTA_X and DELTA_Y as well.
2326 Returns one of the following constants:
2328 scr::Error - failure
2330 scr::NoExpose - call resulted in no new exposed areas
2331 scr::Expose - call resulted in new exposed areas, expect a repaint
2332 Cannot be used inside paint state.
2334 See also: "Paint", "get_invalid_rect"
2336 select
2338 Alias for selected(1) call
2339 See also: "deselect", "selected", "Enter", "Leave"
2341 send_to_back
2343 Sends a widget at bottom of all other siblings widgets
2344 See also: "insert_behind", "bring_to_front", "ZOrderChanged"
2346 ,"first", "next", "prev", "last"
2347 show
2349 Sets widget "::visible" to 1.
2350 See also: "hide", "visible", "Show", "Hide", "showing", "exposed"
2352 show_cursor
2354 Shows the cursor. As many times hide_cursor() was called, as many
2355 time its counterpart show_cursor() must be called to reach the
2356 cursor's initial state.
2357 See also: "hide_cursor", "cursorVisible"
2359 showing
2361 Returns a boolean value, indicating whether the widget and its
2362 owners have all "::visible" 1 or not.
2363 unlock
2365 Turns on the ability of a widget to re-paint itself. As many times
2366 lock() was called, as may times its counterpart, unlock() must be
2367 called to enable re-painting again. When last unlock() is called,
2368 an implicit repaint() call is made. Returns a boolean success
2369 flag.
2370 See also: "lock", "repaint", "Paint", "get_locked"
2372 update_view
2374 If any parts of a widget were marked as 'invalid' by either
2375 invalidate_rect() or repaint() calls or the exposure caused by
2376 window movements ( or any other), then "Paint" notification is
2377 immediately called. If no parts are invalid, no action is
2378 performed. If a widget has "::syncPaint" set to 1, update_view()
2379 is always a no-operation call.
2380 See also: "invalidate_rect", "get_invalid_rect", "repaint",
2382 "Paint", "syncPaint", "update_view"
2383 validate_rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET Y_TOP_OFFSET
2385 Reverses the effect of invalidate_rect(), restoring the original,
2386 'valid' state of widget area covered by the rectangular area
2387 passed. If a widget with previously invalid areas was wholly
2388 validated by this method, no "Paint" notifications occur.
2389 See also: "invalidate_rect", "get_invalid_rect", "repaint",
2391 "Paint", "syncPaint", "update_view"
2392 Get-methods
2394 get_default_font
2395 Returns the default font for a Prima::Widget class.
2396 See also: "font"
2398 get_default_popup_font
2400 Returns the default font for a Prima::Popup class.
2401 See also: "font"
2403 get_invalid_rect
2405 Returns the result of successive calls invalidate_rect(),
2406 validate_rect() and repaint(), as a rectangular area ( four
2407 integers ) that cover all invalid regions in a widget. If none
2408 found, (0,0,0,0) is returned.
2409 See also: "validate_rect", "invalidate_rect", "repaint", "Paint",
2411 "syncPaint", "update_view"
2412 get_handle
2414 Returns a system handle for a widget
2415 See also: "get_parent_handle", "Window::get_client_handle"
2417 get_locked
2419 Returns 1 if a widget is in lock() - initiated repaint-blocked
2420 state.
2421 See also: "lock", "unlock"
2423 get_mouse_state
2425 Returns a combination of "mb::XXX" constants, reflecting the
2426 currently pressed mouse buttons.
2427 See also: "pointerPos", "get_shift_state"
2429 get_parent
2431 Returns the owner widget that clips the widget boundaries, or
2432 application object if a widget is top-level.
2433 See also: "clipOwner"
2435 get_parent_handle
2437 Returns a system handle for a parent of a widget, a window that
2438 belongs to another program. Returns 0 if the widget's owner and
2439 parent are in the same application and process space.
2440 See also: "get_handle", "clipOwner"
2442 get_pointer_size
2444 Returns two integers, width and height of a icon, that the system
2445 accepts as valid for a pointer. If the icon is supplied that is
2446 more or less than these values, it is truncated or padded with
2447 transparency bits, but is not stretched. Can be called with class
2448 syntax.
2449 get_shift_state
2451 Returns a combination of "km::XXX" constants, reflecting the
2452 currently pressed keyboard modifier buttons.
2453 See also: "get_shift_state"
2455 get_virtual_size
2457 Returns virtual width and height of a widget. See "Geometry",
2458 Implicit size regulations.
2459 See also: "width", "height", "size" "growMode", "Move", "Size",
2461 "sizeMax", "sizeMin"
2462 get_widgets
2464 Returns list of children widgets.
2465 Events
2467 Change
2468 Generic notification, used for Prima::Widget descendants;
2469 Prima::Widget itself neither calls not uses the event. Designed to
2470 be called when an arbitrary major state of a widget is changed.
2471 Click
2473 Generic notification, used for Prima::Widget descendants;
2474 Prima::Widget itself neither calls not uses the event. Designed to
2475 be called when an arbitrary major action for a widget is called.
2476 Close
2478 Triggered by can_close() and close() functions. If the event flag
2479 is cleared during execution, these functions fail.
2480 See also: "close", "can_close"
2482 ColorChanged INDEX
2484 Called when one of widget's color properties is changed, either by
2485 direct property change or by the system. INDEX is one of "ci::XXX"
2486 constants.
2487 See also: "colorIndex"
2489 Disable
2491 Triggered by a successive enabled(0) call
2492 See also: "Enable", "enabled", "responsive"
2494 DragBegin CLIPBOARD, ACTION, MOD, X, Y, COUNTERPART
2496 Triggered on a receiver widget when a mouse with a DND object
2497 enters it. "CLIPBOARD" contains the DND data, "ACTION" is a
2498 combination of "dnd::" constants, the actions the sender is ready
2499 to offer, "MOD" is a combination of modifier keys ("kb::"), and "X"
2500 and "Y" are coordinates where the mouse has entered the widget.
2501 This event, and the following "DragOver" and "DragEnd" events are
2502 happening only if the property "dndAware" is set either to 1, or if
2503 it matches a clipboard format that exists in "CLIPBOARD".
2504 "COUNTERPART" is the Prima DND sender widget, if the session is
2506 initiated within the same program.
2507 See also: "Drag and Drop", "DragOver", "DragEnd"
2509 DragEnd CLIPBOARD, ACTION, MOD, X, Y, COUNTERPART, ANSWER
2511 Triggered on a received widget when the user either drops or
2512 cancels the DND session. In case of a canceled drop, "CLIPBOARD" is
2513 set to "undef" and "ACTION" to "dnd::None". On a successful drop,
2514 input data are same as on "DragBegin", and output data are to be
2515 stored in hashref "ANSWER", if any. The following answers can be
2516 stored:
2517 allow BOOLEAN
2519 Is pre-set to 1. If changed to 0, a signal will be send to the
2520 sender that a drop is not accepted.
2521 action INTEGER
2523 A "dnd::" constant (not a combination) to be returned to the
2524 sender with the action the receiver has accepted, if any.
2525 "COUNTERPART" is the Prima DND sender widget, if the session is
2527 initiated within the same program.
2528 See also: "Drag and Drop", "DragBegin", "DragOver"
2530 DragOver CLIPBOARD, ACTION, MOD, X, Y, COUNTERPART, ANSWER
2532 Triggered on a received widget when a mouse with a DND moves within
2533 the widget. Input data are same as on "DragBegin", and output data
2534 are to be stored in hashref "ANSWER", if any. The following answers
2535 can be stored:
2536 allow BOOLEAN
2538 Is pre-set to 1. If changed to 0, a signal will be send to the
2539 sender that a drop action cannot happen with the input
2540 provided.
2541 action INTEGER
2543 A "dnd::" constant (not a combination) to be returned to the
2544 sender with the action the receiver is ready to accept, if any.
2545 pad X, Y, WIDTH, HEIGHT
2547 If set, instructs the sender not to repeat "DragOver" events
2548 that contains same input data, while the mouse pointer is
2549 within these geometrical limits.
2550 "COUNTERPART" is the Prima DND sender widget, if the session is
2552 initiated within the same program.
2553 DragQuery MOD, ANSWERS, COUNTERPART
2555 Triggered on a sender DND widget when there was detected a change
2556 in mouse or modifier buttons, or the user pressed "Escape" key to
2557 cancel the DND session. The combination of mouse and modifier
2558 buttons is stored in "MOD" integer, together with a special
2559 "km::Escape" constant for the "Escape" key.
2560 It is up to this event to decide whether to continue the drag
2562 session or not, and if it is decided not to continue,
2563 "$answer-"{allow}> must be set to 0.
2564 Additionally, "$answer-"{action}> can be set to select a single
2566 "dnd::" action that will be used to propose to the receiver a
2567 single concrete action based on the "MOD" value (f.ex. a
2568 "dnd::Move" if a control modifier was pressed).
2569 Note: This action will only forward the change to the receiver on
2571 X11, but it is advised to implement it anyway for portability.
2572 "COUNTERPART" is the Prima DND receiver widget, if within the same
2574 program.
2575 See also: "Drag and Drop", "DragResponse"
2577 DragResponse ALLOW, ACTION, COUNTERPART
2579 Triggered on a sender DND widget when there was detected a change
2580 in mouse or modifier buttons, or the mouse was moved from one DND
2581 target to another. The sender event is then presented with the new
2582 input, collected from interaction with the new target; there,
2583 "ALLOW" is set to a boolean value whether the sender is allowed to
2584 drop data, and "ACTION" is a "dnd::" constant with the action the
2585 receiver has agreed to accept, if any.
2586 If the drag and drop session was told not to update mouse pointers
2588 on such event, the handle should update the pointer in this
2589 callback. It is not needed though to save and restore mouse
2590 pointers before and after the DND session.
2591 "COUNTERPART" is the Prima DND receiver widget, if within the same
2593 program. See also: "Drag and Drop", "dnd_start", "begin_drag".
2594 Enable
2596 Triggered by a successive enabled(1) call
2597 See also: "Disable", "enabled", "responsive"
2599 Enter
2601 Called when a widget receives the input focus.
2602 See also: "Leave", "focused", "selected"
2604 FontChanged
2606 Called when a widget font is changed either by direct property
2607 change or by the system.
2608 See also: "font", "ColorChanged"
2610 Hide
2612 Triggered by a successive visible(0) call
2613 See also: "Show", "visible", "showing", "exposed"
2615 Hint SHOW_FLAG
2617 Called when the hint label is about to show or hide, depending on
2618 SHOW_FLAG. The hint show or hide action fails, if the event flag is
2619 cleared during execution.
2620 See also: "showHint", "ownerShowHint", "hintVisible", "ownerHint"
2622 KeyDown CODE, KEY, MOD, REPEAT
2624 Sent to the focused widget when the user presses a key. CODE
2625 contains an eventual character code, KEY is one of "kb::XXX"
2626 constants, MOD is a combination of the modifier keys pressed when
2627 the event occurred ( "km::XXX" ). REPEAT is how many times the key
2628 was pressed; usually it is 1. ( see "::briefKeys" ).
2629 The valid "km::" constants are:
2631 km::Shift
2633 km::Ctrl
2634 km::Alt
2635 km::KeyPad
2636 km::DeadKey
2637 km::Unicode
2638 The valid "kb::" constants are grouped in several sets. Some codes
2640 are aliased, like, "kb::PgDn" and "kb::PageDown".
2641 Modifier keys
2643 kb::ShiftL kb::ShiftR kb::CtrlL kb::CtrlR
2644 kb::AltL kb::AltR kb::MetaL kb::MetaR
2645 kb::SuperL kb::SuperR kb::HyperL kb::HyperR
2646 kb::CapsLock kb::NumLock kb::ScrollLock kb::ShiftLock
2647 Keys with character code defined
2649 kb::Backspace kb::Tab kb::Linefeed kb::Enter
2650 kb::Return kb::Escape kb::Esc kb::Space
2651 Function keys
2653 kb::F1 .. kb::F30
2654 kb::L1 .. kb::L10
2655 kb::R1 .. kb::R10
2656 Other
2658 kb::Clear kb::Pause kb::SysRq kb::SysReq
2659 kb::Delete kb::Home kb::Left kb::Up
2660 kb::Right kb::Down kb::PgUp kb::Prior
2661 kb::PageUp kb::PgDn kb::Next kb::PageDown
2662 kb::End kb::Begin kb::Select kb::Print
2663 kb::PrintScr kb::Execute kb::Insert kb::Undo
2664 kb::Redo kb::Menu kb::Find kb::Cancel
2665 kb::Help kb::Break kb::BackTab
2666 See also: "KeyUp", "briefKeys", "key_down", "help", "popup",
2668 "tabOrder", "tabStop", "accelTable"
2669 KeyUp CODE, KEY, MOD
2671 Sent to the focused widget when the user releases a key. CODE
2672 contains an eventual character code, KEY is one of "kb::XXX"
2673 constants, MOD is a combination of the modifier keys pressed when
2674 the event occurred ( "km::XXX" ).
2675 See also: "KeyDown", "key_up"
2677 Leave
2679 Called when the input focus is removed from a widget
2680 See also: "Enter", "focused", "selected"
2682 Menu MENU VAR_NAME
2684 Called before the user-navigated menu ( pop-up or pull-down ) is
2685 about to show another level of submenu on the screen. MENU is
2686 Prima::AbstractMenu descendant, that children to a widget, and
2687 VAR_NAME is the name of the menu item that is about to be shown.
2688 Used for making changes in the menu structures dynamically.
2690 See also: "popupItems"
2692 MouseClick BUTTON, MOD, X, Y, NTH
2694 Called when a mouse click ( button is pressed, and then released
2695 within system-defined interval of time ) is happened in the widget
2696 area. BUTTON is one of "mb::XXX" constants, MOD is a combination of
2697 "km::XXX" constants, reflecting pressed modifier keys during the
2698 event, X and Y are the mouse pointer coordinates. NTH is an
2699 integer, set to 0 if it was a single click, and to 2 and up if it
2700 was a double (triple etc etc) click.
2701 "mb::XXX" constants are:
2703 mb::b1 or mb::Left
2705 mb::b2 or mb::Middle
2706 mb::b3 or mb::Right
2707 mb::b4
2708 mb::b5
2709 mb::b6
2710 mb::b7
2711 mb::b8
2712 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseMove",
2714 "MouseEnter", "MouseLeave"
2715 MouseDown BUTTON, MOD, X, Y
2717 Occurs when the user presses mouse button on a widget. BUTTON is
2718 one of "mb::XXX" constants, MOD is a combination of "km::XXX"
2719 constants, reflecting the pressed modifier keys during the event, X
2720 and Y are the mouse pointer coordinates.
2721 See also: "MouseUp", "MouseClick", "MouseWheel", "MouseMove",
2723 "MouseEnter", "MouseLeave"
2724 MouseEnter MOD, X, Y
2726 Occurs when the mouse pointer is entered the area occupied by a
2727 widget ( without mouse button pressed ). MOD is a combination of
2728 "km::XXX" constants, reflecting the pressed modifier keys during
2729 the event, X and Y are the mouse pointer coordinates.
2730 See also: "MouseDown", "MouseUp", "MouseClick", "MouseWheel",
2732 "MouseMove", "MouseLeave"
2733 MouseLeave
2735 Occurs when the mouse pointer is driven off the area occupied by a
2736 widget ( without mouse button pressed ).
2737 See also: "MouseDown", "MouseUp", "MouseClick", "MouseWheel",
2739 "MouseMove", "MouseEnter"
2740 MouseMove MOD, X, Y
2742 Occurs when the mouse pointer is transported over a widget. MOD is
2743 a combination of "km::XXX" constants, reflecting the pressed
2744 modifier keys during the event, X and Y are the mouse pointer
2745 coordinates.
2746 See also: "MouseDown", "MouseUp", "MouseClick", "MouseWheel",
2748 "MouseEnter", "MouseLeave"
2749 MouseUp BUTTON, MOD, X, Y
2751 Occurs when the user depresses mouse button on a widget. BUTTON is
2752 one of "mb::XXX" constants, MOD is a combination of "km::XXX"
2753 constants, reflecting the pressed modifier keys during the event, X
2754 and Y are the mouse pointer coordinates.
2755 See also: "MouseDown", "MouseClick", "MouseWheel", "MouseMove",
2757 "MouseEnter", "MouseLeave"
2758 MouseWheel MOD, X, Y, INCR
2760 Occurs when the user rotates mouse wheel on a widget. MOD is a
2761 combination of "km::XXX" constants, reflecting the pressed modifier
2762 keys during the event, INCR is the wheel movement, scaled by 120.
2763 +120 is a step upwards, or -120 downwards. For wheels which are
2764 discrete button clicks INCR is +/-120 but other devices may give
2765 other amounts. A widget should scroll by INCR/120 many units, or
2766 partial unit, for whatever its unit of movement might be, such as
2767 lines of text, slider ticks, etc.
2768 A widget might like to vary its unit move according to the MOD
2770 keys. For example "Prima::SpinEdit" has a "step" and "pageStep"
2771 and moves by "pageStep" when "km::Ctrl" is held down (see
2772 Prima::Sliders).
2773 See also: "MouseDown", "MouseUp", "MouseClick", "MouseMove",
2775 "MouseEnter", "MouseLeave"
2776 Move OLD_X, OLD_Y, NEW_X, NEW_Y
2778 Triggered when widget changes its position relative to its parent,
2779 either by Prima::Widget methods or by the user. OLD_X and OLD_Y
2780 are the old coordinates of a widget, NEW_X and NEW_Y are the new
2781 ones.
2782 See also: "Size", "origin", "growMode", "centered", "clipOwner"
2784 Paint CANVAS
2786 Caused when the system calls for the refresh of a graphic context,
2787 associated with a widget. CANVAS is the widget itself, however its
2788 usage instead of widget is recommended ( see "Graphic content" ).
2789 See also: "repaint", "syncPaint", "get_invalid_rect", "scroll",
2791 "colorIndex", "font"
2792 Popup BY_MOUSE, X, Y
2794 Called by the system when the user presses a key or mouse
2795 combination defined for a context pop-up menu execution. By
2796 default executes the associated Prima::Popup object, if it is
2797 present. If the event flag is cleared during the execution of
2798 callbacks, the pop-up menu is not shown.
2799 See also: "popup"
2801 Setup
2803 This message is posted right after "Create" notification, and comes
2804 first from the event loop. Prima::Widget does not use it.
2805 Show
2807 Triggered by a successive visible(1) call
2808 See also: "Show", "visible", "showing", "exposed"
2810 Size OLD_WIDTH, OLD_HEIGHT, NEW_WIDTH, NEW_HEIGHT
2812 Triggered when widget changes its size, either by Prima::Widget
2813 methods or by the user. OLD_WIDTH and OLD_HEIGHT are the old
2814 extensions of a widget, NEW_WIDTH and NEW_HEIGHT are the new ones.
2815 See also: "Move", "origin", "size", "growMode", "sizeMax",
2817 "sizeMin", "rect", "clipOwner"
2818 SysHandle
2820 Same as in "Component", but introduces the following "Widget"
2821 properties can trigger it:
2822 "clipOwner", "syncPaint", "layered", "transparent"
2824 This event will be only needed when the system handle (that can be
2826 acquired by "get_handle" ) is needed.
2827 TranslateAccel CODE, KEY, MOD
2829 A distributed "KeyDown" event. Traverses all the object tree that
2830 the widget which received original "KeyDown" event belongs to. Once
2831 the event flag is cleared, the iteration stops.
2832 Used for tracking keyboard events by out-of-focus widgets.
2834 See also: "KeyDown"
2836 ZOrderChanged
2838 Triggered when a widget changes its stacking order, or Z-order
2839 among its siblings, either by Prima::Widget methods or by the user.
2840 See also: "bring_to_front", "insert_behind", "send_to_back"
2842
2844 Dmitry Karasik, <dmitry@karasik.eu.org>.
2845
2847 Prima, Prima::Object, Prima::Drawable.
2848perl v5.38.0 2023-07-21 pod::Prima::Widget(3)