diff options
Diffstat (limited to 'api/dwb-js.7')
-rw-r--r-- | api/dwb-js.7 | 222 |
1 files changed, 220 insertions, 2 deletions
diff --git a/api/dwb-js.7 b/api/dwb-js.7 index d1fbb313..75ae3ac0 100644 --- a/api/dwb-js.7 +++ b/api/dwb-js.7 @@ -2,12 +2,12 @@ .\" Title: dwb-js .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] .\" Generator: DocBook XSL Stylesheets v1.77.1 <http://docbook.sf.net/> -.\" Date: 12/06/2012 +.\" Date: 12/07/2012 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "DWB\-JS" "7" "12/06/2012" "\ \&" "\ \&" +.TH "DWB\-JS" "7" "12/07/2012" "\ \&" "\ \&" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -1135,6 +1135,224 @@ Label used for displaying uris, third child of Label used for status information, fourth child of \fBgui\&.statusBox\fR\&. .RE +.SS "Deferred" +.sp +Deferred objects can be used to manage asynchronous operations\&. It can trigger a callback function when an asynchrounous operation has finished, and allows chaining of callbacks\&. Deferred basically have 2 callback chains, a \fIdone\fR\-chain and a \fIfail\fR\-chain\&. If a asynchronous operation is successful the deferred should be resolved and the done callback chain of the deferred is called\&. If a asynchronous operation fails the deferred should be rejected and the fail callback chain of the deferred is called\&. +.sp +Deferreds implement the following methods: +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBvoid Deferred.done(Function callback)\fR +.RS 4 +.sp +Registers a function for the done\-chain\&. +.PP +\fIcallback\fR +.RS 4 +A callback function that will be called when the Deferred is resolved\&. If the function returns a deferred the original deferred will be replaced with the new deferred\&. +.RE +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBvoid Deferred.fail(Function callback)\fR +.RS 4 +.sp +Registers a function for the fail\-chain\&. +.PP +\fIcallback\fR +.RS 4 +A callback function that will be called when the deferred is rejected\&. If the function returns a deferred the original deferred will be replaced with the new deferred\&. +.RE +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBvoid Deferred.reject(arguments)\fR +.RS 4 +.sp +Rejects a deferred, the fail\-chain is called when a deferred is rejected\&. +.PP +\fIarguments\fR +.RS 4 +Arguments passed to the +\fIfail\fR +callbacks\&. +.RE +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBvoid Deferred.resolve(arguments)\fR +.RS 4 +.sp +Resolves a deferred, the done\-chain is called when a deferred is resolved\&. +.PP +\fIarguments\fR +.RS 4 +Arguments passed to the +\fIdone\fR +callbacks\&. +.RE +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBvoid Deferred.then(Function ondone, Function onfail)\fR +.RS 4 +.sp +Registers a function for the done and fail chain\&. +.PP +\fIondone\fR +.RS 4 +A callback function that will be called when the deferred is resolved\&. If the function returns a deferred the original deferred will be replaced with the new deferred\&. +.RE +.PP +\fIonfail\fR +.RS 4 +A callback function that will be called when the deferred is rejected\&. If the function returns a deferred the original deferred will be replaced with the new deferred\&. +.RE +.sp +Simple usage of a deferred: +.sp +.if n \{\ +.RS 4 +.\} +.nf +function loadUri(uri) { + var d = new Deferred(); + tabs\&.current\&.loadUri(uri, function(wv) { + if (wv\&.loadStatus == LoadStatus\&.finished) + { + d\&.resolve("Finished"); + return true; + } + else if (wv\&.loadStatus == LoadStatus\&.failed) + { + d\&.reject("Failed"); + return true; + } + }); + return d; +} + +loadUri("http://www\&.example\&.com")\&.then( + function(response) { + io\&.print(response); // Finished + }, + function(response) { + io\&.print(response); // Failed + } +); +.fi +.if n \{\ +.RE +.\} +.sp +Chaining of a deferred: +.sp +.if n \{\ +.RS 4 +.\} +.nf +function foo() +{ + var d = new Deferred(); + timerStart(2000, function() { + d\&.reject("rejected"); + }); + return d; +} + +function onResponse(response) +{ + io\&.print(response); +} + +// Will print "rejected" twice to stdout after 2 seconds +foo()\&.fail(onResponse)\&.fail(onResponse); +.fi +.if n \{\ +.RE +.\} +.sp +Note that if the deferred is rejected only the fail chain is called, when it is resolved only the done chain is called\&. It is not possible to mix up done and fail chain\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +function foo() +{ + var d = new Deferred(); + timerStart(2000, function() { + d\&.reject("rejected"); + // Already rejected, will not execute the done chain + d\&.resolve("rejected"); + }); + return d; +} + +function onResponse(response) +{ + io\&.print(response); +} + +// Will not be executed at all\&. +foo()\&.done(onResponse)\&.fail(onResponse); +// Only the first callback is executed +foo()\&.fail(onResponse)\&.done(onResponse); +.fi +.if n \{\ +.RE +.\} +.sp +Changing the deferred in a callback chain: +.sp +.if n \{\ +.RS 4 +.\} +.nf +function foo(message) +{ + var d = new Deferred(); + timerStart(2000, function() { + d\&.resolve(message); + }); + return d; +} + +foo("foo")\&.done( + function(response) { + io\&.print(response); // Prints "foo" after 2 seconds + + // Return a new Deferred, will replace the old one\&. + return foo("bar"); + })\&.done( + function(response) { + io\&.print(response); // Prints "bar" after 4 seconds + }); +.fi +.if n \{\ +.RE +.\} +.RE .SH "WEBKIT OBJECTS" .sp All webkit objects correspond to gobject objects, i\&.e\&. they have the same properties, but the javascript properties are all camelcase\&. For example, a WebKitWebView has the property \fBzoom\-level\fR, the corresponding javascript property is \fBzoomLevel\fR: |