Subversion Repositories Kolibri OS

Rev

Go to most recent revision | Blame | Last modification | View Log | Download | RSS feed

  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_phase;
  72.  
  73. /**
  74.  * The default action fetcher
  75.  *
  76.  * \param type   The type of the event
  77.  * \param phase  The phase of the default action callback
  78.  * \param pw     The return private data of the callback function
  79.  * \return a callback function, NULL if there is none.
  80.  */
  81. typedef dom_default_action_callback (*dom_events_default_action_fetcher)
  82.                 (dom_string *type, dom_default_action_phase phase,
  83.                 void **pw);
  84.  
  85. dom_exception _dom_document_event_create_event(dom_document_event *de,
  86.                 dom_string *type, struct dom_event **evt);
  87. #define dom_document_event_create_event(d, t, e) \
  88.                 _dom_document_event_create_event((dom_document_event *) (d), \
  89.                 (dom_string *) (t), (struct dom_event **) (e))
  90.  
  91. dom_exception _dom_document_event_can_dispatch(dom_document_event *de,
  92.                 dom_string *namespace, dom_string *type,
  93.                 bool* can);
  94. #define dom_document_event_can_dispatch(d, n, t, c) \
  95.                 _dom_document_event_can_dispatch((dom_document_event *) (d), \
  96.                 (dom_string *) (n), (dom_string *) (t),\
  97.                 (bool *) (c))
  98.  
  99. #endif
  100.  
  101.