Etk
Main Page Object Hierarchy Data Structures Related Pages
Etk

Etk_Object


Detailed Description

The Etk_Object class is the base class for all the objects and widgets of Etk.

Etk_Object implements advanced features such as inheritance, constructors/destructors, signals and properties.


Constructors/Destructors:
A new object can be created with etk_object_new(). For example:
 //Creates a new focusable slider, for the range [1.0 - 3.0] and with the initial value 2.0
 slider = etk_object_new(ETK_SLIDER_TYPE, "theme-group", "slider", "focusable", ETK_TRUE, "lower", 1.0, "upper", 3.0, "value", 2.0, NULL);
The first argument is the type of the object to create, followed by any number of property-name/property-value pairs, and terminated with NULL.
etk_object_new() automatically calls the corresponding constructors of the object, from the constructor of the base class to the constructor of the more derived class.

You can then destroy the object with etk_object_destroy(): it sets the weak-pointers of the object to NULL (see etk_object_weak_pointer_add()), emits the "destroyed" signal and queues the object for freeing. Thus, the destructors will only be called at the beginning of the next main loop iteration (from the destructor of the more derived class to the destructor of the ultimate base class). You should then not assume that etk_object_destroy() will directly call the destructors.

Signal concept:
Each object has a list of signals that can be connected to one or several callbacks. The callbacks connected to a signal will be automatically called when the signal is emitted with etk_signal_emit().
You can connect a callback to a signal of an object with etk_signal_connect(). For example:

 //Callback prototype
 void clicked_cb(Etk_Button *button, void *data);

 //Connects the callback "clicked_cb()" to the signal "clicked" of the button
 etk_signal_connect("clicked", ETK_OBJECT(button), ETK_CALLBACK(clicked_cb), user_data);

You can also disconnect a callback from a signal of an object with etk_signal_disconnect(). For instance:

 //Disconnects the callback "clicked_cb()" from the signal "clicked"
 etk_signal_disconnect("clicked", ETK_OBJECT(button), ETK_CALLBACK(clicked_cb));

Each object inherits the signals from its parent classes (for instance, an Etk_Button has the signals of Etk_Object, Etk_Widget, Etk_Container, Etk_Bin and Etk_Button). Each object's documentation page has a list of the object's signals with the associated callback prototype and a short explanation.
For more information about signals, see the documentation page of Etk_Signal.

Property concept:
Each object also has a list of properties. Each property has a specific type, a default value, and can be either readable, writable or both. You can set or get the value of a property with etk_object_properties_set() and etk_object_properties_set().

Another important point about the property system is that you can add a notification callback to a property. The callback will be called each time the value of the property is changed (i.e. each time etk_object_notify() is called on that property). This can be done with etk_object_notification_callback_add(). For example:

 //Notification callback prototype
 void value_changed_cb(Etk_Object *object, const char *property_name, void *data);

 //Adds a notification callback to the property "upper" of the slider.
 //It will be called when the upper bound of the slider is changed
 etk_object_notification_callback_add(ETK_OBJECT(slider), "upper", value_changed_cb, user_data);

Each object inherits the properties from its parent classes (for instance, an Etk_Button has the properties of Etk_Object, Etk_Widget, Etk_Container, Etk_Bin and Etk_Button).




Object Hierarchy:
  • Etk_Object
Signals:
  • "destroyed": Emitted when the object is destroyed, before all the destructors of the object are called. Since the destructors have not been called yet, the object should still be usable at this point.
    • Callback: void callback(Etk_Object *object, void *data)
      • object: the object which is about to be destroyed
      • data: the user data set when the callback has been connected to the signal
Properties:
  • "name": The name of the object
    • Type: String (char *)
    • Access: Read/Write
    • Default Value: NULL


Data Structures

struct  Etk_Notification_Callback
 A callback called each time the value of the associated property is modified. More...
struct  Etk_Object
 [Object] The base class for all the objects and widgets of Etk More...

Defines

#define ETK_OBJECT_TYPE   (etk_object_type_get())
#define ETK_OBJECT(obj)   (ETK_OBJECT_CAST((obj), ETK_OBJECT_TYPE, Etk_Object))
#define ETK_IS_OBJECT(obj)   (ETK_OBJECT_CHECK_TYPE((obj), ETK_OBJECT_TYPE))

Functions

Etk_Object * etk_object_new (Etk_Type *object_type, const char *first_property,...)
 Creates a new object: it calls the corresponding constructors (from the constructor of the base class to the constructor of the more derived class) and then sets the values of the given properties.
Etk_Object * etk_object_new_valist (Etk_Type *object_type, const char *first_property, va_list args)
 Creates a new object: it calls the corresponding constructors (from the constructor of the base class to the constructor of the more derived class) and then sets the values of the given properties.
void etk_object_destroy (Etk_Object *object)
 Destroys the object: it first sets the weak-pointers to NULL, emits the "destroyed" signal, and then queues the object in the list of objects to free. Thus, the destructors will only be called at the beginning of the next main loop iteration (from the destructor of the more derived class to the destructor of the ultimate base class).
void etk_object_name_set (Etk_Object *object, const char *name)
 Sets the name of the object. The object can then be retrieved from his name with etk_object_name_find().
const char * etk_object_name_get (Etk_Object *object)
 Gets the name of the object.
Etk_Object * etk_object_name_find (const char *name)
 Finds the object called name.
Etk_Object * etk_object_check_cast (Etk_Object *object, Etk_Type *type)
 Checks if object can be cast to type. If object doesn't inherit from type, a warning is displayed in the console but the object is returned anyway.
Etk_Type * etk_object_object_type_get (Etk_Object *object)
 Gets the type of the object.
void etk_object_weak_pointer_add (Etk_Object *object, void **pointer_location)
 Adds a weak-pointer to the object. A weak-pointer is a pointer that will be automatically set to NULL when the object is destroyed.
void etk_object_weak_pointer_remove (Etk_Object *object, void **pointer_location)
 Removes a weak-pointer from the object.
void etk_object_data_set (Etk_Object *object, const char *key, void *value)
 Associates a data pointer to a key. The pointer will be carried by the object and could be retrieved later with etk_object_data_get(). If the object already has an association for the given key, the old data will be destroyed.
void etk_object_data_set_full (Etk_Object *object, const char *key, void *value, void(*free_cb)(void *data))
 Associates a data pointer to a key. The pointer will be carried by the object and could be retrieved later with etk_object_data_get(). If the object already has an association for the given key, the old data will be destroyed.
void * etk_object_data_get (Etk_Object *object, const char *key)
 Gets the pointer associated to the given key.
void etk_object_property_reset (Etk_Object *object, const char *property_name)
 Resets the default value of a property.
void etk_object_properties_set (Etk_Object *object, const char *first_property,...)
 Sets the values of several properties.
void etk_object_properties_set_valist (Etk_Object *object, const char *first_property, va_list args)
 Sets the values of several properties.
void etk_object_properties_get (Etk_Object *object, const char *first_property,...)
 Gets the values of several properties.
void etk_object_properties_get_valist (Etk_Object *object, const char *first_property, va_list args)
 Gets the values of several properties.
void etk_object_notify (Etk_Object *object, const char *property_name)
 Calls the object's notification callbacks associated the given property. It should be called each time the value of a property is changed.
void etk_object_notification_callback_add (Etk_Object *object, const char *property_name, void(*callback)(Etk_Object *object, const char *property_name, void *data), void *data)
 Adds a notification callback associated to a property of the object. The callback will be called each time the value of the property is changed (i.e. each time etk_object_notify(object, property_name) is called).
void etk_object_notification_callback_remove (Etk_Object *object, const char *property_name, void(*callback)(Etk_Object *object, const char *property_name, void *data))
 Removes a notification callback associated to a property of the object.


Define Documentation

#define ETK_OBJECT_TYPE   (etk_object_type_get())

Gets the type of an object

#define ETK_OBJECT ( obj   )     (ETK_OBJECT_CAST((obj), ETK_OBJECT_TYPE, Etk_Object))

Casts the object to an Etk_Object

#define ETK_IS_OBJECT ( obj   )     (ETK_OBJECT_CHECK_TYPE((obj), ETK_OBJECT_TYPE))

Checks if the object is an Etk_Object


Function Documentation

Etk_Object * etk_object_new ( Etk_Type *  object_type,
const char *  first_property,
  ... 
)

Creates a new object: it calls the corresponding constructors (from the constructor of the base class to the constructor of the more derived class) and then sets the values of the given properties.

Parameters:
object_type the type of object to create
first_property the name of the first property to set
... the value of the first property, followed by any number of property-name/property-value pairs, terminated with NULL
Returns:
Returns the new Etk_Object of type object_type

Etk_Object * etk_object_new_valist ( Etk_Type *  object_type,
const char *  first_property,
va_list  args 
)

Creates a new object: it calls the corresponding constructors (from the constructor of the base class to the constructor of the more derived class) and then sets the values of the given properties.

Parameters:
object_type the type of object to create
first_property the name of the first property to set
args the value of the first property, followed by any number of property-name/property-value pairs, terminated with NULL
Returns:
Returns the new Etk_Object of type object_type

void etk_object_destroy ( Etk_Object *  object  ) 

Destroys the object: it first sets the weak-pointers to NULL, emits the "destroyed" signal, and then queues the object in the list of objects to free. Thus, the destructors will only be called at the beginning of the next main loop iteration (from the destructor of the more derived class to the destructor of the ultimate base class).

Parameters:
object the object to destroy
Warning:
You should not assume that this function will call directly the destructors of the object!

void etk_object_name_set ( Etk_Object *  object,
const char *  name 
)

Sets the name of the object. The object can then be retrieved from his name with etk_object_name_find().

Parameters:
object an object
name the name to set
See also:
etk_object_name_find()

const char * etk_object_name_get ( Etk_Object *  object  ) 

Gets the name of the object.

Parameters:
object a object
Returns:
Returns the name of the object

Etk_Object * etk_object_name_find ( const char *  name  ) 

Finds the object called name.

Parameters:
name the name of the object to find
Returns:
Returns the object called name

Etk_Object * etk_object_check_cast ( Etk_Object *  object,
Etk_Type *  type 
)

Checks if object can be cast to type. If object doesn't inherit from type, a warning is displayed in the console but the object is returned anyway.

Parameters:
object the object to cast
type the type to which we cast the object
Returns:
Returns the object
Note:
You usually do not need to call this function, use specific macros instead (ETK_IS_WIDGET() for example)

Etk_Type * etk_object_object_type_get ( Etk_Object *  object  ) 

Gets the type of the object.

Parameters:
object an object
Returns:
Returns the type of object (NULL on failure)

void etk_object_weak_pointer_add ( Etk_Object *  object,
void **  pointer_location 
)

Adds a weak-pointer to the object. A weak-pointer is a pointer that will be automatically set to NULL when the object is destroyed.

Parameters:
object an object
pointer_location the location of the weak-pointer
Warning:
if the pointer_location is not accessible when the object is destroyed, it may segfaults. So you have to use etk_object_weak_pointer_remove() when pointer_location becomes inaccessible
See also:
etk_object_weak_pointer_remove()

void etk_object_weak_pointer_remove ( Etk_Object *  object,
void **  pointer_location 
)

Removes a weak-pointer from the object.

Parameters:
object an object
pointer_location the location of the weak-pointer to remove
See also:
etk_object_weak_pointer_add()

void etk_object_data_set ( Etk_Object *  object,
const char *  key,
void *  value 
)

Associates a data pointer to a key. The pointer will be carried by the object and could be retrieved later with etk_object_data_get(). If the object already has an association for the given key, the old data will be destroyed.

Parameters:
object the object which the data will be added to
key the key to associate to the data
value the value of the data
Note:
If you want the data to be freed when the object is destroyed or when the value is changed, use etk_object_data_set_full() instead.

void etk_object_data_set_full ( Etk_Object *  object,
const char *  key,
void *  value,
void(*)(void *data)  free_cb 
)

Associates a data pointer to a key. The pointer will be carried by the object and could be retrieved later with etk_object_data_get(). If the object already has an association for the given key, the old data will be destroyed.

Parameters:
object the object which the data will be added to
key the key to associate to the data
value the value of the data
free_cb the function to call on value when the object is destroyed or when the value is changed

void * etk_object_data_get ( Etk_Object *  object,
const char *  key 
)

Gets the pointer associated to the given key.

Parameters:
object the object which has the data
key the key associated to the data
Returns:
Returns the associated pointer, NULL on failure

void etk_object_property_reset ( Etk_Object *  object,
const char *  property_name 
)

Resets the default value of a property.

Parameters:
object the object that has the property to reset
property_name the name of the property to reset

void etk_object_properties_set ( Etk_Object *  object,
const char *  first_property,
  ... 
)

Sets the values of several properties.

Parameters:
object the object that has the properties
first_property the name of the first property value
... the value of the first property, followed by any number of property-name/property-value pairs, terminated with NULL

void etk_object_properties_set_valist ( Etk_Object *  object,
const char *  first_property,
va_list  args 
)

Sets the values of several properties.

Parameters:
object the object that has the properties
first_property the name of the first property value
args the value of the first property, followed by any number of property-name/property-value pairs, terminated with NULL

void etk_object_properties_get ( Etk_Object *  object,
const char *  first_property,
  ... 
)

Gets the values of several properties.

Parameters:
object the object that has the properties
first_property the name of the first property value
... the value of the first property, followed by any number of property-name/property-value-location pairs, terminated with NULL

void etk_object_properties_get_valist ( Etk_Object *  object,
const char *  first_property,
va_list  args 
)

Gets the values of several properties.

Parameters:
object the object that has the properties
first_property the name of the first property value
args the value of the first property, followed by any number of property-name/property-value-location pairs, terminated with NULL

void etk_object_notify ( Etk_Object *  object,
const char *  property_name 
)

Calls the object's notification callbacks associated the given property. It should be called each time the value of a property is changed.

Parameters:
object an object
property_name the name of the property
Note:
This function is mainly used in object implementations, you usually don't have to call it yourself</i> page)

void etk_object_notification_callback_add ( Etk_Object *  object,
const char *  property_name,
void(*)(Etk_Object *object, const char *property_name, void *data)  callback,
void *  data 
)

Adds a notification callback associated to a property of the object. The callback will be called each time the value of the property is changed (i.e. each time etk_object_notify(object, property_name) is called).

Parameters:
object an object
property_name the name of the property
callback the callback function
data the data to pass to the callback

void etk_object_notification_callback_remove ( Etk_Object *  object,
const char *  property_name,
void(*)(Etk_Object *object, const char *property_name, void *data)  callback 
)

Removes a notification callback associated to a property of the object.

Parameters:
object an object
property_name the name of the property
callback the callback function to remove