From b657c277f517f4ab0a4da21e4f8c4cb6f8f53013 Mon Sep 17 00:00:00 2001 From: John Mark Bell Date: Mon, 30 Aug 2010 13:06:19 +0000 Subject: Merge branches/struggleyb/libdom-html to trunk. A few additional fixes to reduce the number of regressions to single figures. svn path=/trunk/dom/; revision=10724 --- include/dom/events/document_event.h | 67 +++++++++++++++++++++++++++++++++---- 1 file changed, 61 insertions(+), 6 deletions(-) (limited to 'include/dom/events') 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 + #include struct dom_string; @@ -17,16 +19,69 @@ 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); -- cgit v1.2.3