1 files changed, 61 insertions, 6 deletions

diff --git a/include/dom/events/document_event.h b/include/dom/events/document_event.h
index 3c1ea1b..be0646f 100644
--- a/include/dom/events/document_event.h
+++ b/include/dom/events/document_event.h
@@ -8,6 +8,8 @@
 #ifndef dom_events_document_event_h_
 #define dom_events_document_event_h_
 
+#include <stdbool.h>
+
 #include <dom/core/exceptions.h>
 
 struct dom_string;
@@ -18,15 +20,68 @@ struct lwc_string_s;
 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
  *
- * @note: When the implementation reach the end of the event flow, it will call
- * this function to get the default action handler. If it does not return a
- * NULL, the returned dom_event_listener will be invoked as the event is not
- * canceled.
+ * \param type   The type of the event
+ * \param phase  The phase of the default action callback
+ * \param pw     The return privat data of the callback function
+ * \return a callback function, NULL if there is none.
  */
-typedef struct dom_event_listener *(*dom_events_default_action_fetcher)
-		(struct lwc_string_s *name, struct lwc_string_s *type);
+typedef dom_default_action_callback (*dom_events_default_action_fetcher)
+		(struct lwc_string_s *type, dom_default_action_phase phase, 
+		void **pw);
 
 dom_exception _dom_document_event_create_event(dom_document_event *de,
 		struct dom_string *type, struct dom_event **evt);