summaryrefslogtreecommitdiff
path: root/api/dwb-js.7
diff options
context:
space:
mode:
Diffstat (limited to 'api/dwb-js.7')
-rw-r--r--api/dwb-js.7222
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: