/simpletypesystem/trunk : contents of libssts/Callback.h at revision 103

: (revision 103)

To get this branch, use:

bzr branch
http://gegoxaren.bato24.eu/bzr/simpletypesystem/trunk

#ifndef __H_CALLBACK__
#define __H_CALLBACK__

#include "baseobject.h"
#include "defs.h"
#include "Func.h"

BEGIN_DECLS

/**
 * @file
 * @defgroup SCallback SCallback
 * @addtogroup SCallback
 * @{
 * Callbacks are used to signals one part of the a program to an other.
 * It is manly used in SObject s and its children.
 *
 * Please note that this is the best way to implement an "interface".
 *
 * @sa GlobalNotify
 */


/**
 * The types for callbacks.
 */
typedef enum {
  S_CALLBACK_NULL,
  S_CALLBACK_CALLBACK,
  S_CALLBACK_NOTIFY,
  S_CALLBACK_NOTIFY_CHANGE
} SCallbackType;


/**
 * A list containing the names of the callback types.
 */
static char * SCallbackTypeNames[] __attribute__((unused)) = {
  "NULL",
  "CALLBACK",
  "NOTIFY",
  "NOTIFY_CHANGE",
  0x0,
  0x0,
};

/**
 * An SCallbackEntry is used for convenience when installing callbacks into
 * SObjects.
 *
 * an example of how this could be used is:
 @code{.c}
const SCallbackEntry foo_callback_entries[] = {
  {"val_x_change", S_CALLBACK_NOTIFY_CHANGE, CALLBACK(foo_val_x_change_func)},
  {"used", S_CALLBACK_CALLBACK, CALLBACK(foo_used)}
};
s_object_install_callbacks (S_OBJECT(Foo), &foo_callback_entries);
 * @endcode
 * 
 * The callback must have the following signature:
 * @code{.c}
spointer
foo_some_func (SObject obj, spointer user_data) {
  // Do something
  return ret_val; // Must return something, Be it NULL or something important
}
 @endcode
 */
typedef struct SCallbackEntry {
  char * name; /**< The name that is used to invoke the callback. */
  Callback callback; /**< The callback that will be invoked.*/
  SCallbackType type; /**< The type of the callback, is it a standard callback
                       * or a notify? */
} SCallbackEntry;

/**
 * @}
 * @addtogroup SObject
 * @{
 */

/**
 * Installs an array of callbackentries into an SObject.
 * 
 * @param obj The object to install the callback entries into.
 * @param callbackentries an array containing the callback entries.
 */
void
s_object_install_callbacks (SObject * obj, SCallbackEntry ** callcackentries);

/**
 * Installs a singel callback into an SObject.
 *
 * @param obj The object to install the callback into.
 * @param callbackentry The callback entry to install.
 */
void
s_object_install_callback (SObject * obj, SCallbackEntry * callbackentry);

/**
 * @breif Do a callback.
 *
 * When this function is called a on an SObject it calls the appropriate
 * callback that has been assigned the name.
 *
 * @param self The object to do the callback on.
 * @param name The name of the callback, can contain any valid non-null
 * character.
 */
spointer
s_object_notify (SObject * self, schar * name, spointer * user_data);

/**
 * Alias to s_object_notify()
 */
#define s_object_call(o, n, d) s_object_notify (o, n, d)

/**@}*/

END_DECLS

#endif

44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	1	#ifndef __H_CALLBACK__
	2	#define __H_CALLBACK__
	3
	4	#include "baseobject.h"
	5	#include "defs.h"
	6	#include "Func.h"
	7
	8	BEGIN_DECLS
	9
	10	/**
	11	* @file
	12	* @defgroup SCallback SCallback
	13	* @addtogroup SCallback
	14	* @{
	15	* Callbacks are used to signals one part of the a program to an other.
	16	* It is manly used in SObject s and its children.
47 by Gustav Hartvigsson * Added a few skeletal functions to Callback.h	17	*
	18	* Please note that this is the best way to implement an "interface".
	19	*
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	20	* @sa GlobalNotify
	21	*/
	22
	23
	24	/**
	25	* The types for callbacks.
	26	*/
	27	typedef enum {
	28	S_CALLBACK_NULL,
	29	S_CALLBACK_CALLBACK,
	30	S_CALLBACK_NOTIFY,
	31	S_CALLBACK_NOTIFY_CHANGE
	32	} SCallbackType;
	33
62 by Gustav Hartvigsson * General documentation clean up.	34
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	35	/**
	36	* A list containing the names of the callback types.
	37	*/
	38	static char * SCallbackTypeNames[] __attribute__((unused)) = {
	39	"NULL",
	40	"CALLBACK",
	41	"NOTIFY",
	42	"NOTIFY_CHANGE",
	43	0x0,
	44	0x0,
	45	};
	46
62 by Gustav Hartvigsson * General documentation clean up.	47	/**
	48	* An SCallbackEntry is used for convenience when installing callbacks into
	49	* SObjects.
	50	*
	51	* an example of how this could be used is:
	52	@code{.c}
	53	const SCallbackEntry foo_callback_entries[] = {
	54	{"val_x_change", S_CALLBACK_NOTIFY_CHANGE, CALLBACK(foo_val_x_change_func)},
	55	{"used", S_CALLBACK_CALLBACK, CALLBACK(foo_used)}
	56	};
	57	s_object_install_callbacks (S_OBJECT(Foo), &foo_callback_entries);
	58	* @endcode
	59	*
	60	* The callback must have the following signature:
	61	* @code{.c}
	62	spointer
	63	foo_some_func (SObject obj, spointer user_data) {
	64	// Do something
	65	return ret_val; // Must return something, Be it NULL or something important
	66	}
	67	@endcode
	68	*/
	69	typedef struct SCallbackEntry {
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	70	char * name; /*< The name that is used to invoke the callback. /
81 by Gustav Hartvigsson * Re arranged members of structs to prevent struct fragmentation and padding.	71	Callback callback; /*< The callback that will be invoked./
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	72	SCallbackType type; /**< The type of the callback, is it a standard callback
	73	* or a notify? */
62 by Gustav Hartvigsson * General documentation clean up.	74	} SCallbackEntry;
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	75
	76	/**
	77	* @}
	78	* @addtogroup SObject
	79	* @{
	80	*/
	81
	82	/**
62 by Gustav Hartvigsson * General documentation clean up.	83	* Installs an array of callbackentries into an SObject.
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	84	*
	85	* @param obj The object to install the callback entries into.
	86	* @param callbackentries an array containing the callback entries.
	87	*/
61 by Gustav Hartvigsson * Made the code more easy to read.	88	void
61 by Gustav Hartvigsson * Made the code more easy to read.	89	s_object_install_callbacks (SObject * obj, SCallbackEntry ** callcackentries);
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	90
	91	/**
	92	* Installs a singel callback into an SObject.
	93	*
	94	* @param obj The object to install the callback into.
	95	* @param callbackentry The callback entry to install.
	96	*/
61 by Gustav Hartvigsson * Made the code more easy to read.	97	void
61 by Gustav Hartvigsson * Made the code more easy to read.	98	s_object_install_callback (SObject * obj, SCallbackEntry * callbackentry);
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	99
47 by Gustav Hartvigsson * Added a few skeletal functions to Callback.h	100	/**
62 by Gustav Hartvigsson * General documentation clean up.	101	* @breif Do a callback.
	102	*
	103	* When this function is called a on an SObject it calls the appropriate
	104	* callback that has been assigned the name.
	105	*
	106	* @param self The object to do the callback on.
	107	* @param name The name of the callback, can contain any valid non-null
	108	* character.
47 by Gustav Hartvigsson * Added a few skeletal functions to Callback.h	109	*/
61 by Gustav Hartvigsson * Made the code more easy to read.	110	spointer
72 by Gustav Hartvigsson * Added our own types for stability and shit and giggles.	111	s_object_notify (SObject * self, schar * name, spointer * user_data);
47 by Gustav Hartvigsson * Added a few skeletal functions to Callback.h	112
	113	/**
	114	* Alias to s_object_notify()
	115	*/
	116	#define s_object_call(o, n, d) s_object_notify (o, n, d)
	117
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	118	/*@}/
	119
	120	END_DECLS
	121
	122	#endif