1pod::Prima::Object(3) User Contributed Perl Documentationpod::Prima::Object(3)
2
6 Prima::Object - Prima toolkit base classes
7
9 if ( $obj-> isa('Prima::Component')) {
10 # set and get a property
12 my $name = $obj-> name;
13 $obj->name( 'an object' );
14 # set a notification callback
16 $obj-> onPostMessage( sub {
17 shift;
18 print "hey! I've received this: @_\n";
19 });
20 # can set multiple properties. note, that 'name' and 'owner',
22 # replace the old values, while onPostMessage are aggregated.
23 $obj-> set(
24 name => 'AnObject',
25 owner => $new_owner,
26 onPostMessage => sub {
27 shift;
28 print "hey! me too!\n";
29 },
30 );
31 # de-reference by name
33 $new_owner-> AnObject-> post_message(1,2);
34 }
35
37 Prima::Object and Prima::Component are the root objects of the Prima
38 toolkit hierarchy. All the other objects are derived from the Component
39 class, which in turn is the only descendant of Object class. Both of
40 these classes are never used for spawning their instances, although
41 this is possible using
42 Prima::Component-> create( .. parameters ... );
44 call. This document describes the basic concepts of the OO programming
46 with Prima toolkit. Although Component has wider functionality than
47 Object, all examples will be explained on Component, since Object has
48 no descendant classes and all the functionality of Object is present in
49 Component. Some of the information here can be found in
50 Prima::internals as well, the difference is that Prima::internals
51 considers the coding tasks from a C programmer's view, whereas this
52 document is wholly about perl programming.
53
55 Creation
56 Object creation has fixed syntax:
57 $new_object = Class-> create(
59 parameter => value,
60 parameter => value,
61 ...
62 );
63 Parameters and values form a hash, which is passed to the create()
65 method. This hash is applied to a default parameter-value hash ( a
66 profile ), specific to every Prima class. The object creation is
67 performed in several stages.
68 create
70 create() calls profile_default() method that returns ( as its name
71 states ) the default profile, a hash with the appropriate default
72 values assigned to its keys. The Component class defaults are (
73 see Classes.pm ):
74 name => ref $_[ 0],
76 owner => $::application,
77 delegations => undef,
78 While the exact meaning of these parameters is described later, in
80 "Properties", the idea is that a newly created object will have
81 'owner' parameter set to '$::application' and 'delegations' to
82 undef etc etc - unless these parameters are explicitly passed to
83 create(). Example:
84 $a1 = Prima::Component-> create();
86 $a1's owner will be $::application
88 $a2 = Prima::Component-> create( owner => $a1);
90 $a2's owner will be $a1. The actual merging of the default and the
92 parameter hashes is performed on the next stage, in
93 profile_check_in() method which is called inside profile_add()
94 method.
95 profile_check_in
97 A profile_check_in() method merges the default and the parameter
98 profiles. By default all specified parameters have the ultimate
99 precedence over the default ones, but in case the specification is
100 incomplete or ambiguous, the profile_check_in()'s task is to
101 determine actual parameter values. In case of Component, this
102 method maintains a simple automatic naming of the newly created
103 objects. If the object name was not specified with create(), it is
104 assigned to a concatenated class name with an integer - Component1,
105 Component2 etc.
106 Another example can be taken from
108 Prima::Widget::profile_check_in(). Prima::Widget horizontal
109 position can be specified by using basic "left" and "width"
110 parameters, and as well by auxiliary "right", "size" and "rect".
111 The default of both "left" and "width" is 100. But if only "right"
112 parameter, for example, was passed to create() it is
113 profile_check_in() job to determine "left" value, given that
114 "width" is still 100.
115 After profiles gets merged, the resulting hash is passed to the
117 third stage, init().
118 init
120 init() duty is to map the profile content into object, e.g., assign
121 "name" property to "name" parameter value, and so on - for all
122 relevant parameters. After that, it has to return the profile in
123 order the overridden subsequent init() methods can perform same
124 actions. This stage along with the previous is exemplified in
125 almost all Prima modules.
126 Note: usually init() attaches the object to its owner in order to
128 keep the newly-created object instance from being deleted by
129 garbage-collection mechanisms. More on that later ( see "Links
130 between objects").
131 After init() finishes, create() calls setup() method
133 setup
135 setup() method is a convenience function, it is used when some
136 post-init actions must be taken. It is seldom overloaded, primarily
137 because the Component::setup() method calls "onCreate"
138 notification, which is more convenient to overload than setup().
139 As can be noticed from the code pieces above, a successful create()
141 call returns a newly created object. If an error condition occurred,
142 undef is returned. It must be noted, that only errors that were
143 generated via die() during init() stage result in undef. Other errors
144 raise an exception instead. It is not recommended to frame create()
145 calls in an "eval{}" block, because the error conditions can only occur
146 in two situations. The first is a system error, either inside perl or
147 Prima guts, and not much can be done here, since that error can very
148 probably lead to an unstable program and almost always signals an
149 implementation bug. The second reason is a caller's error, when an
150 unexistent parameter key or invalid value is passed; such conditions
151 are not subject to a runtime error handling as are not the syntax
152 errors.
153 After create(), the object is subject to the event flow. As "onCreate"
155 event is the first event the object receives, only after that stage
156 other events can be circulated.
157 Destruction
159 Object destruction can be caused by many conditions, but all execution
160 flow is finally passed through destroy() method. destroy(), as well as
161 create() performs several finalizing steps:
162 cleanup
164 The first method called inside destroy() is cleanup(). cleanup()
165 is the pair to setup(), as destroy() is the pair to create().
166 cleanup() generates "onDestroy" event, which can be overridden more
167 easily than cleanup() itself.
168 "onDestroy" is the last event the object sees. After cleanup() no
170 events are allowed to circulate.
171 done
173 done() method is the pair to init(), and is the place where all
174 object resources are freed. Although it is as safe to overload
175 done() as init(), it almost never gets overloaded, primarily
176 because overloading "onDestroy" is easier.
177 The typical conditions that lead to object destructions are direct
179 destroy() call, garbage collections mechanisms, user-initiated window
180 close ( on "Prima::Window" only ), and exception during init() stage.
181 Thus, one must be careful implementing done() which is called after
182 init() throws an exception.
183 Methods
185 The class methods are declared and used with perl OO syntax, which
186 allow both method of object referencing:
187 $object-> method();
189 and
191 method( $object);
193 The actual code is a sub, located under the object class package. The
195 overloaded methods that call their ancestor code use
196 $object-> SUPER::method();
198 syntax. Most Prima methods have fixed number of parameters.
200 Properties
202 Properties are methods that combine functionality of two ephemeral
203 "get" and "set" methods. The idea behind properties is that many object
204 parameters require two independent methods, one that returns some
205 internal state and another that changes it. For example, for managing
206 the object name, set_name() and get_name() methods are needed. Indeed,
207 the early Prima implementation dealt with large amount of these get's
208 and set's, but later these method pairs were deprecated in the favor of
209 properties. Currently, there is only one method name() ( referred as
210 "::name" later in the documentation ).
211 The property returns a value if no parameters ( except the object) are
213 passed, and changes the internal data to the passed parameters
214 otherwise. Here's a sketch code for "::name" property implementation:
215 sub name
217 {
218 return $_[0]-> {name} unless $#_;
219 $_[0]->{name} = $_[1];
220 }
221 There are many examples of properties throughout the toolkit. Not all
223 properties deal with scalar values, some accept arrays or hashes as
224 well. The properties can be set-called not only by name like
225 $object-> name( "new name");
227 but also with set() method. The set() method accepts a hash, that is
229 much like to create(), and assigns the values to the corresponding
230 properties. For example, the code
231 $object-> name( "new name");
233 $object-> owner( $owner);
234 can be rewritten as
236 $object-> set(
238 name => "new name",
239 owner => $owner
240 );
241 A minor positive effect of a possible speed-up is gained by eliminating
243 C-to-perl and perl-to-C calls, especially if the code called is
244 implemented in C. The negative effect of such technique is that the
245 order in which the properties are set, is undefined. Therefore, the
246 usage of set() is recommended either when the property order is
247 irrelevant, or it is known beforehand that such a call speeds up the
248 code, or is an only way to achieve the result. An example of the latter
249 case from Prima::internals shows that Prima::Image calls
250 $image-> type( $a);
252 $image-> palette( $b);
253 and
255 $image-> palette( $b);
257 $image-> type( $a);
258 produce different results. It is indeed the only solution to call for
260 such a change using
261 $image-> set(
263 type => $a,
264 palette => $b
265 );
266 when it is known beforehand that "Prima::Image::set" is aware of such
268 combinations and calls neither "::type" nor "::palette" but performs
269 another image conversion instead.
270 Some properties are read-only and some are write-only. Some methods
272 that might be declared as properties are not; these are declared as
273 plain methods with get_ or set_ name prefix. There is not much
274 certainty about what methods are better off being declared as
275 properties and vice versa.
276 However, if get_ or set_ methods cannot be used in correspondingly
278 write or read fashion, the R/O and W/O properties can. They raise an
279 exception on an attempt to do so.
280 Links between objects
282 Prima::Component descendants can be used as containers, as objects that
283 are on a higher hierarchy level than the others. This scheme is
284 implemented in a child-owner relationship. The 'children' objects have
285 the "::owner" property value assigned to a reference to a 'owner'
286 object, while the 'owner' object conducts the list of its children. It
287 is a one-to-many hierarchy scheme, as a 'child' object can have only
288 one owner, but an 'owner' object can have many children. The same
289 object can be an owner and a child at the same time, so the owner-child
290 hierarchy can be viewed as a tree-like structure.
291 Prima::Component::owner property maintains this relation, and is
293 writable - the object can change its owner dynamically. There is no
294 corresponding property that manages children objects, but is a method
295 get_components(), that returns an array of the child references.
296 The owner-child relationship is used in several ways in the toolkit.
298 For example, the widgets that are children of another widget appear (
299 usually, but not always ) in the geometrical interior of the owner
300 widget. Some events ( keyboard events, for example ) are propagated
301 automatically up and/or down the object tree. Another important feature
302 is that when an object gets destroyed, its children are destroyed
303 first. In a typical program the whole object tree roots in a
304 Prima::Application object instance. When the application finishes, this
305 feature helps cleaning up the widgets and quitting gracefully.
306 Implementation note: name 'owner' was taken instead of initial
308 'parent', because the 'parent' is a fixed term for widget hierarchy
309 relationship description. Prima::Widget relationship between owner and
310 child is not the same as GUI's parent-to-child. The parent is the
311 widget for the children widgets located in and clipped by its inferior.
312 The owner widget is more than that, its children can be located outside
313 its owner boundaries.
314 The special convenience variety of create(), the insert() method is
316 used to explicitly select owner of the newly created object. insert()
317 can be considered a 'constructor' in OO-terms. It makes the construct
318 $obj = Class-> create( owner => $owner, name => 'name);
320 more readable by introducing
322 $obj = $owner-> insert( 'Class', name => 'name');
324 scheme. These two code blocks are identical to each other.
326 There is another type of relation, where objects can hold references to
328 each other. Internally this link level is used to keep objects from
329 deletion by garbage collection mechanisms. This relation is many-to-
330 many scheme, where every object can have many links to other objects.
331 This functionality is managed by attach() and detach() methods.
332
334 Prima::Component descendants employ a well-developed event propagation
335 mechanism, which allows handling events using several different
336 schemes. An event is a condition, caused by the system or the user, or
337 an explicit notify() call. The formerly described events onCreate and
338 onDestroy are triggered after a new object is created or before it gets
339 destroyed. These two events, and the described below onPostMessage are
340 present in namespaces of all Prima objects. New classes can register
341 their own events and define their execution flow, using
342 notification_types() method. This method returns all available
343 information about the events registered in a class.
344 Prima defines also a non-object event dispatching and filtering
346 mechanism, available through "event_hook" static method.
347 Propagation
349 The event propagation mechanism has three layers of user-defined
350 callback registration, that are called in different order and contexts
351 when an event is triggered. The examples below show the usage of these
352 layers. It is assumed that an implicit
353 $obj-> notify("PostMessage", $data1, $data2);
355 call is issued for all these examples.
357 Direct methods
359 As it is usual in OO programming, event callback routines are
360 declared as methods. 'Direct methods' employ such a paradigm, so if
361 a class method with name "on_postmessage" is present, it will be
362 called as a method ( i.e., in the object context ) when
363 "onPostMessage" event is triggered. Example:
364 sub on_postmessage
366 {
367 my ( $self, $data1, $data2) = @_;
368 ...
369 }
370 The callback name is a modified lower-case event name: the name for
372 Create event is on_create, PostMessage - on_postmessage etc. These
373 methods can be overloaded in the object's class descendants. The
374 only note on declaring these methods in the first instance is that
375 no "::SUPER" call is needed, because these methods are not defined
376 by default.
377 Usually the direct methods are used for the internal object book-
379 keeping, reacting on the events that are not designed to be passed
380 higher. For example, a Prima::Button class catches mouse and
381 keyboard events in such a fashion, because usually the only
382 notification that is interesting for the code that employs push-
383 buttons is "Click". This scheme is convenient when an event
384 handling routine serves the internal, implementation-specific
385 needs.
386 Delegated methods
388 The delegated methods are used when objects ( mostly widgets )
389 include other dependent objects, and the functionality requires
390 interaction between these. The callback functions here are the
391 same methods as direct methods, except that they get called in
392 context of two, not one, objects. If, for example, a $obj's owner,
393 $owner would be interested in $obj's PostMessage event, it would
394 register the notification callback by
395 $obj-> delegations([ $owner, 'PostMessage']);
397 where the actual callback sub will be
399 sub Obj_PostMessage
401 {
402 my ( $self, $obj, $data1, $data2) = @_;
403 }
404 Note that the naming style is different - the callback name is
406 constructed from object name ( let assume that $obj's name is
407 'Obj') and the event name. ( This is one of the reasons why
408 Component::profile_check_in() performs automatic naming of newly
409 created onbjects). Note also that context objects are $self ( that
410 equals $owner ) and $obj.
411 The delegated methods can be used not only for the owner-child
413 relations. Every Prima object is free to add a delegation method to
414 every other object. However, if the objects are in other than
415 owner-child relation, it is a good practice to add Destroy
416 notification to the object which events are of interest, so if it
417 gets destroyed, the partner object gets a message about that.
418 Anonymous subroutines
420 The two previous callback types are more relevant when a separate
421 class is developed, but it is not necessary to declare a new class
422 every time the event handling is needed. It is possible to use the
423 third and the most powerful event hook method using perl anonymous
424 subroutines ( subs ) for the easy customization.
425 Contrary to the usual OO event implementations, when only one
427 routine per class dispatches an event, and calls inherited handlers
428 when it is appropriate, Prima event handling mechanism can accept
429 many event handlers for one object ( it is greatly facilitated by
430 the fact that perl has anonymous subs, however).
431 All the callback routines are called when an event is triggered,
433 one by one in turn. If the direct and delegated methods can only be
434 multiplexed by the usual OO inheritance, the anonymous subs are
435 allowed to be multiple by the design. There are three syntaxes for
436 setting such a event hook; the example below sets a hook on $obj
437 using each syntax for a different situation:
438 - during create():
440 $obj = Class-> create(
442 ...
443 onPostMessage => sub {
444 my ( $self, $data1, $data2) = @_;
445 },
446 ...
447 );
448 - after create using set()
450 $obj-> set( onPostMessage => sub {
452 my ( $self, $data1, $data2) = @_;
453 });
454 - after create using event name:
456 $obj-> onPostMessage( sub {
458 my ( $self, $data1, $data2) = @_;
459 });
460 As was noted in Prima, the events can be addressed as properties,
462 with the exception that they are not substitutive but additive.
463 The additivity is that when the latter type of syntax is used, the
464 subs already registered do not get overwritten or discarded but
465 stack in queue. Thus,
466 $obj-> onPostMessage( sub { print "1" });
468 $obj-> onPostMessage( sub { print "2" });
469 $obj-> notify( "PostMessage", 0, 0);
470 code block would print
472 21
474 as the execution result.
476 This, it is a distinctive feature of a toolkit is that two objects
478 of same class may have different set of event handlers.
479 Flow
481 When there is more than one handler of a particular event type present
482 on an object, a question is risen about what are callbacks call
483 priorities and when does the event processing stop. One of ways to
484 regulate the event flow is based on prototyping events, by using
485 notification_types() event type description. This function returns a
486 hash, where keys are the event names and the values are the constants
487 that describe the event flow. The constant can be a bitwise OR
488 combination of several basic flow constants, that control the three
489 aspects of the event flow.
490 Order
492 If both anonymous subs and direct/delegated methods are present, it
493 must be decided which callback class must be called first. Both
494 'orders' are useful: for example, if it is designed that a class's
495 default action is to be overridden, it is better to call the custom
496 actions first. If, on the contrary, the class action is primary,
497 and the others are supplementary, the reverse order is preferred.
498 One of two "nt::PrivateFirst" and "nt::CustomFirst" constants
499 defines the order.
500 Direction
502 Almost the same as order, but for finer granulation of event flow,
503 the direction constants "nt::FluxNormal" and "nt::FluxReverse" are
504 used. The 'normal flux' defines FIFO ( first in first out )
505 direction. That means, that the sooner the callback is registered,
506 the greater priority it would possess during the execution. The
507 code block shown above
508 $obj-> onPostMessage( sub { print "1" });
510 $obj-> onPostMessage( sub { print "2" });
511 $obj-> notify( "PostMessage", 0, 0);
512 results in 21, not 12 because PostMessage event type is prototyped
514 "nt::FluxReverse".
515 Execution control
517 It was stated above that the events are additive, - the callback
518 storage is never discarded when 'set'-syntax is used. However,
519 the event can be told to behave like a substitutive property, e.g.
520 to call one and only one callback. This functionality is governed
521 by "nt::Single" bit in execution control constant set, which
522 consists of the following constants:
523 nt::Single
525 nt::Multiple
526 nt::Event
527 These constants are mutually exclusive, and may not appear together
529 in an event type declaration. A "nt::Single"-prototyped
530 notification calls only the first ( or the last - depending on
531 order and direction bits ) callback. The usage of this constant is
532 somewhat limited.
533 In contrary of "nt::Single", the "nt::Multiple" constant sets the
535 execution control to call all the available callbacks, with respect
536 to direction and order bits.
537 The third constant, "nt::Event", is the impact as "nt::Multiple",
539 except that the event flow can be stopped at any time by calling
540 clear_event() method.
541 Although there are 12 possible event type combinations, a half of them
543 are not viable. Another half were assigned to unique more-less
544 intelligible names:
545 nt::Default ( PrivateFirst | Multiple | FluxReverse)
547 nt::Property ( PrivateFirst | Single | FluxNormal )
548 nt::Request ( PrivateFirst | Event | FluxNormal )
549 nt::Notification ( CustomFirst | Multiple | FluxReverse )
550 nt::Action ( CustomFirst | Single | FluxReverse )
551 nt::Command ( CustomFirst | Event | FluxReverse )
552 Success state
554 Events do not return values, although the event generator, the notify()
555 method does - it returns either 1 or 0, which is the value of event
556 success state. The 0 and 1 results in general do not mean either
557 success or failure, they simply reflect the fact whether clear_event()
558 method was called during the processing - 1 if it was not, 0 otherwise.
559 The state is kept during the whole processing stage, and can be
560 accessed from Component::eventFlag property. Since it is allowed to
561 call notify() inside event callbacks, the object maintains a stack for
562 those states. Component::eventFlags always works with the topmost one,
563 and fails if is called from outside the event processing stage.
564 Actually, clear_event() is an alias for ::eventFlag(0) call. The state
565 stack is operated by push_event() and pop_event() methods.
566 Implementation note: a call of clear_event() inside a
568 "nt::Event"-prototyped event call does not automatically stops the
569 execution. The execution stops if the state value equals to 0 after the
570 callback is finished. A ::eventFlag(1) call thus cancels the effect of
571 clear_event().
572 A particular coding style is used when the event is
574 "nt::Single"-prototyped and is called many times in a row, so overheads
575 of calling notify() become a burden. Although notify() logic is
576 somewhat complicated, it is rather simple with "nt::Single" case. The
577 helper function get_notify_sub() returns the context of callback to-be-
578 called, so it can be used to emulate notify() behavior. Example:
579 for ( ... ) {
581 $result = $obj-> notify( "Measure", @parms);
582 }
583 can be expressed in more cumbersome, but efficient code if
585 "nt::Single"-prototyped event is used:
586 my ( $notifier, @notifyParms) = $obj-> get_notify_sub( "Measure" );
588 $obj-> push_event;
589 for ( ... ) {
590 $notifier-> ( @notifyParms, @parms);
591 # $result = $obj-> eventFlag; # this is optional
592 }
593 $result = $obj-> pop_event;
594
596 Prima::Object methods
597 alive
598 Returns the object 'vitality' state - true if the object is alive
599 and usable, false otherwise. This method can be used as a general
600 checkout if the scalar passed is a Prima object, and if it is
601 usable. The true return value can be 1 for normal and operational
602 object state, and 2 if the object is alive but in its init() stage.
603 Example:
604 print $obj-> name if Prima::Object::alive( $obj);
606 cleanup
608 Called right after destroy() started. Used to initiate "cmDestroy"
609 event. Is never called directly.
610 create CLASS, %PARAMETERS
612 Creates a new object instance of a given CLASS and sets its
613 properties corresponding to the passed parameter hash. Examples:
614 $obj = Class-> create( PARAMETERS);
616 $obj = Prima::Object::create( "class" , PARAMETERS);
617 Is never called in an object context.
619 Alias: new()
621 destroy
623 Initiates the object destruction. Perform in turn cleanup() and
624 done() calls. destroy() can be called several times and is the
625 only Prima re-entrant function, therefore may not be overloaded.
626 done
628 Called by destroy() after cleanup() is finished. Used to free the
629 object resources, as a finalization stage. During done() no events
630 are allowed to circulate, and alive() returns 0. The object is not
631 usable after done() finishes. Is never called directly.
632 Note: the eventual child objects are destroyed inside done() call.
634 get @PARAMETERS
636 Returns hash where keys are @PARAMETERS and values are the
637 corresponding object properties.
638 init %PARAMETERS
640 The most important stage of object creation process. %PARAMETERS
641 is the modified hash that was passed to create(). The modification
642 consists of merging with the result of profile_default() class
643 method inside profile_check_in() method. init() is responsible for
644 applying the relevant data into PARAMETERS to the object
645 properties. Is never called directly.
646 insert CLASS, %PARAMETERS
648 A convenience wrapper for create(), that explicitly sets the owner
649 property for a newly created object.
650 $obj = $owner-> insert( 'Class', name => 'name');
652 is adequate to
654 $obj = Class-> create( owner => $owner, name => 'name);
656 code. insert() has another syntax that allows simultaneous creation
658 of several objects:
659 @objects = $owner-> insert(
661 [ 'Class', %parameters],
662 [ 'Class', %parameters],
663 ...
664 );
665 With such syntax, all newly created objects would have $owner set
667 to their 'owner' properties.
668 new CLASS, %PARAMETERS
670 Same as create.
671 profile_add PROFILE
673 The first stage of object creation process. PROFILE is a reference
674 to a PARAMETERS hash, passed to create(). It is merged with
675 profile_default() after passing both to profile_check_in(). The
676 merge result is stored back in PROFILE. Is never called directly.
677 profile_check_in CUSTOM_PROFILE, DEFAULT_PROFILE
679 The second stage of object creation process. Resolves eventual
680 ambiguities in CUSTOM_PROFILE, which is the reference to PARAMETERS
681 passed to create(), by comparing to and using default values from
682 DEFAULT_PROFILE, which is the result of profile_default() method.
683 Is never called directly.
684 profile_default
686 Returns hash of the appropriate default values for all properties
687 of a class. In object creation process serves as a provider of
688 fall-back values, and is called implicitly. This method can be used
689 directly, contrary to the other creation process-related functions.
690 Can be called in a context of class.
692 raise_ro TEXT
694 Throws an exception with text TEXT when a read-only property is
695 called in a set- context.
696 raise_wo TEXT
698 Throws an exception with text TEXT when a write-only property is
699 called in a get- context.
700 set %PARAMETERS
702 The default behavior is an equivalent to
703 sub set
705 {
706 my $obj = shift;
707 my %PARAMETERS = @_;
708 $obj-> $_( $PARAMETERS{$_}) for keys %PARAMETERS;
709 }
710 code. Assigns object properties correspondingly to PARAMETERS hash.
712 Many Prima::Component descendants overload set() to make it more
713 efficient for particular parameter key patterns.
714 As the code above, raises an exception if the key in PARAMETERS has
716 no correspondent object property.
717 setup
719 The last stage of object creation process. Called after init()
720 finishes. Used to initiate "cmCreate" event. Is never called
721 directly.
722 Prima::Component methods
724 add_notification NAME, SUB, REFERER = undef, INDEX = -1
725 Adds SUB to the list of notification of event NAME. REFERER is the
726 object reference, which is used to create a context to SUB and is
727 passed as a parameter to it when called. If REFERER is undef ( or
728 not specified ), the same object is assumed. REFERER also gets
729 implicitly attached to the object, - the implementation frees the
730 link between objects when one of these gets destroyed.
731 INDEX is a desired insert position in the notification list. By
733 default it is -1, what means 'in the start'. If the notification
734 type contains nt::FluxNormal bit set, the newly inserted SUB will
735 be called first. If it has nt::FluxReverse, it is called last,
736 correspondingly.
737 Returns positive integer value on success, 0 on failure. This
739 value can be later used to refer to the SUB in
740 remove_notification().
741 See also: "remove_notification", "get_notification".
743 attach OBJECT
745 Inserts OBJECT to the attached objects list and increases OBJECT's
746 reference count. The list can not hold more than one reference to
747 the same object. The warning is issued on such an attempt.
748 See also: "detach".
750 bring NAME
752 Looks for a immediate child object that has name equals to NAME.
753 Returns its reference on success, undef otherwise. It is a
754 convenience method, that makes possible the usage of the following
755 constructs:
756 $obj-> name( "Obj");
758 $obj-> owner( $owner);
759 ...
760 $owner-> Obj-> destroy;
761 See also: "find_component"
763 can_event
765 Returns true if the object event circulation is allowed. In
766 general, the same as "alive() == 1", except that can_event() fails
767 if an invalid object reference is passed.
768 clear_event
770 Clears the event state, that is set to 1 when the event processing
771 begins. Signals the event execution stop for nt::Event-prototyped
772 events.
773 See also: "Events", "push_event", "pop_event", "::eventFlag",
775 "notify".
776 detach OBJECT, KILL
778 Removes OBJECT from the attached objects list and decreases
779 OBJECT's reference count. If KILL is true, destroys OBJECT.
780 See also: "attach"
782 event_error
784 Issues a system-dependent warning sound signal.
785 event_hook [ SUB ]
787 Installs a SUB to receive all events on all Prima objects. SUB
788 receives same parameters passed to notify, and must return an
789 integer, either 1 or 0, to pass or block the event respectively.
790 If no SUB is set, returns currently installed event hook pointer.
792 If SUB is set, replaces the old hook sub with SUB. If SUB is
793 'undef', event filtering is not used.
794 Since the 'event_hook' mechanism allows only one hook routine to be
796 installed at a time, direct usage of the method is discouraged.
797 Instead, use Prima::EventHook for multiplexing of the hook access.
798 The method is static, and can be called either with or without
800 class or object as a first parameter.
801 find_component NAME
803 Performs a depth-first search on children tree hierarchy, matching
804 the object that has name equal to NAME. Returns its reference on
805 success, undef otherwise.
806 See also: "bring"
808 get_components
810 Returns array of the child objects.
811 See: "create", "Links between objects".
813 get_handle
815 Returns a system-dependent handle for the object. For example,
816 Prima::Widget return its system WINDOW/HWND handles,
817 Prima::DeviceBitmap - its system PIXMAP/HBITMAP handles, etc.
818 Can be used to pass the handle value outside the program, for an
820 eventual interprocess communication scheme.
821 get_notification NAME, @INDEX_LIST
823 For each index in INDEX_LIST return three scalars, bound at the
824 index position in the NAME event notification list. These three
825 scalars are REFERER, SUB and ID. REFERER and SUB are those passed
826 to "add_notification", and ID is its result.
827 See also: "remove_notification", "add_notification".
829 get_notify_sub NAME
831 A convenience method for nt::Single-prototyped events. Returns
832 code reference and context for the first notification sub for event
833 NAME.
834 See "Success state" for example.
836 notification_types
838 Returns a hash, where the keys are the event names and the values
839 are the "nt::" constants that describe the event flow.
840 Can be called in a context of class.
842 See "Events" and "Flow" for details.
844 notify NAME, @PARAMETERS
846 Calls the subroutines bound to the event NAME with parameters
847 @PARAMETERS in context of the object. The calling order is
848 described by "nt::" constants, contained in the
849 notification_types() result hash.
850 notify() accepts variable number of parameters, and while it is
852 possible, it is not recommended to call notify() with the exceeding
853 number of parameters; the call with the deficient number of
854 parameters results in an exception.
855 Example:
857 $obj-> notify( "PostMessage", 0, 1);
859 See "Events" and "Flow" for details.
861 pop_event
863 Closes event processing stage brackets.
864 See "push_event", "Events"
866 post_message SCALAR1, SCALAR2
868 Calls "PostMessage" event with parameters SCALAR1 and SCALAR2 once
869 during idle event loop. Returns immediately. Does not guarantee
870 that "PostMessage" will be called, however.
871 See also "post" in Prima::Utils
873 push_event
875 Opens event processing stage brackets.
876 See "pop_event", "Events"
878 remove_notification ID
880 Removes a notification subroutine that was registered before with
881 "add_notification", where ID was its result. After successful
882 removal, the eventual context object gets implicitly detached from
883 the storage object.
884 See also: "add_notification", "get_notification".
886 set_notification NAME, SUB
888 Adds SUB to the event NAME notification list. Almost never used
889 directly, but is a key point in enabling the following notification
890 add syntax
891 $obj-> onPostMessage( sub { ... });
893 or
895 $obj-> set( onPostMessage => sub { ... });
897 that are shortcuts for
899 $obj-> add_notification( "PostMessage", sub { ... });
901 unlink_notifier REFERER
903 Removes all notification subs from all event lists bound to REFERER
904 object.
905 Prima::Component properties
907 eventFlag STATE
908 Provides access to the last event processing state in the object
909 event state stack.
910 See also: "Success state", "clear_event", "Events".
912 delegations [ <REFERER>, NAME, <NAME>, < <REFERER>, NAME, ... > ]
914 Accepts an anonymous array in set- context, which consists of a
915 list of event NAMEs, that a REFERER object ( the caller object by
916 default ) is interested in. Registers notification entries for
917 routines if subs with naming scheme REFERER_NAME are present on
918 REFERER name space. The example code
919 $obj-> name("Obj");
921 $obj-> delegations([ $owner, 'PostMessage']);
922 registers Obj_PostMessage callback if it is present in $owner
924 namespace.
925 In get- context returns an array reference that reflects the
927 object's delegated events list content.
928 See also: "Delegated methods".
930 name NAME
932 Maintains object name. NAME can be an arbitrary string, however it
933 is recommended against usage of special characters and spaces in
934 NAME, to facilitate the indirect object access coding style:
935 $obj-> name( "Obj");
937 $obj-> owner( $owner);
938 ...
939 $owner-> Obj-> destroy;
940 and to prevent system-dependent issues. If the system provides
942 capabilities that allow to predefine some object parameters by its
943 name ( or class), then it is impossible to know beforehand the
944 system naming restrictions. For example, in X window system the
945 following resource string would make all Prima toolkit buttons
946 green:
947 Prima*Button*backColor: green
949 In this case, using special characters such as ":" or "*" in the
951 name of an object would make the X resource unusable.
952 owner OBJECT
954 Selects an owner of the object, which may be any Prima::Component
955 descendant. Setting an owner to a object does not alter its
956 reference count. Some classes allow OBJECT to be undef, while some
957 do not. All widget objects can not exist without a valid owner;
958 Prima::Application on the contrary can only exist with owner set to
959 undef. Prima::Image objects are indifferent to the value of the
960 owner property.
961 Changing owner dynamically is allowed, but it is a main source of
963 implementation bugs, since the whole hierarchy tree is needed to be
964 recreated. Although this effect is not visible in perl, the
965 results are deeply system-dependent, and the code that changes
966 owner property should be thoroughly tested.
967 Changes to "owner" result in up to three notifications:
969 "ChangeOwner", which is called to the object itself, "ChildLeave",
970 which notifies the previous owner that the object is about to
971 leave, and "ChildEnter", telling the new owner about the new child.
972 Prima::Component events
974 ChangeOwner OLD_OWNER
975 Called at runtime when the object changes its owner.
976 ChildEnter CHILD
978 Triggered when a child object is attached, either as a new instance
979 or as a result of runtime owner change.
980 ChildLeave CHILD
982 Triggered when a child object is detached, either because it is
983 getting destroyed or as a result of runtime owner change.
984 Create
986 The first event an event sees. Called automatically after init() is
987 finished. Is never called directly.
988 Destroy
990 The last event an event sees. Called automatically before done() is
991 started. Is never called directly.
992 PostMessage SCALAR1, SCALAR2
994 Called after post_message() call is issued, not inside
995 post_message() but at the next idle event loop. SCALAR1 and
996 SCALAR2 are the data passed to post_message().
997 SysHandle
999 Sometimes Prima needs to implicitly re-create the system handle of
1000 a component. The re-creation is not seen on the toolkit level,
1001 except for some repaints when widgets on screen are affected, but
1002 under the hood, when it happens, Prima creates a whole new system
1003 resource. This happens when the underlying system either doesn't
1004 have API to change a certain property during the runtime, or when
1005 such a re-creation happens on one of component's parent, leading to
1006 a downward cascade of children re-creation. Also, it may happen
1007 when the user changes some system settings resolution, so that some
1008 resources have to be changed accordingly.
1009 This event will be only needed when the system handle (that can be
1011 acquired by "get_handle" ) is used further, or in case when Prima
1012 doesn't restore some properties bound to the system handle.
1013
1015 Dmitry Karasik, <dmitry@karasik.eu.org>.
1016
1018 Prima, Prima::internals, Prima::EventHook.
1019perl v5.32.0 2020-07-28 pod::Prima::Object(3)