efl/src/lib/eo/eo_base.eo

import eina_types;

struct Eo.Event_Description {
    [[This struct holds the description of a specific event.]]
    name: const(char) *; [[name of the event.]]
    unfreezable: bool; [[Eina_True if the event cannot be frozen.]]
    legacy_is: bool; [[Internal use: if is a legacy event.]]
    restart: bool; [[Eina_True if when the event is triggered again from a callback, it should start from where it was]]
}

struct Eo.Event {
     [[Parameter passed in event callbacks holding extra event parameters]]
     obj: Eo.Base *; [[The object the event was called on.]]
     desc: const(Eo.Event_Description) *; [[The event description.]]
     info: void *; [[Extra event information passed by the event caller.]]
}

type Eo.Event_Cb: __builtin_event_cb; [[An event callback prototype.
    return $EO_CALLBACK_STOP to stop calling additional callbacks for the event, $EO_CALLBACK_CONTINUE to continue.]]


struct Eo.Callback_Array_Item {
    [[An item in an array of callback desc/func.

      See also \@ref eo_event_callback_array_add.
    ]]
    desc: const(Eo.Event_Description) *; [[The event description.]]
    func: Eo.Event_Cb; [[The callback function.]]
}

struct Eo.Dbg_Info {
     [[The structure for the debug info used by Eo.]]
     name: Eina.Stringshare *; [[The name of the part (stringshare).]]
     value: generic_value; [[The value.]]
}


type Eo.Callback_Priority: short; [[Callback priority value. Range is -32k - 32k.
                                    The lower the number, the higher the priority.

                                    See \@ref EO_CALLBACK_PRIORITY_AFTER,
                                    \@ref EO_CALLBACK_PRIORITY_BEFORE
                                    \@ref EO_CALLBACK_PRIORITY_DEFAULT
                                  ]]

abstract Eo.Base ()
{
   eo_prefix: eo;
   legacy_prefix: null;

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

           Parents keep references to their children so in order to
           delete objects that have parents you need to set parent to
           NULL or use eo_del() that does that for you (and also unrefs
           the object).

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

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

         set {
         }
         get {
         }
         values {
            parent: Eo.Base * @nullable; [[the new parent]]
         }
      }
      del @const {
         [[Unrefs the object and reparents it to NULL.

           Because eo_del() unrefs and reparents to NULL, it doesn't really delete the object.

           This method accepts a const object for convenience, so all objects
           could be passed to it easily.
         ]]
      }
      @property id {
         [[ The id/name of the object.

           Every object can have a string name. Names may not contain
           the following charactors:
             / ? * [ ] ! \ :
           They are illegal. Using it 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/id at all.
         ]]
         set {
         }
         get {
         }
         values {
           id: const(char)* @nullable; [[the id/name]]
         }
      }
      @property comment {
         [[ A human readable comment for the object

           Every object can have a string comment intended for developers
           and debugging. An empty string is considered the same as a NULL
           string or no string for the comment at all.
         ]]
         set {
         }
         get {
         }
         values {
           comment: const(char)* @nullable; [[the comment]]
         }
      }
      @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, false otherwise.]]
         get {
         }
         values {
            finalized: bool;
         }
      }
      @property loop {
         [[The owning loop object.

           Objects that have anything to do with I/O, time based events
           or anything async should have an owining loop. They will ask
           their parent for the owning loop and iterate until the
           toplevel/root object. The root object should be a loop object
           which will return itself. Some objects may shortcut this
           and be fixed to live in only a single loop. Either way all
           you need to do is get the loop for an object and use that
           for I/O, timing etc. needs.
         ]]
         get {
         }
         values {
            obj: Eo.Base *; [[ XXX: this should be Efl.Loop *; ]]
         }
      }
      constructor {
         [[Call the object's constructor.

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

           Should not be used with #eo_do. Only use it with #eo_do_super.
         ]]
      }
      finalize {
         [[Called at the end of #eo_add. Should not be called, just overridden.]]
         return: Eo.Base *; [[The new object created, can be NULL if aborting]]
      }
      id_find {
         [[Find a child object with the given name/id and return it.
           The search string can be a glob (shell style). 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 class is specified, and name is empty like "class:" then
           the search will match any object of that class.
         ]]
         params {
            @in search: const(char)*; [[the name/id search string]]
         }
         return: Eo.Base *; [[the first object found]]
      }
      wref_add {
         [[Add a new weak reference to obj.

           This function registers the object handle pointed by wref to
           obj so when obj is deleted it'll be updated to NULL. This
           functions should be used when you want to keep track of an
           object in a safe way, but you don't want to prevent it from
           being freed.
         ]]
         params {
            @out wref: Eo.Base *;
         }
      }
      wref_del {
         [[Delete the weak reference passed.]]
         params {
            @in wref: Eo.Base **;
         }
      }
      key_data_set {
         [[Set generic data to object.

           The user is in change to free the data.
         ]]
         params {
            @in key: const(char)*; [[the key associated with the data]]
            @in data: const(void)*; [[the data to set]]
         }
      }
      key_data_get @const {
         [[Get generic data from object.]]
         params {
            @in key: const(char)*; [[the key associated with the data]]
         }
         return: void *; [[the data for the key]]
      }
      key_del {
         [[Del generic data from object.]]
         params {
            @in key: const(char)*; [[the key associated with the data]]
         }
      }
      key_obj_set {
         [[Set generic object reference to object.

           The object will be automatically ref'd when set and unref'd
           when replaced or deleted or referring object is deleted. If
           the referenced object is deleted then the key is deleted
           automatically.

           This is the same key store used by key_data_set etc. so keys
           are shared and can store only one thing
         ]]
         params {
            @in key: const(char)*; [[the key associated with the object ref]]
            @in objdata: Eo.Base *; [[the object to set]]
         }
      }
      key_obj_get @const {
         [[Get generic object reference from object.]]
         params {
            @in key: const(char)*; [[the key associated with the object ref]]
         }
         return: Eo.Base *; [[the object reference for the key]]
      }
      key_value_set {
         [[Set value on the object.

           This stores the value with the given string key on the object
           and it will be freed when replaced or deleted or the referring
           object is deleted.

           This is the same key store used by key_data_set and key_obj_set
           etc. so keys are shared and can store only one thing
         ]]
         params {
            @in key: const(char)*; [[the key associated with the value]]
            @in value: Eina.Value *; [[the value to set]]
         }
      }
      key_value_get @const {
         [[Get generic value from object.]]
         params {
            @in key: const(char)*; [[the key associated with the value]]
         }
         return: Eina.Value *; [[the value for the key]]
      }
      event_thaw {
         [[thaw events of object.

           Lets event callbacks be called for the object.
         ]]
      }
      event_freeze {
         [[freeze events of object.

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

           Lets event callbacks be called for the object.
         ]]
      }
      event_global_freeze @class {
         [[freeze events of object.

           Prevents event callbacks from being called for the object.
         ]]
      }
      event_callback_priority_add {
         [[Add a callback for an event with a specific priority.

           callbacks of the same priority are called in reverse order of
           creation.
         ]]
         return: bool; [[Return true when the callback has been successfully added.]]
         params {
            @in desc: const(Eo.Event_Description)*; [[The description of the event to listen to]]
            @in priority: Eo.Callback_Priority; [[The priority of the callback]]
            @in cb: Eo.Event_Cb; [[the callback to call]]
            @in data: const(void)*; [[additional data to pass to the callback]]
         }
      }
      event_callback_del {
         [[Del a callback with a specific data associated to it for an event.]]
         return: bool; [[Return true when the callback has been successfully removed.]]
         params {
            @in desc: const(Eo.Event_Description)*; [[The description of the event to listen to]]
            @in func: Eo.Event_Cb; [[the callback to delete]]
            @in user_data: const(void)*; [[The data to compare]]
         }
      }
      event_callback_array_priority_add {
         [[Add a callback array for an event with a specific priority.

           callbacks of the same priority are called in reverse order of
           creation.
         ]]
         return: bool; [[Return true when the callback has been successfully added.]]
         params {
            @in array: const(Eo.Callback_Array_Item)*; [[an #Eo_Callback_Array_Item of events to listen to]]
            @in priority: Eo.Callback_Priority; [[The priority of the callback]]
            @in data: const(void)*; [[additional data to pass to the callback]]
         }
      }
      event_callback_array_del {
         [[Del a callback array with a specific data associated to it for an
           event.
         ]]
         return: bool; [[Return true when the callback has been successfully removed.]]
         params {
            @in array: const(Eo.Callback_Array_Item)*; [[an #Eo_Callback_Array_Item of events to listen to]]
            @in user_data: const(void)*; [[The data to compare]]
         }
      }
      event_callback_call {
         [[Call the callbacks for an event of an object.]]
         params {
            @in desc: const(Eo.Event_Description)*; [[The description of the event to call]]
            @in event_info: void *; [[Extra event info to pass to the callbacks]]
         }
         return: bool; [[$true if one of the callbacks aborted the call,
                         $false otherwise
                       ]]
      }
      event_callback_forwarder_add {
         [[Add an event callback forwarder for an event and an object.]]
         params {
            @in desc: const(Eo.Event_Description)*; [[The description of the event to listen to]]
            @in new_obj: Eo.Base *; [[The object to emit events from]]
         }
      }
      event_callback_forwarder_del {
         [[Remove an event callback forwarder for an event and an object.]]
         params {
            @in desc: const(Eo.Event_Description)*; [[The description of the event to listen to]]
            @in new_obj: Eo.Base *; [[The object to emit events from]]
         }
      }
      dbg_info_get {
         [[Get dbg information from the object.]]
         params {
            @in root_node: Eo.Dbg_Info*; [[node of the tree]]
         }
      }
      children_iterator_new {
         [[Get an iterator on all childrens]]
         return: free(own(iterator<Eo.Base *> *), eina_iterator_free) @warn_unused;
      }
      composite_attach @beta {
           [[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 is not possible to attach more then 1 composite of the same class.
             This functions also sets the parent of comp_obj to parent.

             See @.composite_detach, @.composite_part_is.
           ]]
           params {
                @in comp_obj: Eo.Base *; [[the object that will be used to composite the parent.]]
           }
           return: bool; [[$true if successful. $false otherwise.]]
      }
      composite_detach @beta {
           [[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: Eo.Base *; [[the object that will be removed from the parent.]]
           }
           return: bool; [[$true if successful. $false otherwise.]]
      }
      composite_part_is @beta {
           [[Check if an object is part of a composite object.

             See @.composite_attach, @.composite_part_is.
           ]]
           return: bool; [[$true if it is. $false otherwise.]]
      }
   }
   implements {
        class.constructor;
        class.destructor;
   }
   events {
      callback,add @hot; [[A callback was added.]]
      callback,del @hot; [[A callback was deleted.]]
      del @hot; [[Obj is being deleted.]]
   }
}