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 origin X Y
1472 Maintains the left and bottom boundaries of a widget relative to
1473 its owner ( or to the screen if "::clipOwner" is set to 0 ).
1474 See also: "bottom", "right", "top", "left", "rect", "growMode",
1476 "Move"
1477 packInfo %OPTIONS
1479 See Prima::Widget::pack
1480 palette [ @PALETTE ]
1482 Specifies array of colors, that are desired to be present into the
1483 system palette, as close to the PALETTE as possible. This property
1484 works only if the graphic device allows palette operations. See
1485 "palette" in Prima::Drawable.
1486 See also: "ownerPalette"
1488 parentHandle SYSTEM_WINDOW
1490 If SYSTEM_WINDOW is a valid system-dependent window handle, then a
1491 widget becomes the child of the window specified, given the
1492 widget's "::clipOwner" is 0. The parent window can belong to
1493 another application.
1494 Default value is undef.
1496 See also: "clipOwner"
1498 placeInfo %OPTIONS
1500 See Prima::Widget::place
1501 pointer cr::XXX or ICON
1503 Specifies the pointer icon; discerns between "cr::XXX" constants
1504 and an icon. If an icon contains a hash variable "__pointerHotSpot"
1505 with an array of two integers, these integers will be treated as
1506 the pointer hot spot. In get-mode call, this variable is
1507 automatically assigned to an icon, if the result is an icon object.
1508 See also: "pointerHotSpot", "pointerIcon", "pointerType"
1510 pointerHotSpot X_OFFSET Y_OFFSET
1512 Specifies the hot spot coordinates of a pointer icon, associated
1513 with a widget.
1514 See also: "pointer", "pointerIcon", "pointerType"
1516 pointerIcon ICON
1518 Specifies the pointer icon, associated with a widget.
1519 See also: "pointerHotSpot", "pointer", "pointerType"
1521 pointerPos X_OFFSET Y_OFFSET
1523 Specifies the mouse pointer coordinates relative to widget's
1524 coordinates.
1525 See also: "get_mouse_state", "screen_to_client", "client_to_screen"
1527 pointerType TYPE
1529 Specifies the type of the pointer, associated with the widget.
1530 TYPE can accept one constant of "cr::XXX" set:
1531 cr::Default same pointer type as owner's
1533 cr::Arrow arrow pointer
1534 cr::Text text entry cursor-like pointer
1535 cr::Wait hourglass
1536 cr::Size general size action pointer
1537 cr::Move general move action pointer
1538 cr::SizeWest, cr::SizeW right-move action pointer
1539 cr::SizeEast, cr::SizeE left-move action pointer
1540 cr::SizeWE general horizontal-move action pointer
1541 cr::SizeNorth, cr::SizeN up-move action pointer
1542 cr::SizeSouth, cr::SizeS down-move action pointer
1543 cr::SizeNS general vertical-move action pointer
1544 cr::SizeNW up-right move action pointer
1545 cr::SizeSE down-left move action pointer
1546 cr::SizeNE up-left move action pointer
1547 cr::SizeSW down-right move action pointer
1548 cr::Invalid invalid action pointer
1549 cr::DragNone pointer for an invalid dragging target
1550 cr::DragCopy pointer to indicate that a dnd::Copy action can be accepted
1551 cr::DragMove pointer to indicate that a dnd::Move action can be accepted
1552 cr::DragLink pointer to indicate that a dnd::Link action can be accepted
1553 cr::User user-defined icon
1554 All constants except "cr::User" and "cr::Default" present a system-
1556 defined pointers, their icons and hot spot offsets. "cr::User" is a
1557 sign that an icon object was specified explicitly via
1558 "::pointerIcon" property. "cr::Default" is a way to tell that a
1559 widget inherits its owner pointer type, no matter is it a system-
1560 defined pointer or a custom icon.
1561 See also: "pointerHotSpot", "pointerIcon", "pointer"
1563 popup OBJECT
1565 Manages a Prima::Popup object associated with a widget. The
1566 purpose of the popup object is to show a context menu when the user
1567 right-clicks or selects the corresponding keyboard combination.
1568 Prima::Widget can host many children objects, Prima::Popup as well.
1569 But only the one that is set in "::popup" property will be
1570 activated automatically.
1571 The popup object can be destroyed safely; its cancellation can be
1573 done either via popup(undef) or destroy() call.
1574 See also: "Prima::Menu", "Popup", "Menu", "popupItems",
1576 "popupColorIndex", "popupFont"
1577 popupColorIndex INDEX, COLOR
1579 Maintains eight color properties of a pop-up context menu,
1580 associated with a widget. INDEX must be one of "ci::XXX" constants
1581 ( see "::colorIndex" property ).
1582 See also: "popupItems", "popupFont", "popup"
1584 popupColor COLOR
1586 Basic foreground in a popup context menu color.
1587 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1589 popupBackColor COLOR
1591 Basic background in a popup context menu color.
1592 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1594 popupDark3DColor COLOR
1596 Color for drawing dark shadings in a popup context menu.
1597 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1599 popupDisabledColor COLOR
1601 Foreground color for disabled items in a popup context menu.
1602 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1604 popupDisabledBackColor COLOR
1606 Background color for disabled items in a popup context menu.
1607 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1609 popupFont %FONT
1611 Maintains the font of a pop-up context menu, associated with a
1612 widget.
1613 See also: "popupItems", "popupColorIndex", "popup"
1615 popupHiliteColor COLOR
1617 Foreground color for selected items in a popup context menu.
1618 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1620 popupHiliteBackColor COLOR
1622 Background color for selected items in a popup context menu.
1623 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1625 popupItems [ ITEM_LIST ]
1627 Manages items of a Prima::Popup object associated with a widget.
1628 The ITEM_LIST format is same as "Prima::AbstractMenu::items" and is
1629 described in Prima::Menu.
1630 See also: "popup", "popupColorIndex", "popupFont"
1632 popupLight3DColor COLOR
1634 Color for drawing light shadings in a popup context menu.
1635 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1637 rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET Y_TOP_OFFSET
1639 Maintains the rectangular boundaries of a widget relative to its
1640 owner ( or to the screen if "::clipOwner" is set to 0 ).
1641 See also: "bottom", "right", "top", "left", "origin", "width",
1643 "height", "size" "growMode", "Move", "Size", "get_virtual_size",
1644 "sizeMax", "sizeMin"
1645 right INTEGER
1647 Maintains the right boundary of a widget. If changed, does not
1648 affect the widget width; but does so, if called in set() together
1649 with "::left".
1650 See also: "left", "bottom", "top", "origin", "rect", "growMode",
1652 "Move"
1653 scaleChildren BOOLEAN
1655 If a widget has "::scaleChildren" set to 1, then the newly-created
1656 children widgets inserted in it will be scaled corresponding to the
1657 owner's "::designScale", given that widget's "::designScale" is not
1658 "undef" and the owner's is not [0,0].
1659 Default is 1.
1661 See also: "designScale"
1663 selectable BOOLEAN
1665 If 1, a widget can be granted focus implicitly, or by means of the
1666 user actions. select() regards this property, and does not focus a
1667 widget that has "::selectable" set to 0.
1668 Default value is 0
1670 See also: "current", "currentWidget", "selected", "selectedWidget",
1672 "focused"
1673 selected BOOLEAN
1675 If called in get-mode, returns whether a widget or one of its
1676 (grand-) children is focused. If in set-mode, either simply turns
1677 the system with no-focus state ( if 0 ), or sends input focus to
1678 itself or one of the widgets tracked down by "::currentWidget"
1679 chain.
1680 See also: "current", "currentWidget", "selectable",
1682 "selectedWidget", "focused"
1683 selectedWidget OBJECT
1685 Points to a child widget, that has property "::selected" set to 1.
1686 See also: "current", "currentWidget", "selectable", "selected",
1688 "focused"
1689 selectingButtons FLAGS
1691 FLAGS is a combination of "mb::XXX" ( mouse button ) flags. If a
1692 widget receives a click with a mouse button, that has the
1693 corresponding bit set in "::selectingButtons", then select() is
1694 called.
1695 See also: "MouseDown", "firstClick", "selectable", "selected",
1697 "focused"
1698 shape REGION
1700 Maintains the non-rectangular shape of a widget. When setting,
1701 REGION is either a Prima::Image object, with 0 bits treated as
1702 transparent pixels, and 1 bits as opaque pixels, or a Prima::Region
1703 object. When getting, it is either undef or a Prima::Region
1704 object.
1705 Successive only if "sv::ShapeExtension" value is true.
1707 showHint BOOLEAN
1709 If 1, the toolkit is allowed to show the hint label over a widget.
1710 If 0, the display of the hint is forbidden. The "::hint" property
1711 must contain non-empty string as well, if the hint label must be
1712 shown.
1713 Default value is 1.
1715 See also: "hint", "ownerShowHint", "hintVisible", "ownerHint"
1717 size WIDTH HEIGHT
1719 Maintains the width and height of a widget.
1720 See also: "width", "height" "growMode", "Move", "Size",
1722 "get_virtual_size", "sizeMax", "sizeMin"
1723 sizeMax WIDTH HEIGHT
1725 Specifies the maximal size for a widget that it is allowed to
1726 accept.
1727 See also: "width", "height", "size" "growMode", "Move", "Size",
1729 "get_virtual_size", "sizeMin"
1730 sizeMin WIDTH HEIGHT
1732 Specifies the minimal size for a widget that it is allowed to
1733 accept.
1734 See also: "width", "height", "size" "growMode", "Move", "Size",
1736 "get_virtual_size", "sizeMax"
1737 syncPaint BOOLEAN
1739 If 0, the "Paint" request notifications are stacked until the event
1740 loop is called. If 1, every time the widget surface gets
1741 invalidated, the "Paint" notification is called.
1742 Default value is 0.
1744 See also: "invalidate_rect", "repaint", "validate_rect", "Paint"
1746 tabOrder INTEGER
1748 Maintains the order in which tab- and shift-tab- key navigation
1749 algorithms select the sibling widgets. INTEGER is unique among the
1750 sibling widgets. In set mode, if INTEGER value is already taken,
1751 the occupier is assigned another unique value, but without
1752 destruction of a queue - widgets with ::tabOrder greater than of
1753 the widget, receive their new values too. Special value -1 is
1754 accepted as 'the end of list' indicator; the negative value is
1755 never returned.
1756 See also: "tabStop", "next_tab", "selectable", "selected",
1758 "focused"
1759 tabStop BOOLEAN
1761 Specifies whether a widget is interested in tab- and shift-tab- key
1762 navigation or not.
1763 Default value is 1.
1765 See also: "tabOrder", "next_tab", "selectable", "selected",
1767 "focused"
1768 text TEXT
1770 A text string for generic purpose. Many Prima::Widget descendants
1771 use this property heavily - buttons, labels, input lines etc, but
1772 Prima::Widget itself does not.
1773 If "TEXT" is a reference to a string, it is translated as a markup
1775 string, and is compiled into a "Prima::Drawable::Markup" object
1776 internally.
1777 See Prima::Drawable::Markup, examples/markup.pl
1779 top INTEGER
1781 Maintains the upper boundary of a widget. If changed, does not
1782 affect the widget height; but does so, if called in set() together
1783 with "::bottom".
1784 See also: "left", "right", "bottom", "origin", "rect", "growMode",
1786 "Move"
1787 transparent BOOLEAN
1789 Specifies whether the background of a widget before it starts
1790 painting is of any importance. If 1, a widget can gain certain
1791 transparency look if it does not clear the background during
1792 "Paint" event.
1793 Default value is 0
1795 See also: "Paint", "buffered".
1797 visible BOOLEAN
1799 Specifies whether a widget is visible or not. See "Visibility".
1800 See also: "Show", "Hide", "showing", "exposed"
1802 widgetClass CLASS
1804 Maintains the integer value, designating the color class that is
1805 defined by the system and is associated with Prima::Widget eight
1806 basic color properties. CLASS can be one of "wc::XXX" constants:
1807 wc::Undef
1809 wc::Button
1810 wc::CheckBox
1811 wc::Combo
1812 wc::Dialog
1813 wc::Edit
1814 wc::InputLine
1815 wc::Label
1816 wc::ListBox
1817 wc::Menu
1818 wc::Popup
1819 wc::Radio
1820 wc::ScrollBar
1821 wc::Slider
1822 wc::Widget or wc::Custom
1823 wc::Window
1824 wc::Application
1825 These constants are not associated with the toolkit classes; any
1827 class can use any of these constants in "::widgetClass".
1828 See also: "map_color", "colorIndex"
1830 widgets @WIDGETS
1832 In get-mode, returns list of immediate children widgets (identical
1833 to "get_widgets"). In set-mode accepts set of widget profiles, as
1834 "insert" does, as a list or an array. This way it is possible to
1835 create widget hierarchy in a single call.
1836 width WIDTH
1838 Maintains the width of a widget.
1839 See also: "height" "growMode", "Move", "Size", "get_virtual_size",
1841 "sizeMax", "sizeMin"
1842 x_centered BOOLEAN
1844 A write-only property. Once set, widget is centered by the
1845 horizontal axis relative to its owner.
1846 See also: "centered", "y_centered", "growMode", "origin", "Move".
1848 y_centered BOOLEAN
1850 A write-only property. Once set, widget is centered by the vertical
1851 axis relative to its owner.
1852 See also: "x_centered", "centered", "growMode", "origin", "Move".
1854 Methods
1856 begin_drag [ DATA | %OPTIONS ]
1857 Wrapper over "dnd_start" that takes care of some DND session
1858 aspects other than the default system's. All input is contained in
1859 %OPTIONS hash, except for the case of a single-parameter call, in
1860 which case it is equivalent to "text => DATA" when "DATA" is a
1861 scalar, and to "image => DATA" when "DATA" is a reference.
1862 Returns -1 if a session cannot start, "dnd::None" if it was
1864 canceled by the user, or any other "dnd::" constant when the DND
1865 receiver has selected and successfully performed that action. For
1866 example, after a call to "dnd_start" returning "dnd::Move"
1867 (depending on a context), the caller may remove the data the user
1868 selected to move ("Prima::InputLine" and "Prima::Edit" do exactly
1869 this).
1870 In "wantarray" context also returns the widget that accepted the
1872 drop, if that was a Prima widget. Check this before handling
1873 "dnd::Move" actions that require data to be deleted on the source,
1874 to not occasionally delete the freshly transferred data. The method
1875 uses a precaution for this scenario and by default won't let the
1876 widget to be both a sender and a receiver though ( see "self_aware"
1877 below ).
1878 The following input is recognized:
1880 actions INTEGER = dnd::Copy
1882 Combination of "dnd::" constants, to tell a DND receiver
1883 whether copying, moving, and/or linking of the data is allowed.
1884 The method fails on the invalid "actions" input.
1885 format FORMAT, data INPUT
1887 If set, the clipboard will be assigned to contain a single
1888 entry of "INPUT" of the "FORMAT" format, where format is either
1889 one of the standard "Text" or "Image", or one of the format
1890 registered by "Clipboard::register_format".
1891 If not set, the caller needs to fill the clipboard in advance,
1893 f.ex. to offer data in more than one format.
1894 image INPUT
1896 Shortcut for " format =" 'Image', data => $INPUT, preview =>
1897 $INPUT >
1898 preview INPUT
1900 If set, mouse pointers sending feedback to the user will be
1901 equipped with either text or image (depending on whether
1902 "INPUT" is a scalar or an image reference).
1903 self_aware BOOLEAN = 1
1905 If unset the widget's "dndAware" will be temporarily set to 0,
1906 to exclude a possibility of an operation that may end in
1907 sending data to itself.
1908 text INPUT
1910 Shortcut for " format =" 'Text', data => $INPUT, preview =>
1911 $INPUT >
1912 track INTEGER = 5
1914 When set, waits with starting the DND process until the user
1915 moves the pointer from the starting point further than "track"
1916 pixels, which makes sense if the method to be called directly
1917 from a "MouseDown" event handler.
1918 If the drag did not happen because the user released the button
1920 or otherwise marked that this is not a drag, -1 is returned. In
1921 that case, the caller should continue to handle "MouseDown"
1922 event as if no drag session was ever started.
1923 bring_to_front
1925 Sends a widget on top of all other siblings widgets
1926 See also: "insert_behind", "send_to_back", "ZOrderChanged"
1928 ,"first", "next", "prev", "last"
1929 can_close
1931 Sends "Close" message, and returns its boolean exit state.
1932 See also: "Close", "close"
1934 client_to_screen @OFFSETS
1936 Maps array of X and Y integer offsets from widget to screen
1937 coordinates. Returns the mapped OFFSETS.
1938 See also: "screen_to_client", "clipOwner"
1940 close
1942 Calls can_close(), and if successful, destroys a widget. Returns
1943 the can_close() result.
1944 See also: "can_close", "Close"
1946 defocus
1948 Alias for focused(0) call
1949 See also: "focus", "focused", "Enter", "Leave"
1951 deselect
1953 Alias for selected(0) call
1954 See also: "select", "selected", "Enter", "Leave"
1956 dnd_start ACTIONS = dnd::Copy, USE_DEFAULT_POINTERS = 1
1958 Starts a drag and drop session with a combination of "ACTIONS"
1959 allowed. It is expected that a DND clipboard will be filled with
1960 data that are prepared to be sent to a DND receiver.
1961 Returns -1 if a session cannot start, "dnd::None" if it was
1963 canceled by the user, or any other "dnd::" constant when the DND
1964 receiver has selected and successfully performed that action. For
1965 example, after a call to "dnd_start" returning "dnd::Move"
1966 (depending on a context), the called may remove the data the user
1967 selected to move ("Prima::InputLine" and "Prima::Edit" do exactly
1968 this).
1969 Also returns the widget that accepted the drop, if that was a Prima
1971 widget within the same program.
1972 If USE_DEFAULT_POINTERS is set, then the system will use default
1974 drag pointers. Otherwise it is expected that a "DragResponse"
1975 action will change them according to current action, to give the
1976 user a visual feedback.
1977 See "begin_drag" for a wrapper over this method that handles also
1979 for other DND aspects.
1980 See also: "Drag and Drop", "DragQuery", "DragResponse".
1982 exposed
1984 Returns a boolean value, indicating whether a widget is at least
1985 partly visible on the screen. Never returns 1 if a widget has
1986 "::visible" set to 0.
1987 See also: "visible", "showing", "Show", "Hide"
1989 fetch_resource CLASS_NAME, NAME, CLASS_RESOURCE, RESOURCE, OWNER,
1991 RESOURCE_TYPE = fr::String
1992 Returns a system-defined scalar of resource, defined by the widget
1993 hierarchy, its class, name and owner. RESOURCE_TYPE can be one of
1994 type constants:
1995 fr::Color - color resource
1997 fr::Font - font resource
1998 fs::String - text string resource
1999 Such a number of the parameters is used because the method can be
2001 called before a widget is created. CLASS_NAME is widget class
2002 string, NAME is widget name. CLASS_RESOURCE is class of resource,
2003 and RESOURCE is the resource name.
2004 For example, resources 'color' and 'disabledColor' belong to the
2006 resource class 'Foreground'.
2007 first
2009 Returns the first ( from bottom ) sibling widget in Z-order.
2010 See also: "last", "next", "prev"
2012 focus
2014 Alias for focused(1) call
2015 See also: "defocus", "focused", "Enter", "Leave"
2017 hide
2019 Sets widget "::visible" to 0.
2020 See also: "hide", "visible", "Show", "Hide", "showing", "exposed"
2022 hide_cursor
2024 Hides the cursor. As many times hide_cursor() was called, as many
2025 time its counterpart show_cursor() must be called to reach the
2026 cursor's initial state.
2027 See also: "show_cursor", "cursorVisible"
2029 help
2031 Starts an interactive help viewer opened on "::helpContext" string
2032 value.
2033 The string value is combined from the widget's owner
2035 "::helpContext" strings if the latter is empty or begins with a
2036 slash. A special meaning is assigned to an empty string " " - the
2037 help() call fails when such value is found to be the section
2038 component. This feature can be useful when a window or a dialog
2039 presents a standalone functionality in a separate module, and the
2040 documentation is related more to the module than to an embedding
2041 program. In such case, the grouping widget holds "::helpContext" as
2042 a pod manpage name with a trailing slash, and its children widgets
2043 are assigned "::helpContext" to the topics without the manpage but
2044 the leading slash instead. If the grouping widget has an empty
2045 string " " as "::helpContext" then the help is forced to be
2046 unavailable for all the children widgets.
2047 See also: "helpContext"
2049 insert CLASS, %PROFILE [[ CLASS, %PROFILE], ... ]
2051 Creates one or more widgets with "owner" property set to the caller
2052 widget, and returns the list of references to the newly created
2053 widgets.
2054 Has two calling formats:
2056 Single widget
2058 $parent-> insert( 'Child::Class',
2059 name => 'child',
2060 ....
2061 );
2062 Multiple widgets
2064 $parent-> insert(
2065 [
2066 'Child::Class1',
2067 name => 'child1',
2068 ....
2069 ],
2070 [
2071 'Child::Class2',
2072 name => 'child2',
2073 ....
2074 ],
2075 );
2076 insert_behind OBJECT
2078 Sends a widget behind the OBJECT on Z-axis, given that the OBJECT
2079 is a sibling to the widget.
2080 See also: "bring_to_front", "send_to_back", "ZOrderChanged"
2082 ,"first", "next", "prev", "last"
2083 invalidate_rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET
2085 Y_TOP_OFFSET
2086 Marks the rectangular area of a widget as 'invalid', so re-painting
2087 of the area happens. See "Graphic content".
2088 See also: "validate_rect", "get_invalid_rect", "repaint", "Paint",
2090 "syncPaint", "update_view"
2091 is_surface_layered
2093 Returns true if both the widget and it's top-most parent are
2094 layered. If the widget itself is top-most, i.e. a window, a non-
2095 clipOwner widget, or a child to application, then is the same as
2096 "layered".
2097 See also: "layered"
2099 key_down CODE, KEY = kb::NoKey, MOD = 0, REPEAT = 1, POST = 0
2101 The method sends or posts ( POST flag ) simulated "KeyDown" event
2102 to the system. CODE, KEY, MOD and REPEAT are the parameters to be
2103 passed to the notification callbacks.
2104 See also: "key_up", "key_event", "KeyDown"
2106 key_event COMMAND, CODE, KEY = kb::NoKey, MOD = 0, REPEAT = 1, POST = 0
2108 The method sends or posts ( POST flag ) simulated keyboard event to
2109 the system. CODE, KEY, MOD and REPEAT are the parameters to be
2110 passed to an eventual "KeyDown" or "KeyUp" notifications. COMMAND
2111 is allowed to be either "cm::KeyDown" or "cm::KeyUp".
2112 See also: "key_down", "key_up", "KeyDown", "KeyUp"
2114 key_up CODE, KEY = kb::NoKey, MOD = 0, POST = 0
2116 The method sends or posts ( POST flag ) simulated "KeyUp" event to
2117 the system. CODE, KEY and MOD are the parameters to be passed to
2118 the notification callbacks.
2119 See also: "key_down", "key_event", "KeyUp"
2121 last
2123 Returns the last ( the topmost ) sibling widget in Z-order.
2124 See also: "first", "next", "prev"
2126 lock
2128 Turns off the ability of a widget to re-paint itself. As many
2129 times lock() was called, as may times its counterpart, unlock()
2130 must be called to enable re-painting again. Returns a boolean
2131 success flag.
2132 See also: "unlock", "repaint", "Paint", "get_locked"
2134 map_color COLOR
2136 Transforms "cl::XXX" and "ci::XXX" combinations into RGB color
2137 representation and returns the result. If COLOR is already in RGB
2138 format, no changes are made.
2139 See also: "colorIndex"
2141 mouse_click BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, NTH = 0, POST = 0
2143 The method sends or posts ( POST flag ) simulated "MouseClick"
2144 event to the system. BUTTON, MOD, X, Y, and NTH are the parameters
2145 to be passed to the notification callbacks.
2146 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseMove",
2148 "MouseEnter", "MouseLeave"
2149 mouse_down BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, POST = 0
2151 The method sends or posts ( POST flag ) simulated "MouseDown" event
2152 to the system. BUTTON, MOD, X, and Y are the parameters to be
2153 passed to the notification callbacks.
2154 See also: "MouseUp", "MouseWheel", "MouseClick", "MouseMove",
2156 "MouseEnter", "MouseLeave"
2157 mouse_enter MOD = 0, X = 0, Y = 0, POST = 0
2159 The method sends or posts ( POST flag ) simulated "MouseEnter"
2160 event to the system. MOD, X, and Y are the parameters to be passed
2161 to the notification callbacks.
2162 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseClick",
2164 "MouseMove", "MouseLeave"
2165 mouse_event COMMAND = cm::MouseDown, BUTTON = mb::Left, MOD = 0, X = 0,
2167 Y = 0, DBL_CLICK = 0, POST = 0
2168 The method sends or posts ( POST flag ) simulated mouse event to
2169 the system. BUTTON, MOD, X, Y and DBL_CLICK are the parameters to
2170 be passed to an eventual mouse notifications. COMMAND is allowed
2171 to be one of "cm::MouseDown", "cm::MouseUp", "cm::MouseWheel",
2172 "cm::MouseClick", "cm::MouseMove", "cm::MouseEnter",
2173 "cm::MouseLeave" constants.
2174 See also: "mouse_down", "mouse_up", "mouse_wheel", "mouse_click",
2176 "mouse_move", "mouse_enter", "mouse_leave", "MouseDown", "MouseUp",
2177 "MouseWheel", "MouseClick", "MouseMove", "MouseEnter", "MouseLeave"
2178 mouse_leave
2180 The method sends or posts ( POST flag ) simulated "MouseLeave"
2181 event to the system.
2182 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseClick",
2184 "MouseMove", "MouseEnter", "MouseLeave"
2185 mouse_move MOD = 0, X = 0, Y = 0, POST = 0
2187 The method sends or posts ( POST flag ) simulated "MouseMove" event
2188 to the system. MOD, X, and Y are the parameters to be passed to the
2189 notification callbacks.
2190 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseClick",
2192 "MouseEnter", "MouseLeave"
2193 mouse_up BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, POST = 0
2195 The method sends or posts ( POST flag ) simulated "MouseUp" event
2196 to the system. BUTTON, MOD, X, and Y are the parameters to be
2197 passed to the notification callbacks.
2198 See also: "MouseDown", "MouseWheel", "MouseClick", "MouseMove",
2200 "MouseEnter", "MouseLeave"
2201 mouse_wheel MOD = 0, X = 0, Y = 0, INCR = 0, POST = 0
2203 The method sends or posts ( POST flag ) simulated "MouseUp" event
2204 to the system. MOD, X, Y and INCR are the parameters to be passed
2205 to the notification callbacks.
2206 See also: "MouseDown", "MouseUp", "MouseClick", "MouseMove",
2208 "MouseEnter", "MouseLeave"
2209 next
2211 Returns the neighbor sibling widget, next ( above ) in Z-order. If
2212 none found, undef is returned.
2213 See also: "first", "last", "prev"
2215 next_tab FORWARD = 1
2217 Returns the next widget in the sorted by "::tabOrder" list of
2218 sibling widgets. FORWARD is a boolean lookup direction flag. If
2219 none found, the first ( or the last, depending on FORWARD flag )
2220 widget is returned. Only widgets with "::tabStop" set to 1
2221 participate.
2222 Also used by the internal keyboard navigation code.
2224 See also: "next_positional", "tabOrder", "tabStop", "selectable"
2226 next_positional DELTA_X DELTA_Y
2228 Returns a sibling, (grand-)child of a sibling or (grand-)child
2229 widget, that matched best the direction specified by DELTA_X and
2230 DELTA_Y. At one time, only one of these parameters can be zero;
2231 another parameter must be either 1 or -1.
2232 Also used by the internal keyboard navigation code.
2234 See also: "next_tab", "origin"
2236 pack, packForget, packSlaves
2238 See Prima::Widget::pack
2239 place, placeForget, placeSlaves
2241 See Prima::Widget::place
2242 prev
2244 Returns the neighbor sibling widget, previous ( below ) in Z-order.
2245 If none found, undef is returned.
2246 See also: "first", "last", "next"
2248 repaint
2250 Marks the whole widget area as 'invalid', so re-painting of the
2251 area happens. See "Graphic content".
2252 See also: "validate_rect", "get_invalid_rect", "invalidate_rect",
2254 "Paint", "update_view", "syncPaint"
2255 rect_bevel $CANVAS, @RECT, %OPTIONS
2257 Draws a rectangular area, similar to produced by "rect3d" over
2258 @RECT that is 4-integer coordinates of the area, but implicitly
2259 using widget's "light3DColor" and "dark3DColor" properties' values.
2260 The following options are recognized:
2261 fill COLOR
2263 If set, the area is filled with COLOR, otherwise is left
2264 intact.
2265 width INTEGER
2267 Width of the border in pixels
2268 concave BOOLEAN
2270 If 1, draw a concave area, bulged otherwise
2271 responsive
2273 Returns a boolean flag, indicating whether a widget and its owners
2274 have all "::enabled" 1 or not. Useful for fast check if a widget
2275 should respond to the user actions.
2276 See also: "enabled"
2278 screen_to_client @OFFSETS
2280 Maps array of X and Y integer offsets from screen to widget
2281 coordinates. Returns the mapped OFFSETS.
2282 See also: "client_to_screen"
2284 scroll DELTA_X DELTA_Y %OPTIONS
2286 Scrolls the graphic context area by DELTA_X and DELTA_Y pixels.
2287 OPTIONS is hash, that contains optional parameters to the scrolling
2288 procedure:
2289 clipRect [X1, Y1, X2, Y2]
2291 The clipping area is confined by X1, Y1, X2, Y2 rectangular
2292 area. If not specified, the clipping area covers the whole
2293 widget. Only the bits, covered by clipRect are affected. Bits
2294 scrolled from the outside of the rectangle to the inside are
2295 painted; bits scrolled from the inside of the rectangle to the
2296 outside are not painted.
2297 confineRect [X1, Y1, X2, Y2]
2299 The scrolling area is confined by X1, Y1, X2, Y2 rectangular
2300 area. If not specified, the scrolling area covers the whole
2301 widget.
2302 withChildren BOOLEAN
2304 If 1, the scrolling performs with the eventual children widgets
2305 change their positions to DELTA_X and DELTA_Y as well.
2306 Returns one of the following constants:
2308 scr::Error - failure
2310 scr::NoExpose - call resulted in no new exposed areas
2311 scr::Expose - call resulted in new exposed areas, expect a repaint
2312 Cannot be used inside paint state.
2314 See also: "Paint", "get_invalid_rect"
2316 select
2318 Alias for selected(1) call
2319 See also: "deselect", "selected", "Enter", "Leave"
2321 send_to_back
2323 Sends a widget at bottom of all other siblings widgets
2324 See also: "insert_behind", "bring_to_front", "ZOrderChanged"
2326 ,"first", "next", "prev", "last"
2327 show
2329 Sets widget "::visible" to 1.
2330 See also: "hide", "visible", "Show", "Hide", "showing", "exposed"
2332 show_cursor
2334 Shows the cursor. As many times hide_cursor() was called, as many
2335 time its counterpart show_cursor() must be called to reach the
2336 cursor's initial state.
2337 See also: "hide_cursor", "cursorVisible"
2339 showing
2341 Returns a boolean value, indicating whether the widget and its
2342 owners have all "::visible" 1 or not.
2343 unlock
2345 Turns on the ability of a widget to re-paint itself. As many times
2346 lock() was called, as may times its counterpart, unlock() must be
2347 called to enable re-painting again. When last unlock() is called,
2348 an implicit repaint() call is made. Returns a boolean success
2349 flag.
2350 See also: "lock", "repaint", "Paint", "get_locked"
2352 update_view
2354 If any parts of a widget were marked as 'invalid' by either
2355 invalidate_rect() or repaint() calls or the exposure caused by
2356 window movements ( or any other), then "Paint" notification is
2357 immediately called. If no parts are invalid, no action is
2358 performed. If a widget has "::syncPaint" set to 1, update_view()
2359 is always a no-operation call.
2360 See also: "invalidate_rect", "get_invalid_rect", "repaint",
2362 "Paint", "syncPaint", "update_view"
2363 validate_rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET Y_TOP_OFFSET
2365 Reverses the effect of invalidate_rect(), restoring the original,
2366 'valid' state of widget area covered by the rectangular area
2367 passed. If a widget with previously invalid areas was wholly
2368 validated by this method, no "Paint" notifications occur.
2369 See also: "invalidate_rect", "get_invalid_rect", "repaint",
2371 "Paint", "syncPaint", "update_view"
2372 Get-methods
2374 get_default_font
2375 Returns the default font for a Prima::Widget class.
2376 See also: "font"
2378 get_default_popup_font
2380 Returns the default font for a Prima::Popup class.
2381 See also: "font"
2383 get_invalid_rect
2385 Returns the result of successive calls invalidate_rect(),
2386 validate_rect() and repaint(), as a rectangular area ( four
2387 integers ) that cover all invalid regions in a widget. If none
2388 found, (0,0,0,0) is returned.
2389 See also: "validate_rect", "invalidate_rect", "repaint", "Paint",
2391 "syncPaint", "update_view"
2392 get_handle
2394 Returns a system handle for a widget
2395 See also: "get_parent_handle", "Window::get_client_handle"
2397 get_locked
2399 Returns 1 if a widget is in lock() - initiated repaint-blocked
2400 state.
2401 See also: "lock", "unlock"
2403 get_mouse_state
2405 Returns a combination of "mb::XXX" constants, reflecting the
2406 currently pressed mouse buttons.
2407 See also: "pointerPos", "get_shift_state"
2409 get_parent
2411 Returns the owner widget that clips the widget boundaries, or
2412 application object if a widget is top-level.
2413 See also: "clipOwner"
2415 get_parent_handle
2417 Returns a system handle for a parent of a widget, a window that
2418 belongs to another program. Returns 0 if the widget's owner and
2419 parent are in the same application and process space.
2420 See also: "get_handle", "clipOwner"
2422 get_pointer_size
2424 Returns two integers, width and height of a icon, that the system
2425 accepts as valid for a pointer. If the icon is supplied that is
2426 more or less than these values, it is truncated or padded with
2427 transparency bits, but is not stretched. Can be called with class
2428 syntax.
2429 get_shift_state
2431 Returns a combination of "km::XXX" constants, reflecting the
2432 currently pressed keyboard modifier buttons.
2433 See also: "get_shift_state"
2435 get_virtual_size
2437 Returns virtual width and height of a widget. See "Geometry",
2438 Implicit size regulations.
2439 See also: "width", "height", "size" "growMode", "Move", "Size",
2441 "sizeMax", "sizeMin"
2442 get_widgets
2444 Returns list of children widgets.
2445 Events
2447 Change
2448 Generic notification, used for Prima::Widget descendants;
2449 Prima::Widget itself neither calls not uses the event. Designed to
2450 be called when an arbitrary major state of a widget is changed.
2451 Click
2453 Generic notification, used for Prima::Widget descendants;
2454 Prima::Widget itself neither calls not uses the event. Designed to
2455 be called when an arbitrary major action for a widget is called.
2456 Close
2458 Triggered by can_close() and close() functions. If the event flag
2459 is cleared during execution, these functions fail.
2460 See also: "close", "can_close"
2462 ColorChanged INDEX
2464 Called when one of widget's color properties is changed, either by
2465 direct property change or by the system. INDEX is one of "ci::XXX"
2466 constants.
2467 See also: "colorIndex"
2469 Disable
2471 Triggered by a successive enabled(0) call
2472 See also: "Enable", "enabled", "responsive"
2474 DragBegin CLIPBOARD, ACTION, MOD, X, Y, COUNTERPART
2476 Triggered on a receiver widget when a mouse with a DND object
2477 enters it. "CLIPBOARD" contains the DND data, "ACTION" is a
2478 combination of "dnd::" constants, the actions the sender is ready
2479 to offer, "MOD" is a combination of modifier keys ("kb::"), and "X"
2480 and "Y" are coordinates where the mouse has entered the widget.
2481 This event, and the following "DragOver" and "DragEnd" events are
2482 happening only if the property "dndAware" is set either to 1, or if
2483 it matches a clipboard format that exists in "CLIPBOARD".
2484 "COUNTERPART" is the Prima DND sender widget, if the session is
2486 initiated within the same program.
2487 See also: "Drag and Drop", "DragOver", "DragEnd"
2489 DragEnd CLIPBOARD, ACTION, MOD, X, Y, COUNTERPART, ANSWER
2491 Triggered on a received widget when the user either drops or
2492 cancels the DND session. In case of a canceled drop, "CLIPBOARD" is
2493 set to "undef" and "ACTION" to "dnd::None". On a successful drop,
2494 input data are same as on "DragBegin", and output data are to be
2495 stored in hashref "ANSWER", if any. The following answers can be
2496 stored:
2497 allow BOOLEAN
2499 Is pre-set to 1. If changed to 0, a signal will be send to the
2500 sender that a drop is not accepted.
2501 action INTEGER
2503 A "dnd::" constant (not a combination) to be returned to the
2504 sender with the action the receiver has accepted, if any.
2505 "COUNTERPART" is the Prima DND sender widget, if the session is
2507 initiated within the same program.
2508 See also: "Drag and Drop", "DragBegin", "DragOver"
2510 DragOver CLIPBOARD, ACTION, MOD, X, Y, COUNTERPART, ANSWER
2512 Triggered on a received widget when a mouse with a DND moves within
2513 the widget. Input data are same as on "DragBegin", and output data
2514 are to be stored in hashref "ANSWER", if any. The following answers
2515 can be stored:
2516 allow BOOLEAN
2518 Is pre-set to 1. If changed to 0, a signal will be send to the
2519 sender that a drop action cannot happen with the input
2520 provided.
2521 action INTEGER
2523 A "dnd::" constant (not a combination) to be returned to the
2524 sender with the action the receiver is ready to accept, if any.
2525 pad X, Y, WIDTH, HEIGHT
2527 If set, instructs the sender not to repeat "DragOver" events
2528 that contains same input data, while the mouse pointer is
2529 within these geometrical limits.
2530 "COUNTERPART" is the Prima DND sender widget, if the session is
2532 initiated within the same program.
2533 DragQuery MOD, ANSWERS, COUNTERPART
2535 Triggered on a sender DND widget when there was detected a change
2536 in mouse or modifier buttons, or the user pressed "Escape" key to
2537 cancel the DND session. The combination of mouse and modifier
2538 buttons is stored in "MOD" integer, together with a special
2539 "km::Escape" constant for the "Escape" key.
2540 It is up to this event to decide whether to continue the drag
2542 session or not, and if it is decided not to continue,
2543 "$answer-"{allow}> must be set to 0.
2544 Additionally, "$answer-"{action}> can be set to select a single
2546 "dnd::" action that will be used to propose to the receiver a
2547 single concrete action based on the "MOD" value (f.ex. a
2548 "dnd::Move" if a control modifier was pressed).
2549 Note: This action will only forward the change to the receiver on
2551 X11, but it is advised to implement it anyway for portability.
2552 "COUNTERPART" is the Prima DND receiver widget, if within the same
2554 program.
2555 See also: "Drag and Drop", "DragResponse"
2557 DragResponse ALLOW, ACTION, COUNTERPART
2559 Triggered on a sender DND widget when there was detected a change
2560 in mouse or modifier buttons, or the mouse was moved from one DND
2561 target to another. The sender event is then presented with the new
2562 input, collected from interaction with the new target; there,
2563 "ALLOW" is set to a boolean value whether the sender is allowed to
2564 drop data, and "ACTION" is a "dnd::" constant with the action the
2565 receiver has agreed to accept, if any.
2566 If the drag and drop session was told not to update mouse pointers
2568 on such event, the handle should update the pointer in this
2569 callback. It is not needed though to save and restore mouse
2570 pointers before and after the DND session.
2571 "COUNTERPART" is the Prima DND receiver widget, if within the same
2573 program. See also: "Drag and Drop", "dnd_start", "begin_drag".
2574 Enable
2576 Triggered by a successive enabled(1) call
2577 See also: "Disable", "enabled", "responsive"
2579 Enter
2581 Called when a widget receives the input focus.
2582 See also: "Leave", "focused", "selected"
2584 FontChanged
2586 Called when a widget font is changed either by direct property
2587 change or by the system.
2588 See also: "font", "ColorChanged"
2590 Hide
2592 Triggered by a successive visible(0) call
2593 See also: "Show", "visible", "showing", "exposed"
2595 Hint SHOW_FLAG
2597 Called when the hint label is about to show or hide, depending on
2598 SHOW_FLAG. The hint show or hide action fails, if the event flag is
2599 cleared during execution.
2600 See also: "showHint", "ownerShowHint", "hintVisible", "ownerHint"
2602 KeyDown CODE, KEY, MOD, REPEAT
2604 Sent to the focused widget when the user presses a key. CODE
2605 contains an eventual character code, KEY is one of "kb::XXX"
2606 constants, MOD is a combination of the modifier keys pressed when
2607 the event occurred ( "km::XXX" ). REPEAT is how many times the key
2608 was pressed; usually it is 1. ( see "::briefKeys" ).
2609 The valid "km::" constants are:
2611 km::Shift
2613 km::Ctrl
2614 km::Alt
2615 km::KeyPad
2616 km::DeadKey
2617 km::Unicode
2618 The valid "kb::" constants are grouped in several sets. Some codes
2620 are aliased, like, "kb::PgDn" and "kb::PageDown".
2621 Modifier keys
2623 kb::ShiftL kb::ShiftR kb::CtrlL kb::CtrlR
2624 kb::AltL kb::AltR kb::MetaL kb::MetaR
2625 kb::SuperL kb::SuperR kb::HyperL kb::HyperR
2626 kb::CapsLock kb::NumLock kb::ScrollLock kb::ShiftLock
2627 Keys with character code defined
2629 kb::Backspace kb::Tab kb::Linefeed kb::Enter
2630 kb::Return kb::Escape kb::Esc kb::Space
2631 Function keys
2633 kb::F1 .. kb::F30
2634 kb::L1 .. kb::L10
2635 kb::R1 .. kb::R10
2636 Other
2638 kb::Clear kb::Pause kb::SysRq kb::SysReq
2639 kb::Delete kb::Home kb::Left kb::Up
2640 kb::Right kb::Down kb::PgUp kb::Prior
2641 kb::PageUp kb::PgDn kb::Next kb::PageDown
2642 kb::End kb::Begin kb::Select kb::Print
2643 kb::PrintScr kb::Execute kb::Insert kb::Undo
2644 kb::Redo kb::Menu kb::Find kb::Cancel
2645 kb::Help kb::Break kb::BackTab
2646 See also: "KeyUp", "briefKeys", "key_down", "help", "popup",
2648 "tabOrder", "tabStop", "accelTable"
2649 KeyUp CODE, KEY, MOD
2651 Sent to the focused widget when the user releases a key. CODE
2652 contains an eventual character code, KEY is one of "kb::XXX"
2653 constants, MOD is a combination of the modifier keys pressed when
2654 the event occurred ( "km::XXX" ).
2655 See also: "KeyDown", "key_up"
2657 Leave
2659 Called when the input focus is removed from a widget
2660 See also: "Enter", "focused", "selected"
2662 Menu MENU VAR_NAME
2664 Called before the user-navigated menu ( pop-up or pull-down ) is
2665 about to show another level of submenu on the screen. MENU is
2666 Prima::AbstractMenu descendant, that children to a widget, and
2667 VAR_NAME is the name of the menu item that is about to be shown.
2668 Used for making changes in the menu structures dynamically.
2670 See also: "popupItems"
2672 MouseClick BUTTON, MOD, X, Y, NTH
2674 Called when a mouse click ( button is pressed, and then released
2675 within system-defined interval of time ) is happened in the widget
2676 area. BUTTON is one of "mb::XXX" constants, MOD is a combination of
2677 "km::XXX" constants, reflecting pressed modifier keys during the
2678 event, X and Y are the mouse pointer coordinates. NTH is an
2679 integer, set to 0 if it was a single click, and to 2 and up if it
2680 was a double (triple etc etc) click.
2681 "mb::XXX" constants are:
2683 mb::b1 or mb::Left
2685 mb::b2 or mb::Middle
2686 mb::b3 or mb::Right
2687 mb::b4
2688 mb::b5
2689 mb::b6
2690 mb::b7
2691 mb::b8
2692 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseMove",
2694 "MouseEnter", "MouseLeave"
2695 MouseDown BUTTON, MOD, X, Y
2697 Occurs when the user presses mouse button on a widget. BUTTON is
2698 one of "mb::XXX" constants, MOD is a combination of "km::XXX"
2699 constants, reflecting the pressed modifier keys during the event, X
2700 and Y are the mouse pointer coordinates.
2701 See also: "MouseUp", "MouseClick", "MouseWheel", "MouseMove",
2703 "MouseEnter", "MouseLeave"
2704 MouseEnter MOD, X, Y
2706 Occurs when the mouse pointer is entered the area occupied by a
2707 widget ( without mouse button pressed ). MOD is a combination of
2708 "km::XXX" constants, reflecting the pressed modifier keys during
2709 the event, X and Y are the mouse pointer coordinates.
2710 See also: "MouseDown", "MouseUp", "MouseClick", "MouseWheel",
2712 "MouseMove", "MouseLeave"
2713 MouseLeave
2715 Occurs when the mouse pointer is driven off the area occupied by a
2716 widget ( without mouse button pressed ).
2717 See also: "MouseDown", "MouseUp", "MouseClick", "MouseWheel",
2719 "MouseMove", "MouseEnter"
2720 MouseMove MOD, X, Y
2722 Occurs when the mouse pointer is transported over a widget. MOD is
2723 a combination of "km::XXX" constants, reflecting the pressed
2724 modifier keys during the event, X and Y are the mouse pointer
2725 coordinates.
2726 See also: "MouseDown", "MouseUp", "MouseClick", "MouseWheel",
2728 "MouseEnter", "MouseLeave"
2729 MouseUp BUTTON, MOD, X, Y
2731 Occurs when the user depresses mouse button on a widget. BUTTON is
2732 one of "mb::XXX" constants, MOD is a combination of "km::XXX"
2733 constants, reflecting the pressed modifier keys during the event, X
2734 and Y are the mouse pointer coordinates.
2735 See also: "MouseDown", "MouseClick", "MouseWheel", "MouseMove",
2737 "MouseEnter", "MouseLeave"
2738 MouseWheel MOD, X, Y, INCR
2740 Occurs when the user rotates mouse wheel on a widget. MOD is a
2741 combination of "km::XXX" constants, reflecting the pressed modifier
2742 keys during the event, INCR is the wheel movement, scaled by 120.
2743 +120 is a step upwards, or -120 downwards. For wheels which are
2744 discrete button clicks INCR is +/-120 but other devices may give
2745 other amounts. A widget should scroll by INCR/120 many units, or
2746 partial unit, for whatever its unit of movement might be, such as
2747 lines of text, slider ticks, etc.
2748 A widget might like to vary its unit move according to the MOD
2750 keys. For example "Prima::SpinEdit" has a "step" and "pageStep"
2751 and moves by "pageStep" when "km::Ctrl" is held down (see
2752 Prima::Sliders).
2753 See also: "MouseDown", "MouseUp", "MouseClick", "MouseMove",
2755 "MouseEnter", "MouseLeave"
2756 Move OLD_X, OLD_Y, NEW_X, NEW_Y
2758 Triggered when widget changes its position relative to its parent,
2759 either by Prima::Widget methods or by the user. OLD_X and OLD_Y
2760 are the old coordinates of a widget, NEW_X and NEW_Y are the new
2761 ones.
2762 See also: "Size", "origin", "growMode", "centered", "clipOwner"
2764 Paint CANVAS
2766 Caused when the system calls for the refresh of a graphic context,
2767 associated with a widget. CANVAS is the widget itself, however its
2768 usage instead of widget is recommended ( see "Graphic content" ).
2769 See also: "repaint", "syncPaint", "get_invalid_rect", "scroll",
2771 "colorIndex", "font"
2772 Popup BY_MOUSE, X, Y
2774 Called by the system when the user presses a key or mouse
2775 combination defined for a context pop-up menu execution. By
2776 default executes the associated Prima::Popup object, if it is
2777 present. If the event flag is cleared during the execution of
2778 callbacks, the pop-up menu is not shown.
2779 See also: "popup"
2781 Setup
2783 This message is posted right after "Create" notification, and comes
2784 first from the event loop. Prima::Widget does not use it.
2785 Show
2787 Triggered by a successive visible(1) call
2788 See also: "Show", "visible", "showing", "exposed"
2790 Size OLD_WIDTH, OLD_HEIGHT, NEW_WIDTH, NEW_HEIGHT
2792 Triggered when widget changes its size, either by Prima::Widget
2793 methods or by the user. OLD_WIDTH and OLD_HEIGHT are the old
2794 extensions of a widget, NEW_WIDTH and NEW_HEIGHT are the new ones.
2795 See also: "Move", "origin", "size", "growMode", "sizeMax",
2797 "sizeMin", "rect", "clipOwner"
2798 SysHandle
2800 Same as in "Component", but introduces the following "Widget"
2801 properties can trigger it:
2802 "clipOwner", "syncPaint", "layered", "transparent"
2804 This event will be only needed when the system handle (that can be
2806 acquired by "get_handle" ) is needed.
2807 TranslateAccel CODE, KEY, MOD
2809 A distributed "KeyDown" event. Traverses all the object tree that
2810 the widget which received original "KeyDown" event belongs to. Once
2811 the event flag is cleared, the iteration stops.
2812 Used for tracking keyboard events by out-of-focus widgets.
2814 See also: "KeyDown"
2816 ZOrderChanged
2818 Triggered when a widget changes its stacking order, or Z-order
2819 among its siblings, either by Prima::Widget methods or by the user.
2820 See also: "bring_to_front", "insert_behind", "send_to_back"
2822
2824 Dmitry Karasik, <dmitry@karasik.eu.org>.
2825
2827 Prima, Prima::Object, Prima::Drawable.
2828perl v5.36.0 2023-03-20 pod::Prima::Widget(3)