 |
Etk_Signal
Detailed Description
The signal system is a flexible system to create, connect and emit signals.
TODO: write doc for Etk_Signal!!
|
Data Structures |
struct | Etk_Signal |
| The structure of a signal. More...
|
Defines |
#define | ETK_MEMBER_OFFSET(type, member) ((long)((long *)&((type *)0)->member)) |
Functions |
Etk_Signal * | etk_signal_new (const char *signal_name, Etk_Type *object_type, long handler_offset, Etk_Marshaller marshaller, Etk_Accumulator accumulator, void *accum_data) |
| Creates a new signal called signal_name, for the object type object_type.
|
void | etk_signal_delete (Etk_Signal *signal) |
| Deletes the signal. The signal could not be connected or emitted anymore.
|
Etk_Signal * | etk_signal_lookup (const char *signal_name, Etk_Type *type) |
| Gets the the signal corresponding to the name and the object type.
|
const char * | etk_signal_name_get (Etk_Signal *signal) |
| Gets the name of the signal.
|
void | etk_signal_connect_full (Etk_Signal *signal, Etk_Object *object, Etk_Callback callback, void *data, Etk_Bool swapped, Etk_Bool after) |
| Connects a callback to a signal of the object object. When the signal of the object will be emitted, this callback will be automatically called.
|
void | etk_signal_connect (const char *signal_name, Etk_Object *object, Etk_Callback callback, void *data) |
| Connects a callback to a signal of the object object. The callback is added at the start of the list of callbacks to call. It means that when the signal is emitted, this callback will the first to be called. This way, you can prevent the other callbacks from being called using etk_signal_stop() when this callback gets called.
|
void | etk_signal_connect_after (const char *signal_name, Etk_Object *object, Etk_Callback callback, void *data) |
| Connects a callback to a signal of the object object. The callback is added at the end of the list of callbacks to call which means that when the signal is emitted, this callback will the last to be called. If you don't need a specific call-order, use etk_signal_connect() rather.
|
void | etk_signal_connect_swapped (const char *signal_name, Etk_Object *object, Etk_Callback callback, void *data) |
| Connects a callback to a signal of the object object. The callback is added at the start of the list of callbacks to call. It means that when the signal is emitted, this callback will the first to be called. This way, you can prevent the other callbacks from being called using etk_signal_stop() when this callback gets called.
|
void | etk_signal_disconnect (const char *signal_name, Etk_Object *object, Etk_Callback callback) |
| Disconnects a callback from a signal, the callback won't be called anymore when the signal is emitted.
|
void | etk_signal_disconnect_all (const char *signal_name, Etk_Object *object) |
| Disconnects all callbacks from a signal.
|
void | etk_signal_block (const char *signal_name, Etk_Object *object, Etk_Callback callback) |
| Blocks a callback from being called when the corresponding signal is emitted. Unlike etk_signal_disconnect(), the callback is note removed, and can be easily unblock with etk_signal_unblock().
|
void | etk_signal_unblock (const char *signal_name, Etk_Object *object, Etk_Callback callback) |
| Unblocks a blocked callback. The callback will no longer be prevented from being called when the corresponding signal is emitted.
|
Etk_Bool | etk_signal_emit (Etk_Signal *signal, Etk_Object *object, void *return_value,...) |
| Emits the signal: it will call the callbacks connected to the signal signal.
|
Etk_Bool | etk_signal_emit_by_name (const char *signal_name, Etk_Object *object, void *return_value,...) |
| Emits the signal: it will call the callbacks connected to the signal signal.
|
Etk_Bool | etk_signal_emit_valist (Etk_Signal *signal, Etk_Object *object, void *return_value, va_list args) |
| Emits the signal: it will call the callbacks connected to the signal signal.
|
Etk_Marshaller | etk_signal_marshaller_get (Etk_Signal *signal) |
| Gets the marshaller used by the signal.
|
void | etk_signal_stop () |
| Stops the propagation of the last emitted signal: the remaining callbacks/handler won't be called.
It's usually called in a callback to avoid the other callbacks to be called.
|
Define Documentation
#define ETK_MEMBER_OFFSET |
( |
type, |
|
|
member |
|
) |
((long)((long *)&((type *)0)->member)) |
Gets the offset of a member of a struct (used when you create a new signal with a default handler, with etk_signal_new())
Function Documentation
Etk_Signal * etk_signal_new |
( |
const char * |
signal_name, |
|
|
Etk_Type * |
object_type, |
|
|
long |
handler_offset, |
|
|
Etk_Marshaller |
marshaller, |
|
|
Etk_Accumulator |
accumulator, |
|
|
void * |
accum_data | |
|
) |
| | |
Creates a new signal called signal_name, for the object type object_type.
- Parameters:
-
| signal_name | the name of the new signal |
| object_type | the object type of the new signal |
| handler_offset | the offset of the default handler in the object's struct (use ETK_MEMBER_OFFSET() to get it). -1 if there is no default handler |
| marshaller | the marshaller of the signal: it will treat and pass the arguments to the callbacks |
| accumulator | the accumulator used to combine together the different values returned by the callbacks. Set it to NULL if the callbacks does not return any value or if you only want to keep the last returned value. |
| accum_data | the value to pass to the accumulator |
- Returns:
- Returns the new signal, or NULL on failure
Deletes the signal. The signal could not be connected or emitted anymore.
- Parameters:
-
| signal | the signal to delete |
Gets the the signal corresponding to the name and the object type.
- Parameters:
-
| signal_name | the name of the signal to return |
| type | the object type of the signal to return |
- Returns:
- Returns the signal called signal_name, for the object type type, or NULL on failure
const char * etk_signal_name_get |
( |
Etk_Signal * |
signal |
) |
|
Gets the name of the signal.
- Parameters:
-
- Returns:
- Returns the name of the signal, or NULL on failure
void etk_signal_connect_full |
( |
Etk_Signal * |
signal, |
|
|
Etk_Object * |
object, |
|
|
Etk_Callback |
callback, |
|
|
void * |
data, |
|
|
Etk_Bool |
swapped, |
|
|
Etk_Bool |
after | |
|
) |
| | |
Connects a callback to a signal of the object object. When the signal of the object will be emitted, this callback will be automatically called.
- Parameters:
-
| signal | the signal to connect to the callback |
| object | the object to connect to the callback |
| callback | the callback to call when the signal is emitted |
| data | the data to pass to the callback |
| swapped | if swapped == ETK_TRUE, the callback will be called with data as the only argument. It can be useful to set it to ETK_TRUE if you just want to call one function on an object when the signal is emitted |
| after | if after == ETK_TRUE, the callback will be called after all the callbacks already connected to this signal. Otherwise, it will be called before all of them (default behavior) |
void etk_signal_connect |
( |
const char * |
signal_name, |
|
|
Etk_Object * |
object, |
|
|
Etk_Callback |
callback, |
|
|
void * |
data | |
|
) |
| | |
Connects a callback to a signal of the object object. The callback is added at the start of the list of callbacks to call. It means that when the signal is emitted, this callback will the first to be called. This way, you can prevent the other callbacks from being called using etk_signal_stop() when this callback gets called.
- Parameters:
-
| signal | the signal to connect to the callback |
| object | the object to connect to the callback |
| callback | the callback to call when the signal is emitted |
| data | the data to pass to the callback |
void etk_signal_connect_after |
( |
const char * |
signal_name, |
|
|
Etk_Object * |
object, |
|
|
Etk_Callback |
callback, |
|
|
void * |
data | |
|
) |
| | |
Connects a callback to a signal of the object object. The callback is added at the end of the list of callbacks to call which means that when the signal is emitted, this callback will the last to be called. If you don't need a specific call-order, use etk_signal_connect() rather.
- Parameters:
-
| signal | the signal to connect to the callback |
| object | the object to connect to the callback |
| callback | the callback to call when the signal is emitted |
| data | the data to pass to the callback |
void etk_signal_connect_swapped |
( |
const char * |
signal_name, |
|
|
Etk_Object * |
object, |
|
|
Etk_Callback |
callback, |
|
|
void * |
data | |
|
) |
| | |
Connects a callback to a signal of the object object. The callback is added at the start of the list of callbacks to call. It means that when the signal is emitted, this callback will the first to be called. This way, you can prevent the other callbacks from being called using etk_signal_stop() when this callback gets called.
- Parameters:
-
| signal_name | the name of the signal to connect to the object to |
| object | the object that will connect the signal |
| callback | the callback to call when the signal is emitted |
| data | the data to pass to the callback |
void etk_signal_disconnect |
( |
const char * |
signal_name, |
|
|
Etk_Object * |
object, |
|
|
Etk_Callback |
callback | |
|
) |
| | |
Disconnects a callback from a signal, the callback won't be called anymore when the signal is emitted.
- Parameters:
-
| signal_name | the name of the signal connected to the callback to disconnect |
| object | the object connected to the callback to disconnect |
| callback | the callback to disconnect |
void etk_signal_disconnect_all |
( |
const char * |
signal_name, |
|
|
Etk_Object * |
object | |
|
) |
| | |
Disconnects all callbacks from a signal.
- Parameters:
-
| signal_name | the name of the signal for which all callbacks will be disconnected |
| object | the object for which all callbacks will be disconnected |
void etk_signal_block |
( |
const char * |
signal_name, |
|
|
Etk_Object * |
object, |
|
|
Etk_Callback |
callback | |
|
) |
| | |
Blocks a callback from being called when the corresponding signal is emitted. Unlike etk_signal_disconnect(), the callback is note removed, and can be easily unblock with etk_signal_unblock().
- Parameters:
-
| signal_name | the name of the signal connected to the callback to block |
| object | the object connected to the callback to block |
| callback | the callback function to block |
void etk_signal_unblock |
( |
const char * |
signal_name, |
|
|
Etk_Object * |
object, |
|
|
Etk_Callback |
callback | |
|
) |
| | |
Unblocks a blocked callback. The callback will no longer be prevented from being called when the corresponding signal is emitted.
- Parameters:
-
| signal_name | the name of the signal connected to the callback to unblock |
| object | the object connected to the callback to unblock |
| callback | the callback function to unblock |
Emits the signal: it will call the callbacks connected to the signal signal.
- Parameters:
-
| signal | the signal to emit |
| object | the object which will emit the signal |
| return_value | the location where store the return value ( return_value may be NULL) |
| ... | the arguments to pass to the callback function |
- Returns:
- Returns ETK_FALSE if the signal has been stopped (i.e. etk_signal_stop() has been called in one of the callbacks), and ETK_TRUE otherwise
Etk_Bool etk_signal_emit_by_name |
( |
const char * |
signal_name, |
|
|
Etk_Object * |
object, |
|
|
void * |
return_value, |
|
|
|
... | |
|
) |
| | |
Emits the signal: it will call the callbacks connected to the signal signal.
- Parameters:
-
| signal | the name of the signal to emit |
| object | the object which will emit the signal |
| return_value | the location where store the return value ( return_value may be NULL) |
| ... | the arguments to pass to the callback function |
- Returns:
- Returns ETK_FALSE if the signal has been stopped (i.e. etk_signal_stop() has been called in one of the callbacks), and ETK_TRUE otherwise
Etk_Bool etk_signal_emit_valist |
( |
Etk_Signal * |
signal, |
|
|
Etk_Object * |
object, |
|
|
void * |
return_value, |
|
|
va_list |
args | |
|
) |
| | |
Emits the signal: it will call the callbacks connected to the signal signal.
- Parameters:
-
| signal | the signal to emit |
| object | the object which will emit the signal |
| return_value | the location where store the return value ( return_value may be NULL) |
| args | the arguments to pass to the callback function |
- Returns:
- Returns object, or NULL if object has been destroyed by one of the callbacks
Returns ETK_FALSE if the signal has been stopped (i.e. etk_signal_stop() has been called in one of the callbacks), and ETK_TRUE otherwise
Etk_Marshaller etk_signal_marshaller_get |
( |
Etk_Signal * |
signal |
) |
|
Gets the marshaller used by the signal.
- Parameters:
-
- Returns:
- Returns the marshaller used by the signal or NULL on failure
Stops the propagation of the last emitted signal: the remaining callbacks/handler won't be called.
It's usually called in a callback to avoid the other callbacks to be called.
- Note:
- It has no effect if no signal is being emitted
|
 |