path: root/src/lib/eo/efl_object.eo

import eina_types;

struct Efl.Event_Description {
    [[This struct holds the description of a specific event.]]
    name: string; [[name of the event.]]
    unfreezable: bool; [[$true if the event cannot be frozen.]]
    legacy_is: bool; [[Internal use: $true if a legacy event.]]
    restart: bool; [[$true if when the event is triggered again from a callback it'll start from where it was]]
}

abstract Efl.Object
{
   [[Abstract Efl object class]]
   eo_prefix: efl;

   methods {
      @property parent {
         [[The parent of an object.

           Parents keep references to their children. In order to
           delete objects which have parents you need to set parent to
           NULL or use efl_del(). This will both delete & unref
           the object).

           The Eo parent is conceptually user set. That means that a parent
           should not be changed behind the scenes in an unexpected way.

           For example:
           If you have a widget that has a box internally and
           when you 'swallow' a widget and the swallowed object ends up in
           the box, the parent should be the widget, not the box.
         ]]

         set {
         }
         get {
         }
         values {
            parent: Efl.Object @nullable; [[The new parent]]
         }
      }
      @property name {
         [[ The name of the object.

           Every object can have a string name. Names may not contain
           the following characters:
             / ? * [ ] ! \ :
           Using any of these in a name will result in undefined
           behavior later on. An empty string is considered the same as a
           NULL string or no string for the name.
         ]]
         set {
         }
         get {
         }
         values {
           name: string @nullable; [[The name]]
         }
      }
      @property comment {
         [[ A human readable comment for the object

           Every object can have a string comment. This is intended for developers
           and debugging. An empty string is considered the same as a NULL
           string or no string for the comment.
         ]]
         set {
         }
         get {
         }
         values {
           comment: string @nullable; [[The comment]]
         }
      }
      debug_name_override {
         [[ Build a read-only name for this object used for debugging.

            Multiple calls using efl_super() can be chained in order to build
            the entire debug name, from parent to child classes. In C the usual
            way to build the string is as follows:

            efl_debug_name_override(efl_super(obj, MY_CLASS), sb);
            eina_strbuf_append_printf(sb, "new_information");

            Usually more debug information should be added to $sb after
            calling the super function.

            @since 1.21
         ]]
         params {
            @in sb: ptr(Eina.Strbuf); [[A string buffer, must not be $null.]]
         }
      }
      @property event_global_freeze_count @class {
         get {
            [[Return freeze events of object.

              Return event freeze count.
            ]]
         }
         values {
            fcount: int; [[The event freeze count of the object]]
         }
      }
      @property event_freeze_count {
         get {
            [[Return freeze events of object.

              Return event freeze count.
            ]]
         }
         values {
            fcount: int; [[The event freeze count of the object]]
         }
      }
      @property finalized {
         [[True if the object is already finalized, otherwise false.]]
         get {
         }
         values {
            finalized: bool; [[$true if the object is finalized, $false otherwise]]
         }
      }
      @property invalidated {
         [[True if the object is already invalidated, otherwise false.]]
         get {
         }
         values {
            finalized: bool; [[$true if the object is invalidated, $false otherwise]]
         }
      }
      @property invalidating {
         [[True if the object is about to be invalidated, and the invalidation of the children is already happening.

           Note this is true before the invalidate call on the object.
         ]]
         get {
         }
         values {
            invalidating: bool; [[$true if the object is invalidating, $false otherwise]]
         }
      }
      provider_find @const {
        [[Searches upwards in the object tree for a provider which knows the given class/interface.

          The object from the provider will then be returned.
          The base implementation calls the provider_find function on the object parent,
          and returns its result. If no parent is present NULL is returned.
          Each implementation has to support this function by overriding
          it and returning itself if the interface matches the parameter.
          If this is not done the class cannot be found up in the object tree.
        ]]
        params {
          klass : const(Efl.Object); [[The class identifier to search for]]
        }
        return : Efl.Object; [[Object from the provider list]]
      }
      constructor {
         [[Call the object's constructor.

           Should not be used with #eo_do. Only use it with #eo_do_super.
         ]]
         return: Efl.Object; [[The new object created, can be NULL if aborting]]
      }
      destructor {
         [[Call the object's destructor.

           Should not be used with #efl_do. Only use it with #efl_do_super.
	   Will be triggered once #invalidate and #noref have been triggered.
         ]]
      }
      finalize {
         [[Called at the end of efl_add. Should not be called, just overridden.]]
         return: Efl.Object; [[The new object created, can be NULL if aborting]]
      }
      invalidate {
         [[Called when parent reference is lost/set to $NULL and switch the state of the object to invalidate.]]
      }
      noref {
         [[Triggered when no reference are keeping the object alive.

           The parent can be the last one keeping an object alive and so $noref can happen before $invalidate
           as it is only impacted by the ref/unref of the object.]]
      }
      name_find @const {
         [[Find a child object with the given name and return it.

           The search string can be a glob (shell style, using *). It can also
           specify class name in the format of "class:name" where ":"
           separates class and name. Both class and name can be globs.
           If the class is specified but the name is empty like "class:" then
           the search will match any object of that class.
         ]]
         params {
            @in search: string; [[The name search string]]
         }
         return: Efl.Object; [[The first object found]]
      }
      event_thaw {
         [[Thaw events of object.

           Allows event callbacks to be called for an object.
         ]]
      }
      event_freeze {
         [[Freeze events of object.

           Prevents event callbacks from being called for an object.
         ]]
      }
      event_global_thaw @class {
         [[Thaw events of object.

           Allows event callbacks be called for an object.
         ]]
      }
      event_global_freeze @class {
         [[Freeze events of object.

           Prevents event callbacks from being called for an object.
         ]]
      }
      event_callback_stop {
         [[Stop the current callback call.

           This stops the current callback call. Any other callbacks for the
           current event will not be called. This is useful when you want to
           filter out events. Just add higher priority events and call this
           under certain conditions to block a certain event.
         ]]
      }
      event_callback_forwarder_add {
         [[Add an event callback forwarder for an event and an object.]]
         params {
            @cref desc: Efl.Event_Description; [[The description of the event to listen to]]
            @in new_obj: Efl.Object; [[The object to emit events from]]
         }
      }
      event_callback_forwarder_del {
         [[Remove an event callback forwarder for an event and an object.]]
         params {
            @cref desc: Efl.Event_Description; [[The description of the event to listen to]]
            @in new_obj: Efl.Object; [[The object to emit events from]]
         }
      }
      children_iterator_new {
         [[Get an iterator on all childrens]]
         return: iterator<Efl.Object> @owned @warn_unused; [[Children iterator]]
      }
      composite_attach {
           [[Make an object a composite object of another.

             The class of comp_obj must be part of the extensions of the class of the parent.
             It isn't possible to attach more then 1 composite of the same class.
             This function also sets the parent of comp_obj to parent.

             See @.composite_detach, @.composite_part_is.
           ]]
           params {
                @in comp_obj: Efl.Object; [[the object that will be used to composite the parent.]]
           }
           return: bool; [[$true if successful. $false otherwise.]]
      }
      composite_detach {
           [[Detach a composite object from another object.

             This functions also sets the parent of comp_obj to $null.

             See @.composite_attach, @.composite_part_is.
           ]]
           params {
                @in comp_obj: Efl.Object; [[The object that will be removed from the parent.]]
           }
           return: bool; [[$true if successful. $false otherwise.]]
      }
      composite_part_is {
           [[Check if an object is part of a composite object.

             See @.composite_attach, @.composite_part_is.
           ]]
           return: bool; [[$true if it is. $false otherwise.]]
      }
      @property allow_parent_unref {
         [[Allow an object to be deleted by unref even if it has a parent.

           This simply hides the error message warning that an object being
           destroyed still has a parent. This property is false by default.

           In a normal object use case, when ownership of an object is given
           to a caller, said ownership should be released with efl_unref().
           If the object has a parent, this will print error messages, as
           $efl_unref() is stealing the ref from the parent.

           Warning: Use this function very carefully, unless you're absolutely
           sure of what you are doing.
         ]]
         values {
            allow: bool(false); [[Whether to allow $efl_unref() to zero
               even if @.parent is not $null.]]
         }
      }
   }
   implements {
        class.constructor;
        class.destructor;
   }
   events {
      del @hot: void; [[Object is being deleted.]]
      invalidate @hot: void; [[Object is being invalidated and loosing its parent.]]
      noref @hot: void; [[Object has lost its last reference, only parent relationship is keeping it alive.]]
      destruct @hot: void; [[Object has been fully destroyed. It can not be used
         beyond this point. This event should only serve to clean up any
         dangling pointer.]]
   }
}

struct Efl.Event {
    [[A parameter passed in event callbacks holding extra event parameters.

      This is the full event information passed to callbacks in C.
    ]]
    object: Efl.Object; [[The object the callback was called on.]]
    desc: const(ptr(Efl.Event_Description)); [[The event description.]]
    info: void_ptr; [[Extra event information passed by the event caller]]
}