Provided by: libprima-perl_1.28-1.1_amd64 bug

NAME

       Prima::Object - Prima toolkit base classes

SYNOPSIS

           if ( $obj-> isa('Prima::Component')) {

               # set and get a property
               my $name = $obj-> name;
               $obj->name( 'an object' );

               # set a notification callback
               $obj-> onPostMessage( sub {
                   shift;
                   print "hey! I've received this: @_\n";
               });

               # can set multiple properties. note, that 'name' and 'owner',
               # replace the old values, while onPostMessage are aggregated.
               $obj-> set(
                   name => 'AnObject',
                   owner => $new_owner,
                   onPostMessage => sub {
                      shift;
                      print "hey! me too!\n";
                   },
               );

               # de-reference by name
               $new_owner-> AnObject-> post_message(1,2);
           }

DESCRIPTION

       Prima::Object and Prima::Component are the root objects of the Prima toolkit hierarchy.
       All the other objects are derived from the Component class, which in turn is the only
       descendant of Object class. Both of these classes are never used for spawning their
       instances, although this is possible using

          Prima::Component-> create( .. parameters ... );

       call. This document describes the basic concepts of the OO programming with Prima toolkit.
       Although Component has wider functionality than Object, all examples will be explained on
       Component, since Object has no descendant classes and all the functionality of Object is
       present in Component.  Some of the information here can be found in Prima::internals as
       well, the difference is that Prima::internals considers the coding tasks from a C
       programmer's view, whereas this document is wholly about perl programming.

Object base features

   Creation
       Object creation has fixed syntax:

          $new_object = Class-> create(
            parameter => value,
            parameter => value,
            ...
          );

       Parameters and values form a hash, which is passed to the create() method.  This hash is
       applied to a default parameter-value hash ( a profile ), specific to every Prima class.
       The object creation is performed in several stages.

       create
           create() calls profile_default() method that returns ( as its name states ) the
           default profile, a hash with the appropriate default values assigned to its keys.  The
           Component class defaults are ( see Classes.pm ):

                name        => ref $_[ 0],
                owner       => $::application,
                delegations => undef,

           While the exact meaning of these parameters is described later, in "Properties", the
           idea is that a newly created object will have 'owner' parameter set to
           '$::application' and 'delegations' to undef etc etc - unless these parameters are
           explicitly passed to create(). Example:

                $a1 = Prima::Component-> create();

           $a1's owner will be $::application

                $a2 = Prima::Component-> create( owner => $a1);

           $a2's owner will be $a1.  The actual merging of the default and the parameter hashes
           is performed on the next stage, in profile_check_in() method which is called inside
           profile_add() method.

       profile_check_in
           A profile_check_in() method merges the default and the parameter profiles. By default
           all specified parameters have the ultimate precedence over the default ones, but in
           case the specification is incomplete or ambiguous, the profile_check_in()'s task is to
           determine actual parameter values. In case of Component, this method maintains a
           simple automatic naming of the newly created objects. If the object name was not
           specified with create(), it is assigned to a concatenated class name with an integer -
           Component1, Component2 etc.

           Another example can be taken from Prima::Widget::profile_check_in().  Prima::Widget
           horizontal position can be specified by using basic "left" and "width" parameters, and
           as well by auxiliary "right", "size" and "rect".  The default of both "left" and
           "width" is 100. But if only "right" parameter, for example, was passed to create() it
           is profile_check_in() job to determine "left" value, given that "width" is still 100.

           After profiles gets merged, the resulting hash is passed to the third stage, init().

       init
           init() duty is to map the profile content into object, e.g., assign "name" property to
           "name" parameter value, and so on - for all relevant parameters.  After that, it has
           to return the profile in order the overridden subsequent init() methods can perform
           same actions. This stage along with the previous is exemplified in almost all Prima
           modules.

           Note: usually init() attaches the object to its owner in order to keep the newly-
           created object instance from being deleted by garbage-collection mechanisms. More on
           that later ( see "Links between objects").

           After init() finishes, create() calls setup() method

       setup
           setup() method is a convenience function, it is used when some post-init actions must
           be taken. It is seldom overloaded, primarily because the Component::setup() method
           calls "onCreate" notification, which is more convenient to overload than setup().

       As can be noticed from the code pieces above, a successful create() call returns a newly
       created object. If an error condition occurred, undef is returned. It must be noted, that
       only errors that were generated via die() during init() stage result in undef. Other
       errors raise an exception instead.  It is not recommended to frame create() calls in an
       "eval{}" block, because the error conditions can only occur in two situations. The first
       is a system error, either inside perl or Prima guts, and not much can be done here, since
       that error can very probably lead to an unstable program and almost always signals an
       implementation bug. The second reason is a caller's error, when an unexistent parameter
       key or invalid value is passed; such conditions are not subject to a runtime error
       handling as are not the syntax errors.

       After create(), the object is subject to the event flow.  As "onCreate" event is the first
       event the object receives, only after that stage other events can be circulated.

   Destruction
       Object destruction can be caused by many conditions, but all execution flow is finally
       passed through destroy() method.  destroy(), as well as create() performs several
       finalizing steps:

       cleanup
           The first method called inside destroy() is cleanup().  cleanup() is the pair to
           setup(), as destroy() is the pair to create(). cleanup() generates "onDestroy" event,
           which can be overridden more easily than cleanup() itself.

           "onDestroy" is the last event the object sees. After cleanup() no events are allowed
           to circulate.

       done
           done() method is the pair to init(), and is the place where all object resources are
           freed. Although it is as safe to overload done() as init(), it almost never gets
           overloaded, primarily because overloading "onDestroy" is easier.

       The typical conditions that lead to object destructions are direct destroy() call, garbage
       collections mechanisms, user-initiated window close ( on "Prima::Window" only ), and
       exception during init() stage. Thus, one must be careful implementing done() which is
       called after init() throws an exception.

   Methods
       The class methods are declared and used with perl OO syntax, which allow both method of
       object referencing:

         $object-> method();

       and

         method( $object);

       The actual code is a sub, located under the object class package.  The overloaded methods
       that call their ancestor code use

         $object-> SUPER::method();

       syntax. Most Prima methods have fixed number of parameters.

   Properties
       Properties are methods that combine functionality of two ephemeral "get" and "set"
       methods. The idea behind properties is that many object parameters require two independent
       methods, one that returns some internal state and another that changes it.  For example,
       for managing the object name, set_name() and get_name() methods are needed. Indeed, the
       early Prima implementation dealt with large amount of these get's and set's, but later
       these method pairs were deprecated in the favor of properties.  Currently, there is only
       one method name() ( referred as "::name" later in the documentation ).

       The property returns a value if no parameters ( except the object) are passed, and changes
       the internal data to the passed parameters otherwise. Here's a sketch code for "::name"
       property implementation:

        sub name
        {
           return $_[0]-> {name} unless $#_;
           $_[0]->{name} = $_[1];
        }

       There are many examples of properties throughout the toolkit.  Not all properties deal
       with scalar values, some accept arrays or hashes as well.  The properties can be set-
       called not only by name like

         $object-> name( "new name");

       but also with set() method. The set() method accepts a hash, that is much like to
       create(), and assigns the values to the corresponding properties. For example, the code

         $object-> name( "new name");
         $object-> owner( $owner);

       can be rewritten as

         $object-> set(
            name  => "new name",
            owner => $owner
         );

       A minor positive effect of a possible speed-up is gained by eliminating C-to-perl and
       perl-to-C calls, especially if the code called is implemented in C. The negative effect of
       such technique is that the order in which the properties are set, is undefined. Therefore,
       the usage of set() is recommended either when the property order is irrelevant, or it is
       known beforehand that such a call speeds up the code, or is an only way to achieve the
       result. An example of the latter case from Prima::internals shows that Prima::Image calls

           $image-> type( $a);
           $image-> palette( $b);

       and

           $image-> palette( $b);
           $image-> type( $a);

       produce different results. It is indeed the only solution to call for such a change using

           $image-> set(
              type => $a,
              palette => $b
           );

       when it is known beforehand that "Prima::Image::set" is aware of such combinations and
       calls neither "::type" nor "::palette" but performs another image conversion instead.

       Some properties are read-only and some are write-only. Some methods that might be declared
       as properties are not; these are declared as plain methods with get_ or set_ name prefix.
       There is not much certainty about what methods are better off being declared as properties
       and vice versa.

       However, if get_ or set_ methods cannot be used in correspondingly write or read fashion,
       the R/O and W/O properties can. They raise an exception on an attempt to do so.

   Links between objects
       Prima::Component descendants can be used as containers, as objects that are on a higher
       hierarchy level than the others. This scheme is implemented in a child-owner relationship.
       The 'children' objects have the "::owner" property value assigned to a reference to a
       'owner' object, while the 'owner' object conducts the list of its children. It is a one-
       to-many hierarchy scheme, as a 'child' object can have only one owner, but an 'owner'
       object can have many children. The same object can be an owner and a child at the same
       time, so the owner-child hierarchy can be viewed as a tree-like structure.

       Prima::Component::owner property maintains this relation, and is writable - the object can
       change its owner dynamically. There is no corresponding property that manages children
       objects, but is a method get_components(), that returns an array of the child references.

       The owner-child relationship is used in several ways in the toolkit.  For example, the
       widgets that are children of another widget appear ( usually, but not always ) in the
       geometrical interior of the owner widget.  Some events ( keyboard events, for example )
       are propagated automatically up and/or down the object tree. Another important feature is
       that when an object gets destroyed, its children are destroyed first.  In a typical
       program the whole object tree roots in a Prima::Application object instance. When the
       application finishes, this feature helps cleaning up the widgets and quitting gracefully.

       Implementation note: name 'owner' was taken instead of initial 'parent', because the
       'parent' is a fixed term for widget hierarchy relationship description. Prima::Widget
       relationship between owner and child is not the same as GUI's parent-to-child.  The parent
       is the widget for the children widgets located in and clipped by its inferior. The owner
       widget is more than that, its children can be located outside its owner boundaries.

       The special convenience variety of create(), the insert() method is used to explicitly
       select owner of the newly created object. insert() can be considered a 'constructor' in
       OO-terms. It makes the construct

          $obj = Class-> create( owner => $owner, name => 'name);

       more readable by introducing

          $obj = $owner-> insert( 'Class', name => 'name');

       scheme. These two code blocks are identical to each other.

       There is another type of relation, where objects can hold references to each other.
       Internally this link level is used to keep objects from deletion by garbage collection
       mechanisms.  This relation is many-to-many scheme, where every object can have many links
       to other objects. This functionality is managed by attach() and detach() methods.

Events

       Prima::Component descendants employ a well-developed event propagation mechanism, which
       allows handling events using several different schemes.  An event is a condition, caused
       by the system or the user, or an explicit notify() call. The formerly described events
       onCreate and onDestroy are triggered after a new object is created or before it gets
       destroyed. These two events, and the described below onPostMessage are present in
       namespaces of all Prima objects.  New classes can register their own events and define
       their execution flow, using notification_types() method.  This method returns all
       available information about the events registered in a class.

       Prima defines also a non-object event dispatching and filtering mechanism, available
       through "event_hook" static method.

   Propagation
       The event propagation mechanism has three layers of user-defined callback registration,
       that are called in different order and contexts when an event is triggered. The examples
       below show the usage of these layers. It is assumed that an implicit

         $obj-> notify("PostMessage", $data1, $data2);

       call is issued for all these examples.

       Direct methods
           As it is usual in OO programming, event callback routines are declared as methods.
           'Direct methods' employ such a paradigm, so if a class method with name
           "on_postmessage" is present, it will be called as a method ( i.e., in the object
           context ) when "onPostMessage" event is triggered. Example:

            sub on_postmessage
            {
               my ( $self, $data1, $data2) = @_;
               ...
            }

           The callback name is a modified lower-case event name: the name for Create event is
           on_create, PostMessage - on_postmessage etc.  These methods can be overloaded in the
           object's class descendants.  The only note on declaring these methods in the first
           instance is that no "::SUPER" call is needed, because these methods are not defined by
           default.

           Usually the direct methods are used for the internal object book-keeping, reacting on
           the events that are not designed to be passed higher. For example, a Prima::Button
           class catches mouse and keyboard events in such a fashion, because usually the only
           notification that is interesting for the code that employs push-buttons is "Click".
           This scheme is convenient when an event handling routine serves the internal,
           implementation-specific needs.

       Delegated methods
           The delegated methods are used when objects ( mostly widgets ) include other dependent
           objects, and the functionality requires interaction between these.  The callback
           functions here are the same methods as direct methods, except that they get called in
           context of two, not one, objects. If, for example, a $obj's owner, $owner would be
           interested in $obj's PostMessage event, it would register the notification callback by

              $obj-> delegations([ $owner, 'PostMessage']);

           where the actual callback sub will be

            sub Obj_PostMessage
            {
               my ( $self, $obj, $data1, $data2) = @_;
            }

           Note that the naming style is different - the callback name is constructed from object
           name ( let assume that $obj's name is 'Obj') and the event name. ( This is one of the
           reasons why Component::profile_check_in() performs automatic naming of newly created
           onbjects). Note also that context objects are $self ( that equals $owner ) and $obj.

           The delegated methods can be used not only for the owner-child relations. Every Prima
           object is free to add a delegation method to every other object. However, if the
           objects are in other than owner-child relation, it is a good practice to add Destroy
           notification to the object which events are of interest, so if it gets destroyed, the
           partner object gets a message about that.

       Anonymous subroutines
           The two previous callback types are more relevant when a separate class is developed,
           but it is not necessary to declare a new class every time the event handling is
           needed.  It is possible to use the third and the most powerful event hook method using
           perl anonymous subroutines ( subs ) for the easy customization.

           Contrary to the usual OO event implementations, when only one routine per class
           dispatches an event, and calls inherited handlers when it is appropriate, Prima event
           handling mechanism can accept many event handlers for one object ( it is greatly
           facilitated by the fact that perl has anonymous subs, however).

           All the callback routines are called when an event is triggered, one by one in turn.
           If the direct and delegated methods can only be multiplexed by the usual OO
           inheritance, the anonymous subs are allowed to be multiple by the design.  There are
           three syntaxes for setting such a event hook; the example below sets a hook on $obj
           using each syntax for a different situation:

           - during create():

              $obj = Class-> create(
               ...
               onPostMessage => sub {
                  my ( $self, $data1, $data2) = @_;
               },
               ...
               );

           - after create using set()

              $obj-> set( onPostMessage => sub {
                  my ( $self, $data1, $data2) = @_;
              });

           - after create using event name:

              $obj-> onPostMessage( sub {
                  my ( $self, $data1, $data2) = @_;
              });

           As was noted in Prima, the events can be addressed as properties, with the exception
           that they are not substitutive but additive.  The additivity is that when the latter
           type of syntax is used, the subs already registered do not get overwritten or
           discarded but stack in queue. Thus,

              $obj-> onPostMessage( sub { print "1" });
              $obj-> onPostMessage( sub { print "2" });
              $obj-> notify( "PostMessage", 0, 0);

           code block would print

              21

           as the execution result.

           This, it is a distinctive feature of a toolkit is that two objects of same class may
           have different set of event handlers.

   Flow
       When there is more than one handler of a particular event type present on an object, a
       question is risen about what are callbacks call priorities and when does the event
       processing stop. One of ways to regulate the event flow is based on prototyping events, by
       using notification_types() event type description.  This function returns a hash, where
       keys are the event names and the values are the constants that describe the event flow.
       The constant can be a bitwise OR combination of several basic flow constants, that control
       the three aspects of the event flow.

       Order
           If both anonymous subs and direct/delegated methods are present, it must be decided
           which callback class must be called first.  Both 'orders' are useful: for example, if
           it is designed that a class's default action is to be overridden, it is better to call
           the custom actions first. If, on the contrary, the class action is primary, and the
           others are supplementary, the reverse order is preferred. One of two
           "nt::PrivateFirst" and "nt::CustomFirst" constants defines the order.

       Direction
           Almost the same as order, but for finer granulation of event flow, the direction
           constants "nt::FluxNormal" and "nt::FluxReverse" are used. The 'normal flux' defines
           FIFO ( first in first out ) direction. That means, that the sooner the callback is
           registered, the greater priority it would possess during the execution.  The code
           block shown above

              $obj-> onPostMessage( sub { print "1" });
              $obj-> onPostMessage( sub { print "2" });
              $obj-> notify( "PostMessage", 0, 0);

           results in 21, not 12 because PostMessage event type is prototyped "nt::FluxReverse".

       Execution control
           It was stated above that the events are additive, - the callback storage is never
           discarded  when 'set'-syntax is used.  However, the event can be told to behave like a
           substitutive property, e.g. to call one and only one callback.  This functionality is
           governed by "nt::Single" bit in execution control constant set, which consists of the
           following constants:

             nt::Single
             nt::Multiple
             nt::Event

           These constants are mutually exclusive, and may not appear together in an event type
           declaration.  A "nt::Single"-prototyped notification calls only the first ( or the
           last - depending on order and direction bits ) callback. The usage of this constant is
           somewhat limited.

           In contrary of "nt::Single", the "nt::Multiple" constant sets the execution control to
           call all the available callbacks, with respect to direction and order bits.

           The third constant, "nt::Event", is the  impact as "nt::Multiple", except that the
           event flow can be stopped at any time by calling clear_event() method.

       Although there are 12 possible event type combinations, a half of them are not viable.
       Another half were assigned to unique more-less intelligible names:

         nt::Default       ( PrivateFirst | Multiple | FluxReverse)
         nt::Property      ( PrivateFirst | Single   | FluxNormal )
         nt::Request       ( PrivateFirst | Event    | FluxNormal )
         nt::Notification  ( CustomFirst  | Multiple | FluxReverse )
         nt::Action        ( CustomFirst  | Single   | FluxReverse )
         nt::Command       ( CustomFirst  | Event    | FluxReverse )

   Success state
       Events do not return values, although the event generator, the notify() method does - it
       returns either 1 or 0, which is the value of event success state.  The 0 and 1 results in
       general do not mean either success or failure, they simply reflect the fact whether
       clear_event() method was called during the processing - 1 if it was not, 0 otherwise. The
       state is kept during the whole processing stage, and can be accessed from
       Component::eventFlag property. Since it is allowed to call notify() inside event
       callbacks, the object maintains a stack for those states.  Component::eventFlags always
       works with the topmost one, and fails if is called from outside the event processing
       stage. Actually, clear_event() is an alias for ::eventFlag(0) call. The state stack is
       operated by push_event() and pop_event() methods.

       Implementation note: a call of clear_event() inside a "nt::Event"-prototyped event call
       does not automatically stops the execution. The execution stops if the state value equals
       to 0 after the callback is finished.  A ::eventFlag(1) call thus cancels the effect of
       clear_event().

       A particular coding style is used when the event is "nt::Single"-prototyped and is called
       many times in a row, so overheads of calling notify() become a burden. Although notify()
       logic is somewhat complicated, it is rather simple with "nt::Single" case. The helper
       function get_notify_sub() returns the context of callback to-be-called, so it can be used
       to emulate notify() behavior.  Example:

         for ( ... ) {
            $result = $obj-> notify( "Measure", @parms);
         }

       can be expressed in more cumbersome, but efficient code if "nt::Single"-prototyped event
       is used:

          my ( $notifier, @notifyParms) = $obj-> get_notify_sub( "Measure" );
          $obj-> push_event;
          for ( ... ) {
              $notifier-> ( @notifyParms, @parms);
              # $result = $obj-> eventFlag; # this is optional
          }
          $result = $obj-> pop_event;

API

   Prima::Object methods
       alive
           Returns the object 'vitality' state - true if the object is alive and usable, false
           otherwise.  This method can be used as a general checkout if the scalar passed is a
           Prima object, and if it is usable.  The true return value can be 1 for normal and
           operational object state, and 2 if the object is alive but in its init() stage.
           Example:

             print $obj-> name if Prima::Object::alive( $obj);

       can NAME, CACHE = 1
           Checks if an object namespace contains a NAME method.  Returns the code reference to
           it, if found, and undef if not.  If CACHE is true, caches the result to speed-up
           subsequent calls.

       cleanup
           Called right after destroy() started. Used to initiate "cmDestroy" event. Is never
           called directly.

       create CLASS, %PARAMETERS
           Creates a new object instance of a given CLASS and sets its properties corresponding
           to the passed parameter hash. Examples:

              $obj = Class-> create( PARAMETERS);
              $obj = Prima::Object::create( "class" , PARAMETERS);

           Is never called in an object context.

           Alias: new()

       destroy
           Initiates the object destruction. Perform in turn cleanup() and done() calls.
           destroy() can be called several times and is the only Prima re-entrant function,
           therefore may not be overloaded.

       done
           Called by destroy() after cleanup() is finished. Used to free the object resources, as
           a finalization stage.  During done() no events are allowed to circulate, and alive()
           returns 0. The object is not usable after done() finishes. Is never called directly.

           Note: the eventual child objects are destroyed inside done() call.

       get @PARAMETERS
           Returns hash where keys are @PARAMETERS and values are the corresponding object
           properties.

       init %PARAMETERS
           The most important stage of object creation process.  %PARAMETERS is the modified hash
           that was passed to create().  The modification consists of merging with the result of
           profile_default() class method inside profile_check_in() method. init() is responsible
           for applying the relevant data into PARAMETERS to the object properties. Is never
           called directly.

       insert CLASS, %PARAMETERS
           A convenience wrapper for create(), that explicitly sets the owner property for a
           newly created object.

              $obj = $owner-> insert( 'Class', name => 'name');

           is adequate to

              $obj = Class-> create( owner => $owner, name => 'name);

           code. insert() has another syntax that allows simultaneous creation of several
           objects:

              @objects = $owner-> insert(
                [ 'Class', %parameters],
                [ 'Class', %parameters],
                ...
              );

           With such syntax, all newly created objects would have $owner set to their 'owner'
           properties.

       new CLASS, %PARAMETERS
           Same as create.

       profile_add PROFILE
           The first stage of object creation process.  PROFILE is a reference to a PARAMETERS
           hash, passed to create().  It is merged with profile_default() after passing both to
           profile_check_in(). The merge result is stored back in PROFILE.  Is never called
           directly.

       profile_check_in CUSTOM_PROFILE, DEFAULT_PROFILE
           The second stage of object creation process.  Resolves eventual ambiguities in
           CUSTOM_PROFILE, which is the reference to PARAMETERS passed to create(), by comparing
           to and using default values from DEFAULT_PROFILE, which is the result of
           profile_default() method. Is never called directly.

       profile_default
           Returns hash of the appropriate default values for all properties of a class.  In
           object creation process serves as a provider of fall-back values, and is called
           implicitly. This method can be used directly, contrary to the other creation process-
           related functions.

           Can be called in a context of class.

       raise_ro TEXT
           Throws an exception with text TEXT when a read-only property is called in a set-
           context.

       raise_wo TEXT
           Throws an exception with text TEXT when a write-only property is called in a get-
           context.

       set %PARAMETERS
           The default behavior is an equivalent to

             sub set
             {
                my $obj = shift;
                my %PARAMETERS = @_;
                $obj-> $_( $PARAMETERS{$_}) for keys %PARAMETERS;
             }

           code. Assigns object properties correspondingly to PARAMETERS hash.  Many
           Prima::Component descendants overload set() to make it more efficient for particular
           parameter key patterns.

           As the code above, raises an exception if the key in PARAMETERS has no correspondent
           object property.

       setup
           The last stage of object creation process.  Called after init() finishes. Used to
           initiate "cmCreate" event. Is never called directly.

   Prima::Component methods
       add_notification NAME, SUB, REFERER = undef, INDEX = -1
           Adds SUB to the list of notification of event NAME.  REFERER is the object reference,
           which is used to create a context to SUB and is passed as a parameter to it when
           called.  If REFERER is undef ( or not specified ), the same object is assumed. REFERER
           also gets implicitly attached to the object, - the implementation frees the link
           between objects when one of these gets destroyed.

           INDEX is a desired insert position in the notification list.  By default it is -1,
           what means 'in the start'. If the notification type contains nt::FluxNormal bit set,
           the newly inserted SUB will be called first. If it has nt::FluxReverse, it is called
           last, correspondingly.

           Returns positive integer value on success, 0 on failure.  This value can be later used
           to refer to the SUB in remove_notification().

           See also: "remove_notification", "get_notification".

       attach OBJECT
           Inserts OBJECT to the attached objects list and increases OBJECT's reference count.
           The list can not hold more than one reference to the same object. The warning is
           issued on such an attempt.

           See also: "detach".

       bring NAME
           Looks for a immediate child object that has name equals to NAME.  Returns its
           reference on success, undef otherwise. It is a convenience method, that makes possible
           the usage of the following constructs:

              $obj-> name( "Obj");
              $obj-> owner( $owner);
              ...
              $owner-> Obj-> destroy;

       can_event
           Returns true if the object event circulation is allowed.  In general, the same as
           "alive() == 1", except that can_event() fails if an invalid object reference is
           passed.

       clear_event
           Clears the event state, that is set to 1 when the event processing begins.  Signals
           the event execution stop for nt::Event-prototyped events.

           See also: "Events", "push_event", "pop_event", "::eventFlag", "notify".

       detach OBJECT, KILL
           Removes OBJECT from the attached objects list and decreases OBJECT's reference count.
           If KILL is true, destroys OBJECT.

           See also: "attach"

       event_error
           Issues a system-dependent warning sound signal.

       event_hook [ SUB ]
           Installs a SUB to receive all events on all Prima objects.  SUB receives same
           parameters passed to notify, and must return an integer, either 1 or 0, to pass or
           block the event respectively.

           If no SUB is set, returns currently installed event hook pointer.  If SUB is set,
           replaces the old hook sub with SUB. If SUB is 'undef', event filtering is not used.

           Since the 'event_hook' mechanism allows only one hook routine to be installed at a
           time, direct usage of the method is discouraged.  Instead, use Prima::EventHook for
           multiplexing of the hook access.

           The method is static, and can be called either with or without class or object as a
           first parameter.

       get_components
           Returns array of the child objects.

           See: "create", "Links between objects".

       get_handle
           Returns a system-dependent handle for the object.  For example, Prima::Widget return
           its system WINDOW/HWND handles, Prima::DeviceBitmap - its system PIXMAP/HBITMAP
           handles, etc.

           Can be used to pass the handle value outside the program, for an eventual interprocess
           communication scheme.

       get_notification NAME, @INDEX_LIST
           For each index in INDEX_LIST return three scalars, bound at the index position in the
           NAME event notification list.  These three scalars are REFERER, SUB and ID. REFERER
           and SUB are those passed to "add_notification", and ID is its result.

           See also: "remove_notification", "add_notification".

       get_notify_sub NAME
           A convenience method for nt::Single-prototyped events.  Returns code reference and
           context for the first notification sub for event NAME.

           See "Success state" for example.

       notification_types
           Returns a hash, where the keys are the event names and the values are the "nt::"
           constants that describe the event flow.

           Can be called in a context of class.

           See "Events" and "Flow" for details.

       notify NAME, @PARAMETERS
           Calls the subroutines bound to the event NAME with parameters @PARAMETERS in context
           of the object.  The calling order is described by "nt::" constants, contained in the
           notification_types() result hash.

           notify() accepts variable number of parameters, and while it is possible, it is not
           recommended to call notify() with the exceeding number of parameters; the call with
           the deficient number of parameters results in an exception.

           Example:

              $obj-> notify( "PostMessage", 0, 1);

           See "Events" and "Flow" for details.

       pop_event
           Closes event processing stage brackets.

           See "push_event", "Events"

       post_message SCALAR1, SCALAR2
           Calls "PostMessage" event with parameters SCALAR1 and SCALAR2 once during idle event
           loop. Returns immediately.  Does not guarantee that "PostMessage" will be called,
           however.

           See also "post" in Prima::Utils

       push_event
           Opens event processing stage brackets.

           See "pop_event", "Events"

       remove_notification ID
           Removes a notification subroutine that was registered before with "add_notification",
           where ID was its result. After successful removal, the eventual context object gets
           implicitly detached from the storage object.

           See also: "add_notification", "get_notification".

       set_notification NAME, SUB
           Adds SUB to the event NAME notification list. Almost never used directly, but is a key
           point in enabling the following notification add syntax

              $obj-> onPostMessage( sub { ... });

           or

              $obj-> set( onPostMessage => sub { ... });

           that are shortcuts for

              $obj-> add_notification( "PostMessage", sub { ... });

       unlink_notifier REFERER
           Removes all notification subs from all event lists bound to REFERER object.

   Prima::Component properties
       eventFlag STATE
           Provides access to the last event processing state in the object event state stack.

           See also: "Success state", "clear_event", "Events".

       delegations [ <REFERER>, NAME, <NAME>, < <REFERER>, NAME, ... > ]
           Accepts an anonymous array in set- context, which consists of a list of event NAMEs,
           that a REFERER object ( the caller object by default ) is interested in.  Registers
           notification entries for routines if subs with naming scheme REFERER_NAME are present
           on REFERER name space.  The example code

              $obj-> name("Obj");
              $obj-> delegations([ $owner, 'PostMessage']);

           registers Obj_PostMessage callback if it is present in $owner namespace.

           In get- context returns an array reference that reflects the object's delegated events
           list content.

           See also: "Delegated methods".

       name NAME
           Maintains object name. NAME can be an arbitrary string, however it is recommended
           against usage of special characters and spaces in NAME, to facilitate the indirect
           object access coding style:

              $obj-> name( "Obj");
              $obj-> owner( $owner);
              ...
              $owner-> Obj-> destroy;

           and to prevent system-dependent issues. If the system provides capabilities that allow
           to predefine some object parameters by its name ( or class), then it is impossible to
           know beforehand the system naming restrictions.  For example, in X window system the
           following resource string would make all Prima toolkit buttons green:

             Prima*Button*backColor: green

           In this case, using special characters such as ":" or "*" in the name of an object
           would make the X resource unusable.

       owner OBJECT
           Selects an owner of the object, which may be any Prima::Component descendant.  Setting
           an owner to a object does not alter its reference count. Some classes allow OBJECT to
           be undef, while some do not. All widget objects can not exist without a valid owner;
           Prima::Application on the contrary can only exist with owner set to undef.
           Prima::Image objects are indifferent to the value of the owner property.

           Changing owner dynamically is allowed, but it is a main source of implementation bugs,
           since the whole hierarchy tree is needed to be recreated.  Although this effect is not
           visible in perl, the results are deeply system-dependent, and the code that changes
           owner property should be thoroughly tested.

           Changes to "owner" result in up to three notifications: "ChangeOwner", which is called
           to the object itself, "ChildLeave", which notifies the previous owner that the object
           is about to leave, and "ChildEnter", telling the new owner about the new child.

   Prima::Component events
       ChangeOwner OLD_OWNER
           Called at runtime when the object changes its owner.

       ChildEnter CHILD
           Triggered when a child object is attached, either as a new instance or as a result of
           runtime owner change.

       ChildLeave CHILD
           Triggered when a child object is detached, either because it is getting destroyed or
           as a result of runtime owner change.

       Create
           The first event an event sees. Called automatically after init() is finished.  Is
           never called directly.

       Destroy
           The last event an event sees. Called automatically before done() is started.  Is never
           called directly.

       PostMessage SCALAR1, SCALAR2
           Called after post_message() call is issued, not inside post_message() but at the next
           idle event loop.  SCALAR1 and SCALAR2 are the data passed to post_message().

AUTHOR

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

SEE ALSO

       Prima, Prima::internals, Prima::EventHook.