From 61143e0bd261dcb325335d41443204a806abe792 Mon Sep 17 00:00:00 2001 From: Daniel Silverstone Date: Fri, 3 May 2019 11:53:02 +0100 Subject: Add some more bits to the jsbinding document Signed-off-by: Daniel Silverstone --- docs/jsbinding.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) (limited to 'docs/jsbinding.md') diff --git a/docs/jsbinding.md b/docs/jsbinding.md index c258a678d..cf3bc5a09 100644 --- a/docs/jsbinding.md +++ b/docs/jsbinding.md @@ -57,3 +57,31 @@ binding definitions to implement the interfaces. The bindings are a Domain Specific Language (DSL) which allows implementations to be added to each WebIDL method. + +Javascript implementation +------------------------- + +NetSurf consumes the Duktape JS engine in order to run the JS code which +is used within the browser. Duktape is exceedingly well documented and +its API docs at https://duktape.org/api.html are incredibly useful. + +It'll be worthwhile learning about how duktape stacks work in order to +work on bindings in NetSurf + +Dukky +----- + +Wrappering around and layering between duktape and the browser is a set of +functionality we call `dukky`. This defines a variety of conventions and +capabilities which are common to almost all bindings. The header `dukky.h` +provides the interface to these functions. Normally these functions are +subsequently used by automatically generated content, but if your bindings +need to add DOM nodes back into the JavaScript environment (for example when +returning them from a method implementation) you will want `dukky_push_node()` +or when calling a function in a JS context you'll likely want `dukky_pcall()` + +Dukky automatically terminates any JS call which lasts for more than 10 +seconds. If you are calling a JS function from outside any of the "normal" +means by which dukky might call code on your behalf (`js_exec()`, events, etc) +then you should be sure to use `dukky_pcall()` and pass in `true` in +`reset_timeout` otherwise your code may unexpectedly terminate early. -- cgit v1.2.3