Contents
Working with the DOM
The WebKitGTK+ Reference Manual covers the GTK+ specific interface for WebKit. However, most of the functionality provided by WebKitGTK+ is related to working with the DOM, which is not documented in that manual. Fortunately, there's a workaround for that.
The DOM specification is defined by the W3C in the form of Interface Definition Language (IDL) files, which are included as part of the WebKit source code. The WebKit build system uses these to create the C-language DOM API bindings for WebKitGTK+, as well as the JavaScript bindings, and other graphical front-ends for WebKit such as Objective C bindings for Mac OS X and iOS.
While the GTK+ DOM binding isn't well documented, the IDL itself and the JavaScript binding are very thoroughly documented – see:
The W3C's IDL specifications: http://www.w3.org/TR/#tr_DOM
Mozilla's JavaScript DOM reference: https://developer.mozilla.org/en/Gecko_DOM_Reference
w3schools' JavaScript references and tutorials: http://www.w3schools.com/htmldom/dom_intro.asp
That being the case, it's often easiest to look at the IDL or JavaScript documentation, find a reference to the DOM functionality you need, and then figure out the equivalent WebKitGTK+ API.
For instance, let's say you want to know if the user is holding the control key down when doing a mouse click. The references above show a ctrlKey attribute in the IDL for MouseEvent, and in JavaScript, if you have an event named event, you can test event.ctrlKey. If you go to where your WebKitGTK+ headers are installed, and search for “ctrl”, you will find that WebKitDOMMouseEvent.h contains:
WEBKIT_API gboolean webkit_dom_mouse_event_get_ctrl_key(WebKitDOMMouseEvent* self);
which is exactly the API call you need. In general, if you are looking for a DOM method fooBar, you can easily find the equivalent WebKitGTK+ C function by searching the header files for “foo” or “bar”, and the resulting function prototype will contain foo_bar.
Selected APIs
WebKitGTK+ supports over 1800 different function calls; this document only covers a limited subset.
Visual Appearance
webkit_dom_element_scroll_into_view()
void webkit_dom_element_scroll_into_view (WebKitDOMElement* self,
gboolean align_with_top);This will scroll the specified element into view. If the align_with_top argument is true, the scrolled element will be aligned with the top of the scroll area; otherwise, it will be aligned with the bottom.
webkit_dom_element_scroll_into_view_if_needed()
void webkit_dom_element_scroll_into_view_if_needed(WebKitDOMElement* self, gboolean center_if_needed);
This will scroll an element into view if it is outside the viewport. If the center_if_needed argument is true, this will center the element in the viewport; otherwise, it will scroll as little as possible to make the element visible in the viewport.
Unlike webkit_dom_element_scroll_into_view() , this will not scroll any elements if the argument element is already fully visible in the viewport.
Events
There are many interesting prototypes in WebKitDOMEvent.h; here are a few.
webkit_dom_event_get_type()
GType webkit_dom_event_get_type (void);
Returns the GObject type of a DOM event.
webkit_dom_event_stop_immediate_propagation()
void webkit_dom_event_stop_immediate_propagation(WebKitDOMEvent* self);
If you call this from inside an event listener, it will stop further propagation of the event in the current phase.
webkit_dom_event_target_dispatch_event()
void webkit_dom_event_target_dispatch_event(WebKitDOMEventTarget *target,
WebKitDOMEvent *event,
GError **error);
GObjectEventListenerCallback
typedef void (*GObjectEventListenerCallback) (GObject*,
WebKitDOMEvent*,
void*);This is the actual callback type used by webkit_dom_event_target_add_event_listener() and webkit_dom_event_target_remove_event_listener() below.
webkit_dom_event_target_add_event_listener()
gboolean webkit_dom_event_target_add_event_listener(WebKitDOMEventTarget *target,
const char *eventName,
GCallback handler,
boolean bubble,
gpointer userData);bubble indicates whether the handler should be called during the capture or bubble phase of event propagation. You can register the same function for both phases, and it’s treated as two different handlers for purposes of both being called, and for removal - see webkit_dom_event_target_remove_event_listener() below.
Returns: TRUE if the listener was successfully added.
webkit_dom_event_target_remove_event_listener()
gboolean webkit_dom_event_target_remove_event_listener(WebKitDOMEventTarget *target,
const char *eventName,
GCallback handler,
gboolean bubble);Removes a previously-added event listener.
Returns: TRUE if the listener was successfully removed.
webkit_dom_event_get_target()
WebKitDOMEventTarget* webkit_dom_event_get_target(WebKitDOMEvent* self);
Returns: the element the event actually occurred on. This does not vary with event capturing and bubbling.
webkit_dom_event_get_current_target()
WebKitDOMEventTarget* webkit_dom_event_get_current_target(WebKitDOMEvent* self);
Returns: the element whose event listeners are currently being processed. This changes during event capturing and bubbling.
webkit_dom_event_get_event_phase()
gushort webkit_dom_event_get_event_phase(WebKitDOMEvent* self);
Indicates which phase of the event flow is currently being evaluated.
Returns: 1 if in capturing phase, 2 if at the target, 3 if in bubbling phase
Finding Elements in the DOM
webkit_dom_document_get_elements_by_tag_name()
WebKitDOMNodeList* webkit_dom_document_get_elements_by_tag_name(WebKitDOMDocument* self,
const gchar* tagname);Searches the subtree beneath (but not including) self, and returns a list of elements with the given tag name. The special value "*" matches all tags.
WebKitDOMNodeList* list = webkit_dom_document_get_elements_by_tag_name(doc, “td”);
webkit_dom_document_get_elements_by_tag_name_ns()
WebKitDOMNodeList* webkit_dom_document_get_elements_by_tag_name_ns(
WebKitDOMDocument* self,
const gchar* namespace_uri,
const gchar* local_name);Searches the subtree beneath (but not including) self, and returns a list of elements with the given namespace and tag name. The special value "*" matches all namespaces and tags, respectively.
WebKitDOMNodeList* list = webkit_dom_document_get_elements_by_tag_name(doc,
"http://www.w3.org/1999/xhtml", “td”);
webkit_dom_document_get_elements_by_name()
WebKitDOMNodeList* webkit_dom_document_get_elements_by_name(WebKitDOMDocument* self,
const gchar* element_name);Searches the subtree beneath (but not including) self, and returns a list of elements with the given name attribute.
WebKitDOMNodeList* up_elems = webkit_dom_document_get_elements_by_name(doc, “up”);
webkit_dom_document_get_element_by_id()
WebKitDOMElement* webkit_dom_document_get_element_by_id(WebKitDOMDocument* self,
const gchar* element_id);Returns the element with the specified ID, or NULL if no such element exists. If more than one element has this ID, the behavior is undefined.
webkit_dom_document_get_elements_by_class_name()
WebKitDOMNodeList* webkit_dom_document_get_elements_by_class_name(
WebKitDOMDocument* self,
const gchar* tagname);Searches the subtree beneath (but not including) self, and returns a list of elements with the given class name. Multiple class names can be included by using spaces as separators. For instance:
WebKitDOMNodeList* elems = webkit_dom_document_get_elements_by_class_name(doc,
“red blue”);will retrieve all elements that have both red and blue classes.
webkit_dom_document_get_forms()
WebKitDOMHTMLCollection* webkit_dom_document_get_forms(WebKitDOMDocument* self);
Returns a list of the form elements within self.
webkit_dom_element_get_elements_by_tag_name()
WebKitDOMNodeList* webkit_dom_element_get_elements_by_tag_name(WebKitDOMElement* self,
const gchar* name);Searches the subtree beneath (but not including) self, and returns a list of elements with the given tag name. The special value "*" matches all tags.
webkit_dom_element_get_elements_by_tag_name_ns()
WebKitDOMNodeList* webkit_dom_element_get_elements_by_tag_name_ns(
WebKitDOMElement* self,
const gchar* namespace_uri,
const gchar* local_name);Searches the subtree beneath (but not including) self, and returns a list of elements with the given namespace and tag name. The special value "*" matches all namespaces and tags, respectively.
webkit_dom_element_get_elements_by_class_name()
WebKitDOMNodeList* webkit_dom_element_get_elements_by_class_name(
WebKitDOMElement* self,
const gchar* name);Searches the subtree beneath (but not including) self, and returns a list of elements with the given class name. Multiple class names can be included by using spaces as separators.
webkit_dom_html_document_has_focus()
gboolean webkit_dom_html_document_has_focus(WebKitDOMHTMLDocument* self);
Returns whether or not the document itself, or an element in the document, has focus.
webkit_dom_html_document_get_active_element()
WebKitDOMElement* webkit_dom_html_document_get_active_element(
WebKitDOMHTMLDocument* self);Returns the active element in the document - e.g., either the focused element, or the element that would receive focus if the document itself had focus. For an element to be focused, it must be active, and its document must have focus.
Note: When a document first loads, sometimes an element receives focus without a focus event firing.
webkit_dom_html_form_element_get_elements()
WebKitDOMHTMLCollection* webkit_dom_html_form_element_get_elements(
WebKitDOMHTMLFormElement* self);Returns a collection of all the form control elements in the form.
Working with Node Lists
webkit_dom_node_list_get_length()
gulong webkit_dom_node_list_get_length(WebKitDOMNodeList* self);
Get the number of items in the list.
webkit_dom_node_list_item()
WebKitDOMNode webkit_dom_node_list_item(WebKitDOMNodeList* self, gulong index);
Get the list’s node at the specified index.
Miscellaneous
webkit_dom_html_document_get_active_element()
WebKitDOMElement* webkit_dom_html_document_get_active_element(
WebKitDOMHTMLDocument* self);Get the active element in the specified document.
You can obtain a document to be used here by calling webkit_web_view_get_dom_document() on a WebKitWebView, and then dynamically casting the return value to a WebKitDOMHTMLDocument.