libdom
Loading...
Searching...
No Matches
document_event.h File Reference
#include <stdbool.h>
#include <dom/core/exceptions.h>
#include <dom/core/string.h>

Go to the source code of this file.

Macros

#define dom_document_event_create_event(d, t, e)
 
#define dom_document_event_can_dispatch(d, n, t, c)
 

Typedefs

typedef struct dom_document dom_document_event
 
typedef void(* dom_default_action_callback) (struct dom_event *evt, void *pw)
 
typedef dom_default_action_callback(* dom_events_default_action_fetcher) (dom_string *type, dom_default_action_phase phase, void **pw)
 

Enumerations

enum  dom_default_action_phase { DOM_DEFAULT_ACTION_STARTED = 0 , DOM_DEFAULT_ACTION_PREVENTED , DOM_DEFAULT_ACTION_END , DOM_DEFAULT_ACTION_FINISHED }
 

Functions

dom_exception _dom_document_event_create_event (dom_document_event *de, dom_string *type, struct dom_event **evt)
 
dom_exception _dom_document_event_can_dispatch (dom_document_event *de, dom_string *namespace, dom_string *type, bool *can)
 

Macro Definition Documentation

◆ dom_document_event_can_dispatch

#define dom_document_event_can_dispatch ( d,
n,
t,
c )
Value:
(dom_string *) (n), (dom_string *) (t),\
(bool *) (c))
dom_exception _dom_document_event_can_dispatch(dom_document_event *de, dom_string *namespace, dom_string *type, bool *can)
Definition document_event.c:174
Definition document.h:43
Definition string.h:19

◆ dom_document_event_create_event

#define dom_document_event_create_event ( d,
t,
e )
Value:
(dom_string *) (t), (struct dom_event **) (e))
dom_exception _dom_document_event_create_event(dom_document_event *de, dom_string *type, struct dom_event **evt)
Definition document_event.c:96
Definition event.h:27

Typedef Documentation

◆ dom_default_action_callback

typedef void(* dom_default_action_callback) (struct dom_event *evt, void *pw)

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.
  1. 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.

◆ dom_document_event

◆ dom_events_default_action_fetcher

typedef dom_default_action_callback(* dom_events_default_action_fetcher) (dom_string *type, dom_default_action_phase phase, void **pw)

The default action fetcher

Parameters
typeThe type of the event
phaseThe phase of the default action callback
pwThe return private data of the callback function
Returns
a callback function, NULL if there is none.

Enumeration Type Documentation

◆ dom_default_action_phase

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.
Enumerator
DOM_DEFAULT_ACTION_STARTED 
DOM_DEFAULT_ACTION_PREVENTED 
DOM_DEFAULT_ACTION_END 
DOM_DEFAULT_ACTION_FINISHED 

Function Documentation

◆ _dom_document_event_can_dispatch()

dom_exception _dom_document_event_can_dispatch ( dom_document_event * de,
dom_string * namespace,
dom_string * type,
bool * can )

Tests if the implementation can generate events of a specified type

Parameters
deThe DocumentEvent
namespaceThe namespace of the event
typeThe type of the event
canTrue if we can generate such an event, false otherwise
Returns
DOM_NO_ERR on success, appropriate dom_exception on failure.

We don't support this API now, so the return value should always DOM_NO_SUPPORTED_ERR.

◆ _dom_document_event_create_event()

dom_exception _dom_document_event_create_event ( dom_document_event * de,
dom_string * type,
struct dom_event ** evt )

Create an Event object

Parameters
deThe DocumentEvent object
typeThe Event type
evtThe returned Event object
Returns
DOM_NO_ERR on success, appropriate dom_exception on failure.