101 lines
3.6 KiB
C
101 lines
3.6 KiB
C
/*
|
|
* 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
|
|
|