forked from enlightenment/efl
453 lines
19 KiB
Plaintext
453 lines
19 KiB
Plaintext
struct Efl.Event_Description {
|
|
[[This struct holds the description of a specific event.
|
|
|
|
@since 1.22
|
|
]]
|
|
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]]
|
|
}
|
|
|
|
|
|
type Efl.Callback_Priority : short;
|
|
[[
|
|
Callback priority. Range is -32k - 32k. The lower the number, the higher the priority.
|
|
|
|
This is used to insert an event handler relative to the existing stack of sorted event
|
|
handlers according to that priority. All event handlers always have a priority. If not
|
|
specified @Efl.Callback_Priority_Default is to be assumed.
|
|
|
|
See @Efl.Callback_Priority_Before @Efl.Callback_Priority_Default @Efl.Callback_Priority_After
|
|
|
|
@since 1.22
|
|
]]
|
|
|
|
const Efl.Callback_Priority_Before : Efl.Callback_Priority = -100;
|
|
[[Slightly more prioritized than default.
|
|
|
|
@since 1.22
|
|
]]
|
|
const Efl.Callback_Priority_Default : Efl.Callback_Priority = 0;
|
|
[[Default priority.
|
|
|
|
@since 1.22
|
|
]]
|
|
const Efl.Callback_Priority_After : Efl.Callback_Priority = 100;
|
|
[[Slightly less prioritized than default.
|
|
|
|
@since 1.22
|
|
]]
|
|
|
|
abstract Efl.Object
|
|
{
|
|
[[Abstract EFL object class.
|
|
|
|
All EFL objects inherit from this class, which provides basic functionality
|
|
like naming, debugging, hierarchy traversal, event emission and life cycle
|
|
management.
|
|
|
|
Life Cycle
|
|
Objects are created with efl_add() and mostly disposed of with efl_del().
|
|
As an optimization, efl_add() accepts a list of initialization functions
|
|
which the programmer can use to further customize the object before it is
|
|
fully constructed.
|
|
Also, objects can have a parent which will keep them alive as long as the
|
|
parent is alive, so the programmer does not need to keep track of references.
|
|
(See the @.parent property for details).
|
|
Due to the above characteristics, EFL objects undergo the following phases
|
|
during their Life Cycle:
|
|
- Construction: The @.constructor method is called. Afterwards, any
|
|
user-supplied initialization methods are called.
|
|
- Finalization: The @.finalize method is called and @.finalized is set to
|
|
$true when it returns. Object is usable at this point.
|
|
- Invalidation: The object has lost its parent. The @.invalidate method is
|
|
called so all the object's relationships can be terminated. @.invalidated
|
|
is set to $true.
|
|
- Destruction: The object has no parent and it can be destroyed. The
|
|
@.destructor method is called, use it to return any resources the object
|
|
might have gathered during its life.
|
|
|
|
@since 1.22
|
|
]]
|
|
c_prefix: efl;
|
|
|
|
methods {
|
|
@property parent {
|
|
[[The parent of an object.
|
|
|
|
Parents keep references to their children and will release these
|
|
references when destroyed. In this way, objects can be assigned to
|
|
a parent upon creation, tying their life cycle so the programmer
|
|
does not need to worry about destroying the child object.
|
|
In order to destroy an object before its parent, set the parent to
|
|
$NULL and use efl_unref(), or use efl_del() directly.
|
|
|
|
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 which can swallow objects into an internal
|
|
box, the parent of the swallowed objects should be the widget, not
|
|
the internal box. The user is not even aware of the existence of
|
|
the internal box.
|
|
]]
|
|
|
|
set {
|
|
}
|
|
get {
|
|
}
|
|
values {
|
|
parent: Efl.Object; [[The new parent.]]
|
|
}
|
|
}
|
|
@property name {
|
|
[[The name of the object.
|
|
|
|
Every EFL object can have a 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; [[The name.]]
|
|
}
|
|
}
|
|
@property comment {
|
|
[[A human readable comment for the object.
|
|
|
|
Every EFL object can have a 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; [[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.
|
|
]]
|
|
params {
|
|
@in sb: strbuf; [[A string buffer, must not be $null.]]
|
|
}
|
|
}
|
|
@property event_global_freeze_count @static {
|
|
[[Return the global count of freeze events.
|
|
|
|
This is the amount of calls to @.event_global_freeze minus
|
|
the amount of calls to @.event_global_thaw.
|
|
EFL will not emit any event while this count is > 0 (Except
|
|
events marked $hot).
|
|
]]
|
|
get {
|
|
}
|
|
values {
|
|
fcount: int; [[The global event freeze count.]]
|
|
}
|
|
}
|
|
@property event_freeze_count {
|
|
[[Return the count of freeze events for this object.
|
|
|
|
This is the amount of calls to @.event_freeze minus
|
|
the amount of calls to @.event_thaw.
|
|
This object will not emit any event while this count is > 0
|
|
(Except events marked $hot).
|
|
]]
|
|
get {
|
|
}
|
|
values {
|
|
fcount: int; [[The event freeze count of this object.]]
|
|
}
|
|
}
|
|
@property finalized {
|
|
[[$true if the object has been finalized, i.e. construction has finished.
|
|
See the Life Cycle section in this class' description.]]
|
|
get {
|
|
}
|
|
values {
|
|
finalized: bool; [[$true if the object is finalized, $false otherwise.]]
|
|
}
|
|
}
|
|
@property invalidated {
|
|
[[$true if the object has been invalidated, i.e. it has no parent.
|
|
See the Life Cycle section in this class' description.]]
|
|
get {
|
|
}
|
|
values {
|
|
finalized: bool; [[$true if the object is invalidated, $false otherwise.]]
|
|
}
|
|
}
|
|
@property invalidating {
|
|
[[$true if the object has started the invalidation phase, but has not
|
|
finished it yet.
|
|
Note: This might become $true before @.invalidate is called.
|
|
See the Life Cycle section in this class' description.]]
|
|
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.Class); [[The class identifier to search for.]]
|
|
}
|
|
return : Efl.Object; [[Object from the provider list.]]
|
|
}
|
|
constructor {
|
|
[[Implement this method to provide optional initialization code for your object.
|
|
|
|
See the Life Cycle section in this class' description.]]
|
|
return: Efl.Object; [[The new object, can be $NULL if aborted.]]
|
|
}
|
|
destructor {
|
|
[[Implement this method to provide deinitialization code for your object if you need it.
|
|
|
|
Will be called once @.invalidate has returned.
|
|
See the Life Cycle section in this class' description.]]
|
|
}
|
|
finalize {
|
|
[[Implement this method to finish the initialization of your object
|
|
after all (if any) user-provided configuration methods have been
|
|
executed.
|
|
|
|
Use this method to delay expensive operations until user configuration
|
|
has finished, to avoid building the object in a "default" state in the
|
|
constructor, just to have to throw it all away because a user
|
|
configuration (a property being set, for example) requires a different
|
|
state.
|
|
This is the last call inside efl_add() and will set @.finalized to $true
|
|
once it returns.
|
|
This is an optimization and implementing this method is optional if you
|
|
already perform all your initialization in the @.constructor method.
|
|
See the Life Cycle section in this class' description.]]
|
|
return: Efl.Object; [[The new object. Return $NULL to abort object creation.]]
|
|
}
|
|
invalidate {
|
|
[[Implement this method to perform special actions when your object loses
|
|
its parent, if you need to.
|
|
|
|
It is called when the parent reference is lost or set to $NULL. After this
|
|
call returns, @.invalidated is set to $true.
|
|
This allows a simpler tear down of complex hierarchies, by performing
|
|
object destruction in two steps, first all object relationships are
|
|
broken and then the isolated objects are destroyed. Performing everything
|
|
in the @.destructor can sometimes lead to deadlocks, but implementing
|
|
this method is optional if this is not your case.
|
|
When an object with a parent is destroyed, it first receives a call to
|
|
@.invalidate and then to @.destructor.
|
|
See the Life Cycle section in this class' description.]]
|
|
}
|
|
name_find @const @beta {
|
|
[[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 again for this object after a call
|
|
to @.event_freeze. The amount of thaws must match the amount of freezes
|
|
for events to be re-enabled.
|
|
]]
|
|
}
|
|
event_freeze {
|
|
[[Freeze events of this object.
|
|
|
|
Prevents event callbacks from being called for this object. Enable
|
|
events again using @.event_thaw. Events marked $hot cannot be stopped.
|
|
]]
|
|
}
|
|
event_global_thaw @static {
|
|
[[Globally thaw events for ALL EFL OBJECTS.
|
|
|
|
Allows event callbacks to be called for all EFL objects after they have
|
|
been disabled by @.event_global_freeze. The amount of thaws must match
|
|
the amount of freezes for events to be re-enabled.
|
|
]]
|
|
}
|
|
event_global_freeze @static {
|
|
[[Globally freeze events for ALL EFL OBJECTS.
|
|
|
|
Prevents event callbacks from being called for all EFL objects.
|
|
Enable events again using @.event_global_thaw. Events marked $hot
|
|
cannot be stopped.
|
|
|
|
Note: USE WITH CAUTION.
|
|
]]
|
|
}
|
|
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_priority_add {
|
|
[[Add an event callback forwarder that will make this object emit an event whenever another
|
|
object ($source) emits it. The event is said to be forwarded from $source to this object.
|
|
|
|
The event is unaffected on $source and behave like any other event being propagated on
|
|
any object and will trigger all the handler registered on $source like nothing special
|
|
happened.
|
|
|
|
This allow object that hide internally another object to easily be able to propagate an event
|
|
without the need to add custom handler.
|
|
|
|
Note: The priority is used to make sure that you are intercepting the event when you expect
|
|
by inserting a handler at the right position in the stack of event handler on the object that
|
|
emit the event.]]
|
|
params {
|
|
@in desc: const(Efl.Event_Description) @by_ref; [[The description of the event to listen to]]
|
|
@in priority: Efl.Callback_Priority; [[The priority at which to insert the event forwarder handler
|
|
in the existing list of handler on the source of event object. The lower the number, the higher
|
|
the priority. As a shortcut @Efl.Callback_Priority_Before,
|
|
@Efl.Callback_Priority_Default and @Efl.Callback_Priority_After can be used. See
|
|
@Efl.Callback_Priority for more details.]]
|
|
@in source: Efl.Object; [[The object which emits the initial event]]
|
|
}
|
|
}
|
|
event_callback_forwarder_del {
|
|
[[Remove an event callback forwarder for a specified event and object.]]
|
|
params {
|
|
@in desc: const(Efl.Event_Description) @by_ref; [[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 children.]]
|
|
return: iterator<Efl.Object> @move @no_unused; [[Children iterator]]
|
|
}
|
|
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 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 @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: Efl.Object; [[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.]]
|
|
}
|
|
@property allow_parent_unref @beta {
|
|
[[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.]]
|
|
}
|
|
}
|
|
provider_register {
|
|
[[Will register a manager of a specific class to be answered by @.provider_find.]]
|
|
params {
|
|
@in klass: const(Efl.Class); [[The class provided by the registered provider.]]
|
|
@in provider: const(Efl.Object); [[The provider for the newly registered class that has to provide that
|
|
said Efl.Class.]]
|
|
}
|
|
return: bool; [[$true if successfully register, $false otherwise.]]
|
|
}
|
|
provider_unregister {
|
|
[[Will unregister a manager of a specific class that was previously registered and answered by
|
|
@.provider_find.]]
|
|
params {
|
|
@in klass: const(Efl.Class); [[The class provided by the provider to unregister for.]]
|
|
@in provider: const(Efl.Object); [[The provider for the registered class to unregister.]]
|
|
}
|
|
return: bool; [[$true if successfully unregistered, $false otherwise.]]
|
|
}
|
|
}
|
|
implements {
|
|
class.constructor;
|
|
class.destructor;
|
|
}
|
|
constructors {
|
|
.parent @optional;
|
|
}
|
|
events {
|
|
del @hot: void; [[Object is being deleted. See @.destructor.]]
|
|
invalidate @hot: void; [[Object is being invalidated and losing its parent. See @.invalidate.]]
|
|
noref @hot: void; [[Object has lost its last reference, only parent relationship is keeping it alive.
|
|
Advanced usage.]]
|
|
ownership,unique @hot: void; [[Object has lost a reference and only one is left. It has just one owner now.
|
|
Triggered whenever the refcount goes from two to one.]]
|
|
ownership,shared @hot: void; [[Object has acquired a second reference. It has multiple owners now.
|
|
Triggered whenever increasing the refcount from one to two,
|
|
it will not trigger by further increasing the refcount beyond two.]]
|
|
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
|
|
reference you keep to the object.]]
|
|
}
|
|
}
|