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

: (revision 109.1.1)

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.
 */
UNUSED
static char *
SCallbackTypeNames[] = {
  "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 {
  schar * 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;

#define s_callback_entry_new(n, c, t)\
 s_callback_entry_new_real (n, CALLBACK (c), t)

SCallbackEntry *
s_callback_entry_new_real (const schar * name,
			   Callback callback,
			   SCallbackType type);

void
s_callback_entry_free (SCallbackEntry * entry);

/**
 * @}
 * @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,
			    size_t n_callbacks,
			    SCallbackEntry ** callback_entries);

/**
 * 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 * callback_entry);

/**
 * @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	*/
109.1.1 by Gustav Hartvigsson * SMap seems to be broken... Or could it be SObject's Callback stuff? Or SLinkedList?	38	UNUSED
	39	static char *
	40	SCallbackTypeNames[] = {
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	41	"NULL",
	42	"CALLBACK",
	43	"NOTIFY",
	44	"NOTIFY_CHANGE",
	45	0x0,
	46	0x0,
	47	};
	48
62 by Gustav Hartvigsson * General documentation clean up.	49	/**
	50	* An SCallbackEntry is used for convenience when installing callbacks into
	51	* SObjects.
	52	*
	53	* an example of how this could be used is:
	54	@code{.c}
	55	const SCallbackEntry foo_callback_entries[] = {
	56	{"val_x_change", S_CALLBACK_NOTIFY_CHANGE, CALLBACK(foo_val_x_change_func)},
	57	{"used", S_CALLBACK_CALLBACK, CALLBACK(foo_used)}
	58	};
	59	s_object_install_callbacks (S_OBJECT(Foo), &foo_callback_entries);
	60	* @endcode
109.1.1 by Gustav Hartvigsson * SMap seems to be broken... Or could it be SObject's Callback stuff? Or SLinkedList?	61	*
62 by Gustav Hartvigsson * General documentation clean up.	62	* The callback must have the following signature:
	63	* @code{.c}
	64	spointer
	65	foo_some_func (SObject obj, spointer user_data) {
	66	// Do something
	67	return ret_val; // Must return something, Be it NULL or something important
	68	}
	69	@endcode
	70	*/
	71	typedef struct SCallbackEntry {
109.1.1 by Gustav Hartvigsson * SMap seems to be broken... Or could it be SObject's Callback stuff? Or SLinkedList?	72	schar * 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.	73	Callback callback; /*< The callback that will be invoked./
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	74	SCallbackType type; /**< The type of the callback, is it a standard callback
	75	* or a notify? */
62 by Gustav Hartvigsson * General documentation clean up.	76	} SCallbackEntry;
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	77
109.1.1 by Gustav Hartvigsson * SMap seems to be broken... Or could it be SObject's Callback stuff? Or SLinkedList?	78	#define s_callback_entry_new(n, c, t)\
	79	s_callback_entry_new_real (n, CALLBACK (c), t)
	80
	81	SCallbackEntry *
	82	s_callback_entry_new_real (const schar * name,
	83	Callback callback,
	84	SCallbackType type);
	85
	86	void
	87	s_callback_entry_free (SCallbackEntry * entry);
	88
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	89	/**
	90	* @}
	91	* @addtogroup SObject
	92	* @{
	93	*/
	94
	95	/**
62 by Gustav Hartvigsson * General documentation clean up.	96	* Installs an array of callbackentries into an SObject.
109.1.1 by Gustav Hartvigsson * SMap seems to be broken... Or could it be SObject's Callback stuff? Or SLinkedList?	97	*
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	98	* @param obj The object to install the callback entries into.
	99	* @param callbackentries an array containing the callback entries.
	100	*/
61 by Gustav Hartvigsson * Made the code more easy to read.	101	void
109.1.1 by Gustav Hartvigsson * SMap seems to be broken... Or could it be SObject's Callback stuff? Or SLinkedList?	102	s_object_install_callbacks (SObject * obj,
	103	size_t n_callbacks,
	104	SCallbackEntry ** callback_entries);
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	105
	106	/**
	107	* Installs a singel callback into an SObject.
	108	*
	109	* @param obj The object to install the callback into.
	110	* @param callbackentry The callback entry to install.
	111	*/
61 by Gustav Hartvigsson * Made the code more easy to read.	112	void
109.1.1 by Gustav Hartvigsson * SMap seems to be broken... Or could it be SObject's Callback stuff? Or SLinkedList?	113	s_object_install_callback (SObject * obj, SCallbackEntry * callback_entry);
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	114
47 by Gustav Hartvigsson * Added a few skeletal functions to Callback.h	115	/**
62 by Gustav Hartvigsson * General documentation clean up.	116	* @breif Do a callback.
	117	*
	118	* When this function is called a on an SObject it calls the appropriate
	119	* callback that has been assigned the name.
	120	*
	121	* @param self The object to do the callback on.
	122	* @param name The name of the callback, can contain any valid non-null
	123	* character.
47 by Gustav Hartvigsson * Added a few skeletal functions to Callback.h	124	*/
61 by Gustav Hartvigsson * Made the code more easy to read.	125	spointer
72 by Gustav Hartvigsson * Added our own types for stability and shit and giggles.	126	s_object_notify (SObject * self, schar * name, spointer * user_data);
47 by Gustav Hartvigsson * Added a few skeletal functions to Callback.h	127
	128	/**
	129	* Alias to s_object_notify()
	130	*/
	131	#define s_object_call(o, n, d) s_object_notify (o, n, d)
	132
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	133	/*@}/
	134
	135	END_DECLS
	136
	137	#endif