|
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:
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:
You can also disconnect a callback from a signal of an object with etk_signal_disconnect(). For instance:
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:
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:
-
- 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: Etk_Bool callback(Etk_Object *object, void *data)
object: the object which is about to be destroyeddata: 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/WriteDefault 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.
|
Variables |
int | ETK_OBJECT_DESTROYED_SIGNAL |
| Symbols for signals.
|
int | ETK_OBJECT_DESTROYED_SIGNAL |
| Symbols for signals.
|
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)) |
#define ETK_IS_OBJECT |
( |
obj |
|
) |
(ETK_OBJECT_CHECK_TYPE((obj), ETK_OBJECT_TYPE)) |
Function Documentation
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
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 | |
|
) |
| | |
const char * etk_object_name_get |
( |
Etk_Object * |
object |
) |
|
Gets the name of the object.
- Parameters:
-
- 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
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)
Gets the type of the object.
- Parameters:
-
- 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 |
Variable Documentation
|
|