Etk
Main Page Object Hierarchy Data Structures Related Pages
Etk

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

void etk_signal_delete ( Etk_Signal *  signal  ) 

Deletes the signal. The signal could not be connected or emitted anymore.

Parameters:
signal the signal to delete

Etk_Signal * etk_signal_lookup ( const char *  signal_name,
Etk_Type *  type 
)

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:
signal a signal
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

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.

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:
signal a signal
Returns:
Returns the marshaller used by the signal or NULL on failure

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.

Note:
It has no effect if no signal is being emitted