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