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-> create( .. 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-> create(
59            parameter => value,
60            parameter => value,
61            ...
62          );
63
64       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
69       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
75                name        => ref $_[ 0],
76                owner       => $::application,
77                delegations => undef,
78
79           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
85                $a1 = Prima::Component-> create();
86
87           $a1's owner will be $::application
88
89                $a2 = Prima::Component-> create( owner => $a1);
90
91           $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
96       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
107           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
116           After profiles gets merged, the resulting hash is passed to the
117           third stage, init().
118
119       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
127           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
132           After init() finishes, create() calls setup() method
133
134       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
140       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
154       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
158   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
163       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
169           "onDestroy" is the last event the object sees. After cleanup() no
170           events are allowed to circulate.
171
172       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
178       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
184   Methods
185       The class methods are declared and used with perl OO syntax, which
186       allow both method of object referencing:
187
188         $object-> method();
189
190       and
191
192         method( $object);
193
194       The actual code is a sub, located under the object class package.  The
195       overloaded methods that call their ancestor code use
196
197         $object-> SUPER::method();
198
199       syntax. Most Prima methods have fixed number of parameters.
200
201   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
212       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
216        sub name
217        {
218           return $_[0]-> {name} unless $#_;
219           $_[0]->{name} = $_[1];
220        }
221
222       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
226         $object-> name( "new name");
227
228       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
232         $object-> name( "new name");
233         $object-> owner( $owner);
234
235       can be rewritten as
236
237         $object-> set(
238            name  => "new name",
239            owner => $owner
240         );
241
242       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
251           $image-> type( $a);
252           $image-> palette( $b);
253
254       and
255
256           $image-> palette( $b);
257           $image-> type( $a);
258
259       produce different results. It is indeed the only solution to call for
260       such a change using
261
262           $image-> set(
263              type => $a,
264              palette => $b
265           );
266
267       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
271       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
277       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
281   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
292       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
297       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
307       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
315       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
319          $obj = Class-> create( owner => $owner, name => 'name);
320
321       more readable by introducing
322
323          $obj = $owner-> insert( 'Class', name => 'name');
324
325       scheme. These two code blocks are identical to each other.
326
327       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

Events

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
345       Prima defines also a non-object event dispatching and filtering
346       mechanism, available through "event_hook" static method.
347
348   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
354         $obj-> notify("PostMessage", $data1, $data2);
355
356       call is issued for all these examples.
357
358       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
365            sub on_postmessage
366            {
367               my ( $self, $data1, $data2) = @_;
368               ...
369            }
370
371           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
378           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
387       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
396              $obj-> delegations([ $owner, 'PostMessage']);
397
398           where the actual callback sub will be
399
400            sub Obj_PostMessage
401            {
402               my ( $self, $obj, $data1, $data2) = @_;
403            }
404
405           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
412           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
419       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
426           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
432           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
439           - during create():
440
441              $obj = Class-> create(
442               ...
443               onPostMessage => sub {
444                  my ( $self, $data1, $data2) = @_;
445               },
446               ...
447               );
448
449           - after create using set()
450
451              $obj-> set( onPostMessage => sub {
452                  my ( $self, $data1, $data2) = @_;
453              });
454
455           - after create using event name:
456
457              $obj-> onPostMessage( sub {
458                  my ( $self, $data1, $data2) = @_;
459              });
460
461           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
467              $obj-> onPostMessage( sub { print "1" });
468              $obj-> onPostMessage( sub { print "2" });
469              $obj-> notify( "PostMessage", 0, 0);
470
471           code block would print
472
473              21
474
475           as the execution result.
476
477           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
480   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
491       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
501       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
509              $obj-> onPostMessage( sub { print "1" });
510              $obj-> onPostMessage( sub { print "2" });
511              $obj-> notify( "PostMessage", 0, 0);
512
513           results in 21, not 12 because PostMessage event type is prototyped
514           "nt::FluxReverse".
515
516       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
524             nt::Single
525             nt::Multiple
526             nt::Event
527
528           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
534           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
538           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
542       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
546         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
553   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
567       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
573       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
580         for ( ... ) {
581            $result = $obj-> notify( "Measure", @parms);
582         }
583
584       can be expressed in more cumbersome, but efficient code if
585       "nt::Single"-prototyped event is used:
586
587          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

API

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
605             print $obj-> name if Prima::Object::alive( $obj);
606
607       cleanup
608           Called right after destroy() started. Used to initiate "cmDestroy"
609           event. Is never called directly.
610
611       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
615              $obj = Class-> create( PARAMETERS);
616              $obj = Prima::Object::create( "class" , PARAMETERS);
617
618           Is never called in an object context.
619
620           Alias: new()
621
622       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
627       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
633           Note: the eventual child objects are destroyed inside done() call.
634
635       get @PARAMETERS
636           Returns hash where keys are @PARAMETERS and values are the
637           corresponding object properties.
638
639       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
647       insert CLASS, %PARAMETERS
648           A convenience wrapper for create(), that explicitly sets the owner
649           property for a newly created object.
650
651              $obj = $owner-> insert( 'Class', name => 'name');
652
653           is adequate to
654
655              $obj = Class-> create( owner => $owner, name => 'name);
656
657           code. insert() has another syntax that allows simultaneous creation
658           of several objects:
659
660              @objects = $owner-> insert(
661                [ 'Class', %parameters],
662                [ 'Class', %parameters],
663                ...
664              );
665
666           With such syntax, all newly created objects would have $owner set
667           to their 'owner' properties.
668
669       new CLASS, %PARAMETERS
670           Same as create.
671
672       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
678       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
685       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
691           Can be called in a context of class.
692
693       raise_ro TEXT
694           Throws an exception with text TEXT when a read-only property is
695           called in a set- context.
696
697       raise_wo TEXT
698           Throws an exception with text TEXT when a write-only property is
699           called in a get- context.
700
701       set %PARAMETERS
702           The default behavior is an equivalent to
703
704             sub set
705             {
706                my $obj = shift;
707                my %PARAMETERS = @_;
708                $obj-> $_( $PARAMETERS{$_}) for keys %PARAMETERS;
709             }
710
711           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
715           As the code above, raises an exception if the key in PARAMETERS has
716           no correspondent object property.
717
718       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
723   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
732           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
738           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
742           See also: "remove_notification", "get_notification".
743
744       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
749           See also: "detach".
750
751       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
757              $obj-> name( "Obj");
758              $obj-> owner( $owner);
759              ...
760              $owner-> Obj-> destroy;
761
762           See also: "find_component"
763
764       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
769       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
774           See also: "Events", "push_event", "pop_event", "::eventFlag",
775           "notify".
776
777       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
781           See also: "attach"
782
783       event_error
784           Issues a system-dependent warning sound signal.
785
786       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
791           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
795           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
799           The method is static, and can be called either with or without
800           class or object as a first parameter.
801
802       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
807           See also: "bring"
808
809       get_components
810           Returns array of the child objects.
811
812           See: "create", "Links between objects".
813
814       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
819           Can be used to pass the handle value outside the program, for an
820           eventual interprocess communication scheme.
821
822       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
828           See also: "remove_notification", "add_notification".
829
830       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
835           See "Success state" for example.
836
837       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
841           Can be called in a context of class.
842
843           See "Events" and "Flow" for details.
844
845       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
851           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
856           Example:
857
858              $obj-> notify( "PostMessage", 0, 1);
859
860           See "Events" and "Flow" for details.
861
862       pop_event
863           Closes event processing stage brackets.
864
865           See "push_event", "Events"
866
867       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
872           See also "post" in Prima::Utils
873
874       push_event
875           Opens event processing stage brackets.
876
877           See "pop_event", "Events"
878
879       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
885           See also: "add_notification", "get_notification".
886
887       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
892              $obj-> onPostMessage( sub { ... });
893
894           or
895
896              $obj-> set( onPostMessage => sub { ... });
897
898           that are shortcuts for
899
900              $obj-> add_notification( "PostMessage", sub { ... });
901
902       unlink_notifier REFERER
903           Removes all notification subs from all event lists bound to REFERER
904           object.
905
906   Prima::Component properties
907       eventFlag STATE
908           Provides access to the last event processing state in the object
909           event state stack.
910
911           See also: "Success state", "clear_event", "Events".
912
913       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
920              $obj-> name("Obj");
921              $obj-> delegations([ $owner, 'PostMessage']);
922
923           registers Obj_PostMessage callback if it is present in $owner
924           namespace.
925
926           In get- context returns an array reference that reflects the
927           object's delegated events list content.
928
929           See also: "Delegated methods".
930
931       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
936              $obj-> name( "Obj");
937              $obj-> owner( $owner);
938              ...
939              $owner-> Obj-> destroy;
940
941           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
948             Prima*Button*backColor: green
949
950           In this case, using special characters such as ":" or "*" in the
951           name of an object would make the X resource unusable.
952
953       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
962           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
968           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
973   Prima::Component events
974       ChangeOwner OLD_OWNER
975           Called at runtime when the object changes its owner.
976
977       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
981       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
985       Create
986           The first event an event sees. Called automatically after init() is
987           finished.  Is never called directly.
988
989       Destroy
990           The last event an event sees. Called automatically before done() is
991           started.  Is never called directly.
992
993       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
998       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
1010           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

AUTHOR

1015       Dmitry Karasik, <dmitry@karasik.eu.org>.
1016

SEE ALSO

1018       Prima, Prima::internals, Prima::EventHook.
1019
1020
1021
1022perl v5.32.1                      2021-01-27             pod::Prima::Object(3)
Impressum