#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