1pod::Prima::Object(3) User Contributed Perl Documentationpod::Prima::Object(3)
2
3
4

NAME

6       Prima::Object - Prima toolkit base classes
7

SYNOPSIS

9           if ( $obj-> isa('Prima::Component')) {
10
11               # set and get a property
12               my $name = $obj-> name;
13               $obj->name( 'an object' );
14
15               # set a notification callback
16               $obj-> onPostMessage( sub {
17                   shift;
18                   print "hey! I've received this: @_\n";
19               });
20
21               # 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
32               # de-reference by name
33               $new_owner-> AnObject-> post_message(1,2);
34           }
35

DESCRIPTION

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
43          Prima::Component-> new( .. parameters ... );
44
45       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

Object base features

55   Creation
56       Object creation has fixed syntax:
57
58          $new_object = Class-> new(
59            parameter => value,
60            parameter => value,
61            ...
62          );
63
64       Parameters and values form a hash, which is passed to the new() method.
65       This hash is applied to a default parameter-value hash ( a profile ),
66       specific to every Prima class. The object creation is performed in
67       several stages.
68
69       new new() calls profile_default() method that returns ( as its name
70           states ) the default profile, a hash with the appropriate default
71           values assigned to its keys.  The Component class defaults are (
72           see Classes.pm ):
73
74                name        => ref $_[ 0],
75                owner       => $::application,
76                delegations => undef,
77
78           While the exact meaning of these parameters is described later, in
79           "Properties", the idea is that a newly created object will have
80           'owner' parameter set to '$::application' and 'delegations' to
81           undef etc etc - unless these parameters are explicitly passed to
82           new(). Example:
83
84                $a1 = Prima::Component-> new();
85
86           $a1's owner will be $::application
87
88                $a2 = Prima::Component-> new( owner => $a1);
89
90           $a2's owner will be $a1.  The actual merging of the default and the
91           parameter hashes is performed on the next stage, in
92           profile_check_in() method which is called inside profile_add()
93           method.
94
95           Note: the older syntax used create() instead of new(), which is
96           still valid but is not preferred
97
98       profile_check_in
99           A profile_check_in() method merges the default and the parameter
100           profiles. By default all specified parameters have the ultimate
101           precedence over the default ones, but in case the specification is
102           incomplete or ambiguous, the profile_check_in()'s task is to
103           determine actual parameter values. In case of Component, this
104           method maintains a simple automatic naming of the newly created
105           objects. If the object name was not specified with new(), it is
106           assigned to a concatenated class name with an integer - Component1,
107           Component2 etc.
108
109           Another example can be taken from
110           Prima::Widget::profile_check_in().  Prima::Widget horizontal
111           position can be specified by using basic "left" and "width"
112           parameters, and as well by auxiliary "right", "size" and "rect".
113           The default of both "left" and "width" is 100. But if only "right"
114           parameter, for example, was passed to new() it is
115           profile_check_in() job to determine "left" value, given that
116           "width" is still 100.
117
118           After profiles gets merged, the resulting hash is passed to the
119           third stage, init().
120
121       init
122           init() duty is to map the profile content into object, e.g., assign
123           "name" property to "name" parameter value, and so on - for all
124           relevant parameters.  After that, it has to return the profile in
125           order the overridden subsequent init() methods can perform same
126           actions. This stage along with the previous is exemplified in
127           almost all Prima modules.
128
129           Note: usually init() attaches the object to its owner in order to
130           keep the newly-created object instance from being deleted by
131           garbage-collection mechanisms. More on that later ( see "Links
132           between objects").
133
134           After init() finishes, new() calls setup() method
135
136       setup
137           setup() method is a convenience function, it is used when some
138           post-init actions must be taken. It is seldom overloaded, primarily
139           because the Component::setup() method calls "onCreate"
140           notification, which is more convenient to overload than setup().
141
142       As can be noticed from the code pieces above, a successful new() call
143       returns a newly created object. If an error condition occurred, undef
144       is returned. It must be noted, that only errors that were generated via
145       die() during init() stage result in undef. Other errors raise an
146       exception instead.  It is not recommended to frame new() calls in an
147       "eval{}" block, because the error conditions can only occur in two
148       situations. The first is a system error, either inside perl or Prima
149       guts, and not much can be done here, since that error can very probably
150       lead to an unstable program and almost always signals an implementation
151       bug. The second reason is a caller's error, when an nonexistent
152       parameter key or invalid value is passed; such conditions are not
153       subject to a runtime error handling as are not the syntax errors.
154
155       After new(), the object is subject to the event flow.  As "onCreate"
156       event is the first event the object receives, only after that stage
157       other events can be circulated.
158
159   Destruction
160       Object destruction can be caused by many conditions, but all execution
161       flow is finally passed through destroy() method.  destroy(), as well as
162       new() performs several finalizing steps:
163
164       cleanup
165           The first method called inside destroy() is cleanup().  cleanup()
166           is the pair to setup(), as destroy() is the pair to new().
167           cleanup() generates "onDestroy" event, which can be overridden more
168           easily than cleanup() itself.
169
170           "onDestroy" is the last event the object sees. After cleanup() no
171           events are allowed to circulate.
172
173       done
174           done() method is the pair to init(), and is the place where all
175           object resources are freed. Although it is as safe to overload
176           done() as init(), it almost never gets overloaded, primarily
177           because overloading "onDestroy" is easier.
178
179       The typical conditions that lead to object destruction are direct
180       destroy() call, garbage collections mechanisms, user-initiated window
181       close ( on "Prima::Window" only ), and exception during init() stage.
182       Thus, one must be careful implementing done() which is called after
183       init() throws an exception.
184
185   Methods
186       The class methods are declared and used with perl OO syntax, which
187       allow both method of object referencing:
188
189         $object-> method();
190
191       and
192
193         method( $object);
194
195       The actual code is a sub, located under the object class package.  The
196       overloaded methods that call their ancestor code use
197
198         $object-> SUPER::method();
199
200       syntax. Most Prima methods have fixed number of parameters.
201
202   Properties
203       Properties are methods that combine functionality of two ephemeral
204       "get" and "set" methods. The idea behind properties is that many object
205       parameters require two independent methods, one that returns some
206       internal state and another that changes it.  For example, for managing
207       the object name, set_name() and get_name() methods are needed. Indeed,
208       the early Prima implementation dealt with large amount of these get's
209       and set's, but later these method pairs were deprecated in the favor of
210       properties.  Currently, there is only one method name() ( referred as
211       "::name" later in the documentation ).
212
213       The property returns a value if no parameters ( except the object) are
214       passed, and changes the internal data to the passed parameters
215       otherwise. Here's a sketch code for "::name" property implementation:
216
217        sub name
218        {
219           return $_[0]-> {name} unless $#_;
220           $_[0]->{name} = $_[1];
221        }
222
223       There are many examples of properties throughout the toolkit.  Not all
224       properties deal with scalar values, some accept arrays or hashes as
225       well.  The properties can be set-called not only by name like
226
227         $object-> name( "new name");
228
229       but also with set() method. The set() method accepts a hash, that is
230       much like to new(), and assigns the values to the corresponding
231       properties. For example, the code
232
233         $object-> name( "new name");
234         $object-> owner( $owner);
235
236       can be rewritten as
237
238         $object-> set(
239            name  => "new name",
240            owner => $owner
241         );
242
243       A minor positive effect of a possible speed-up is gained by eliminating
244       C-to-perl and perl-to-C calls, especially if the code called is
245       implemented in C. The negative effect of such technique is that the
246       order in which the properties are set, is undefined. Therefore, the
247       usage of set() is recommended either when the property order is
248       irrelevant, or it is known beforehand that such a call speeds up the
249       code, or is an only way to achieve the result. An example of the latter
250       case from Prima::internals shows that Prima::Image calls
251
252           $image-> type( $a);
253           $image-> palette( $b);
254
255       and
256
257           $image-> palette( $b);
258           $image-> type( $a);
259
260       produce different results. It is indeed the only solution to call for
261       such a change using
262
263           $image-> set(
264              type => $a,
265              palette => $b
266           );
267
268       when it is known beforehand that "Prima::Image::set" is aware of such
269       combinations and calls neither "::type" nor "::palette" but performs
270       another image conversion instead.
271
272       Some properties are read-only and some are write-only. Some methods
273       that might be declared as properties are not; these are declared as
274       plain methods with get_ or set_ name prefix. There is not much
275       certainty about what methods are better off being declared as
276       properties and vice versa.
277
278       However, if get_ or set_ methods cannot be used in correspondingly
279       write or read fashion, the R/O and W/O properties can. They raise an
280       exception on an attempt to do so.
281
282   Links between objects
283       Prima::Component descendants can be used as containers, as objects that
284       are on a higher hierarchy level than the others. This scheme is
285       implemented in a child-owner relationship.  The 'children' objects have
286       the "::owner" property value assigned to a reference to a 'owner'
287       object, while the 'owner' object conducts the list of its children. It
288       is a one-to-many hierarchy scheme, as a 'child' object can have only
289       one owner, but an 'owner' object can have many children. The same
290       object can be an owner and a child at the same time, so the owner-child
291       hierarchy can be viewed as a tree-like structure.
292
293       Prima::Component::owner property maintains this relation, and is
294       writable - the object can change its owner dynamically. There is no
295       corresponding property that manages children objects, but is a method
296       get_components(), that returns an array of the child references.
297
298       The owner-child relationship is used in several ways in the toolkit.
299       For example, the widgets that are children of another widget appear (
300       usually, but not always ) in the geometrical interior of the owner
301       widget.  Some events ( keyboard events, for example ) are propagated
302       automatically up and/or down the object tree. Another important feature
303       is that when an object gets destroyed, its children are destroyed
304       first.  In a typical program the whole object tree roots in a
305       Prima::Application object instance. When the application finishes, this
306       feature helps cleaning up the widgets and quitting gracefully.
307
308       Implementation note: name 'owner' was taken instead of initial
309       'parent', because the 'parent' is a fixed term for widget hierarchy
310       relationship description. Prima::Widget relationship between owner and
311       child is not the same as GUI's parent-to-child.  The parent is the
312       widget for the children widgets located in and clipped by its inferior.
313       The owner widget is more than that, its children can be located outside
314       its owner boundaries.
315
316       The special convenience variety of new(), the insert() method is used
317       to explicitly select owner of the newly created object. insert() can be
318       considered a 'constructor' in OO-terms. It makes the construct
319
320          $obj = Class-> new( owner => $owner, name => 'name);
321
322       more readable by introducing
323
324          $obj = $owner-> insert( 'Class', name => 'name');
325
326       scheme. These two code blocks are identical to each other.
327
328       There is another type of relation, where objects can hold references to
329       each other. Internally this link level is used to keep objects from
330       deletion by garbage collection mechanisms.  This relation is many-to-
331       many scheme, where every object can have many links to other objects.
332       This functionality is managed by attach() and detach() methods.
333

Events

335       Prima::Component descendants employ a well-developed event propagation
336       mechanism, which allows handling events using several different
337       schemes.  An event is a condition, caused by the system or the user, or
338       an explicit notify() call. The formerly described events onCreate and
339       onDestroy are triggered after a new object is created or before it gets
340       destroyed. These two events, and the described below onPostMessage are
341       present in namespaces of all Prima objects.  New classes can register
342       their own events and define their execution flow, using
343       notification_types() method.  This method returns all available
344       information about the events registered in a class.
345
346       Prima defines also a non-object event dispatching and filtering
347       mechanism, available through "event_hook" static method.
348
349   Propagation
350       The event propagation mechanism has three layers of user-defined
351       callback registration, that are called in different order and contexts
352       when an event is triggered. The examples below show the usage of these
353       layers. It is assumed that an implicit
354
355         $obj-> notify("PostMessage", $data1, $data2);
356
357       call is issued for all these examples.
358
359       Direct methods
360           As it is usual in OO programming, event callback routines are
361           declared as methods. 'Direct methods' employ such a paradigm, so if
362           a class method with name "on_postmessage" is present, it will be
363           called as a method ( i.e., in the object context ) when
364           "onPostMessage" event is triggered. Example:
365
366            sub on_postmessage
367            {
368               my ( $self, $data1, $data2) = @_;
369               ...
370            }
371
372           The callback name is a modified lower-case event name: the name for
373           Create event is on_create, PostMessage - on_postmessage etc.  These
374           methods can be overloaded in the object's class descendants.  The
375           only note on declaring these methods in the first instance is that
376           no "::SUPER" call is needed, because these methods are not defined
377           by default.
378
379           Usually the direct methods are used for the internal object book-
380           keeping, reacting on the events that are not designed to be passed
381           higher. For example, a Prima::Button class catches mouse and
382           keyboard events in such a fashion, because usually the only
383           notification that is interesting for the code that employs push-
384           buttons is "Click".  This scheme is convenient when an event
385           handling routine serves the internal, implementation-specific
386           needs.
387
388       Delegated methods
389           The delegated methods are used when objects ( mostly widgets )
390           include other dependent objects, and the functionality requires
391           interaction between these.  The callback functions here are the
392           same methods as direct methods, except that they get called in
393           context of two, not one, objects. If, for example, a $obj's owner,
394           $owner would be interested in $obj's PostMessage event, it would
395           register the notification callback by
396
397              $obj-> delegations([ $owner, 'PostMessage']);
398
399           where the actual callback sub will be
400
401            sub Obj_PostMessage
402            {
403               my ( $self, $obj, $data1, $data2) = @_;
404            }
405
406           Note that the naming style is different - the callback name is
407           constructed from object name ( let assume that $obj's name is
408           'Obj') and the event name. ( This is one of the reasons why
409           Component::profile_check_in() performs automatic naming of newly
410           created objects). Note also that context objects are $self ( that
411           equals $owner ) and $obj.
412
413           The delegated methods can be used not only for the owner-child
414           relations. Every Prima object is free to add a delegation method to
415           every other object. However, if the objects are in other than
416           owner-child relation, it is a good practice to add Destroy
417           notification to the object which events are of interest, so if it
418           gets destroyed, the partner object gets a message about that.
419
420       Anonymous subroutines
421           The two previous callback types are more relevant when a separate
422           class is developed, but it is not necessary to declare a new class
423           every time the event handling is needed.  It is possible to use the
424           third and the most powerful event hook method using perl anonymous
425           subroutines ( subs ) for the easy customization.
426
427           Contrary to the usual OO event implementations, when only one
428           routine per class dispatches an event, and calls inherited handlers
429           when it is appropriate, Prima event handling mechanism can accept
430           many event handlers for one object ( it is greatly facilitated by
431           the fact that perl has anonymous subs, however).
432
433           All the callback routines are called when an event is triggered,
434           one by one in turn. If the direct and delegated methods can only be
435           multiplexed by the usual OO inheritance, the anonymous subs are
436           allowed to be multiple by the design.  There are three syntaxes for
437           setting such a event hook; the example below sets a hook on $obj
438           using each syntax for a different situation:
439
440           - during new():
441
442              $obj = Class-> new(
443               ...
444               onPostMessage => sub {
445                  my ( $self, $data1, $data2) = @_;
446               },
447               ...
448               );
449
450           - after new using set()
451
452              $obj-> set( onPostMessage => sub {
453                  my ( $self, $data1, $data2) = @_;
454              });
455
456           - after new using event name:
457
458              $obj-> onPostMessage( sub {
459                  my ( $self, $data1, $data2) = @_;
460              });
461
462           As was noted in Prima, the events can be addressed as properties,
463           with the exception that they are not substitutive but additive.
464           The additivity is that when the latter type of syntax is used, the
465           subs already registered do not get overwritten or discarded but
466           stack in queue. Thus,
467
468              $obj-> onPostMessage( sub { print "1" });
469              $obj-> onPostMessage( sub { print "2" });
470              $obj-> notify( "PostMessage", 0, 0);
471
472           code block would print
473
474              21
475
476           as the execution result.
477
478           This, it is a distinctive feature of a toolkit is that two objects
479           of same class may have different set of event handlers.
480
481   Flow
482       When there is more than one handler of a particular event type present
483       on an object, a question is risen about what are callbacks call
484       priorities and when does the event processing stop. One of ways to
485       regulate the event flow is based on prototyping events, by using
486       notification_types() event type description.  This function returns a
487       hash, where keys are the event names and the values are the constants
488       that describe the event flow. The constant can be a bitwise OR
489       combination of several basic flow constants, that control the three
490       aspects of the event flow.
491
492       Order
493           If both anonymous subs and direct/delegated methods are present, it
494           must be decided which callback class must be called first.  Both
495           'orders' are useful: for example, if it is designed that a class's
496           default action is to be overridden, it is better to call the custom
497           actions first. If, on the contrary, the class action is primary,
498           and the others are supplementary, the reverse order is preferred.
499           One of two "nt::PrivateFirst" and "nt::CustomFirst" constants
500           defines the order.
501
502       Direction
503           Almost the same as order, but for finer granulation of event flow,
504           the direction constants "nt::FluxNormal" and "nt::FluxReverse" are
505           used. The 'normal flux' defines FIFO ( first in first out )
506           direction. That means, that the sooner the callback is registered,
507           the greater priority it would possess during the execution.  The
508           code block shown above
509
510              $obj-> onPostMessage( sub { print "1" });
511              $obj-> onPostMessage( sub { print "2" });
512              $obj-> notify( "PostMessage", 0, 0);
513
514           results in 21, not 12 because PostMessage event type is prototyped
515           "nt::FluxReverse".
516
517       Execution control
518           It was stated above that the events are additive, - the callback
519           storage is never discarded  when 'set'-syntax is used.  However,
520           the event can be told to behave like a substitutive property, e.g.
521           to call one and only one callback.  This functionality is governed
522           by "nt::Single" bit in execution control constant set, which
523           consists of the following constants:
524
525             nt::Single
526             nt::Multiple
527             nt::Event
528
529           These constants are mutually exclusive, and may not appear together
530           in an event type declaration.  A "nt::Single"-prototyped
531           notification calls only the first ( or the last - depending on
532           order and direction bits ) callback. The usage of this constant is
533           somewhat limited.
534
535           In contrary of "nt::Single", the "nt::Multiple" constant sets the
536           execution control to call all the available callbacks, with respect
537           to direction and order bits.
538
539           The third constant, "nt::Event", is the  impact as "nt::Multiple",
540           except that the event flow can be stopped at any time by calling
541           clear_event() method.
542
543       Although there are 12 possible event type combinations, a half of them
544       are not viable. Another half were assigned to unique more-less
545       intelligible names:
546
547         nt::Default       ( PrivateFirst | Multiple | FluxReverse)
548         nt::Property      ( PrivateFirst | Single   | FluxNormal )
549         nt::Request       ( PrivateFirst | Event    | FluxNormal )
550         nt::Notification  ( CustomFirst  | Multiple | FluxReverse )
551         nt::Action        ( CustomFirst  | Single   | FluxReverse )
552         nt::Command       ( CustomFirst  | Event    | FluxReverse )
553
554   Success state
555       Events do not return values, although the event generator, the notify()
556       method does - it returns either 1 or 0, which is the value of event
557       success state.  The 0 and 1 results in general do not mean either
558       success or failure, they simply reflect the fact whether clear_event()
559       method was called during the processing - 1 if it was not, 0 otherwise.
560       The state is kept during the whole processing stage, and can be
561       accessed from Component::eventFlag property. Since it is allowed to
562       call notify() inside event callbacks, the object maintains a stack for
563       those states.  Component::eventFlags always works with the topmost one,
564       and fails if is called from outside the event processing stage.
565       Actually, clear_event() is an alias for ::eventFlag(0) call. The state
566       stack is operated by push_event() and pop_event() methods.
567
568       Implementation note: a call of clear_event() inside a
569       "nt::Event"-prototyped event call does not automatically stops the
570       execution. The execution stops if the state value equals to 0 after the
571       callback is finished.  A ::eventFlag(1) call thus cancels the effect of
572       clear_event().
573
574       A particular coding style is used when the event is
575       "nt::Single"-prototyped and is called many times in a row, so overheads
576       of calling notify() become a burden. Although notify() logic is
577       somewhat complicated, it is rather simple with "nt::Single" case. The
578       helper function get_notify_sub() returns the context of callback to-be-
579       called, so it can be used to emulate notify() behavior.  Example:
580
581         for ( ... ) {
582            $result = $obj-> notify( "Measure", @parms);
583         }
584
585       can be expressed in more cumbersome, but efficient code if
586       "nt::Single"-prototyped event is used:
587
588          my ( $notifier, @notifyParms) = $obj-> get_notify_sub( "Measure" );
589          $obj-> push_event;
590          for ( ... ) {
591              $notifier-> ( @notifyParms, @parms);
592              # $result = $obj-> eventFlag; # this is optional
593          }
594          $result = $obj-> pop_event;
595

API

597   Prima::Object methods
598       alive
599           Returns the object 'vitality' state - true if the object is alive
600           and usable, false otherwise.  This method can be used as a general
601           checkout if the scalar passed is a Prima object, and if it is
602           usable.  The true return value can be 1 for normal and operational
603           object state, and 2 if the object is alive but in its init() stage.
604           Example:
605
606             print $obj-> name if Prima::Object::alive( $obj);
607
608       cleanup
609           Called right after destroy() started. Used to initiate "cmDestroy"
610           event. Is never called directly.
611
612       create CLASS, %PARAMETERS
613           Same as new.
614
615       destroy
616           Initiates the object destruction. Perform in turn cleanup() and
617           done() calls.  destroy() can be called several times and is the
618           only Prima re-entrant function, therefore may not be overloaded.
619
620       done
621           Called by destroy() after cleanup() is finished. Used to free the
622           object resources, as a finalization stage.  During done() no events
623           are allowed to circulate, and alive() returns 0. The object is not
624           usable after done() finishes. Is never called directly.
625
626           Note: the eventual child objects are destroyed inside done() call.
627
628       get @PARAMETERS
629           Returns hash where keys are @PARAMETERS and values are the
630           corresponding object properties.
631
632       init %PARAMETERS
633           The most important stage of object creation process.  %PARAMETERS
634           is the modified hash that was passed to new().  The modification
635           consists of merging with the result of profile_default() class
636           method inside profile_check_in() method. init() is responsible for
637           applying the relevant data into PARAMETERS to the object
638           properties. Is never called directly.
639
640       insert CLASS, %PARAMETERS
641           A convenience wrapper for new(), that explicitly sets the owner
642           property for a newly created object.
643
644              $obj = $owner-> insert( 'Class', name => 'name');
645
646           is adequate to
647
648              $obj = Class-> new( owner => $owner, name => 'name);
649
650           code. insert() has another syntax that allows simultaneous creation
651           of several objects:
652
653              @objects = $owner-> insert(
654                [ 'Class', %parameters],
655                [ 'Class', %parameters],
656                ...
657              );
658
659           With such syntax, all newly created objects would have $owner set
660           to their 'owner' properties.
661
662       new CLASS, %PARAMETERS
663           Creates a new object instance of a given CLASS and sets its
664           properties corresponding to the passed parameter hash. Examples:
665
666              $obj = Class-> new( PARAMETERS);
667              $obj = Prima::Object::new( "class" , PARAMETERS);
668
669           Is never called in an object context.
670
671           Alias: create()
672
673       profile_add PROFILE
674           The first stage of object creation process.  PROFILE is a reference
675           to a PARAMETERS hash, passed to new().  It is merged with
676           profile_default() after passing both to profile_check_in(). The
677           merge result is stored back in PROFILE.  Is never called directly.
678
679       profile_check_in CUSTOM_PROFILE, DEFAULT_PROFILE
680           The second stage of object creation process.  Resolves eventual
681           ambiguities in CUSTOM_PROFILE, which is the reference to PARAMETERS
682           passed to new(), by comparing to and using default values from
683           DEFAULT_PROFILE, which is the result of profile_default() method.
684           Is never called directly.
685
686       profile_default
687           Returns hash of the appropriate default values for all properties
688           of a class.  In object creation process serves as a provider of
689           fall-back values, and is called implicitly. This method can be used
690           directly, contrary to the other creation process-related functions.
691
692           Can be called in a context of class.
693
694       raise_ro TEXT
695           Throws an exception with text TEXT when a read-only property is
696           called in a set- context.
697
698       raise_wo TEXT
699           Throws an exception with text TEXT when a write-only property is
700           called in a get- context.
701
702       set %PARAMETERS
703           The default behavior is an equivalent to
704
705             sub set
706             {
707                my $obj = shift;
708                my %PARAMETERS = @_;
709                $obj-> $_( $PARAMETERS{$_}) for keys %PARAMETERS;
710             }
711
712           code. Assigns object properties correspondingly to PARAMETERS hash.
713           Many Prima::Component descendants overload set() to make it more
714           efficient for particular parameter key patterns.
715
716           As the code above, raises an exception if the key in PARAMETERS has
717           no correspondent object property.
718
719       setup
720           The last stage of object creation process.  Called after init()
721           finishes. Used to initiate "cmCreate" event. Is never called
722           directly.
723
724   Prima::Component methods
725       add_notification NAME, SUB, REFERRER = undef, INDEX = -1
726           Adds SUB to the list of notification of event NAME.  REFEREE is the
727           object reference, which is used to create a context to SUB and is
728           passed as a parameter to it when called.  If REFEREE is undef ( or
729           not specified ), the same object is assumed. REFEREE also gets
730           implicitly attached to the object, - the implementation frees the
731           link between objects when one of these gets destroyed.
732
733           INDEX is a desired insert position in the notification list.  By
734           default it is -1, what means 'in the start'. If the notification
735           type contains nt::FluxNormal bit set, the newly inserted SUB will
736           be called first. If it has nt::FluxReverse, it is called last,
737           correspondingly.
738
739           Returns positive integer value on success, 0 on failure.  This
740           value can be later used to refer to the SUB in
741           remove_notification().
742
743           See also: "remove_notification", "get_notification".
744
745       attach OBJECT
746           Inserts OBJECT to the attached objects list and increases OBJECT's
747           reference count. The list can not hold more than one reference to
748           the same object. The warning is issued on such an attempt.
749
750           See also: "detach".
751
752       bring NAME, MAX_DEPTH=0
753           Looks for a child object that has name equals to NAME.  Returns its
754           reference on success, undef otherwise. It is a convenience method,
755           that makes possible the usage of the following constructs:
756
757              $obj-> name( "Obj");
758              $obj-> owner( $owner);
759              ...
760              $owner-> Obj-> destroy;
761              ...
762              $obj-> AUTOLOAD_DEEP_LOOKUP(1);
763              $obj-> insert(Foo => name => 'Bar');
764              $owner-> Bar-> do_something;
765
766           See also: "find_component", "AUTOLOAD_DEEP_LOOKUP"
767
768       can_event
769           Returns true if the object event circulation is allowed.  In
770           general, the same as "alive() == 1", except that can_event() fails
771           if an invalid object reference is passed.
772
773       clear_event
774           Clears the event state, that is set to 1 when the event processing
775           begins.  Signals the event execution stop for nt::Event-prototyped
776           events.
777
778           See also: "Events", "push_event", "pop_event", "::eventFlag",
779           "notify".
780
781           Use this call in your overloaded event handlers when wanted to
782           signal that further processing should be stopped, f ex onMouseDown
783           doing something else than the base widget.
784
785           See more in "Execution control". Consult the exact "nt::" type of
786           the event in the Prima/Classes.pm source.
787
788       detach OBJECT, KILL
789           Removes OBJECT from the attached objects list and decreases
790           OBJECT's reference count. If KILL is true, destroys OBJECT.
791
792           See also: "attach"
793
794       event_error
795           Issues a system-dependent warning sound signal.
796
797       event_hook [ SUB ]
798           Installs a SUB to receive all events on all Prima objects.  SUB
799           receives same parameters passed to notify, and must return an
800           integer, either 1 or 0, to pass or block the event respectively.
801
802           If no SUB is set, returns currently installed event hook pointer.
803           If SUB is set, replaces the old hook sub with SUB. If SUB is
804           'undef', event filtering is not used.
805
806           Since the 'event_hook' mechanism allows only one hook routine to be
807           installed at a time, direct usage of the method is discouraged.
808           Instead, use Prima::EventHook for multiplexing of the hook access.
809
810           The method is static, and can be called either with or without
811           class or object as a first parameter.
812
813       find_component NAME
814           Performs a depth-first search on children tree hierarchy, matching
815           the object that has name equal to NAME.  Returns its reference on
816           success, undef otherwise.
817
818           See also: "bring"
819
820       get_components
821           Returns array of the child objects.
822
823           See: "new", "Links between objects".
824
825       get_handle
826           Returns a system-dependent handle for the object.  For example,
827           Prima::Widget return its system WINDOW/HWND handles,
828           Prima::DeviceBitmap - its system PIXMAP/HBITMAP handles, etc.
829
830           Can be used to pass the handle value outside the program, for an
831           eventual interprocess communication scheme.
832
833       get_notification NAME, @INDEX_LIST
834           For each index in INDEX_LIST return three scalars, bound at the
835           index position in the NAME event notification list.  These three
836           scalars are REFERRER, SUB and ID. REFERRER and SUB are those passed
837           to "add_notification", and ID is its result.
838
839           See also: "remove_notification", "add_notification".
840
841       get_notify_sub NAME
842           A convenience method for nt::Single-prototyped events.  Returns
843           code reference and context for the first notification sub for event
844           NAME.
845
846           See "Success state" for example.
847
848       notification_types
849           Returns a hash, where the keys are the event names and the values
850           are the "nt::" constants that describe the event flow.
851
852           Can be called in a context of class.
853
854           See "Events" and "Flow" for details.
855
856       notify NAME, @PARAMETERS
857           Calls the subroutines bound to the event NAME with parameters
858           @PARAMETERS in context of the object.  The calling order is
859           described by "nt::" constants, contained in the
860           notification_types() result hash.
861
862           notify() accepts variable number of parameters, and while it is
863           possible, it is not recommended to call notify() with the exceeding
864           number of parameters; the call with the deficient number of
865           parameters results in an exception.
866
867           Example:
868
869              $obj-> notify( "PostMessage", 0, 1);
870
871           See "Events" and "Flow" for details.
872
873       pop_event
874           Closes event processing stage brackets.
875
876           See "push_event", "Events"
877
878       post_message SCALAR1, SCALAR2
879           Calls "PostMessage" event with parameters SCALAR1 and SCALAR2 once
880           during idle event loop. Returns immediately.  Does not guarantee
881           that "PostMessage" will be called, however.
882
883           See also "post" in Prima::Utils
884
885       push_event
886           Opens event processing stage brackets.
887
888           See "pop_event", "Events"
889
890       remove_notification ID
891           Removes a notification subroutine that was registered before with
892           "add_notification", where ID was its result. After successful
893           removal, the eventual context object gets implicitly detached from
894           the storage object.
895
896           See also: "add_notification", "get_notification".
897
898       set_notification NAME, SUB
899           Adds SUB to the event NAME notification list. Almost never used
900           directly, but is a key point in enabling the following notification
901           add syntax
902
903              $obj-> onPostMessage( sub { ... });
904
905           or
906
907              $obj-> set( onPostMessage => sub { ... });
908
909           that are shortcuts for
910
911              $obj-> add_notification( "PostMessage", sub { ... });
912
913       unlink_notifier REFERRER
914           Removes all notification subs from all event lists bound to
915           REFERRER object.
916
917   Prima::Component properties
918       AUTOLOAD_DEEP_LOOKUP BOOL
919           If set, autoload component lookup by name uses a breadth-first deep
920           lookup into the object hierarchy.  If unset (default), only
921           immediate children objects are searched.
922
923              $self->AUTOLOAD_DEEP_LOOKUP(0);
924              $self->Child1->GrandChild2;
925              ...
926              $self->AUTOLOAD_DEEP_LOOKUP(1);
927              $self->GrandChild2;
928
929       eventFlag STATE
930           Provides access to the last event processing state in the object
931           event state stack.
932
933           See also: "Success state", "clear_event", "Events".
934
935       delegations [ <REFERRER>, NAME, <NAME>, < <REFERRER>, NAME, ... > ]
936           Accepts an anonymous array in set- context, which consists of a
937           list of event NAMEs, that a REFERRER object ( the caller object by
938           default ) is interested in.  Registers notification entries for
939           routines if subs with naming scheme REFERRER_NAME are present on
940           REFERRER name space.  The example code
941
942              $obj-> name("Obj");
943              $obj-> delegations([ $owner, 'PostMessage']);
944
945           registers Obj_PostMessage callback if it is present in $owner
946           namespace.
947
948           In get- context returns an array reference that reflects the
949           object's delegated events list content.
950
951           See also: "Delegated methods".
952
953       name NAME
954           Maintains object name. NAME can be an arbitrary string, however it
955           is recommended against usage of special characters and spaces in
956           NAME, to facilitate the indirect object access coding style:
957
958              $obj-> name( "Obj");
959              $obj-> owner( $owner);
960              ...
961              $owner-> Obj-> destroy;
962
963           and to prevent system-dependent issues. If the system provides
964           capabilities that allow to predefine some object parameters by its
965           name ( or class), then it is impossible to know beforehand the
966           system naming restrictions.  For example, in X window system the
967           following resource string would make all Prima toolkit buttons
968           green:
969
970             Prima*Button*backColor: green
971
972           In this case, using special characters such as ":" or "*" in the
973           name of an object would make the X resource unusable.
974
975       owner OBJECT
976           Selects an owner of the object, which may be any Prima::Component
977           descendant.  Setting an owner to a object does not alter its
978           reference count. Some classes allow OBJECT to be undef, while some
979           do not. All widget objects can not exist without a valid owner;
980           Prima::Application on the contrary can only exist with owner set to
981           undef. Prima::Image objects are indifferent to the value of the
982           owner property.
983
984           Changing owner dynamically is allowed, but it is a main source of
985           implementation bugs, since the whole hierarchy tree is needed to be
986           recreated.  Although this effect is not visible in perl, the
987           results are deeply system-dependent, and the code that changes
988           owner property should be thoroughly tested.
989
990           Changes to "owner" result in up to three notifications:
991           "ChangeOwner", which is called to the object itself, "ChildLeave",
992           which notifies the previous owner that the object is about to
993           leave, and "ChildEnter", telling the new owner about the new child.
994
995   Prima::Component events
996       ChangeOwner OLD_OWNER
997           Called at runtime when the object changes its owner.
998
999       ChildEnter CHILD
1000           Triggered when a child object is attached, either as a new instance
1001           or as a result of runtime owner change.
1002
1003       ChildLeave CHILD
1004           Triggered when a child object is detached, either because it is
1005           getting destroyed or as a result of runtime owner change.
1006
1007       Create
1008           The first event an event sees. Called automatically after init() is
1009           finished.  Is never called directly.
1010
1011       Destroy
1012           The last event an event sees. Called automatically before done() is
1013           started.  Is never called directly.
1014
1015       PostMessage SCALAR1, SCALAR2
1016           Called after post_message() call is issued, not inside
1017           post_message() but at the next idle event loop.  SCALAR1 and
1018           SCALAR2 are the data passed to post_message().
1019
1020       SysHandle
1021           Sometimes Prima needs to implicitly re-create the system handle of
1022           a component.  The re-creation is not seen on the toolkit level,
1023           except for some repaints when widgets on screen are affected, but
1024           under the hood, when it happens, Prima creates a whole new system
1025           resource. This happens when the underlying system either doesn't
1026           have API to change a certain property during the runtime, or when
1027           such a re-creation happens on one of component's parent, leading to
1028           a downward cascade of children re-creation. Also, it may happen
1029           when the user changes some system settings resolution, so that some
1030           resources have to be changed accordingly.
1031
1032           This event will be only needed when the system handle (that can be
1033           acquired by "get_handle" ) is used further, or in case when Prima
1034           doesn't restore some properties bound to the system handle.
1035

AUTHOR

1037       Dmitry Karasik, <dmitry@karasik.eu.org>.
1038

SEE ALSO

1040       Prima, Prima::internals, Prima::EventHook.
1041
1042
1043
1044perl v5.36.0                      2023-03-20             pod::Prima::Object(3)
Impressum