summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorVincent Sanders <vince@kyllikki.org>2019-05-06 12:03:08 +0100
committerVincent Sanders <vince@kyllikki.org>2019-05-06 12:04:06 +0100
commitdbf02c37f4f1652561b9542530dd93b3ba310e9f (patch)
tree8b5015c155e4c23fc4ff51ff8d337561183782e1 /docs
parent183f9ed8bc4be1f379e365fae5f47dbb348b7978 (diff)
downloadnetsurf-dbf02c37f4f1652561b9542530dd93b3ba310e9f.tar.gz
netsurf-dbf02c37f4f1652561b9542530dd93b3ba310e9f.tar.bz2
complete basic binding documentation
improve the alert() method parameter handling
Diffstat (limited to 'docs')
-rw-r--r--docs/jsbinding.md123
1 files changed, 121 insertions, 2 deletions
diff --git a/docs/jsbinding.md b/docs/jsbinding.md
index 42d61a676..8b24a80a5 100644
--- a/docs/jsbinding.md
+++ b/docs/jsbinding.md
@@ -113,10 +113,10 @@ The binding implementations are in the form of C code fragments
directly pasted into the generated code with generated setup code
surrounding it.
-### Simple getter and setter example
+### Simple attribute example
The Window interface (class) in the HTML specification has an
-attribute called `name`.
+attribute (property) called `name`.
The full WebIDL for the Window interface is defined in the
`content/handlers/javascript/WebIDL/html.idl` file but the
@@ -189,6 +189,125 @@ So for the name attribute case the complete setter binding is:
return 0;
%}
+This uses browser_window_set_name() interface to set the name of the
+window. The return indicates the success of the operation.
### Simple method example
+The Location interface (class) in the HTML specification has an
+operation (method) called `asign`. This method causes the browser to
+navigate to a new url.
+
+The full WebIDL for the Window interface is defined in the
+`content/handlers/javascript/WebIDL/html.idl` file but the
+fragment for our example is:
+
+ interface Location {
+ void assign(DOMString url);
+ }
+
+This shows there is an operation called assign in the Location
+interface which takes a single string parameter and returns nothing.
+
+The method binding will be added to `Location.bnd` similarly to how
+the attribute example used `Window.bnd`
+
+ method Location::assign()
+ %{
+ window_private_t *priv_win;
+ nsurl *joined;
+ duk_size_t slen;
+ const char *url;
+
+ /* retrieve the private data from the root object (window) */
+ duk_push_global_object(ctx);
+ duk_get_prop_string(ctx, -1, PRIVATE_MAGIC);
+ priv_win = duk_get_pointer(ctx, -1);
+ duk_pop(ctx);
+
+ if (priv_win == NULL || priv_win->win == NULL) {
+ NSLOG(netsurf, INFO, "failed to get browser context");
+ return 0;
+ }
+
+ url = duk_safe_to_lstring(ctx, 0, &slen);
+
+ nsurl_join(priv->url, url, &joined);
+ browser_window_navigate(priv_win->win,
+ joined,
+ NULL,
+ BW_NAVIGATE_HISTORY,
+ NULL,
+ NULL,
+ NULL);
+ nsurl_unref(joined);
+ return 0;
+ %}
+
+The nsgenbind tool generates code that automatically allows acess to
+the classes private data structure elements through a variable called
+`priv` and the duktape stack in the variable `ctx`.
+
+In this case nsgenbind will generate code that will ensure there is at
+least one parameter and coerce it to a string on the duktape `ctx`
+stack returning a type error if it is unable to do so.
+
+The binding implementation shown here uses browser_window_navigate()
+to navigate to the new url. To do this it needs the browser window
+handle (pointer) which is obtained from the global object (the window)
+private structure.
+
+Note that the duk_safe_to_lstring() call used to obtain the url
+parameter needs no additional checking as nsgenbind emits this code
+automaticaly.
+
+### Overloaded method example
+
+The Window interface (class) in the HTML specification has an
+operation (method) called `alert`. This method is supposed to cause
+the user to be alerted about something on the page.
+
+The full WebIDL for the Window interface is defined in the
+`content/handlers/javascript/WebIDL/html.idl` file but the
+fragment for our example is:
+
+ interface Window : EventTarget {
+ void alert();
+ void alert(DOMString message);
+ };
+
+This indicates there is an operation called `alert`. It has two
+overloaded prototypes, one takes no parameters and one takes a string
+parameter (technicaly a DOMString but the implementation does not
+differentiate between string types)
+
+The method binding will be added to `Window.bnd` as the attribute example
+
+ method Window::alert()
+ %{
+ duk_idx_t dukky_argc = duk_get_top(ctx);
+ if (dukky_argc == 0) {
+ NSLOG(netsurf, INFO, "JS ALERT");
+ } else {
+ duk_size_t msg_len;
+ const char *msg;
+
+ if (!duk_is_string(ctx, 0)) {
+ duk_to_string(ctx, 0);
+ }
+ msg = duk_safe_to_lstring(ctx, 0, &msg_len);
+ NSLOG(netsurf, INFO, "JS ALERT: %*s", (int)msg_len, msg);
+ }
+ return 0;
+ %}
+
+The nsgenbind tool generates code that automatically allows acess to
+the classes private data structure elements through a variable called
+`priv` and the duktape stack in the variable `ctx`.
+
+For overloaded method calls nsgenbind does not emit code to do
+parameter verification and the binding code has to deal with all
+possible parameters itself.
+
+This binding checks the number of parameters and if one is present it
+coerces it to be a string and logs the result. \ No newline at end of file