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

: (revision 150)

To get this branch, use:

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

#pragma once

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

S_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.
 */
S_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)

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


S_EXPORTED
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.
 */
S_EXPORTED
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.
 */
S_EXPORTED
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.
 */
S_EXPORTED
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)

/**@}*/

S_END_DECLS

126.1.1 by Gustav Hartvigsson * Using	1	#pragma once
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	2
	3	#include "baseobject.h"
	4	#include "defs.h"
	5	#include "Func.h"
	6
110 by Gustav Hartvigsson * added S_ prifix to my macros. I should not be a scrub.	7	S_BEGIN_DECLS
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	8
	9	/**
	10	* @file
	11	* @defgroup SCallback SCallback
	12	* @addtogroup SCallback
	13	* @{
	14	* Callbacks are used to signals one part of the a program to an other.
	15	* It is manly used in SObject s and its children.
47 by Gustav Hartvigsson * Added a few skeletal functions to Callback.h	16	*
	17	* Please note that this is the best way to implement an "interface".
	18	*
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	19	* @sa GlobalNotify
	20	*/
	21
	22
	23	/**
	24	* The types for callbacks.
	25	*/
	26	typedef enum {
	27	S_CALLBACK_NULL,
	28	S_CALLBACK_CALLBACK,
	29	S_CALLBACK_NOTIFY,
	30	S_CALLBACK_NOTIFY_CHANGE
	31	} SCallbackType;
	32
62 by Gustav Hartvigsson * General documentation clean up.	33
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	34	/**
	35	* A list containing the names of the callback types.
	36	*/
109.1.5 by Gustav Hartvigsson * Getting closer to fixing the callbacks...	37	S_UNUSED
109.1.1 by Gustav Hartvigsson * SMap seems to be broken... Or could it be SObject's Callback stuff? Or SLinkedList?	38	static char *
	39	SCallbackTypeNames[] = {
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	40	"NULL",
	41	"CALLBACK",
	42	"NOTIFY",
	43	"NOTIFY_CHANGE",
	44	0x0,
	45	0x0,
	46	};
	47
62 by Gustav Hartvigsson * General documentation clean up.	48	/**
	49	* An SCallbackEntry is used for convenience when installing callbacks into
	50	* SObjects.
	51	*
	52	* an example of how this could be used is:
	53	@code{.c}
	54	const SCallbackEntry foo_callback_entries[] = {
	55	{"val_x_change", S_CALLBACK_NOTIFY_CHANGE, CALLBACK(foo_val_x_change_func)},
	56	{"used", S_CALLBACK_CALLBACK, CALLBACK(foo_used)}
	57	};
	58	s_object_install_callbacks (S_OBJECT(Foo), &foo_callback_entries);
	59	* @endcode
109.1.1 by Gustav Hartvigsson * SMap seems to be broken... Or could it be SObject's Callback stuff? Or SLinkedList?	60	*
62 by Gustav Hartvigsson * General documentation clean up.	61	* The callback must have the following signature:
	62	* @code{.c}
	63	spointer
	64	foo_some_func (SObject obj, spointer user_data) {
	65	// Do something
	66	return ret_val; // Must return something, Be it NULL or something important
	67	}
	68	@endcode
	69	*/
	70	typedef struct SCallbackEntry {
109.1.1 by Gustav Hartvigsson * SMap seems to be broken... Or could it be SObject's Callback stuff? Or SLinkedList?	71	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.	72	Callback callback; /*< The callback that will be invoked./
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	73	SCallbackType type; /**< The type of the callback, is it a standard callback
	74	* or a notify? */
62 by Gustav Hartvigsson * General documentation clean up.	75	} SCallbackEntry;
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	76
109.1.1 by Gustav Hartvigsson * SMap seems to be broken... Or could it be SObject's Callback stuff? Or SLinkedList?	77	#define s_callback_entry_new(n, c, t)\
	78	s_callback_entry_new_real (n, CALLBACK (c), t)
	79
150 by Gustav Hartvigsson * Fixed the tests in the CMake file	80	S_EXPORTED
109.1.1 by Gustav Hartvigsson * SMap seems to be broken... Or could it be SObject's Callback stuff? Or SLinkedList?	81	SCallbackEntry *
	82	s_callback_entry_new_real (const schar * name,
140 by Gustav Hartvigsson * Added Better comments to SRingBuffer	83	Callback callback,
	84	SCallbackType type);
109.1.1 by Gustav Hartvigsson * SMap seems to be broken... Or could it be SObject's Callback stuff? Or SLinkedList?	85
119 by Gustav Hartvigsson * added S_EXPERTED to public functions.	86
	87	S_EXPORTED
109.1.1 by Gustav Hartvigsson * SMap seems to be broken... Or could it be SObject's Callback stuff? Or SLinkedList?	88	void
	89	s_callback_entry_free (SCallbackEntry * entry);
	90
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	91	/**
	92	* @}
	93	* @addtogroup SObject
	94	* @{
	95	*/
	96
	97	/**
62 by Gustav Hartvigsson * General documentation clean up.	98	* 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?	99	*
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	100	* @param obj The object to install the callback entries into.
	101	* @param callbackentries an array containing the callback entries.
	102	*/
119 by Gustav Hartvigsson * added S_EXPERTED to public functions.	103	S_EXPORTED
61 by Gustav Hartvigsson * Made the code more easy to read.	104	void
109.1.1 by Gustav Hartvigsson * SMap seems to be broken... Or could it be SObject's Callback stuff? Or SLinkedList?	105	s_object_install_callbacks (SObject * obj,
140 by Gustav Hartvigsson * Added Better comments to SRingBuffer	106	size_t n_callbacks,
	107	SCallbackEntry ** callback_entries);
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	108
	109	/**
	110	* Installs a singel callback into an SObject.
	111	*
	112	* @param obj The object to install the callback into.
	113	* @param callbackentry The callback entry to install.
	114	*/
119 by Gustav Hartvigsson * added S_EXPERTED to public functions.	115	S_EXPORTED
61 by Gustav Hartvigsson * Made the code more easy to read.	116	void
109.1.1 by Gustav Hartvigsson * SMap seems to be broken... Or could it be SObject's Callback stuff? Or SLinkedList?	117	s_object_install_callback (SObject * obj, SCallbackEntry * callback_entry);
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	118
47 by Gustav Hartvigsson * Added a few skeletal functions to Callback.h	119	/**
62 by Gustav Hartvigsson * General documentation clean up.	120	* @breif Do a callback.
	121	*
	122	* When this function is called a on an SObject it calls the appropriate
	123	* callback that has been assigned the name.
	124	*
	125	* @param self The object to do the callback on.
	126	* @param name The name of the callback, can contain any valid non-null
	127	* character.
47 by Gustav Hartvigsson * Added a few skeletal functions to Callback.h	128	*/
119 by Gustav Hartvigsson * added S_EXPERTED to public functions.	129	S_EXPORTED
61 by Gustav Hartvigsson * Made the code more easy to read.	130	spointer
72 by Gustav Hartvigsson * Added our own types for stability and shit and giggles.	131	s_object_notify (SObject * self, schar * name, spointer * user_data);
47 by Gustav Hartvigsson * Added a few skeletal functions to Callback.h	132
	133	/**
	134	* Alias to s_object_notify()
	135	*/
	136	#define s_object_call(o, n, d) s_object_notify (o, n, d)
	137
44 by Gustav Hartvigsson * Started to structuce the dectumentation a little better.	138	/*@}/
	139
110 by Gustav Hartvigsson * added S_ prifix to my macros. I should not be a scrub.	140	S_END_DECLS