1pod::Prima::Widget(3) User Contributed Perl Documentationpod::Prima::Widget(3)
2
6 Prima::Widget - window management
7
9 # create a widget
10 my $widget = Prima::Widget-> new(
11 size => [ 200, 200],
12 color => cl::Green,
13 visible => 0,
14 onPaint => sub {
15 my ($self,$canvas) = @_;
16 $canvas-> clear;
17 $canvas-> text_out( "Hello world!", 10, 10);
18 },
19 );
20 # manipulate the widget
22 $widget-> origin( 10, 10);
23 $widget-> show;
24
26 Prima::Widget is a descendant of Prima::Component, a class, especially
27 crafted to reflect and govern properties of a system-dependent window,
28 such as its position, hierarchy, outlook etc. Prima::Widget is mapped
29 into the screen space as a rectangular area, with distinct boundaries,
30 pointer and sometimes cursor, and a user-selectable input focus.
31
33 Prima::Widget class and its descendants are used widely throughout the
34 toolkit, and, indeed provide almost all its user interaction and input-
35 output. The notification system, explained in Prima::Object, is
36 employed in Prima::Widget heavily, providing the programmer with
37 unified access to the system-generated events, that occur when the user
38 moves windows, clicks the mouse, types the keyboard, etc. Descendants
39 of Prima::Widget use the internal, the direct method of overriding the
40 notifications, whereas end programs tend to use the toolkit widgets
41 equipped with anonymous subroutines ( see Prima::Object for the
42 details).
43 The class functionality is much more extensive comparing to the other
45 built-in classes, and therefore the explanations are grouped in several
46 topics.
47
49 The widget creation syntax is the same as for the other Prima objects:
50 Prima::Widget-> create(
52 name => 'Widget',
53 size => [ 20, 10],
54 onMouseClick => sub { print "click\n"; },
55 owner => $owner,
56 );
57 In the real life, a widget must be almost always explicitly told about
59 its owner. The owner object is either a Prima::Widget descendant, in
60 which case the widget is drawn inside its inferior, or the application
61 object, and in the latter case a widget becomes top-level. This is the
62 reason why the "insert" syntax is much more often used, as it is more
63 illustrative and is more convenient for creating several widgets in one
64 call ( see Prima::Object ).
65 $owner-> insert( 'Prima::Widget',
67 name => 'Widget',
68 size => [ 20, 10],
69 onMouseClick => sub { print "click\n"; },
70 );
71 These two examples produce identical results.
73 As a descendant of Prima::Component, Prima::Widget sends "Create"
75 notification when created ( more precisely, after its init stage is
76 finished. See Prima::Object for details). This notification is called
77 and processed within "create()" call. In addition, another notification
78 "Setup" is sent after the widget is created. This message is posted, so
79 it is called within "create()" but processed in the application event
80 loop. This means that the execution time of "Setup" is uncertain, as it
81 is with all posted messages; its delivery time is system-dependent, so
82 its use must be considered with care.
83 After a widget is created, it is usually asked to render its content,
85 provided that the widget is visible. This request is delivered by means
86 of "Paint" notification.
87 When the life time of a widget is over, its method "destroy()" is
89 called, often implicitly. If a widget gets destroyed because its owner
90 also does, it is guaranteed that the children widgets will be destroyed
91 first, and the owner afterwards. In such situation, widget can operate
92 with a limited functionality both on itself and its owners ( see
93 Prima::Object, Creation section ).
94
96 A widget can use two different ways for representing its graphic
97 content to the user. The first method is event-driven, when the "Paint"
98 notification arrives, notifying the widget that it must re-paint
99 itself. The second is the 'direct' method, when the widget generates
100 graphic output unconditionally.
101 Event-driven rendering
103 A notification responsible for widget repainting is "Paint". It
104 provides a single ( besides the widget itself ) parameter, an object,
105 where the drawing is performed. In an event-driven call, it is always
106 equals to the widget. However, if a custom mechanism should be used
107 that directly calls, for example,
108 $widget-> notify('Paint', $some_other_widget);
110 for whatever purpose, it is recommended ( not required, though ), to
112 use this parameter, not the widget itself for painting and drawing
113 calls.
114 The example of "Paint" callback is quite simple:
116 Prima::Widget-> create(
118 ...
119 onPaint => sub {
120 my ( $self, $canvas) = @_;
121 $canvas-> clear;
122 $canvas-> text_out("Clicked $self->{clicked} times", 10, 10);
123 },
124 onMouseClick => sub {
125 $_[0]-> {clicked}++;
126 $_[0]-> repaint;
127 },
128 );
129 The example uses several important features of the event-driven
131 mechanism. First, no "begin_paint()"/"end_paint()" brackets are used
132 within the callback. These are called implicitly. Second, when the
133 custom refresh of the widget's graphic content is needed, no code like
134 "notify(q(Paint))" is used - "repaint()" method is used instead. It
135 must be noted, that the actual execution of "Paint" callbacks might or
136 might not occur inside the "repaint()" call. This behavior is governed
137 by the "::syncPaint" property. "repaint()" marks the whole widget's
138 area to be refreshed, or invalidates the area. For the finer gradation
139 of the area that should be repainted, "invalidate_rect()" and
140 "validate_rect()" pair of functions is used. Thus,
141 $x-> repaint()
143 code is a mere alias to
145 $x-> invalidate_rect( 0, 0, $x-> size);
147 call. It must be realized, that the area, passed to "invalidate_rect()"
149 only in its ideal ( but a quite often ) execution case will be
150 pertained as a clipping rectangle when a widget executes its "Paint"
151 notification. The user and system interactions can result in
152 exposition of other parts of a widget ( like, moving windows over a
153 widget ), and the resulting clipping rectangle can be different from
154 the one that was passed to "invalidate_rect()". Moreover, the clipping
155 rectangle can become empty as the result of these influences, and the
156 notification will not be called at all.
157 Invalid rectangle is presented differently inside and outside the
159 drawing mode. The first, returned by "::clipRect", employs inclusive-
160 inclusive coordinates, whereas "invalidate_rect()", "validate_rect()"
161 and "get_invalid_rect()" - inclusive-exclusive coordinates. The ideal
162 case exemplifies the above said:
163 $x-> onPaint( sub {
165 my @c = $_[0]-> clipRect;
166 print "clip rect:@c\n";
167 });
168 $x-> invalidate_rect( 10, 10, 20, 20);
169 ...
170 clip rect: 10 10 19 19
171 As noted above, "::clipRect" property is set to the clipping rectangle
173 of the widget area that is needed to be refreshed, and an event handler
174 code can take advantage of this information, increasing the efficiency
175 of the painting procedure.
176 Further assignments of "::clipRect" property do not make possible over-
178 painting on the screen area that lies outside the original clipping
179 region. This is also valid for all paint operations, however since the
180 original clipping rectangle is the full area of a canvas, this rule is
181 implicit and unnecessary, because whatever large the clipping rectangle
182 is, drawing and painting cannot be performed outside the physical
183 boundaries of the canvas.
184 Direct rendering
186 The direct rendering, contrary to the event-driven, is initiated by the
187 program, not by the system. If a programmer wishes to paint over a
188 widget immediately, then "begin_paint()" is called, and, if successful,
189 the part of the screen occupied by the widget is accessible to the
190 drawing and painting routines.
191 This method is useful, for example, for graphic demonstration programs,
193 that draw continuously without any input. Another field is the screen
194 drawing, which is performed with Prima::Application class, that does
195 not have "Paint" notification. Application's graphic canvas represents
196 the whole screen, allowing over-drawing the graphic content of other
197 programs.
198 The event-driven rendering method adds implicit
200 "begin_paint()"/"end_paint()" brackets ( plus some system-dependent
201 actions ) and is a convenience version of the direct rendering.
202 Sometimes, however, the changes needed to be made to a widget's graphic
203 context are so insignificant, so the direct rendering method is
204 preferable, because of the cleaner and terser code. As an example might
205 serve a simple progress bar, that draws a simple colored bar. The
206 event-driven code would be ( in short, omitting many details ) as such:
207 $bar = Widget-> create(
209 width => 100,
210 onPaint => sub {
211 my ( $self, $canvas) = @_;
212 $canvas-> color( cl::Blue);
213 $canvas-> bar( 0, 0, $self-> {progress}, $self-> height);
214 $canvas-> color( cl::Back);
215 $canvas-> bar( $self-> {progress}, 0, $self-> size);
216 },
217 );
218 ...
219 $bar-> {progress} += 10;
220 $bar-> repaint;
221 # or, more efficiently, ( but clumsier )
222 # $bar-> invalidate_rect( $bar->{progress}-10, 0,
223 # $bar->{progress}, $bar-> height);
224 And the direct driven:
226 $bar = Widget-> create( width => 100 );
228 ...
229 $bar-> begin_paint;
230 $bar-> color( cl::Blue);
231 $bar-> bar( $progress, 0, $progress + 10, $bar-> height);
232 $bar-> end_paint;
233 $progress += 10;
234 The pros and contras are obvious: the event-driven rendered widget
236 correctly represents the status after an eventual repaint, for example
237 when the user sweeps a window over the progress bar widget. The direct
238 method cannot be that smart, but if the status bar is an insignificant
239 part of the program, the trade-off of the functionality in favor to the
240 code simplicity might be preferred.
241 Both methods can be effectively disabled using the paint locking
243 mechanism. The "lock()" and "unlock()" methods can be called several
244 times, stacking the requests. This feature is useful because many
245 properties implicitly call "repaint()", and if several of these
246 properties activate in a row, the unnecessary redrawing of the widget
247 can be avoided. The drawback is that the last "unlock()" call triggers
248 "repaint()" unconditionally.
249
251 Basic properties
252 A widget always has its position and size determined, even if it is not
253 visible on the screen. Prima::Widget provides several properties with
254 overlapping functionality, that govern the geometry of a widget. The
255 base properties are "::origin" and "::size", and the derived are
256 "::left", "::bottom", "::right", "::top", "::width", "::height" and
257 "::rect". "::origin" and "::size" operate with two integers, "::rect"
258 with four, others with one integer value.
259 As the Prima toolkit coordinate space begins in the lower bottom
261 corner, the combination of "::left" and "::bottom" is same as
262 "::origin", and combination of "::left", "::bottom", "::right" and
263 "::top" - same as "::rect".
264 When a widget is moved or resized, correspondingly two notifications
266 occur: "Move" and "Size". The parameters to both are old and new
267 position and size. The notifications occur irrespectable to whether the
268 geometry change was issued by the program itself or by the user.
269 Implicit size regulations
271 Concerning the size of a widget, two additional two-integer properties
272 exist, "::sizeMin" and "::sizeMax", that constrain the extension of a
273 widget in their boundaries. The direct call that assigns values to the
274 size properties that lie outside "::sizeMin" and "::sizeMax"
275 boundaries, will fail - the widget extension will be adjusted to the
276 boundary values, not to the specified ones.
277 Change to widget's position and size can occur not only by an explicit
279 call to one of the geometry properties. The toolkit contains implicit
280 rules, that can move and resize a widget corresponding to the flags,
281 given to the "::growMode" property. The exact meaning of the "gm::XXX"
282 flags is not given here ( see description to "::growMode" in API
283 section ), but in short, it is possible with simple means to maintain
284 widget's size and position regarding its owner, when the latter is
285 resized. By default, and the default behavior corresponds to
286 "::growMode" 0, widget does not change neither its size nor position
287 when its owner is resized. It stays always in 'the left bottom corner'.
288 When, for example, a widget is expected to stay in 'the right bottom
289 corner', or 'the left top corner', the "gm::GrowLoX" and "gm::GrowLoY"
290 values must be used, correspondingly. When a widget is expected to
291 cover, for example, its owner's lower part and change its width in
292 accord with the owner's, ( a horizontal scroll bar in an editor window
293 is the example), the "gm::GrowHiX" value must be used.
294 When this implicit size change does occur, the "::sizeMin" and
296 "::sizeMax" do take their part as well - they still do not allow the
297 widget's size to exceed their boundaries. However, this algorithm has a
298 problem, that is illustrated by the following setup. Imagine a widget
299 with size-dependent "::growMode" ( with "gm::GrowHiX" or "gm::GrowHiY"
300 bits set ) that must maintain certain relation between the owner's size
301 and its own. If the implicit size change would depend on the actual
302 widget size, derived as a result from the previous implicit size
303 action, then its size (and probably position) will be incorrect after
304 an attempt is made to change the widget's size to values outside the
305 size boundaries.
306 Example: child widget has width 100, growMode set to "gm::GrowHiX" and
308 sizeMin set to (95, 95). Its owner has width 200. If the owner widget
309 changes gradually its width from 200 to 190 and then back, the
310 following width table emerges:
311 Owner Child
313 Initial state 200 100
314 Shrink 195 -5 95
315 Shrink 190 -5 95 - as it can not be less than 95.
316 Grow 195 +5 100
317 Grow 200 +5 105
318 That effect would exist if the differential-size algorithm would be
320 implemented, - the owner changes width by 5, and the child does the
321 same. The situation is fixed by introducing the virtual size term.
322 The "::size" property is derived from virtual size, and as "::size"
323 cannot exceed the size boundaries, virtual size can. It can even
324 accept the negative values. With this intermediate stage added, the
325 correct picture occurs:
326 Owner Child's Child's
328 virtual width width
329 Initial state 200 100 100
330 Shrink 195 -5 95 95
331 Shrink 190 -5 90 95
332 Grow 195 +5 95 95
333 Grow 200 +5 100 100
334 Geometry managers
336 The concept of geometry managers is imported from Tk, which in turn is
337 a port of Tcl-Tk. The idea behind it is that a widget size and position
338 is governed by one of the managers, which operate depending on the
339 specific options given to the widget. The selection is operated by
340 "::geometry" property, and is one of "gt::XXX" constants. The native (
341 and the default ) geometry manager is the described above grow-mode
342 algorithm ( "gt::GrowMode" ). The currently implemented Tk managers are
343 packer ( "gt::Pack" ) and placer ( "gt::Place"). Each has its own set
344 of options and methods, and their manuals are provided separately in
345 Prima::Widget::pack and Prima::Widget::place ( the manpages are also
346 imported from Tk ).
347 Another concept that comes along with geometry managers is the
349 'geometry request size'. It is realized as a two-integer property
350 "::geomSize", which reflects the size deduced by some intrinsic widget
351 knowledge. The idea is that "::geomSize" it is merely a request to a
352 geometry manager, whereas the latter changes "::size" accordingly. For
353 example, a button might set its 'intrinsic' width in accord with the
354 width of text string displayed in it. If the default width for such a
355 button is not overridden, it is assigned with such a width. By default,
356 under "gt::GrowMode" geometry manager, setting "::geomSize" ( and its
357 two semi-alias properties "::geomWidth" and "::geomHeight" ) also
358 changes the actual widget size.Moreover, when the size is passed to the
359 Widget initialization code, "::size" properties are used to initialize
360 "::geomSize". Such design minimizes the confusion between the two
361 properties, and also minimizes the direct usage of "::geomSize",
362 limiting it for selecting advisory size in widget internal code.
363 The geometry request size is useless under "gt::GrowMode" geometry
365 manager, but Tk managers use it extensively.
366 Relative coordinates
368 Another geometry issue, or rather a programming technique must be
369 mentioned - the relative coordinates. It is the well-known problem,
370 when a dialog window, developed with one font looks garbled on another
371 system with another font. The relative coordinates solve that problem;
372 the solution is to use the "::designScale" two-integer property, the
373 width and height of the font, that was used when the dialog window was
374 designed. With this property supplied, the position and size supplied
375 when a widget is actually created, are transformed in proportion
376 between the designed and the actual font metrics.
377 The relative coordinates can be used only when passing the geometry
379 properties values, and only before the creation stage, before a widget
380 is created, because the scaling calculations perform in
381 Prima::Widget::"profile_check_in()" method.
382 In order to employ the relative coordinates scheme, the owner ( or the
384 dialog ) widget must set its "::designScale" to the font metrics and
385 "::scaleChildren" property to 1. Widgets, created with owner that
386 meets these requirements, participate in the relative coordinates
387 scheme. If a widget must be excluded from the relative geometry
388 applications, either the owner's property "::scaleChildren" must be set
389 to 0, or the widget's "::designScale" must be set to "undef". As the
390 default "::designScale" value is "undef", no default implicit relative
391 geometry schemes are applied.
392 The "::designScale" property is auto-inherited; its value is copied to
394 the children widgets, unless the explicit "::designScale" was given
395 during the widget's creation. This is used when such a child widget
396 serves as an owner for some other grand-children widgets; the
397 inheritance scheme allows the grand- ( grand- etc ) children to
398 participate in the relative geometry scheme.
399 Note: it is advised to test such applications with the Prima::Stress
401 module, which assigns a random font as the default, so the testing
402 phase does not involve tweaking of the system settings.
403
405 In case when two widgets overlap, one of these is drawn in full,
406 whereas the another only partly. Prima::Widget provides management of
407 the Z-axis ordering, but since Z-ordering paradigm can hardly be fit
408 into the properties scheme, the toolkit uses methods instead.
409 A widget can use four query methods: "first()", "last()", "next()", and
411 "prev()". These return, correspondingly, the first and the last widgets
412 in Z-order stack, and the direct neighbors of a widget ( $widget->
413 next-> prev always equals to the $widget itself, given that $widget->
414 next exists ).
415 The last widget is the topmost one, the one that is drawn fully. The
417 first is the most obscured one, given that all the widgets overlap.
418 Z-order can also be changed at runtime ( but not during widget's
420 creation). There are three methods: "bring_to_front()", that sets the
421 widget last in the order, making it topmost, "send_to_back()", that
422 does the reverse, and "insert_behind()", that sets a widget behind the
423 another widget, passed as an argument.
424 Changes to Z-order trigger "ZOrderChanged" notification.
426
428 By default, if a widget is a child to a widget or a window, it
429 maintains two features: it is clipped by its owner's boundaries and is
430 moved together as the owner widget moves, i.e. a child is inferior to
431 its parent. However, a widget without a parent still does have a valid
432 owner. Instead of implementing parent property, the "::clipOwner"
433 property was devised. It is 1 by default, and if it is 1, then owner of
434 a widget is its parent, at the same time. However, when it is 0, many
435 things change. The widget is neither clipped nor moved together with
436 its parent. The widget become parentless, or, more strictly speaking,
437 the screen becomes its parent. Moreover, the widget's origin offset is
438 calculated then not from the owner's coordinates but from the screen,
439 and mouse events in the widget do not transgress implicitly to the
440 owner's top-level window eventual decorations.
441 The same results are produced if a widget is inserted in the
443 application object, which does not have screen visualization. A widget
444 that belongs to the application object, can not reset its "::clipOwner"
445 value to 1.
446 The "::clipOwner" property opens a possibility for the toolkit widgets
448 to live inside other programs' windows. If the "::parentHandle" is
449 changed from its default "undef" value to a valid system window handle,
450 the widget becomes child to this window, which can belong to any
451 application residing on the same display. This option is dangerous,
452 however: normally widgets never get destroyed by no reason. A top-level
453 window is never destroyed before its "Close" notification grants the
454 destruction. The case with "::parentHandle" is special, because a
455 widget, inserted into an alien application, must be prepared to be
456 destroyed at any moment. It is recommended to use prior knowledge about
457 such the application, and, even better, use one or another inter-
458 process communication scheme to interact with it.
459 A widget does not need to undertake anything special to become an
461 'owner'. Any widget, that was set in "::owner" property on any other
462 widget, becomes an owner automatically. Its "get_widgets()" method
463 returns non-empty widget list. "get_widgets()" serves same purpose as
464 Prima::Component::"get_components()", but returns only Prima::Widget
465 descendants.
466 A widget can change its owner at any moment. The "::owner" property is
468 both readable and writable, and if a widget is visible during the owner
469 change, it is immediately appeared under different coordinates and
470 different clipping condition after the property change, given that its
471 "::clipOwner" is set to 1.
472
474 A widget is created visible by default. Visible means that it is shown
475 on the screen if it is not shadowed by other widgets or windows. The
476 visibility is governed by the "::visible" property, and its two
477 convenience aliases, "show()" and "hide()".
478 When a widget is invisible, its geometry is not discarded; the widget
480 pertains its position and size, and is subject to all previously
481 discussed implicit sizing issues. When change to "::visible" property
482 is made, the screen is not updated immediately, but in the next event
483 loop invocation, because uncovering of the underlying area of a hidden
484 widget, and repainting of a new-shown widget both depend onto the
485 event-driven rendering functionality. If the graphic content must be
486 updated, "update_view()" must be called, but there's a problem. It is
487 obvious that if a widget is shown, the only content to be updated is
488 its own. When a widget becomes hidden, it may uncover more than one
489 widget, depending on the geometry, so it is unclear what widgets must
490 be updated. For the practical reasons, it is enough to get one event
491 loop passed, by calling "yield()" method of the $::application object.
492 The other notifications may pass here as well, however.
493 There are other kinds of visibility. A widget might be visible, but one
495 of its owners might not. Or, a widget and its owners might be visible,
496 but they might be over-shadowed by the other windows. These conditions
497 are returned by "showing()" and "exposed()" functions, correspondinly.
498 These return boolean values corresponding to the condition described.
499 So, if a widget is 'exposed', it is 'showing' and 'visible';
500 "exposed()" returns always 0 if a widget is either not 'showing' or not
501 'visible'. If a widget is 'showing', then it is always 'visible'.
502 "showing()" returns always 0 if a widget is invisible.
503 Visibility changes trigger "Hide" and "Show" notifications.
505
507 One of the key points of any GUI is that only one window at a time can
508 possess a focus. The widget is focused, if the user's keyboard input is
509 directed to it. The toolkit adds another layer in the focusing scheme,
510 as often window managers do, highlighting the decorations of a top-
511 level window over a window with the input focus.
512 Prima::Widget property "::focused" governs the focused state of a
514 widget. It is sometimes too powerful to be used. Its more often
515 substitutes, "::selected" and "::current" properties provide more
516 respect to widget hierarchy.
517 "::selected" property sets focus to a widget if it is allowed to be
519 focused, by the usage of the "::selectable" property. With this
520 granted, the focus is passed to the widget or to the one of its (
521 grand-) children. So to say, when 'selecting' a window with a text
522 field by clicking on a window, one does not expect the window itself to
523 be focused, but the text field. To achieve this goal and reduce
524 unnecessary coding, the "::current" property is introduced. With all
525 equal conditions, a widget that is 'current' gets precedence in getting
526 selected over widgets that are not 'current'.
527 De-selecting, in its turn, leaves the system in such a state when no
529 window has input focus. There are two convenience shortcuts "select()"
530 and "deselect()" defined, aliased to selected(1) and selected(0),
531 correspondingly.
532 As within the GUI space, there can be only one 'focused' widget, so
534 within the single widget space, there can be only one 'current' widget.
535 A widget can be marked as a current by calling "::current" ( or,
536 identically, "::currentWidget" on the owner widget ). The
537 reassignments are performed automatically when a widget is focused.
538 The reverse is also true: if a widget is explicitly marked as
539 'current', and belongs to the widget tree with the focus in one of its
540 widgets, then the focus passed to the 'current' widget, or down to its
541 hierarchy if it is not selectable.
542 These relations between current widget pointer and focus allow the
544 toolkit easily implement the focusing hierarchy. The focused widget is
545 always on the top of the chain of its owner widgets, each of whose is a
546 'current' widget. If, for example, a window that contains a widget that
547 contains a focused button, become un-focused, and then user selects the
548 window again, then the button will become focused automatically.
549 Changes to focus produce "Enter" and "Leave" notifications.
551 Below discussed mouse- and keyboard- driven focusing schemes. Note
553 that all of these work via "::selected", and do not focus the widgets
554 with "::selectable" property set to 0.
555 Mouse-aided focusing
557 Typically, when the user clicks the left mouse button on a widget, the
558 latter becomes focused. One can note that not all widgets become
559 focused after the mouse click - scroll bars are the examples. Another
560 kind of behavior is the described above window with the text field -
561 clicking mouse on a window focuses a text field.
562 Prima::Widget has the "::selectingButtons" property, a combination of
564 mb::XXX ( mouse buttons ) flags. If the bits corresponding to the
565 buttons are set, then click of this button will automatically call
566 ::selected(1) ( not ::focused(1) ).
567 Another boolean property, "::firstClick" determines the behavior when
569 the mouse button action is up to focus a widget, but the widget's top-
570 level window is not active. The default value of "::firstClick" is 1,
571 but if set otherwise, the user must click twice to a widget to get it
572 focused. The property does not influence anything if the top-level
573 window was already active when the click event occured.
574 Due to different GUI designs, it is hardly possibly to force selection
576 of one top-level window when the click was on the another. The window
577 manager or the OS can interfere, although this does not always happen,
578 and produces different results on different platforms. Since the
579 primary goal of the toolkit is portability, such functionality must be
580 considered with care. Moreover, when the user selects a window by
581 clicking not on the toolkit-created widgets, but on the top-level
582 window decorations, it is not possible to discern the case from any
583 other kind of focusing.
584 Keyboard focusing
586 The native way to navigate between the toolkit widgets are tab- and
587 arrow- navigation. The tab ( and its reverse, shift-tab ) key
588 combinations circulate the focus between the widgets in same top-level
589 group ( but not inside the same owner widget group ). The arrow keys,
590 if the focused widget is not interested in these keystrokes, move the
591 focus in the specified direction, if it is possible. The methods that
592 provide the navigations are available and called "next_tab()" and
593 "next_positional()", correspondingly ( see API for the details).
594 When "next_positional()" operates with the geometry of the widgets,
596 "next_tab()" uses the "::tabStop" and "::tabOrder" properties.
597 "::tabStop", the boolean property, set to 1 by default, tells if a
598 widget is willing to participate in tab-aided focus circulation. If it
599 doesn't, "next_tab()" never uses it in its iterations. "::tabOrder"
600 value is an integer, unique within the sibling widgets ( sharing same
601 owner ) list, and is used as simple tag when the next tab-focus
602 candidate is picked up. The default "::tabOrder" value is -1, which
603 changes automatically after widget creation to a unique value.
604
606 The toolkit responds to the two basic means of the user input - the
607 keyboard and the mouse. Below described three aspects of the input
608 handling - the event-driven, the polling and the simulated input
609 issues. The event-driven input is the more or less natural way of
610 communicating with the user, so when the user presses the key or moves
611 the mouse, a system event occurs and triggers the notification in one
612 or more widgets. Polling methods provide the immediate state of the
613 input devices; the polling is rarely employed, primarily because of its
614 limited usability, and because the information it provides is passed to
615 the notification callbacks anyway. The simulated input is little more
616 than "notify()" call with specifically crafted parameters. It interacts
617 with the system, so the emulation can gain the higher level of
618 similarity to the user actions. The simulated input functions allow the
619 notifications to be called right away, or post it, delaying the
620 notification until the next event loop invocation.
621 Keyboard
623 Event-driven
624 Keyboard input generates several notifications, where the most
625 important are "KeyDown" and "KeyUp". Both have almost the same list
626 of parameters ( see API ), that contain the key code, its modifiers
627 ( if any ) that were pressed and an eventual character code. The
628 algorithms that extract the meaning of the key, for example,
629 discretion between character and functional keys etc are not
630 described here. The reader is advised to look at Prima::KeySelector
631 module, which provides convenience functions for keyboard input
632 values transformations, and to the Prima::Edit and Prima::InputLine
633 modules, the classes that use extensively the keyboard input. But
634 in short, the key code is one of the "kb::XXX" ( like, kb::F10,
635 kb::Esc ) constants, and the modifier value is a combination of the
636 "km::XXX" ( km::Ctrl, km::Shift) constants. The notable exception
637 is kb::None value, which hints that the character code is of value.
638 Some other "kb::XXX"-marked keys have the character code as well,
639 and it is up to a programmer how to treat these combinations. It is
640 advised, however, to look at the key code first, and then to the
641 character code.
642 "KeyDown" event has also the repeat integer parameter, that shows
644 the repetitive count how many times the key was pressed. Usually
645 it is 1, but if a widget was not able to get its portion of events
646 between the key presses, its value can be higher. If a code
647 doesn't check for this parameter, some keyboard input may be lost.
648 If the code will be too much complicated by introducing the repeat-
649 value, one may consider setting the "::briefKeys" property to 0.
650 "::briefKeys", the boolean property, is 1 by default. If set to 0,
651 it guarantees that the repeat value will always be 1, but with the
652 price of certain under-optimization. If the core "KeyDown"
653 processing code sees repeat value greater than 1, it simply calls
654 the notification again.
655 Along with these two notifications, the "TranslateAccel" event is
657 generated after "KeyDown", if the focused widget is not interested
658 in the key event. Its usage covers the needs of the other widgets
659 that are willing to read the user input, even being out of focus.
660 A notable example can be a button with a hot key, that reacts on
661 the key press when the focus is elsewhere within its top-level
662 window. "TranslateAccel" has same parameters as "KeyDown", except
663 the REPEAT parameter.
664 Such out-of-focus input is also used with built-in menu keys
666 translations. If a descendant of Prima::AbstractMenu is in the
667 reach of the widget tree hierarchy, then it is checked whether it
668 contains some hot keys that match the user input. See Prima::Menu
669 for the details. In particular, Prima::Widget has "::accelTable"
670 property, a mere slot for an object that contains a table of hot
671 keys mappings to custom subroutines.
672 Polling
674 The polling function for the keyboard is limited to the modifier
675 keys only. "get_shift_state()" method returns the press state of
676 the modifier keys, a combination of "km::XXX" constants.
677 Simulated input
679 There are two methods, corresponding to the major notifications -
680 "key_up()" and "key_down()", that accept the same parameters as the
681 "KeyUp" and "KeyDown" notifications do, plus the POST boolean flag.
682 See "API" for details.
683 These methods are convenience wrappers for "key_event()" method,
685 which is never used directly.
686 Mouse
688 Event-driven
689 Mouse notifications are send in response when the user moves the
690 mouse, or presses and releases mouse buttons. The notifications
691 are logically grouped in two sets, the first contains "MouseDown",
692 "MouseUp", "MouseClick", and "MouseWheel", and the second -
693 "MouseMove", "MouseEnter", end "MouseLeave".
694 The first set deals with button actions. Pressing, de-pressing,
696 clicking ( and double-clicking ), the turn of mouse wheel
697 correspond to the four notifications. The notifications are sent
698 together with the mouse pointer coordinates, the button that was
699 touched, and the eventual modifier keys that were pressed. In
700 addition, "MouseClick" provides the boolean flag if the click was
701 single or double, and "MouseWheel" the wheel turn amount. These
702 notifications occur when the mouse event occurs within the
703 geometrical bounds of a widget, with one notable exception, when a
704 widget is in capture mode. If the "::capture" is set to 1, then
705 these events are sent to the widget even if the mouse pointer is
706 outside, and not sent to the widgets and windows that reside under
707 the pointer.
708 The second set deals with the pointer movements. When the pointer
710 passes over a widget, it receives first "MouseEnter", then series
711 of "MouseMove", and finally "MouseLeave". "MouseMove" and
712 "MouseEnter" notifications provide X,Y-coordinates and modificator
713 keys; "MouseLeave" passes no parameters.
714 Polling
716 The mouse input polling procedures are "get_mouse_state()" method,
717 that returns combination of "mb::XXX" constants, and the
718 "::pointerPos" two-integer property that reports the current
719 position of the mouse pointer.
720 Simulated input
722 There are five methods, corresponding to the mouse events -
723 "mouse_up()", "mouse_down()", "mouse_click()", "mouse_wheel()" and
724 "mouse_move()", that accept the same parameters as their event
725 counterparts do, plus the POST boolean flag. See "API" for details.
726 These methods are convenience wrappers for "mouse_event()" method,
728 which is never used directly.
729
731 Prima::Drawable deals only with such color values, that can be
732 unambiguously decomposed to their red, green and blue components.
733 Prima::Widget extends the range of the values acceptable by its color
734 properties, introducing the color schemes. The color can be set
735 indirectly, without prior knowledge of what is its RGB value. There are
736 several constants defined in "cl::" name space, that correspond to the
737 default values of different color properties of a widget.
738 Prima::Widget revises the usage of "::color" and "::backColor", the
740 properties inherited from Prima::Drawable. Their values are widget's
741 'foreground' and 'background' colors, in addition to their function as
742 template values. Moreover, their dynamic change induces the repainting
743 of a widget, and they can be inherited from the owner. The inheritance
744 is governed by properties "::ownerColor" and "::ownerBackColor". While
745 these are true, changes to owner "::color" or "::backColor" copied
746 automatically to a widget. Once the widget's "::color" or "::backColor"
747 are explicitly set, the owner link breaks automatically by setting
748 "::ownerColor" or "::ownerBackColor" to 0.
749 In addition to these two color properties, Prima::Widget introduces six
751 others. These are "::disabledColor", "::disabledBackColor",
752 "::hiliteColor", "::hiliteBackColor", "::light3DColor", and
753 "::dark3DColor". The 'disabled' color pair contains the values that
754 are expected to be used as foreground and background when a widget is
755 in the disabled state ( see API, "::enabled" property ). The 'hilite'
756 values serve as the colors for representation of selection inside a
757 widget. Selection may be of any kind, and some widgets do not provide
758 any. But for those that do, the 'hilite' color values provide distinct
759 alternative colors. Examples are selections in the text widgets, or in
760 the list boxes. The last pair, "::light3DColor" and "::dark3DColor" is
761 used for drawing 3D-looking outlines of a widget. The purpose of all
762 these properties is the adequate usage of the color settings, selected
763 by the user using system-specific tools, so the program written with
764 the toolkit would look not such different, and more or less conformant
765 to the user's color preferences.
766 The additional "cl::" constants, mentioned above, represent these eight
768 color properties. These named correspondingly, cl::NormalText,
769 cl::Normal, cl::HiliteText, cl::Hilite, cl::DisabledText, cl::Disabled,
770 cl::Light3DColor and cl::Dark3DColor. cl::NormalText is alias to
771 cl::Fore, and cl::Normal - to cl::Back. Another constant set, "ci::"
772 can be used with the "::colorIndex" property, a multiplexer for all
773 eight color properties. "ci::" constants mimic their non-RGB "cl::"
774 counterparts, so the call "hiliteBackColor(cl::Red)" is equal to
775 "colorIndex(ci::Hilite, cl::Red)".
776 Mapping from these constants to the RGB color representation is used
778 with "map_color()" method. These "cl::" constants alone are sufficient
779 for acquiring the default values, but the toolkit provides wider
780 functionality than this. The "cl::" constants can be combined with the
781 "wc::" constants, that represent standard widget class. The widget
782 class is implicitly used when single "cl::" constant is used; its value
783 is read from the "::widgetClass" property, unless one of "wc::"
784 constants is combined with the non-RGB "cl::" value. "wc::" constants
785 are described in "API"; their usage can make call of, for example,
786 "backColor( cl::Back)" on a button and on an input line result in
787 different colors, because the "cl::Back" is translated in the first
788 case into "cl::Back|wc::Button", and in another -
789 "cl::Back|wc::InputLine".
790 Dynamic change of the color properties result in the "ColorChanged"
792 notification.
793
795 Prima::Widget does not change the handling of fonts - the font
796 selection inside and outside "begin_paint()"/"end_paint()" is not
797 different at all. A matter of difference is how does Prima::Widget
798 select the default font.
799 First, if the "::ownerFont" property is set to 1, then font of the
801 owner is copied to the widget, and is maintained all the time while the
802 property is true. If it is not, the default font values read from the
803 system.
804 The default font metrics for a widget returned by "get_default_font()"
806 method, that often deals with system-dependent and user-selected
807 preferences ( see "Additional resources" ). Because a widget can host
808 an eventual Prima::Popup object, it contains "get_default_popup_font()"
809 method, that returns the default font for the popup objects. The
810 dynamic popup font settings governed, naturally, by the "::popupFont"
811 property. Prima::Window extends the functionality to
812 "get_default_menu_font()" and the "::menuFont" property.
813 Dynamic change of the font property results in the "FontChanged"
815 notification.
816
818 The resources, operated via Prima::Widget class but not that strictly
819 bound to the widget concept, are gathered in this section. The section
820 includes overview of pointer, cursor, hint, menu objects and user-
821 specified resources.
822 Pointer
824 The mouse pointer is the shared resource, that can change its visual
825 representation when it hovers over different kinds of widgets. It is
826 usually a good practice for a text field, for example, set the pointer
827 icon to a jagged vertical line, or indicate a moving window with a
828 cross-arrowed pointer.
829 A widget can select either one of the predefined system pointers,
831 mapped by the "cr::XXX" constant set, or supply its own pointer icon of
832 an arbitrary size and color depth.
833 NB: Not all systems allow the colored pointer icons. System value under
835 sv::ColorPointer index containing a boolean value, whether the colored
836 icons are allowed or not.
837 In general, the "::pointer" property is enough for these actions. It
839 discerns whether it has an icon or a constant passed, and sets the
840 appropriate properties. These properties are also accessible
841 separately, although their usage is not encouraged, primarily because
842 of the tangled relationship between them. These properties are:
843 "::pointerType", "::pointerIcon", and "::pointerHotSpot". See their
844 details in the "API" sections.
845 Another property, which is present only in Prima::Application name
847 space is called "::pointerVisible", and governs the visibility of the
848 pointer - but for all widget instances at once.
849 Cursor
851 The cursor is a blinking rectangular area, indicating the availability
852 of the input focus in a widget. There can be only one active cursor per
853 a GUI space, or none at all. Prima::Widget provides several cursor
854 properties: "::cursorVisible", "::cursorPos", and "::cursorSize". There
855 are also two methods, "show_cursor()" and "hide_cursor()", which are
856 not the convenience shortcuts but the functions accounting the cursor
857 hide count. If "hide_cursor()" was called three times, then
858 "show_cursor()" must be called three times as well for the cursor to
859 become visible.
860 Hint
862 "::hint" is a text string, that usually describes the widget's purpose
863 to the user in a brief manner. If the mouse pointer is hovered over the
864 widget longer than some timeout ( see Prima::Application::hintPause ),
865 then a label appears with the hint text, until the pointer is drawn
866 away. The hint behavior is governed by Prima::Application, but a
867 widget can do two additional things about hint: it can enable and
868 disable it by calling "::showHint" property, and it can inherit the
869 owner's "::hint" and "::showHint" properties using "::ownerHint" and
870 "::ownerShowHint" properties. If, for example, "::ownerHint" is set to
871 1, then "::hint" value is automatically copied from the widget's owner,
872 when it changes. If, however, the widget's "::hint" or "::showHint" are
873 explicitly set, the owner link breaks automatically by setting
874 "::ownerHint" or "::ownerShowHint" to 0.
875 The widget can also operate the "::hintVisible" property, that shows or
877 hides the hint label immediately, if the mouse pointer is inside the
878 widget's boundaries.
879 Menu objects
881 The default functionality of Prima::Widget coexists with two kinds of
882 the Prima::AbstractMenu descendants - Prima::AccelTable and
883 Prima::Popup ( Prima::Window is also equipped with Prima::Menu
884 reference). The "::items" property of these objects are accessible
885 through "::accelItems" and "::popupItems", whereas the objects
886 themselves - through "::accelTable" and "::popup", correspondingly. As
887 mentioned in "User input", these objects hook the user keyboard input
888 and call the programmer-defined callback subroutine if the key stroke
889 equals to one of their table values. As for "::accelTable", its
890 function ends here. "::popup" provides access to a context pop-up menu,
891 which can be invoked by either right-clicking or pressing a system-
892 dependent key combination. As a little customization, the
893 "::popupColorIndex" and "::popupFont" properties are introduced. (
894 "::popupColorIndex" is multiplexed to "::popupColor",
895 "::popupHiliteColor", "::popupHiliteBackColor", etc etc properties
896 exactly like the "::colorIndex" property ).
897 The font and color of a menu object might not always be writable
899 (Win32).
900 The Prima::Window class provides equivalent methods for the menu bar,
902 introducing "::menu", "::menuItems", "::menuColorIndex" ( with
903 multiplexing ) and "::menuFont" properties.
904 User-specified resources
906 It is considered a good idea to incorporate the user preferences into
907 the toolkit look-and-feel. Prima::Widget relies to the system-specific
908 code that tries to map these preferences as close as possible to the
909 toolkit paradigm.
910 Unix version employs XRDB ( X resource database ), which is the natural
912 way for the user to tell the preferences with fine granularity. Win32
913 reads the setting that the user has to set interactively, using system
914 tools. Nevertheless, the toolkit can not emulate all user settings that
915 are available on the supported platforms; it rather takes a 'least
916 common denominator', which is colors and fonts. "fetch_resource()"
917 method is capable of returning any of such settings, provided it's
918 format is font, color or a string. The method is rarely called
919 directly.
920 The appealing idea of making every widget property adjustable via the
922 user-specified resources is not implemented in full. It can be
923 accomplished up to a certain degree using "fetch_resource()" existing
924 functionality, but it is believed that calling up the method for the
925 every property for the every widget created is prohibitively expensive.
926
928 Properties
929 accelItems [ ITEM_LIST ]
930 Manages items of a Prima::AccelTable object associated with a
931 widget. The ITEM_LIST format is same as
932 "Prima::AbstractMenu::items" and is described in Prima::Menu.
933 See also: "accelTable"
935 accelTable OBJECT
937 Manages a Prima::AccelTable object associated with a widget. The
938 sole purpose of the accelTable object is to provide convenience
939 mapping of key combinations to anonymous subroutines. Instead of
940 writing an interface specifically for Prima::Widget, the existing
941 interface of Prima::AbstractMenu was taken.
942 The accelTable object can be destroyed safely; its cancellation can
944 be done either via "accelTable(undef)" or "destroy()" call.
945 Default value: undef
947 See also: "accelItems"
949 autoEnableChildren BOOLEAN
951 If TRUE, all immediate children widgets maintain the same "enabled"
952 state as the widget. This property is useful for the group-like
953 widgets ( ComboBox, SpinEdit etc ), that employ their children for
954 visual representation.
955 Default value: 0
957 backColor COLOR
959 In widget paint state, reflects background color in the graphic
960 context. In widget normal state, manages the basic background
961 color. If changed, initiates "ColorChanged" notification and
962 repaints the widget.
963 See also: "color", "colorIndex", "ColorChanged"
965 bottom INTEGER
967 Maintains the lower boundary of a widget. If changed, does not
968 affect the widget height; but does so, if called in "set()"
969 together with "::top".
970 See also: "left", "right", "top", "origin", "rect", "growMode",
972 "Move"
973 briefKeys BOOLEAN
975 If 1, contracts the repetitive key press events into one
976 notification, increasing REPEAT parameter of "KeyDown" callbacks.
977 If 0, REPEAT parameter is always 1.
978 Default value: 1
980 See also: "KeyDown"
982 buffered BOOLEAN
984 If 1, a widget "Paint" callback draws not on the screen, but on the
985 off-screen memory instead. The memory content is copied to the
986 screen then. Used when complex drawing methods are used, or if
987 output smoothness is desired.
988 This behavior can not be always granted, however. If there is not
990 enough memory, then widget draws in the usual manner.
991 Default value: 0
993 See also: "Paint"
995 capture BOOLEAN, CLIP_OBJECT = undef
997 Manipulates capturing of the mouse events. If 1, the mouse events
998 are not passed to the widget the mouse pointer is over, but are
999 redirected to the caller widget. The call for capture might not be
1000 always granted due the race conditions between programs.
1001 If CLIP_OBJECT widget is defined in set-mode call, the pointer
1003 movements are confined to CLIP_OBJECT inferior.
1004 See also: "MouseDown", "MouseUp", "MouseMove", "MouseWheel",
1006 "MouseClick".
1007 centered BOOLEAN
1009 A write-only property. Once set, widget is centered by X and Y axis
1010 relative to its owner.
1011 See also: "x_centered", "y_centered", "growMode", "origin", "Move".
1013 clipChildren BOOLEAN
1015 Affects the drawing mode when children widgets are present and
1016 obscuring the drawing area. If set, the children widgets are
1017 automatically added to the clipping area, and drawing over them
1018 will not happen. If unset, the painting can be done over the
1019 children widgets.
1020 Default: 1
1022 clipOwner BOOLEAN
1024 If 1, a widget is clipped by its owner boundaries. It is the
1025 default and expected behavior. If clipOwner is 0, a widget behaves
1026 differently: it does not clipped by the owner, it is not moved
1027 together with the parent, the origin offset is calculated not from
1028 the owner's coordinates but from the screen, and mouse events in a
1029 widget do not transgress to the top-level window decorations. In
1030 short, it itself becomes a top-level window, that, contrary to the
1031 one created from Prima::Window class, does not have any
1032 interference with system-dependent window stacking and positioning
1033 ( and any other ) policy, and is not ornamented by the window
1034 manager decorations.
1035 Default value: 1
1037 See "Parent-child relationship"
1039 See also: "Prima::Object" owner section, "parentHandle"
1041 color COLOR
1043 In widget paint state, reflects foreground color in the graphic
1044 context. In widget normal state, manages the basic foreground
1045 color. If changed, initiates "ColorChanged" notification and
1046 repaints the widget.
1047 See also: "backColor", "colorIndex", "ColorChanged"
1049 colorIndex INDEX, COLOR
1051 Manages the basic color properties indirectly, by accessing via
1052 "ci::XXX" constant. Is a complete alias for "::color",
1053 "::backColor", "::hiliteColor", "::hiliteBackColor",
1054 "::disabledColor", "::disabledBackColor", "::light3DColor", and
1055 "::dark3DColor" properties. The "ci::XXX" constants are:
1056 ci::NormalText or ci::Fore
1058 ci::Normal or ci::Back
1059 ci::HiliteText
1060 ci::Hilite
1061 ci::DisabledText
1062 ci::Disabled
1063 ci::Light3DColor
1064 ci::Dark3DColor
1065 The non-RGB "cl::" constants, specific to the Prima::Widget color
1067 usage are identical to their "ci::" counterparts:
1068 cl::NormalText or cl::Fore
1070 cl::Normal or cl::Back
1071 cl::HiliteText
1072 cl::Hilite
1073 cl::DisabledText
1074 cl::Disabled
1075 cl::Light3DColor
1076 cl::Dark3DColor
1077 See also: "color", "backColor", "ColorChanged"
1079 current BOOLEAN
1081 If 1, a widget (or one of its children) is marked as the one to be
1082 focused ( or selected) when the owner widget receives "select()"
1083 call. Within children widgets, only one or none at all can be
1084 marked as a current.
1085 See also: "currentWidget", "selectable", "selected",
1087 "selectedWidget", "focused"
1088 currentWidget OBJECT
1090 Points to a children widget, that is to be focused ( or selected)
1091 when the owner widget receives "select()" call.
1092 See also: "current", "selectable", "selected", "selectedWidget",
1094 "focused"
1095 cursorPos X_OFFSET Y_OFFSET
1097 Specifies the lower left corner of the cursor
1098 See also: "cursorSize", "cursorVisible"
1100 cursorSize WIDTH HEIGHT
1102 Specifies width and height of the cursor
1103 See also: "cursorPos", "cursorVisible"
1105 cursorVisible BOOLEAN
1107 Specifies cursor visibility flag. Default value is 0.
1108 See also: "cursorSize", "cursorPos"
1110 dark3DColor COLOR
1112 The color used to draw dark shades.
1113 See also: "light3DColor", "colorIndex", "ColorChanged"
1115 designScale X_SCALE Y_SCALE
1117 The width and height of a font, that was used when a widget (
1118 usually a dialog or a grouping widget ) was designed.
1119 See also: "scaleChildren", "width", "height", "size", "font"
1121 disabledBackColor COLOR
1123 The color used to substitute "::backColor" when a widget is in its
1124 disabled state.
1125 See also: "disabledColor", "colorIndex", "ColorChanged"
1127 disabledColor COLOR
1129 The color used to substitute "::color" when a widget is in its
1130 disabled state.
1131 See also: "disabledBackColor", "colorIndex", "ColorChanged"
1133 enabled BOOLEAN
1135 Specifies if a widget can accept focus, keyboard and mouse events.
1136 Default value is 1, however, being 'enabled' does not automatically
1137 allow the widget become focused. Only the reverse is true - if
1138 enabled is 0, focusing can never happen.
1139 See also: "responsive", "visible", "Enable", "Disable"
1141 font %FONT
1143 Manages font context. Same syntax as in Prima::Drawable. If
1144 changed, initiates "FontChanged" notification and repaints the
1145 widget.
1146 See also: "designScale", "FontChanged", "ColorChanged"
1148 geometry INTEGER
1150 Selects one of the available geometry managers. The corresponding
1151 integer constants are:
1152 gt::GrowMode, gt::Default - the default grow-mode algorithm
1154 gt::Pack - Tk packer
1155 gt::Place - Tk placer
1156 See "growMode", Prima::Widget::pack, Prima::Widget::place.
1158 growMode MODE
1160 Specifies widget behavior, when its owner is resized or moved.
1161 MODE can be 0 ( default ) or a combination of the following
1162 constants:
1163 Basic constants
1165 gm::GrowLoX widget's left side is kept in constant
1166 distance from owner's right side
1167 gm::GrowLoY widget's bottom side is kept in constant
1168 distance from owner's top side
1169 gm::GrowHiX widget's right side is kept in constant
1170 distance from owner's right side
1171 gm::GrowHiY widget's top side is kept in constant
1172 distance from owner's top side
1173 gm::XCenter widget is kept in center on its owner's
1174 horizontal axis
1175 gm::YCenter widget is kept in center on its owner's
1176 vertical axis
1177 gm::DontCare widgets origin is maintained constant relative
1178 to the screen
1179 Derived or aliased constants
1181 gm::GrowAll gm::GrowLoX|gm::GrowLoY|gm::GrowHiX|gm::GrowHiY
1182 gm::Center gm::XCenter|gm::YCenter
1183 gm::Client gm::GrowHiX|gm::GrowHiY
1184 gm::Right gm::GrowLoX|gm::GrowHiY
1185 gm::Left gm::GrowHiY
1186 gm::Floor gm::GrowHiX
1187 See also: "Move", "origin"
1189 firstClick BOOLEAN
1191 If 0, a widget bypasses first mouse click on it, if the top-level
1192 window it belongs to was not activated, so selecting such a widget
1193 it takes two mouse clicks.
1194 Default value is 1
1196 See also: "MouseDown", "selectable", "selected", "focused",
1198 "selectingButtons"
1199 focused BOOLEAN
1201 Specifies whether a widget possesses the input focus or not.
1202 Disregards "::selectable" property on set-call.
1203 See also: "selectable", "selected", "selectedWidget", "KeyDown"
1205 geomWidth, geomHeight, geomSize
1207 Three properties that select geometry request size. Writing and
1208 reading to "::geomWidth" and "::geomHeight" is equivalent to
1209 "::geomSize". The properies are run-time only, and behave
1210 differently under different circumstances:
1211 · As the properties are run-time only, they can not be set in the
1213 profile, and their initial value is fetched from "::size"
1214 property. Thus, setting the explicit size is aditionally sets
1215 the advised size in case the widget is to be used with the Tk
1216 geometry managers.
1217 · Setting the properties under the "gt::GrowMode" geometry
1219 manager also sets the corresponding "::width", "::height", or
1220 "::size". When the properties are read, though, the real size
1221 properties are not read; the values are kept separately.
1222 · Setting the properties under Tk geometry managers cause widgets
1224 size and position changed according to the geometry manager
1225 policy.
1226 height
1228 Maintains the height of a widget.
1229 See also: "width", "growMode", "Move", "Size", "get_virtual_size",
1231 "sizeMax", "sizeMin"
1232 helpContext STRING
1234 A string that binds a widget, a logical part it plays with the
1235 application and an interactive help topic. STRING format is defined
1236 as POD link ( see perlpod ) - "manpage/section", where 'manpage' is
1237 the file with POD content and 'section' is the topic inside the
1238 manpage.
1239 See also: "help"
1241 hiliteBackColor COLOR
1243 The color used to draw alternate background areas with high
1244 contrast.
1245 See also: "hiliteColor", "colorIndex", "ColorChanged"
1247 hiliteColor COLOR
1249 The color used to draw alternate foreground areas with high
1250 contrast.
1251 See also: "hiliteBackColor", "colorIndex", "ColorChanged"
1253 hint TEXT
1255 A text, shown under mouse pointer if it is hovered over a widget
1256 longer than "Prima::Application::hintPause" timeout. The text shows
1257 only if the "::showHint" is 1.
1258 See also: "hintVisible", "showHint", "ownerHint", "ownerShowHint"
1260 hintVisible BOOLEAN
1262 If called in get-form, returns whether the hint label is shown or
1263 not. If in set-form, immediately turns on or off the hint label,
1264 disregarding the timeouts. It does regard the mouse pointer
1265 location, however, and does not turn on the hint label if the
1266 pointer is away.
1267 See also: "hint", "showHint", "ownerHint", "ownerShowHint"
1269 layered BOOLEAN
1271 If set, the widget will try to use alpha transparency available on
1272 the system. See "Layering" in Prima::Image for more details.
1273 Default: false
1275 See also: "is_surface_layered"
1277 Note: In Windows, mouse events will not be delivered to the layered
1279 widget if the pixel under the mouse pointer is fully transparent.
1280 In X11, you need to run a composition manager, f.ex. compiz or
1282 xcompmgr.
1283 left INTEGER
1285 Maintains the left boundary of a widget. If changed, does not
1286 affect the widget width; but does so, if called in "set()" together
1287 with "::right".
1288 See also: "bottom", "right", "top", "origin", "rect", "growMode",
1290 "Move"
1291 light3DColor COLOR
1293 The color used to draw light shades.
1294 See also: "dark3DColor", "colorIndex", "ColorChanged"
1296 ownerBackColor BOOLEAN
1298 If 1, the background color is synchronized with the owner's.
1299 Automatically set to 0 if "::backColor" property is explicitly set.
1300 See also: "ownerColor", "backColor", "colorIndex"
1302 ownerColor BOOLEAN
1304 If 1, the foreground color is synchronized with the owner's.
1305 Automatically set to 0 if "::color" property is explicitly set.
1306 See also: "ownerBackColor", "color", "colorIndex"
1308 ownerFont BOOLEAN
1310 If 1, the font is synchronized with the owner's. Automatically set
1311 to 0 if "::font" property is explicitly set.
1312 See also: "font", "FontChanged"
1314 ownerHint BOOLEAN
1316 If 1, the hint is synchronized with the owner's. Automatically set
1317 to 0 if "::hint" property is explicitly set.
1318 See also: "hint", "showHint", "hintVisible", "ownerShowHint"
1320 ownerShowHint BOOLEAN
1322 If 1, the show hint flag is synchronized with the owner's.
1323 Automatically set to 0 if "::showHint" property is explicitly set.
1324 See also: "hint", "showHint", "hintVisible", "ownerHint"
1326 ownerPalette BOOLEAN
1328 If 1, the palette array is synchronized with the owner's.
1329 Automatically set to 0 if "::palette" property is explicitly set.
1330 See also: "palette"
1332 origin X Y
1334 Maintains the left and bottom boundaries of a widget relative to
1335 its owner ( or to the screen if "::clipOwner" is set to 0 ).
1336 See also: "bottom", "right", "top", "left", "rect", "growMode",
1338 "Move"
1339 packInfo %OPTIONS
1341 See Prima::Widget::pack
1342 palette [ @PALETTE ]
1344 Specifies array of colors, that are desired to be present into the
1345 system palette, as close to the PALETTE as possible. This property
1346 works only if the graphic device allows palette operations. See
1347 "palette" in Prima::Drawable.
1348 See also: "ownerPalette"
1350 parentHandle SYSTEM_WINDOW
1352 If SYSTEM_WINDOW is a valid system-dependent window handle, then a
1353 widget becomes the child of the window specified, given the
1354 widget's "::clipOwner" is 0. The parent window can belong to
1355 another application.
1356 Default value is undef.
1358 See also: "clipOwner"
1360 placeInfo %OPTIONS
1362 See Prima::Widget::place
1363 pointer cr::XXX or ICON
1365 Specifies the pointer icon; discerns between "cr::XXX" constants
1366 and an icon. If an icon contains a hash variable "__pointerHotSpot"
1367 with an array of two integers, these integers will be treated as
1368 the pointer hot spot. In get-mode call, this variable is
1369 automatically assigned to an icon, if the result is an icon object.
1370 See also: "pointerHotSpot", "pointerIcon", "pointerType"
1372 pointerHotSpot X_OFFSET Y_OFFSET
1374 Specifies the hot spot coordinates of a pointer icon, associated
1375 with a widget.
1376 See also: "pointer", "pointerIcon", "pointerType"
1378 pointerIcon ICON
1380 Specifies the pointer icon, associated with a widget.
1381 See also: "pointerHotSpot", "pointer", "pointerType"
1383 pointerPos X_OFFSET Y_OFFSET
1385 Specifies the mouse pointer coordinates relative to widget's
1386 coordinates.
1387 See also: "get_mouse_state", "screen_to_client", "client_to_screen"
1389 pointerType TYPE
1391 Specifies the type of the pointer, associated with the widget.
1392 TYPE can accept one constant of "cr::XXX" set:
1393 cr::Default same pointer type as owner's
1395 cr::Arrow arrow pointer
1396 cr::Text text entry cursor-like pointer
1397 cr::Wait hourglass
1398 cr::Size general size action pointer
1399 cr::Move general move action pointer
1400 cr::SizeWest, cr::SizeW right-move action pointer
1401 cr::SizeEast, cr::SizeE left-move action pointer
1402 cr::SizeWE general horizontal-move action pointer
1403 cr::SizeNorth, cr::SizeN up-move action pointer
1404 cr::SizeSouth, cr::SizeS down-move action pointer
1405 cr::SizeNS general vertical-move action pointer
1406 cr::SizeNW up-right move action pointer
1407 cr::SizeSE down-left move action pointer
1408 cr::SizeNE up-left move action pointer
1409 cr::SizeSW down-right move action pointer
1410 cr::Invalid invalid action pointer
1411 cr::User user-defined icon
1412 All constants except "cr::User" and "cr::Default" present a system-
1414 defined pointers, their icons and hot spot offsets. "cr::User" is a
1415 sign that an icon object was specified explicitly via
1416 "::pointerIcon" property. "cr::Default" is a way to tell that a
1417 widget inherits its owner pointer type, no matter is it a system-
1418 defined pointer or a custom icon.
1419 See also: "pointerHotSpot", "pointerIcon", "pointer"
1421 popup OBJECT
1423 Manages a Prima::Popup object associated with a widget. The
1424 purpose of the popup object is to show a context menu when the user
1425 right-clicks or selects the corresponding keyboard combination.
1426 Prima::Widget can host many children objects, Prima::Popup as well.
1427 But only the one that is set in "::popup" property will be
1428 activated automatically.
1429 The popup object can be destroyed safely; its cancellation can be
1431 done either via "popup(undef)" or "destroy()" call.
1432 See also: "Prima::Menu", "Popup", "Menu", "popupItems",
1434 "popupColorIndex", "popupFont"
1435 popupColorIndex INDEX, COLOR
1437 Maintains eight color properties of a pop-up context menu,
1438 associated with a widget. INDEX must be one of "ci::XXX" constants
1439 ( see "::colorIndex" property ).
1440 See also: "popupItems", "popupFont", "popup"
1442 popupColor COLOR
1444 Basic foreground in a popup context menu color.
1445 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1447 popupBackColor COLOR
1449 Basic background in a popup context menu color.
1450 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1452 popupDark3DColor COLOR
1454 Color for drawing dark shadings in a popup context menu.
1455 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1457 popupDisabledColor COLOR
1459 Foreground color for disabled items in a popup context menu.
1460 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1462 popupDisabledBackColor COLOR
1464 Background color for disabled items in a popup context menu.
1465 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1467 popupFont %FONT
1469 Maintains the font of a pop-up context menu, associated with a
1470 widget.
1471 See also: "popupItems", "popupColorIndex", "popup"
1473 popupHiliteColor COLOR
1475 Foreground color for selected items in a popup context menu.
1476 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1478 popupHiliteBackColor COLOR
1480 Background color for selected items in a popup context menu.
1481 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1483 popupItems [ ITEM_LIST ]
1485 Manages items of a Prima::Popup object associated with a widget.
1486 The ITEM_LIST format is same as "Prima::AbstractMenu::items" and is
1487 described in Prima::Menu.
1488 See also: "popup", "popupColorIndex", "popupFont"
1490 popupLight3DColor COLOR
1492 Color for drawing light shadings in a popup context menu.
1493 See also: "popupItems", "popupColorIndex", "popupFont", "popup"
1495 rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET Y_TOP_OFFSET
1497 Maintains the rectangular boundaries of a widget relative to its
1498 owner ( or to the screen if "::clipOwner" is set to 0 ).
1499 See also: "bottom", "right", "top", "left", "origin", "width",
1501 "height", "size" "growMode", "Move", "Size", "get_virtual_size",
1502 "sizeMax", "sizeMin"
1503 right INTEGER
1505 Maintains the right boundary of a widget. If changed, does not
1506 affect the widget width; but does so, if called in "set()" together
1507 with "::left".
1508 See also: "left", "bottom", "top", "origin", "rect", "growMode",
1510 "Move"
1511 scaleChildren BOOLEAN
1513 If a widget has "::scaleChildren" set to 1, then the newly-created
1514 children widgets inserted in it will be scaled corresponding to the
1515 owner's "::designScale", given that widget's "::designScale" is not
1516 "undef" and the owner's is not [0,0].
1517 Default is 1.
1519 See also: "designScale"
1521 selectable BOOLEAN
1523 If 1, a widget can be granted focus implicitly, or by means of the
1524 user actions. "select()" regards this property, and does not focus
1525 a widget that has "::selectable" set to 0.
1526 Default value is 0
1528 See also: "current", "currentWidget", "selected", "selectedWidget",
1530 "focused"
1531 selected BOOLEAN
1533 If called in get-mode, returns whether a widget or one of its
1534 (grand-) children is focused. If in set-mode, either simply turns
1535 the system with no-focus state ( if 0 ), or sends input focus to
1536 itself or one of the widgets tracked down by "::currentWidget"
1537 chain.
1538 See also: "current", "currentWidget", "selectable",
1540 "selectedWidget", "focused"
1541 selectedWidget OBJECT
1543 Points to a child widget, that has property "::selected" set to 1.
1544 See also: "current", "currentWidget", "selectable", "selected",
1546 "focused"
1547 selectingButtons FLAGS
1549 FLAGS is a combination of "mb::XXX" ( mouse button ) flags. If a
1550 widget receives a click with a mouse button, that has the
1551 corresponding bit set in "::selectingButtons", then "select()" is
1552 called.
1553 See also: "MouseDown", "firstClick", "selectable", "selected",
1555 "focused"
1556 shape REGION
1558 Maintains the non-rectangular shape of a widget. When setting,
1559 REGION is either a Prima::Image object, with 0 bits treated as
1560 transparent pixels, and 1 bits as opaque pixels, or a Prima::Region
1561 object. When getting, it is either undef or a Prima::Region
1562 object.
1563 Successive only if "sv::ShapeExtension" value is true.
1565 showHint BOOLEAN
1567 If 1, the toolkit is allowed to show the hint label over a widget.
1568 If 0, the display of the hint is forbidden. The "::hint" property
1569 must contain non-empty string as well, if the hint label must be
1570 shown.
1571 Default value is 1.
1573 See also: "hint", "ownerShowHint", "hintVisible", "ownerHint"
1575 size WIDTH HEIGHT
1577 Maintains the width and height of a widget.
1578 See also: "width", "height" "growMode", "Move", "Size",
1580 "get_virtual_size", "sizeMax", "sizeMin"
1581 sizeMax WIDTH HEIGHT
1583 Specifies the maximal size for a widget that it is allowed to
1584 accept.
1585 See also: "width", "height", "size" "growMode", "Move", "Size",
1587 "get_virtual_size", "sizeMin"
1588 sizeMin WIDTH HEIGHT
1590 Specifies the minimal size for a widget that it is allowed to
1591 accept.
1592 See also: "width", "height", "size" "growMode", "Move", "Size",
1594 "get_virtual_size", "sizeMax"
1595 syncPaint BOOLEAN
1597 If 0, the "Paint" request notifications are stacked until the event
1598 loop is called. If 1, every time the widget surface gets
1599 invalidated, the "Paint" notification is called.
1600 Default value is 0.
1602 See also: "invalidate_rect", "repaint", "validate_rect", "Paint"
1604 tabOrder INTEGER
1606 Maintains the order in which tab- and shift-tab- key navigation
1607 algorithms select the sibling widgets. INTEGER is unique among the
1608 sibling widgets. In set mode, if INTEGER value is already taken,
1609 the occupier is assigned another unique value, but without
1610 destruction of a queue - widgets with ::tabOrder greater than of
1611 the widget, receive their new values too. Special value -1 is
1612 accepted as 'the end of list' indicator; the negative value is
1613 never returned.
1614 See also: "tabStop", "next_tab", "selectable", "selected",
1616 "focused"
1617 tabStop BOOLEAN
1619 Specifies whether a widget is interested in tab- and shift-tab- key
1620 navigation or not.
1621 Default value is 1.
1623 See also: "tabOrder", "next_tab", "selectable", "selected",
1625 "focused"
1626 text TEXT
1628 A text string for generic purpose. Many Prima::Widget descendants
1629 use this property heavily - buttons, labels, input lines etc, but
1630 Prima::Widget itself does not.
1631 top INTEGER
1633 Maintains the upper boundary of a widget. If changed, does not
1634 affect the widget height; but does so, if called in "set()"
1635 together with "::bottom".
1636 See also: "left", "right", "bottom", "origin", "rect", "growMode",
1638 "Move"
1639 transparent BOOLEAN
1641 Specifies whether the background of a widget before it starts
1642 painting is of any importance. If 1, a widget can gain certain
1643 transparency look if it does not clear the background during
1644 "Paint" event.
1645 Default value is 0
1647 See also: "Paint", "buffered".
1649 visible BOOLEAN
1651 Specifies whether a widget is visible or not. See "Visibility".
1652 See also: "Show", "Hide", "showing", "exposed"
1654 widgetClass CLASS
1656 Maintains the integer value, designating the color class that is
1657 defined by the system and is associated with Prima::Widget eight
1658 basic color properties. CLASS can be one of "wc::XXX" constants:
1659 wc::Undef
1661 wc::Button
1662 wc::CheckBox
1663 wc::Combo
1664 wc::Dialog
1665 wc::Edit
1666 wc::InputLine
1667 wc::Label
1668 wc::ListBox
1669 wc::Menu
1670 wc::Popup
1671 wc::Radio
1672 wc::ScrollBar
1673 wc::Slider
1674 wc::Widget or wc::Custom
1675 wc::Window
1676 wc::Application
1677 These constants are not associated with the toolkit classes; any
1679 class can use any of these constants in "::widgetClass".
1680 See also: "map_color", "colorIndex"
1682 widgets @WIDGETS
1684 In get-mode, returns list of immediate children widgets (identical
1685 to "get_widgets"). In set-mode accepts set of widget profiles, as
1686 "insert" does, as a list or an array. This way it is possible to
1687 create widget hierarchy in a single call.
1688 width WIDTH
1690 Maintains the width of a widget.
1691 See also: "height" "growMode", "Move", "Size", "get_virtual_size",
1693 "sizeMax", "sizeMin"
1694 x_centered BOOLEAN
1696 A write-only property. Once set, widget is centered by the
1697 horizontal axis relative to its owner.
1698 See also: "centered", "y_centered", "growMode", "origin", "Move".
1700 y_centered BOOLEAN
1702 A write-only property. Once set, widget is centered by the vertical
1703 axis relative to its owner.
1704 See also: "x_centered", "centered", "growMode", "origin", "Move".
1706 Methods
1708 bring_to_front
1709 Sends a widget on top of all other siblings widgets
1710 See also: "insert_behind", "send_to_back", "ZOrderChanged"
1712 ,"first", "next", "prev", "last"
1713 can_close
1715 Sends "Close" message, and returns its boolean exit state.
1716 See also: "Close", "close"
1718 client_to_screen @OFFSETS
1720 Maps array of X and Y integer offsets from widget to screen
1721 coordinates. Returns the mapped OFFSETS.
1722 See also: "screen_to_client", "clipOwner"
1724 close
1726 Calls "can_close()", and if successful, destroys a widget. Returns
1727 the "can_close()" result.
1728 See also: "can_close", "Close"
1730 defocus
1732 Alias for focused(0) call
1733 See also: "focus", "focused", "Enter", "Leave"
1735 deselect
1737 Alias for selected(0) call
1738 See also: "select", "selected", "Enter", "Leave"
1740 exposed
1742 Returns a boolean value, indicating whether a widget is at least
1743 partly visible on the screen. Never returns 1 if a widget has
1744 "::visible" set to 0.
1745 See also: "visible", "showing", "Show", "Hide"
1747 fetch_resource CLASS_NAME, NAME, CLASS_RESOURCE, RESOURCE, OWNER,
1749 RESOURCE_TYPE = fr::String
1750 Returns a system-defined scalar of resource, defined by the widget
1751 hierarchy, its class, name and owner. RESOURCE_TYPE can be one of
1752 type qualificators:
1753 fr::Color - color resource
1755 fr::Font - font resource
1756 fs::String - text string resource
1757 Such a number of the parameters is used because the method can be
1759 called before a widget is created. CLASS_NAME is widget class
1760 string, NAME is widget name. CLASS_RESOURCE is class of resource,
1761 and RESOURCE is the resource name.
1762 For example, resources 'color' and 'disabledColor' belong to the
1764 resource class 'Foreground'.
1765 first
1767 Returns the first ( from bottom ) sibling widget in Z-order.
1768 See also: "last", "next", "prev"
1770 focus
1772 Alias for focused(1) call
1773 See also: "defocus", "focused", "Enter", "Leave"
1775 hide
1777 Sets widget "::visible" to 0.
1778 See also: "hide", "visible", "Show", "Hide", "showing", "exposed"
1780 hide_cursor
1782 Hides the cursor. As many times "hide_cursor()" was called, as many
1783 time its counterpart "show_cursor()" must be called to reach the
1784 cursor's initial state.
1785 See also: "show_cursor", "cursorVisible"
1787 help
1789 Starts an interactive help viewer opened on "::helpContext" string
1790 value.
1791 The string value is combined from the widget's owner
1793 "::helpContext" strings if the latter is empty or begins with a
1794 slash. A special meaning is assigned to an empty string " " - the
1795 help() call fails when such value is found to be the section
1796 component. This feature can be useful when a window or a dialog
1797 presents a standalone functionality in a separate module, and the
1798 documentation is related more to the module than to an embedding
1799 program. In such case, the grouping widget holds "::helpContext" as
1800 a pod manpage name with a trailing slash, and its children widgets
1801 are assigned "::helpContext" to the topics without the manpage but
1802 the leading slash instead. If the grouping widget has an empty
1803 string " " as "::helpContext" then the help is forced to be
1804 unavailable for all the children widgets.
1805 See also: "helpContext"
1807 insert CLASS, %PROFILE [[ CLASS, %PROFILE], ... ]
1809 Creates one or more widgets with "owner" property set to the caller
1810 widget, and returns the list of references to the newly created
1811 widgets.
1812 Has two calling formats:
1814 Single widget
1816 $parent-> insert( 'Child::Class',
1817 name => 'child',
1818 ....
1819 );
1820 Multiple widgets
1822 $parent-> insert(
1823 [
1824 'Child::Class1',
1825 name => 'child1',
1826 ....
1827 ],
1828 [
1829 'Child::Class2',
1830 name => 'child2',
1831 ....
1832 ],
1833 );
1834 insert_behind OBJECT
1836 Sends a widget behind the OBJECT on Z-axis, given that the OBJECT
1837 is a sibling to the widget.
1838 See also: "bring_to_front", "send_to_back", "ZOrderChanged"
1840 ,"first", "next", "prev", "last"
1841 invalidate_rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET
1843 Y_TOP_OFFSET
1844 Marks the rectangular area of a widget as 'invalid', so re-painting
1845 of the area happens. See "Graphic content".
1846 See also: "validate_rect", "get_invalid_rect", "repaint", "Paint",
1848 "syncPaint", "update_view"
1849 is_surface_layered
1851 Returns true if both the widget and it's top-most parent are
1852 layered. If the widget itself is top-most, i.e. a window, a non-
1853 clipOwner widget, or a child to application, then is the same as
1854 "layered".
1855 See also: layered
1857 key_down CODE, KEY = kb::NoKey, MOD = 0, REPEAT = 1, POST = 0
1859 The method sends or posts ( POST flag ) simulated "KeyDown" event
1860 to the system. CODE, KEY, MOD and REPEAT are the parameters to be
1861 passed to the notification callbacks.
1862 See also: "key_up", "key_event", "KeyDown"
1864 key_event COMMAND, CODE, KEY = kb::NoKey, MOD = 0, REPEAT = 1, POST = 0
1866 The method sends or posts ( POST flag ) simulated keyboard event to
1867 the system. CODE, KEY, MOD and REPEAT are the parameters to be
1868 passed to an eventual "KeyDown" or "KeyUp" notifications. COMMAND
1869 is allowed to be either "cm::KeyDown" or "cm::KeyUp".
1870 See also: "key_down", "key_up", "KeyDown", "KeyUp"
1872 key_up CODE, KEY = kb::NoKey, MOD = 0, POST = 0
1874 The method sends or posts ( POST flag ) simulated "KeyUp" event to
1875 the system. CODE, KEY and MOD are the parameters to be passed to
1876 the notification callbacks.
1877 See also: "key_down", "key_event", "KeyUp"
1879 last
1881 Returns the last ( the topmost ) sibling widget in Z-order.
1882 See also: "first", "next", "prev"
1884 lock
1886 Turns off the ability of a widget to re-paint itself. As many
1887 times "lock()" was called, as may times its counterpart, "unlock()"
1888 must be called to enable re-painting again. Returns a boolean
1889 success flag.
1890 See also: "unlock", "repaint", "Paint", "get_locked"
1892 map_color COLOR
1894 Transforms "cl::XXX" and "ci::XXX" combinations into RGB color
1895 representation and returns the result. If COLOR is already in RGB
1896 format, no changes are made.
1897 See also: "colorIndex"
1899 mouse_click BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, DBL_CLICK = 0,
1901 POST = 0
1902 The method sends or posts ( POST flag ) simulated "MouseClick"
1903 event to the system. BUTTON, MOD, X, Y, and DBL_CLICK are the
1904 parameters to be passed to the notification callbacks.
1905 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseMove",
1907 "MouseEnter", "MouseLeave"
1908 mouse_down BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, POST = 0
1910 The method sends or posts ( POST flag ) simulated "MouseDown" event
1911 to the system. BUTTON, MOD, X, and Y are the parameters to be
1912 passed to the notification callbacks.
1913 See also: "MouseUp", "MouseWheel", "MouseClick", "MouseMove",
1915 "MouseEnter", "MouseLeave"
1916 mouse_enter MOD = 0, X = 0, Y = 0, POST = 0
1918 The method sends or posts ( POST flag ) simulated "MouseEnter"
1919 event to the system. MOD, X, and Y are the parameters to be passed
1920 to the notification callbacks.
1921 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseClick",
1923 "MouseMove", "MouseLeave"
1924 mouse_event COMMAND = cm::MouseDown, BUTTON = mb::Left, MOD = 0, X = 0,
1926 Y = 0, DBL_CLICK = 0, POST = 0
1927 The method sends or posts ( POST flag ) simulated mouse event to
1928 the system. BUTTON, MOD, X, Y and DBL_CLICK are the parameters to
1929 be passed to an eventual mouse notifications. COMMAND is allowed
1930 to be one of "cm::MouseDown", "cm::MouseUp", "cm::MouseWheel",
1931 "cm::MouseClick", "cm::MouseMove", "cm::MouseEnter",
1932 "cm::MouseLeave" constants.
1933 See also: "mouse_down", "mouse_up", "mouse_wheel", "mouse_click",
1935 "mouse_move", "mouse_enter", "mouse_leave", "MouseDown", "MouseUp",
1936 "MouseWheel", "MouseClick", "MouseMove", "MouseEnter", "MouseLeave"
1937 mouse_leave
1939 The method sends or posts ( POST flag ) simulated "MouseLeave"
1940 event to the system.
1941 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseClick",
1943 "MouseMove", "MouseEnter", "MouseLeave"
1944 mouse_move MOD = 0, X = 0, Y = 0, POST = 0
1946 The method sends or posts ( POST flag ) simulated "MouseMove" event
1947 to the system. MOD, X, and Y are the parameters to be passed to the
1948 notification callbacks.
1949 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseClick",
1951 "MouseEnter", "MouseLeave"
1952 mouse_up BUTTON = mb::Left, MOD = 0, X = 0, Y = 0, POST = 0
1954 The method sends or posts ( POST flag ) simulated "MouseUp" event
1955 to the system. BUTTON, MOD, X, and Y are the parameters to be
1956 passed to the notification callbacks.
1957 See also: "MouseDown", "MouseWheel", "MouseClick", "MouseMove",
1959 "MouseEnter", "MouseLeave"
1960 mouse_wheel MOD = 0, X = 0, Y = 0, INCR = 0, POST = 0
1962 The method sends or posts ( POST flag ) simulated "MouseUp" event
1963 to the system. MOD, X, Y and INCR are the parameters to be passed
1964 to the notification callbacks.
1965 See also: "MouseDown", "MouseUp", "MouseClick", "MouseMove",
1967 "MouseEnter", "MouseLeave"
1968 next
1970 Returns the neighbor sibling widget, next ( above ) in Z-order. If
1971 none found, undef is returned.
1972 See also: "first", "last", "prev"
1974 next_tab FORWARD = 1
1976 Returns the next widget in the sorted by "::tabOrder" list of
1977 sibling widgets. FORWARD is a boolean lookup direction flag. If
1978 none found, the first ( or the last, depending on FORWARD flag )
1979 widget is returned. Only widgets with "::tabStop" set to 1
1980 participate.
1981 Also used by the internal keyboard navigation code.
1983 See also: "next_positional", "tabOrder", "tabStop", "selectable"
1985 next_positional DELTA_X DELTA_Y
1987 Returns a sibling, (grand-)child of a sibling or (grand-)child
1988 widget, that matched best the direction specified by DELTA_X and
1989 DELTA_Y. At one time, only one of these parameters can be zero;
1990 another parameter must be either 1 or -1.
1991 Also used by the internal keyboard navigation code.
1993 See also: "next_tab", "origin"
1995 pack, packForget, packSlaves
1997 See Prima::Widget::pack
1998 place, placeForget, placeSlaves
2000 See Prima::Widget::place
2001 prev
2003 Returns the neighbor sibling widget, previous ( below ) in Z-order.
2004 If none found, undef is returned.
2005 See also: "first", "last", "next"
2007 repaint
2009 Marks the whole widget area as 'invalid', so re-painting of the
2010 area happens. See "Graphic content".
2011 See also: "validate_rect", "get_invalid_rect", "invalidate_rect",
2013 "Paint", "update_view", "syncPaint"
2014 rect_bevel $CANVAS, @RECT, %OPTIONS
2016 Draws a rectangular area, similar to produced by "rect3d" over
2017 @RECT that is 4-integer coordinates of the area, but implicitly
2018 using widget's "light3DColor" and "dark3DColor" properties' values.
2019 The following options are recognized:
2020 fill COLOR
2022 If set, the area is filled with COLOR, ortherwise is left
2023 intact.
2024 width INTEGER
2026 Width of the border in pixels
2027 concave BOOLEAN
2029 If 1, draw a concave area, bulged otherwise
2030 responsive
2032 Returns a boolean flag, indicating whether a widget and its owners
2033 have all "::enabled" 1 or not. Useful for fast check if a widget
2034 should respond to the user actions.
2035 See also: "enabled"
2037 screen_to_client @OFFSETS
2039 Maps array of X and Y integer offsets from screen to widget
2040 coordinates. Returns the mapped OFFSETS.
2041 See also: "client_to_screen"
2043 scroll DELTA_X DELTA_Y %OPTIONS
2045 Scrolls the graphic context area by DELTA_X and DELTA_Y pixels.
2046 OPTIONS is hash, that contains optional parameters to the scrolling
2047 procedure:
2048 clipRect [X1, Y1, X2, Y2]
2050 The clipping area is confined by X1, Y1, X2, Y2 rectangular
2051 area. If not specified, the clipping area covers the whole
2052 widget. Only the bits, covered by clipRect are affected. Bits
2053 scrolled from the outside of the rectangle to the inside are
2054 painted; bits scrolled from the inside of the rectangle to the
2055 outside are not painted.
2056 confineRect [X1, Y1, X2, Y2]
2058 The scrolling area is confined by X1, Y1, X2, Y2 rectangular
2059 area. If not specified, the scrolling area covers the whole
2060 widget.
2061 withChildren BOOLEAN
2063 If 1, the scrolling performs with the eventual children widgets
2064 change their positions to DELTA_X and DELTA_Y as well.
2065 Cannot be used inside paint state.
2067 See also: "Paint", "get_invalid_rect"
2069 select
2071 Alias for selected(1) call
2072 See also: "deselect", "selected", "Enter", "Leave"
2074 send_to_back
2076 Sends a widget at bottom of all other siblings widgets
2077 See also: "insert_behind", "bring_to_front", "ZOrderChanged"
2079 ,"first", "next", "prev", "last"
2080 show
2082 Sets widget "::visible" to 1.
2083 See also: "hide", "visible", "Show", "Hide", "showing", "exposed"
2085 show_cursor
2087 Shows the cursor. As many times "hide_cursor()" was called, as many
2088 time its counterpart "show_cursor()" must be called to reach the
2089 cursor's initial state.
2090 See also: "hide_cursor", "cursorVisible"
2092 showing
2094 Returns a boolean value, indicating whether the widget and its
2095 owners have all "::visible" 1 or not.
2096 unlock
2098 Turns on the ability of a widget to re-paint itself. As many times
2099 "lock()" was called, as may times its counterpart, "unlock()" must
2100 be called to enable re-painting again. When last "unlock()" is
2101 called, an implicit "repaint()" call is made. Returns a boolean
2102 success flag.
2103 See also: "lock", "repaint", "Paint", "get_locked"
2105 update_view
2107 If any parts of a widget were marked as 'invalid' by either
2108 "invalidate_rect()" or "repaint()" calls or the exposure caused by
2109 window movements ( or any other), then "Paint" notification is
2110 immediately called. If no parts are invalid, no action is
2111 performed. If a widget has "::syncPaint" set to 1, "update_view()"
2112 is always a no-operation call.
2113 See also: "invalidate_rect", "get_invalid_rect", "repaint",
2115 "Paint", "syncPaint", "update_view"
2116 validate_rect X_LEFT_OFFSET Y_BOTTOM_OFFSET X_RIGHT_OFFSET Y_TOP_OFFSET
2118 Reverses the effect of "invalidate_rect()", restoring the original,
2119 'valid' state of widget area covered by the rectangular area
2120 passed. If a widget with previously invalid areas was wholly
2121 validated by this method, no "Paint" notifications occur.
2122 See also: "invalidate_rect", "get_invalid_rect", "repaint",
2124 "Paint", "syncPaint", "update_view"
2125 Get-methods
2127 get_default_font
2128 Returns the default font for a Prima::Widget class.
2129 See also: "font"
2131 get_default_popup_font
2133 Returns the default font for a Prima::Popup class.
2134 See also: "font"
2136 get_invalid_rect
2138 Returns the result of successive calls "invalidate_rect()",
2139 "validate_rect()" and "repaint()", as a rectangular area ( four
2140 integers ) that cover all invalid regions in a widget. If none
2141 found, (0,0,0,0) is returned.
2142 See also: "validate_rect", "invalidate_rect", "repaint", "Paint",
2144 "syncPaint", "update_view"
2145 get_handle
2147 Returns a system handle for a widget
2148 See also: "get_parent_handle", "Window::get_client_handle"
2150 get_locked
2152 Returns 1 if a widget is in "lock()" - initiated repaint-blocked
2153 state.
2154 See also: "lock", "unlock"
2156 get_mouse_state
2158 Returns a combination of "mb::XXX" constants, reflecting the
2159 currently pressed mouse buttons.
2160 See also: "pointerPos", "get_shift_state"
2162 get_parent
2164 Returns the owner widget that clips the widget boundaries, or
2165 application object if a widget is top-level.
2166 See also: "clipOwner"
2168 get_parent_handle
2170 Returns a system handle for a parent of a widget, a window that
2171 belongs to another program. Returns 0 if the widget's owner and
2172 parent are in the same application and process space.
2173 See also: "get_handle", "clipOwner"
2175 get_pointer_size
2177 Returns two integers, width and height of a icon, that the system
2178 accepts as valid for a pointer. If the icon is supplied that is
2179 more or less than these values, it is truncated or padded with
2180 transparency bits, but is not stretched. Can be called with class
2181 syntax.
2182 get_shift_state
2184 Returns a combination of "km::XXX" constants, reflecting the
2185 currently pressed keyboard modificator buttons.
2186 See also: "get_shift_state"
2188 get_virtual_size
2190 Returns virtual width and height of a widget. See "Geometry",
2191 Implicit size regulations.
2192 See also: "width", "height", "size" "growMode", "Move", "Size",
2194 "sizeMax", "sizeMin"
2195 get_widgets
2197 Returns list of children widgets.
2198 Events
2200 Change
2201 Generic notification, used for Prima::Widget descendants;
2202 Prima::Widget itself neither calls not uses the event. Designed to
2203 be called when an arbitrary major state of a widget is changed.
2204 Click
2206 Generic notification, used for Prima::Widget descendants;
2207 Prima::Widget itself neither calls not uses the event. Designed to
2208 be called when an arbitrary major action for a widget is called.
2209 Close
2211 Triggered by "can_close()" and "close()" functions. If the event
2212 flag is cleared during execution, these functions fail.
2213 See also: "close", "can_close"
2215 ColorChanged INDEX
2217 Called when one of widget's color properties is changed, either by
2218 direct property change or by the system. INDEX is one of "ci::XXX"
2219 constants.
2220 See also: "colorIndex"
2222 Disable
2224 Triggered by a successive enabled(0) call
2225 See also: "Enable", "enabled", "responsive"
2227 DragDrop X Y
2229 Design in progress. Supposed to be triggered when a drag-and-drop
2230 session started by the widget. X and Y are mouse pointer
2231 coordinates on the session start.
2232 See also: "DragOver", "EndDrag"
2234 DragOver X Y STATE
2236 Design in progress. Supposed to be called when a mouse pointer is
2237 passed over a widget during a drag-and-drop session. X and Y are
2238 mouse pointer coordinates, identical to "MouseMove" X Y parameters.
2239 STATE value is undefined.
2240 See also: "DragDrop", "EndDrag"
2242 Enable
2244 Triggered by a successive enabled(1) call
2245 See also: "Disable", "enabled", "responsive"
2247 EndDrag X Y
2249 Design in progress. Supposed to be called when a drag-and-drop
2250 session is finished successfully over a widget. X and Y are mouse
2251 pointer coordinates on the session end.
2252 See also: "DragDrop", "DragOver"
2254 Enter
2256 Called when a widget receives the input focus.
2257 See also: "Leave", "focused", "selected"
2259 FontChanged
2261 Called when a widget font is changed either by direct property
2262 change or by the system.
2263 See also: "font", "ColorChanged"
2265 Hide
2267 Triggered by a successive visible(0) call
2268 See also: "Show", "visible", "showing", "exposed"
2270 Hint SHOW_FLAG
2272 Called when the hint label is about to show or hide, depending on
2273 SHOW_FLAG. The hint show or hide action fails, if the event flag is
2274 cleared during execution.
2275 See also: "showHint", "ownerShowHint", "hintVisible", "ownerHint"
2277 KeyDown CODE, KEY, MOD, REPEAT
2279 Sent to the focused widget when the user presses a key. CODE
2280 contains an eventual character code, KEY is one of "kb::XXX"
2281 constants, MOD is a combination of the modificator keys pressed
2282 when the event occurred ( "km::XXX" ). REPEAT is how many times the
2283 key was pressed; usually it is 1. ( see "::briefKeys" ).
2284 The valid "km::" constants are:
2286 km::Shift
2288 km::Ctrl
2289 km::Alt
2290 km::KeyPad
2291 km::DeadKey
2292 km::Unicode
2293 The valid "kb::" constants are grouped in several sets. Some codes
2295 are aliased, like, "kb::PgDn" and "kb::PageDown".
2296 Modificator keys
2298 kb::ShiftL kb::ShiftR kb::CtrlL kb::CtrlR
2299 kb::AltL kb::AltR kb::MetaL kb::MetaR
2300 kb::SuperL kb::SuperR kb::HyperL kb::HyperR
2301 kb::CapsLock kb::NumLock kb::ScrollLock kb::ShiftLock
2302 Keys with character code defined
2304 kb::Backspace kb::Tab kb::Linefeed kb::Enter
2305 kb::Return kb::Escape kb::Esc kb::Space
2306 Function keys
2308 kb::F1 .. kb::F30
2309 kb::L1 .. kb::L10
2310 kb::R1 .. kb::R10
2311 Other
2313 kb::Clear kb::Pause kb::SysRq kb::SysReq
2314 kb::Delete kb::Home kb::Left kb::Up
2315 kb::Right kb::Down kb::PgUp kb::Prior
2316 kb::PageUp kb::PgDn kb::Next kb::PageDown
2317 kb::End kb::Begin kb::Select kb::Print
2318 kb::PrintScr kb::Execute kb::Insert kb::Undo
2319 kb::Redo kb::Menu kb::Find kb::Cancel
2320 kb::Help kb::Break kb::BackTab
2321 See also: "KeyUp", "briefKeys", "key_down", "help", "popup",
2323 "tabOrder", "tabStop", "accelTable"
2324 KeyUp CODE, KEY, MOD
2326 Sent to the focused widget when the user releases a key. CODE
2327 contains an eventual character code, KEY is one of "kb::XXX"
2328 constants, MOD is a combination of the modificator keys pressed
2329 when the event occurred ( "km::XXX" ).
2330 See also: "KeyDown", "key_up"
2332 Leave
2334 Called when the input focus is removed from a widget
2335 See also: "Enter", "focused", "selected"
2337 Menu MENU VAR_NAME
2339 Called before the user-navigated menu ( pop-up or pull-down ) is
2340 about to show another level of submenu on the screen. MENU is
2341 Prima::AbstractMenu descendant, that children to a widget, and
2342 VAR_NAME is the name of the menu item that is about to be shown.
2343 Used for making changes in the menu structures dynamically.
2345 See also: "popupItems"
2347 MouseClick BUTTON, MOD, X, Y, DOUBLE_CLICK
2349 Called when a mouse click ( button is pressed, and then released
2350 within system-defined interval of time ) is happened in the widget
2351 area. BUTTON is one of "mb::XXX" constants, MOD is a combination of
2352 "km::XXX" constants, reflecting pressed modificator keys during the
2353 event, X and Y are the mouse pointer coordinates. DOUBLE_CLICK is a
2354 boolean flag, set to 1 if it was a double click, 0 if a single.
2355 "mb::XXX" constants are:
2357 mb::b1 or mb::Left
2359 mb::b2 or mb::Middle
2360 mb::b3 or mb::Right
2361 mb::b4
2362 mb::b5
2363 mb::b6
2364 mb::b7
2365 mb::b8
2366 See also: "MouseDown", "MouseUp", "MouseWheel", "MouseMove",
2368 "MouseEnter", "MouseLeave"
2369 MouseDown BUTTON, MOD, X, Y
2371 Occurs when the user presses mouse button on a widget. BUTTON is
2372 one of "mb::XXX" constants, MOD is a combination of "km::XXX"
2373 constants, reflecting the pressed modificator keys during the
2374 event, X and Y are the mouse pointer coordinates.
2375 See also: "MouseUp", "MouseClick", "MouseWheel", "MouseMove",
2377 "MouseEnter", "MouseLeave"
2378 MouseEnter MOD, X, Y
2380 Occurs when the mouse pointer is entered the area occupied by a
2381 widget ( without mouse button pressed ). MOD is a combination of
2382 "km::XXX" constants, reflecting the pressed modificator keys during
2383 the event, X and Y are the mouse pointer coordinates.
2384 See also: "MouseDown", "MouseUp", "MouseClick", "MouseWheel",
2386 "MouseMove", "MouseLeave"
2387 MouseLeave
2389 Occurs when the mouse pointer is driven off the area occupied by a
2390 widget ( without mouse button pressed ).
2391 See also: "MouseDown", "MouseUp", "MouseClick", "MouseWheel",
2393 "MouseMove", "MouseEnter"
2394 MouseMove MOD, X, Y
2396 Occurs when the mouse pointer is transported over a widget. MOD is
2397 a combination of "km::XXX" constants, reflecting the pressed
2398 modificator keys during the event, X and Y are the mouse pointer
2399 coordinates.
2400 See also: "MouseDown", "MouseUp", "MouseClick", "MouseWheel",
2402 "MouseEnter", "MouseLeave"
2403 MouseUp BUTTON, MOD, X, Y
2405 Occurs when the user depresses mouse button on a widget. BUTTON is
2406 one of "mb::XXX" constants, MOD is a combination of "km::XXX"
2407 constants, reflecting the pressed modificator keys during the
2408 event, X and Y are the mouse pointer coordinates.
2409 See also: "MouseDown", "MouseClick", "MouseWheel", "MouseMove",
2411 "MouseEnter", "MouseLeave"
2412 MouseWheel MOD, X, Y, INCR
2414 Occurs when the user rotates mouse wheel on a widget. MOD is a
2415 combination of "km::XXX" constants, reflecting the pressed
2416 modificator keys during the event, INCR is the wheel movement,
2417 scaled by 120. +120 is a step upwards, or -120 downwards. For
2418 wheels which are discrete button clicks INCR is +/-120 but other
2419 devices may give other amounts. A widget should scroll by INCR/120
2420 many units, or partial unit, for whatever its unit of movement
2421 might be, such as lines of text, slider ticks, etc.
2422 A widget might like to vary its unit move according to the MOD
2424 keys. For example "Prima::SpinEdit" has a "step" and "pageStep"
2425 and moves by "pageStep" when "km::Ctrl" is held down (see
2426 Prima::Sliders).
2427 See also: "MouseDown", "MouseUp", "MouseClick", "MouseMove",
2429 "MouseEnter", "MouseLeave"
2430 Move OLD_X, OLD_Y, NEW_X, NEW_Y
2432 Triggered when widget changes its position relative to its parent,
2433 either by Prima::Widget methods or by the user. OLD_X and OLD_Y
2434 are the old coordinates of a widget, NEW_X and NEW_Y are the new
2435 ones.
2436 See also: "Size", "origin", "growMode", "centered", "clipOwner"
2438 Paint CANVAS
2440 Caused when the system calls for the refresh of a graphic context,
2441 associated with a widget. CANVAS is the widget itself, however its
2442 usage instead of widget is recommended ( see "Graphic content" ).
2443 See also: "repaint", "syncPaint", "get_invalid_rect", "scroll",
2445 "colorIndex", "font"
2446 Popup BY_MOUSE, X, Y
2448 Called by the system when the user presses a key or mouse
2449 combination defined for a context pop-up menu execution. By
2450 default executes the associated Prima::Popup object, if it is
2451 present. If the event flag is cleared during the execution of
2452 callbacks, the pop-up menu is not shown.
2453 See also: "popup"
2455 Setup
2457 This message is posted right after "Create" notification, and comes
2458 first from the event loop. Prima::Widget does not use it.
2459 Show
2461 Triggered by a successive visible(1) call
2462 See also: "Show", "visible", "showing", "exposed"
2464 Size OLD_WIDTH, OLD_HEIGHT, NEW_WIDTH, NEW_HEIGHT
2466 Triggered when widget changes its size, either by Prima::Widget
2467 methods or by the user. OLD_WIDTH and OLD_HEIGHT are the old
2468 extensions of a widget, NEW_WIDTH and NEW_HEIGHT are the new ones.
2469 See also: "Move", "origin", "size", "growMode", "sizeMax",
2471 "sizeMin", "rect", "clipOwner"
2472 SysHandle
2474 Same as in "Component", but introduces the following "Widget"
2475 properties can trigger it:
2476 clipOwner, syncPaint, layered, transparent
2478 This event will be only needed when the system handle (that can be
2480 acquired by "get_handle" ) is needed.
2481 TranslateAccel CODE, KEY, MOD
2483 A distributed "KeyDown" event. Traverses all the object tree that
2484 the widget which received original "KeyDown" event belongs to. Once
2485 the event flag is cleared, the iteration stops.
2486 Used for tracking keyboard events by out-of-focus widgets.
2488 See also: "KeyDown"
2490 ZOrderChanged
2492 Triggered when a widget changes its stacking order, or Z-order
2493 among its siblings, either by Prima::Widget methods or by the user.
2494 See also: "bring_to_front", "insert_behind", "send_to_back"
2496
2498 Dmitry Karasik, <dmitry@karasik.eu.org>.
2499
2501 Prima, Prima::Object, Prima::Drawable.
2502perl v5.28.1 2019-02-02 pod::Prima::Widget(3)