text: /*
   * This file is part of libdom.
   * Licensed under the MIT License,
   *                http://www.opensource.org/licenses/mit-license.php
   * Copyright 2009 Bo Yang <struggleyb.nku@gmail.com>
   */
  
  #ifndef dom_events_document_event_h_
  #define dom_events_document_event_h_
  
  #include <stdbool.h>
  
  #include <dom/core/exceptions.h>
  #include <dom/core/string.h>
  
  struct dom_event;
  struct dom_document;
  
  typedef struct dom_document dom_document_event;
  
  /**
   * The callback function which is used to process the default action of any
   * event.
   *
   * As ::dom_default_action_phase defines, we have three points in our 
   * implementation where these kinds of callbacks get invoked.
   *
   * When the implementation start to dispatch certain event, it firstly invoke
   * the following callback, which should process the event before the normal
   * event flow.
   *
   * Take a MousePressed event on a check box object as example:
   * 1. The 'pressed' event is generated by OS and catched by our UI code;
   * 2. The UI code dispatch the event to DOM;
   * 3. DOM trys to dispatch the event as what the spec said;
   * 4. Before the real event flow happens, DOM get the 
   *    dom_default_action_callback function from the 
   *    dom_events_default_action_fetcher with param
   *    DOM_DEFAULT_ACTION_STARTED, and then call it;
   * 5. The callback function invoke some System-denpendent API to make the
   *    checkbox checked and then return;
   * 6. Normal event flow goes on.
   * 7. When the implementation reach the end of the event flow, it check whether
   *    the event's default action is prevented, if it is, then go to step 8,
   *    else go to step 9.
   * 8. The event's default action get prevented, DOM get the 
   *    dom_default_action_callback function from the 
   *    dom_events_default_action_fetcher with param
   *    DOM_DEFAULT_ACTION_PREVENTED, and then call it.
   * 8. The event's default action does not get prevented, DOM get the 
   *    dom_default_action_callback function from the 
   *    dom_events_default_action_fetcher with param
   *    DOM_DEFAULT_ACTION_END, and then call it.
   *
   * @note: the point here is that we want the UI related stuff to be done
   * within the default action code. The DOM only take care of the content tree
   * and the event flow itself.
   */
  typedef void (*dom_default_action_callback)(struct dom_event *evt, void *pw);
  
  /**
   * The default action phase
   *
   * @note: we define the following three values to fetch three different types
   * of dom_default_action_callback function and their private data.
   */
  typedef enum {
  	DOM_DEFAULT_ACTION_STARTED = 0,
  	DOM_DEFAULT_ACTION_PREVENTED,
  	DOM_DEFAULT_ACTION_END
  } dom_default_action_phase;
  
  /**
   * The default action fetcher
   *
   * \param type   The type of the event
   * \param phase  The phase of the default action callback
   * \param pw     The return private data of the callback function
   * \return a callback function, NULL if there is none.
   */
  typedef dom_default_action_callback (*dom_events_default_action_fetcher)
  		(dom_string *type, dom_default_action_phase phase, 
  		void **pw);
  
  dom_exception _dom_document_event_create_event(dom_document_event *de,
  		dom_string *type, struct dom_event **evt);
  #define dom_document_event_create_event(d, t, e) \
  		_dom_document_event_create_event((dom_document_event *) (d), \
  		(dom_string *) (t), (struct dom_event **) (e))
  
  dom_exception _dom_document_event_can_dispatch(dom_document_event *de,
  		dom_string *namespace, dom_string *type,
  		bool* can);
  #define dom_document_event_can_dispatch(d, n, t, c) \
  		_dom_document_event_can_dispatch((dom_document_event *) (d), \
  		(dom_string *) (n), (dom_string *) (t),\
  		(bool *) (c))
  
  #endif
  
  