1 /* 2 * This file is part of libdom. 3 * Licensed under the MIT License, 4 * http://www.opensource.org/licenses/mit-license.php 5 * Copyright 2009 Bo Yang <struggleyb.nku@gmail.com> 6 */ 7 8 #ifndef dom_events_document_event_h_ 9 #define dom_events_document_event_h_ 10 11 #include <stdbool.h> 12 13 #include <dom/core/exceptions.h> 14 #include <dom/core/string.h> 15 16 struct dom_event; 17 struct dom_document; 18 19 typedef struct dom_document dom_document_event; 20 21 /** 22 * The callback function which is used to process the default action of any 23 * event. 24 * 25 * As ::dom_default_action_phase defines, we have three points in our 26 * implementation where these kinds of callbacks get invoked. 27 * 28 * When the implementation start to dispatch certain event, it firstly invoke 29 * the following callback, which should process the event before the normal 30 * event flow. 31 * 32 * Take a MousePressed event on a check box object as example: 33 * 1. The 'pressed' event is generated by OS and catched by our UI code; 34 * 2. The UI code dispatch the event to DOM; 35 * 3. DOM trys to dispatch the event as what the spec said; 36 * 4. Before the real event flow happens, DOM get the 37 * dom_default_action_callback function from the 38 * dom_events_default_action_fetcher with param 39 * DOM_DEFAULT_ACTION_STARTED, and then call it; 40 * 5. The callback function invoke some System-denpendent API to make the 41 * checkbox checked and then return; 42 * 6. Normal event flow goes on. 43 * 7. When the implementation reach the end of the event flow, it check whether 44 * the event's default action is prevented, if it is, then go to step 8, 45 * else go to step 9. 46 * 8. The event's default action get prevented, DOM get the 47 * dom_default_action_callback function from the 48 * dom_events_default_action_fetcher with param 49 * DOM_DEFAULT_ACTION_PREVENTED, and then call it. 50 * 8. The event's default action does not get prevented, DOM get the 51 * dom_default_action_callback function from the 52 * dom_events_default_action_fetcher with param 53 * DOM_DEFAULT_ACTION_END, and then call it. 54 * 55 * @note: the point here is that we want the UI related stuff to be done 56 * within the default action code. The DOM only take care of the content tree 57 * and the event flow itself. 58 */ 59 typedef void (*dom_default_action_callback)(struct dom_event *evt, void *pw); 60 61 /** 62 * The default action phase 63 * 64 * @note: we define the following three values to fetch three different types 65 * of dom_default_action_callback function and their private data. 66 */ 67 typedef enum { 68 DOM_DEFAULT_ACTION_STARTED = 0, 69 DOM_DEFAULT_ACTION_PREVENTED, 70 DOM_DEFAULT_ACTION_END, 71 DOM_DEFAULT_ACTION_FINISHED 72 } dom_default_action_phase; 73 74 /** 75 * The default action fetcher 76 * 77 * \param type The type of the event 78 * \param phase The phase of the default action callback 79 * \param pw The return private data of the callback function 80 * \return a callback function, NULL if there is none. 81 */ 82 typedef dom_default_action_callback (*dom_events_default_action_fetcher) 83 (dom_string *type, dom_default_action_phase phase, 84 void **pw); 85 86 dom_exception _dom_document_event_create_event(dom_document_event *de, 87 dom_string *type, struct dom_event **evt); 88 #define dom_document_event_create_event(d, t, e) \ 89 _dom_document_event_create_event((dom_document_event *) (d), \ 90 (dom_string *) (t), (struct dom_event **) (e)) 91 92 dom_exception _dom_document_event_can_dispatch(dom_document_event *de, 93 dom_string *namespace, dom_string *type, 94 bool* can); 95 #define dom_document_event_can_dispatch(d, n, t, c) \ 96 _dom_document_event_can_dispatch((dom_document_event *) (d), \ 97 (dom_string *) (n), (dom_string *) (t),\ 98 (bool *) (c)) 99 100 #endif 101 102