// See COPYING for copyright and license details

// vim: set ft=asciidoc:

= dwb-js(7) =
:doctype: manpage


== NAME ==
dwb-js - dwb's javascript api documentation


== DESCRIPTION ==
dwb provides a javascript api that can be used to write userscripts or
extensions for dwb. 

== GETTING STARTED == 
Scripts that use the javascript api must be located in
*$XDG_CONFIG_HOME/dwb/userscripts* like any other script. 
Scripts that use the javascript api must either start with 

-------
#!javascript
-------

or with 

-------
//!javascript
-------

All native javascript methods can be used in scripts, however there are
limitations:  

* The execution context of userscripts is completely separated from the web
execution context. Due to security concerns it is not possible to communicate
with the web execution context, it is only possible to inject scripts into the
web context.
* In contrast to the global window object in the web execution context, 
the global object is a readonly object, i.e. it is not possible to set
properties on the global object, see also *Global data* for details.

== Global ==

=== Properties

_global (Object, read)_;; Refers to the global object
_session (SoupSession, read)_;; The webkit session

=== Methods ===

==== void pass:[__assert__](Expression expression) 

****
Prints an assertion message and returns, if called in the global context of a
script it stops the execution of the script. Note that pass:[__assert__] is not
actually a function but a macro, a ; is mandatory at the end of an 
pass:[__assert__] statement.

_expression_;; An expression that evaluates to true or false.
****

==== void pass:[__profile__](String profile, ...) 

****
Use this script only for the specified profiles. If the current profile doesn't
match the specified profiles the script will stop immediately. This macro must
be defined at the beginning of the script. Note that pass:[__profile__] is a
macro, a ; is mandatory at the end of a pass:[__profile__] statement.

_profile_;; A list of profiles that use this script.
****

==== Boolean bind(String shortcut, Function callback, [String name])

****

Bind a javascript function to a shortcut. This is the preferred method of
binding keys to shortcuts since the shortcut is evaluated using the native
method, but also the keyPress-signal can be used to bind shortcuts. 

_shortcut_;; A shortcut, will be parsed the same way as if set in
dwb:keys
_callback_;; Callback function that will be called when the shortcut is pressed
_name_;; A name that identifies the function on command line, optional
*returns*;; true if the function was bound successfully
****

==== Boolean execute(String command)

****
Executes a dwb command

_command_;; a dwb command to execute, will be parsed the same way as if executed
from commandline
*returns*;; true if execution was successful
**** 

==== Boolean exit()
****

Exit dwb, must be called if the script is running from commandline. 
****

==== Boolean hint(String shortcut, Function callback, [String command], [String selector])

****

Adds a custom hintmode, similar to bind but executes the function before the
hint will be followed, use unbind to remove the hintmode

_shortcut_;; A shortcut to start the hint mode. 
_callback_;; The callback function, that will be called before the hint is
followed, see followHint. To handle the hint and prevent dwb from following the
hint the callback must return true. The callback won't be called if escape was
pressed.  
_command_;; The command to start the hint mode, optional.
_selector_;; A css selector passed to querySelectorAll, optional.
****


==== Object include(String path, [Boolean global])
****

Includes a file. Note that there is only one context, all scripts are
executed in this context. Included files are not visible in other scripts unless
true is passed as second parameter. 

_path_;; Path to a file to include
_global_;; Whether to include the script into the global scope, optional
*returns*;; The return value of the included file
****

NOTE: Scripts included with include are either visible in the global scope or
invisible, even in the including script. To use an included script it can return
an object with its public objects: 

[source,javascript]
---------------------------------
// included script 

var private = 37;
return {
  getPrivate : function () {
    return private;
  }
};

// Scripts that includes the above
var i = include("/path/to/script");
var p = i.getPrivate();               // 37
---------------------------------

or define a module that can be shared: 

[source,javascript]
---------------------------------
// included script 

var private = 37;
provide("foo", {
    getPrivate : function() {
        return private;
    }
});

// Scripts that includes the above
var i = include("/path/to/script");
require(["foo"], function(foo) {
    var bar = foo.getPrivate();               // 37
})
---------------------------------


==== void provide(String name, Object module)
****
Defines a module that can be used in other scripts, see MODULES for details.

_name_;; Name of the module
_module_;; The module
****

==== void replace(String name, Object module)
****
Same as provide but replaces the module if it was already defined.

_name_;; Name of the module
_module_;; The module, if omitted the module will be deleted, all references to
that module will reference an empty object afterwards, optional.
****

==== void require(Array names, Function callback)
****
Load modules defined with provide.

_names_;; An array of module names or null to get all modules, a module name can
also contain a path, the path must be separated with a *!* from the module name,
see also MODULES for details.
_callback_;; A callback function that is called after initialization of all
scripts and modules. The parameters of the callback function correspond to the
names array. If *names* is null the function is called with one parameter that
contains all modules, see also MODULES for examples.
****

==== Number unbind(Function func|String name)
****

Unbind a shortcut that was previously bound with bind

_func_ or _name_;; Either the function or the optional name passed to bind.
*returns*;; true if the function was unbound
****

==== Object xinclude(String path)
****

Include scripts from an archive.

Same as include but this function can only be called from scripts inside an
archive, so this is mostly useful in extensions. However it is possible to
include scripts from an archive calling the internal function *_xinclude* which
takes two parameters, the path of the archive and the path of the included file
in the archive. All scripts inside an archive share an object *exports* which
can be used to share data between scripts in an archive, all exports objects
have a readonly property id which is unique to all archives, it can be used
together with require/provide to define unique module names.

_path_;; Path of the file in the archive
*returns*;; The object returned from the included file
****

== GLOBAL OBJECTS ==

=== data ===
The data object can be used to determine internally used data securely. All
properties are readonly Strings.

****
_data.bookmarks_;; Bookmark file 
_data.cacheDir_;; Cache directory 
_data.configDir_;; Config directory 
_data.cookies_;; Cookie file 
_data.cookiesWhitelist_;; Whitelist for persistent cookies 
_data.customKeys_;; Custom keyboard shortcuts 
_data.history_;; History file 
_data.keys_;; Shortcuts configuration file 
_data.pluginsWhitelist_;; Whitelist for the plugin blocker
_data.profile_;; Profile which will be *default* unless another profile is specified on command line
_data.quickmarks_;; Quickmark file 
_data.scriptWhitelist_;; Whitelist for scripts
_data.session_;; File with stored sessions for this profile
_data.sessionCookiesWhitelist_;; Whitelist for session cookies
_data.settings_;; Settings configuration file
_data.searchEngines_;; Searchengines 
****


==== Array data.parse(String name)
****

Parses data into an array

_prompt_;; Name of the data to parse, can be one of bookmarks, cookiesWhitelist,
sessionCookiesWhitelist, scriptWhitelist, pluginsWhitelist, quickmarks or
searchEngines.
*returns*;; Array of parsed objects; quickmarks will return an array of objects
with properties mark and url and searchEngines will return an array of objects
with properties keyword, url and host. All other values will return an array of
strings.
****



=== io ===
The io object implements methods for input and output. 

==== void io.confirm(String prompt)
****

Shows a confirmation prompt.

_prompt_;; The prompt message
*returns*;; True if *y* was pressed, false if *n* or Escape was pressed
****

==== void io.debug([Object detail])
****

Prints a debug message and the call stack to stderr. 

_detail_;; Message details, optional
_detail.message_;; The message to show, optional
_detail.error_;; An Error object, optional 
_detail.arguments_;; Arguments, optional
****

==== Array io.dirNames(String path)
****

Get directory entries.

_path_;; A path to a directory
*returns*;; An array with the directory names
****

==== void io.err(String text, [String ...])
****

Print text to stderr

_text_;; The text to print
...;;  Additional arguments, will be printed comma sperated
****


==== void io.error(String text)
****

Shows an error message in the browser window.

_text_;; The message to show
****

==== void io.notify(String text)
****

Shows a message in the browser window.

_text_;; The message to show
****

==== void io.out(String text, [String ...])
****

Print text to stdout

_text_;; The text to print
...;;  Additional arguments, will be printed comma sperated
****

==== String io.prompt(String text, [Boolean visible])
****

Gets user input synchronously.

_text_;; The message for the prompt
_visible_;; Whether the chars should be visible, pass false for a password
prompt, default true, optional
*returns*;; The text that was entered or null
****


==== String io.read(String path)
****

Read from a file.

_path_;; Path to a file that should be read
*returns*;; A string with the file content
****

==== Boolean io.write(String path, String mode, String text)
****

Write to a file

_path_;; Path to a file to write to
_mode_;; Either "a" to append to the file, or "w" to strip the file or
create a new file.
_text_;; The text that should be written to the file
*returns*;; true if writing was successful
****

=== system ===

The system object implements system methods.

==== Boolean system.fileTest(String path, FileTest flags)
****

Checks for FileTest flags on a file.

_path_;; Path to a file to check
_flags_;; The flags to test
*returns*;; true if any of the test on the flags is true
****

==== String system.getEnv(String name) 
****

Get a system environment variable

_name_;; Name of the variable
*returns*;; The variable or null if the variable wasn't found
****

==== Number system.getPid() 
****

Get the current process id of the instance.

*returns*;; The process id. 
****

==== Boolean system.mkdir(String path, Number mode)
****

Creates a directory and all parent directories.

_path_;; Path to create
_mode_;; The permissions the directory will get
*returns*;; true if creation was successful or directory already existed 
****

==== Deferred system.spawn(String command, [Object options])
****

Executes a shell command using the default search path

_command_;; The command to execute
_options_;; Options
_options.onStdout_;; A callback function that is called when a line from stdout
was read. The function takes one parameter, the line that has been read. To get
the complete stdout use either onFinished or the Deferred returned from
system.spawn.
_options.cacheStdout_;; Whether stdout should be cached. If onStdout is defined
stdout will be cached automatically. If it isn't defined and stdout is required
in onFinished or in the Deferred's resolve function cacheStdout must be set to
true, default: false.
_options.onStderr_;; A callback function that is called when a line from stderr
was read. The function takes one parameter, the line that has been read. To get
the complete stderr use either onFinished or the Deferred returned from
system.spawn.
_options.cacheStderr_;; Whether stderr should be cached. If onStderr is defined
stderr will be cached automatically. If it isn't defined and stderr is required
in onFinished or in the Deferred's reject function cacheStderr must be set to
true, default: false.
_options.onFinished_;; A callback that will be called when the child process has
terminated. The callback takes one argument, an object that contains stdout,
stderr and status, i.e. the return code of the child process.
_options.stdin_;; String that will be piped to stdin of the child process.
_options.environment_;; Hash of environment variables that will be set in the childs environment
*returns*;; A deferred, it will be resolved if the child exits normally, it will
be rejected if the child process exits abnormally. The argument passed to
resolve and reject is an Object containing stdout if caching of stdout is
enabled (see cacheStdout), stderr if caching of stderr is enabled (see
cacheStderr) and status, i.e. the return code of the child process.

****

==== Object system.spawnSync(String command, [Object environment])
****

Executes a shell command synchronously using the default search path

_command_;; The command to execute
_environment_;; Object that can be used to add environment variables to the
children environment, optional.
*returns*;; An object that contains stdout, stderr and status.
****

=== tabs ===
The tabs object is an array like object that can be used to get webviews. It has the
following properties. 

_tabs.current (webview, read)_;; The currently focused webview
_tabs.length (Number, read)_;; Total number of tabs
_tabs.number (Number, read)_;; Number of the currently focused tab

Additionally tabs implements all ECMAScript 5 array methods like forEach, map,
filter, ...



=== net ===

Network related functions

==== Array[Cookie] net.allCookies()
****

Gets all cookies from the cookie jar.

*returns*;; An array of cookies.
**** 

==== void net.clearCookies()
****

Removes all cookies from the cookie jar
**** 

==== String net.domainFromHost(String hostname)
****

Gets the base domain name from a hostname where the base domain name is the
effective second level domain name, e.g. for www.example.com it will be
example.com, for www.example.co.uk it will be example.co.uk.

_hostname_;; a hostname
*returns*;; the base domain 
****

==== Boolean net.domainMatch(String domain, String pattern)
****

Checks if two domain match, also checking for .tld which matches all top level
domains.

_domain_;; A domain name
_pattern_;; The domain pattern to check
*returns*;; True if the host matches
****

==== Boolean net.hostMatch(String host, String pattern)
****

Checks if two hosts match, also checking for .tld which matches all top level
domains.

_domain_;; A host name
_pattern_;; The host pattern to check
*returns*;; True if the host matches
****

==== SoupURI net.parseUri(String uri)
****

Parses an uri to a SoupURI object, see also 'SOUPURI'.

_domain_;; The uri to parse
*returns*;; A parsed uri or *null* if the uri isn't valid according to RFC 3986.
****

==== Array[Cookie] net.persistentCookies()
****

Gets all persistent cookies from the cookie jar.

*returns*;; An array of cookies.
**** 


==== void net.sendRequest(String uri, Function callback, [String method], [Object data])
****

Sends a http-request. 

_uri_;; The uri the request will be sent to.
_callback_;; A callback that will be called when the request is finished, the
callback has 2 parameters, the first will be an object that contains body and
headers, the second the associated SoupMessage.
_method_;; The http request method, default GET, optional.
_data_;; Data to sent if method is POST
_data.contentType_;; The content type
_data.data_;; The data to sent
*returns*;; True if the request was sent.
****

==== Object net.sendRequestSync(String uri, [String method])
****

Sends a http-request synchronously. 

_uri_;; The uri the request will be sent to.
_method_;; The http request method, default GET, optional.
*returns*;; Object that contains the response body, the response headers and
the http status code of
the request. 
****

==== Array[Cookie] net.sessionCookies()
****

Gets all session cookies from the cookie jar.

*returns*;; An array of cookies.
**** 

=== timer === 

Functions for timed execution

==== Number timer.start(Number interval, Function func)
****

Executes a function repeatedly until the function returns false or
timerStop is called on the id returned from this function

_interval_;; Interval in milliseconds
_func_;; Function to execute
*returns*;; An id that can be passed to timerStop
****

==== Boolean timer.stop(Number id)
****

Stops a timer started by timerStart

_id_;; The id returned from timerStart
*returns*;; true if the timer was stopped
****


=== util ===

The util object implements helper methods.

==== String util.base64Decode(String text)
****

Decodes a base64-encoded string to a string.


_text_;; The string to decode
*returns*;; The decoded string
****

==== String util.base64Encode(String text)

****

Encodes a string to base64.

_text_;; The string to encode
*returns*;; A base64-representation of the string
****

==== String util.camelize(String text)

****

Converts a non-camelcase string to a camelcase string.

_text_;; A non-camelcase string
*returns*;; The a camelcase string
****

==== String util.checksum(String data, ChecksumType type)
****

Computes a checksum for given data.

_shortcut_;; The to compute the checksum for.
_type_;; The type of the checksum, optional, defaults to ChecksumType.sha256
*returns*;; The checksum
****

==== Object util.clone(Object object) 

****

Clones an object, circular references are not supported. 

_object_;; The object to clone
*returns*;; A copy of the object
****

==== String util.getBody(Function func) 
****

Gets the body of a function, useful for scripts that will be injected into
sites. 

_func_;; A function 
*returns*;; The body of the function as a string
****

==== String util.dispatchEvent(Number event, Modifier modifier, Number keyval) 
****

Dispatches a keyboard or mouse event.

_object_;; Event details, see buttonPress, buttonRelease, keyPress or
keyRelease for details.
_object.type_;; Type of the event, can be either buttonpress (4), doubleclick (5), 
tripleclick (6), buttonrelease (7), keypress (8) or keyrelease (9).
*returns*;; True if the event was dispatched
****

==== Number util.getMode()
****

Gets the the current mode.

*returns*;; The mode, see Modes for possible modes.
****

==== String util.getSelection()
****

Get selected text from the focused webview.

*returns*;; The selection or null if no text was selected.
****

==== String util.hereDoc(Function doc) 

Creates a multiline string.

_doc_;; A function, the body of the function must contain the here document. The
content must be wrapped in /*HEREDOC ...HEREDOC*/

==== String util.markupEscape(String text)
****

Escapes text for usage with pango markup.

_text_;; A text to escape
*returns*;; The escaped text or 'null';
****

==== String util.mixin(Object self, Object ...)
****

Mixes properties of objects into an object. Properties are mixed in from left to
right, so properties will not be overwritten in the leftmost object if they are
already defined.

_self_;; An object
_Object..._;; Variable number of objects to mix in.
*returns*;; self or a new object if self is null or undefined
****

==== void util.tabComplete(String label, Array items, Function callback, [Boolean readonly])
****

Initiates tab completion.

_label_;; The command line label
_items_;; An array of objects, each object can have 2 properties, left which
will be the left completion label and right which will be the right completion
label.
_callback_;; Callback function, the first argument will be the returned string
from the url bar.
_readonly_;; Whether the items are readonly, default false, optional.
****


==== void util.pathComplete(Function callback, [String label], [String initialPath], [Boolean dirOnly])
****

Initializes filename completion.

_callback_;; Callback function called when a path was chosen or escape was pressed
_label_;; The command line label
_initialPath_;; The initial path, defaults to the current working directory
_dirOnly_;; Whether to complete only directories, default false.
****


==== void util.uncamelize(String text)
****

Converts camel-case string for usage with GObject properties to a non-camel-case
String

_text_;; The text to uncamlize
*returns*;; The uncamelized string
****



dwb also adds additional methods to builtin objects 

==== void Object.forEach(Function func(String key, Object value, Object this))
****

Executes a function for each enumarable property of this similar to
Array.forEach.

_func_;; The function to execute
_key_;; The property name
_value_;; The property value
_this_;; The object forEach is called on
****

==== Number Array.fastIndexOf(Object object)
****

This method is basically the same as Array.indexOf but without type checking.

_object_;; The object to search for
*returns*;; The index in the array or -1 if the Object wasn't found.
****

==== Number Array.fastLastIndexOf(Object object)
****

This method is basically the same as Array.lastIndexOf but without type checking.

_object_;; The object to search for
*returns*;; The index in the array or -1 if the Object wasn't found.
****

==== void Function.debug([Object scope])
****

A wrapper method for debugging callbacks, especially useful if it is combined
with script. 

_scope_;; *script* or *this*, optional
*returns*;; A new function that calls script.debug on errors.
****

=== clipboard ===

==== void clipboard.get(Selection selection, [Function callback])
****

Gets the X11 clipboard.

_selection_;; The Selection to get
_callback_;; If a callback function is used the clipboard will be fetched
asynchronously, the first parameter will be the content of the clipboard, else
it will be fetched synchronously
*returns*;; If no callback was provided it returns the text content of the
clipboard.
****

==== void clipboard.set(Selection selection, String text)
****

Sets the X11 clipboard.

_selection_;; The Selection to set
_text_;; Text that will be stored in the clipboard.
****

=== gui === 

Most gtk-widgets can be accessed from scripts, an overview of the layout can be
found under link:https://portix.bitbucket.org/dwb/resources/layout.html[]. 

_gui.window (GtkWindow, read)_;; The main window.
_gui.mainBox (GtkBox, read)_;;   The the main container, child of *gui.window*. 
_gui.tabBox (GtkBox, read)_;;   The box used for tab labels, child of *gui.mainBox*.
_gui.contentBox (GtkBox, read)_;;   The box used for the main content, it contains all
webviews, child of *gui.mainBox*.
_gui.statusWidget (GtkEventBox, read)_;; The outmost statusbar widget, used for setting
the statusbars colors, child of *gui.mainBox*. 
_gui.statusAlignment (GtkAlignment, read)_;; Used for the statusbar alignment, child
of *gui.statusWidget*. 
_gui.statusBox (GtkBox, read)_;; The box that contains the statusbar widgets,
grandchild of *gui.statusAlignment*.
_gui.messageLabel (GtkLabel, read)_;; Label used for notifications, first child of
*gui.statusBox*.
_gui.entry (GtkEntry, read)_;; The entry, second child of *gui.statusBox*.
_gui.uriLabel (GtkLabel, read)_;; Label used for displaying uris, third child of *gui.statusBox*.
_gui.statusLabel (GtkLabel, read)_;; Label used for status information, fourth child of *gui.statusBox*.

=== Cookie === 

Represents a cookie. dwb only uses one cookie jar for persistent and session
cookies. Session cookies can be distinguished from persistent cookies by
checking if *expires* is null.
To get a list of cookies currently used by the dwb instance
*net.allCookies*, *net.sessionCookies* and *net.persistentCookies* can be used. To
implement cookie handling use the *addCookie* event.

A cookie has the following properties

_domain (String, read, write)_;; The cookie domain. 
_expires (Date, read)_;; The cookie expiration date.
_httpOnly (Boolean, read, write)_;; If the cookie shouldn't be exposed to
scripts.
_name (String, read, write)_;; The cookie name. 
_path (String, read, write)_;; The cookie path. 
_secure (Boolean, read, write)_;; If the cookie should only be transferred over
ssl.
_value (String, read, write)_;; The cookie value. 

A cookie implements following methods:

==== void Cookie.delete()
****

Deletes a cookie from the jar
****

==== void Cookie.delete()
****

Saves a cookie to the jar
****

==== void Cookie.setMaxAge(Number seconds)
****

Sets  the maximum age of a cookie

_seconds_;; The number of seconds until the cookie expires, if set to -1 it is a
session cookie.
****


=== Deferred === 

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 has 2 callback chains, a _done_-chain and a _fail_-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. 


Deferreds implement the following properties and methods: 

_Deferred.isFulFilled (Boolean, read)_;; Whether this deferred is resolved or
rejected.

==== void Deferred.always(Function callback)
****

Registers a function for then done and fail chain.

_callback_;; A callback function that will be called when the Deferred is
resolved or rejected. If the function returns a deferred the original deferred will be replaced with
the new deferred.
*returns*;; A new deferred that can be used to chain callbacks. 
****

==== void Deferred.done(Function callback)
****

Registers a function for the done-chain.

_callback_;; 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.
*returns*;; A new deferred that can be used to chain callbacks. 
****

==== Deferred Deferred.fail(Function callback)
****

Registers a function for the fail-chain.

_callback_;; 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.
*returns*;; A new deferred that can be used to chain callbacks. 
****

==== Deferred Deferred.reject(arguments)
****

Rejects a deferred, the fail-chain is called when a deferred is rejected. 

_arguments_;; Arguments passed to the _fail_ callbacks.
****

==== void Deferred.resolve(arguments)
****

Resolves a deferred, the done-chain is called when a deferred is resolved. 

_arguments_;; Arguments passed to the _done_ callbacks.
****

==== Deferred Deferred.then(Function ondone, Function onfail)
****

Registers a function for the done and fail chain.

_ondone_;; 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.
_onfail_;; 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.
*returns*;; A new deferred that can be used to chain callbacks. 
****

Deferred also implements a static method: 

==== Value Deferred.when(Value value, Function ondone, Function onfail)
****

Static method that can be used for synchronous and asynchronous operations. If
if *value* is a Deferred *ondone* is called when the Deferred is resolved and
*onfail* is called if the Deferred is rejected, otherwise ondone is called 
and value is the first parameter of the callback.

_value_;; A Deferred or a value.
_ondone_;; Callback function.
_onfail_;; Callback function.
*returns*;; The value.
****

Simple usage of a deferred:

[source,javascript]
---------------------------------
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.out(response); // Finished
    }, 
    function(response) {
        io.out(response); // Failed
    }
);
---------------------------------

Chaining of a deferred: 

[source,javascript]
---------------------------------
function foo() 
{
    var d = new Deferred();
    timer.start(2000, function() {
        d.reject("rejected");
    });
    return d;
}

function onResponse(response) 
{
    io.out(response);
}

// Will print "rejected" twice to stdout after 2 seconds
foo().fail(onResponse).fail(onResponse);
---------------------------------

Note that if the deferred is rejected only the fail chain is called, when it is
resolved only the done chain is called. 
[source,javascript]
---------------------------------
function foo() 
{
    var d = new Deferred();
    timer.start(2000, function() {
        d.reject("rejected");
        // Already rejected, will not execute the done chain
        d.resolve("rejected");
    });
    return d;
}

function onResponse(response) 
{
    io.out(response);
}

// Only the fail will be executed

foo().fail(onResponse).done(onResponse);
foo().done(onResponse).fail(onResponse);
---------------------------------

Changing the deferred in a callback chain:

[source,javascript]
---------------------------------
function foo(message) 
{
    var d = new Deferred();
    timer.start(2000, function() {
        d.resolve(message);
    });
    return d;
}
function callback1(response) 
{
    io.out(response); // Prints "foo" after 2 seconds

    // Return a new Deferred, will replace the old one.
    return foo("bar");
}
function callback2(response) 
{
    io.out(response); // Prints "bar" after 4 seconds
}

foo("foo").done(callback1).done(callback2);
---------------------------------

Using Deferred.when

[source,javascript]
---------------------------------
function asyncOperation() {
    var d = new Deferred();
    .... 
    return d;
}
function syncOperation()
{
    var result = {};
    .... 
    return result;
}
Deferred.when(asyncOperation(), function() {...});
Deferred.when(syncOperation(), function() {...});
---------------------------------

=== Glob ===

Globs can be used for pattern matching, they are much simpler than regular
expressions, there are only two special characters, the wildcard character '\*' which
matches any number of unknown characters and the joker character '?' which matches exactly one
unknown character. The literal characters "*" and "?" must be escaped with "\\";


==== new Glob(String pattern)
****

Constructs a new Glob.

_pattern_;; The pattern to match against.
****

==== Boolean Glob.match(String string)
****

Matches against a string

_string_;; The string to match against.
*returns*;; True if the string matches the Glob.
****

==== String Glob.toString()
****

Converts a Glob to string.

*returns*;; A string represantation of the Glob.
****

=== settings ===

Readonly object that can be used to query dwb's current settings, all settings
can also be used in camelcase, to modify settings *execute* can be used.

====
[source,javascript]
---------------------------------
if (settings.enablePrivateBrowsing == true)
    execute("set enable-private-browsing false");
---------------------------------
====


== WEBKIT OBJECTS ==

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 *zoom-level*, the corresponding
javascript property is *zoomLevel*:

====
[source,javascript]
---------------------------------
var webview = tabs.current
webview.zoomLevel = webview.zoomLevel * 2;
---------------------------------
====

To check if an object is derived from GObject the instanceof operator can be
used: 

====
[source,javascript]
---------------------------------
if (myObject instanceof GObject) 
{
  ...
}
---------------------------------
====

=== General methods

The following methods are implemented by all Objects derived from GObject

==== void object.blockSignal(Number signalid)
****

Blocks emission of a gobect signal.

_signalid_;; The signalid returned from *object.connect*
****

==== Number object.connect(String name, Function callback, [Boolean after]) 
****

Connect to a gobject-signal, note that all signals are connected using the 
_signal::_- or with _notify::_-prefix. If connecting to a signal the 
_signal::_-prefix must be omitted. The callback function will have the
same parameters as the GObject signal callback, however some parameters may be
undefined if they cannot be converted to javascript objects. 
All signal handlers are executed after dwb's default handler.

_name_;; The signal name to connect to.
_callback_;; Callback function that will be called when the signal is emitted.
_after_;; Whether to install the handler after the default handler, default
false.
*returns*;; The signal id of the signal.
****

==== Number object.connectBlocked(String name, Function callback, [Boolean after]) 
****

Connect to a gobject-signal but block the emission of the own callback during
execution of the callback, useful if the object is connected to a notify event
and the the property is changed in the callback function. 

_name_;; The signal name to connect to.
_callback_;; Callback function that will be called when the signal is emitted.
_after_;; Whether to install the handler after the default handler, default
false.
*returns*;; The signal id of the signal.
****

==== Boolean object.disconnect(Number id) 
****

Disconnect from a gobject-signal.

_id_;; The signal id obtained from connect
*returns*;; true if the signal was disconnected
****

==== Number object.notify(String name, Function callback, [Boolean after]) 
****

Wrapper function for property-change notification, the same as 
_object.connect("notify::" +  name, callback, after);_.

_name_;; The property name to connect to, the name can also be in camelcase.
_callback_;; Callback function that will be called when the property changes.
_after_;; Whether to install the handler after the default handler, default
after.
*returns*;; The signal id of the signal.
****

==== Number object.notifyBlocked(String name, Function callback, [Boolean after]) 
****

Wrapper function for property-change notification, the same as 
_object.connectBlocked("notify::" +  name, callback, after);_.

_name_;; The property name to connect to, the name can also be in camelcase.
_callback_;; Callback function that will be called when the property changes.
_after_;; Whether to install the handler after the default handler, default
after.
*returns*;; The signal id of the signal.
****

==== void object.unblockSignal(Number signalid)
****

Unblocks a signal previously blocked with *object.blockSignal*.

_signalid_;; The signalid returned from *object.connect*
****


=== webview ===
The webview object represents the widget that actually displays the site
content. 

_wv.allFrames (Array of frames, read)_;; All frames of a webview including the mainframe
_wv.focusedFrame (Frame, read)_;; The focused frame of the webview
_wv.historyList (Historylist, read)_;; The focused frame of the webview
_wv.mainFrame (Frame, read)_;; The main frame of the webview
_wv.number (Number, read)_;; The number of the webview, starting at 0
_wv.scrolledWindow (GtkScrollwindow, read)_;; The parent widget of every webview, it
is used for scrolling the webview.
_wv.tabWidget (GtkEventBox, read)_;; The main widget for tab labels, used for coloring
tabs, child of *gui.tabBox*.
_wv.tabBox (GtkBox, read)_;; Horizontal box, child of *wv.tabWidget*.
_wv.tabIcon (GtkImage, read)_;;  Favicon widget, child of *wv.tabBox*.
_wv.tabLabel (GtkLabel, read)_;; Text label of a tab, child of *wv.tabBox*.

Some signal callbacks can also be defined directly on webview instances, they can
be set multiple times. Event properties that start with on are emitted for every
emission of that signal, event properties that start with once are only emitted
once and will be disconnected afterwards. Not that it isn't possible to
disconnect from signals that are set directly on a webview instance.

_wv.onButtonPress_;; Connects the webview to the buttonPress event.
_wv.onceButtonPress_;; Connects the webview to the buttonPress event once.
_wv.onButtonRelease_;; Connects the webview to the buttonRelease event.
_wv.onceButtonRelease_;; Connects the webview to the buttonRelease event once.
_wv.onCloseTab_;; Connects the webview to the closeTab event.
_wv.onceCloseTab_;; Connects the webview to the closeTab event.
_wv.onContextMenu_;; Connects the webview to the contextMenu event.
_wv.onceContextMenu_;; Connects the webview to the contextMenu event once.
_wv.onDocumentLoaded_;; Connects the webview to the documentLoaded event. 
_wv.onceDocumentLoaded_;; Connects the webview to the documentLoaded event once.
_wv.onDownload_;; Connects the webview to the download event.
_wv.onceDownload_;; Connects the webview to the download event once.
_wv.onError_;; Connects the webview to the error event.
_wv.onceError_;; Connects the webview to the error event once.
_wv.onFollowHint_;; Connects the webview to the followHint event.
_wv.onceFollowHint_;; Connects the webview to the followHint event once.
_wv.onFrameCreated_;; Connects the webview to the frameCreated event.
_wv.onceFrameCreated_;; Connects the webview to the frameCreated event once.
_wv.onFrameStatus_;; Connects the webview to the frameStatus event.
_wv.onceFrameStatus_;; Connects the webview to the frameStatus event once.
_wv.onKeyPress_;; Connects the webview to the keyPress event.
_wv.onceKeyPress_;; Connects the webview to the keyPress event once.
_wv.onKeyRelease_;; Connects the webview to the keyRelease event.
_wv.onceKeyRelease_;; Connects the webview to the keyRelease event once.
_wv.onLoadCommitted_;; Connects the webview to the loadCommitted event.
_wv.onceLoadCommitted_;; Connects the webview to the loadCommitted event once.
_wv.onLoadFinished_;; Connects the webview to the loadFinished event.
_wv.onceLoadFinished_;; Connects the webview to the loadFinished event once.
_wv.onLoadStatus_;; Connects the webview to the loadStatus event.
_wv.onceLoadStatus_;; Connects the webview to the loadStatus event once.
_wv.onMimeType_;; Connects the webview to the mimeType event.
_wv.onceMimeType_;; Connects the webview to the mimeType event once.
_wv.onMouseMove_;; Connects the webview to the mouseMove event.
_wv.onceMouseMove_;; Connects the webview to the mouseMove event once.
_wv.onNavigation_;; Connects the webview to the navigation event.
_wv.onceNavigation_;; Connects the webview to the navigation event once.
_wv.onResource_;; Connects the webview to the resource event.
_wv.onceResource_;; Connects the webview to the resource event once.
_wv.onScroll_;; Connects the webview to the scroll event.
_wv.onceScroll_;; Connects the webview to the scroll event once.
_wv.onTabButtonPress_;; Connects the webview to the tabButtonPress event.
_wv.onceTabButtonPress_;; Connects the webview to the tabButtonPress event once.
_wv.onTabFocus_;; Connects the webview to the tabFocus event.
_wv.onceTabFocus_;; Connects the webview to the tabFocus event once.


==== String wv.inject([String code|Function code], [Object arg], [Boolean global]) 
****

Injects a script into a webview

_code_;; The script to inject, either a string or a function. If it is a
function the body will be wrapped inside a new function.
_arg_;; If the script isn't injected into the global scope the script is
wrapped inside a function. 'arg' then is accesible via
'arguments' in the injected script, optional 
_line_;; Starting line number, useful for debugging. If linenumber is
greater than 0 error messages will be printed to stderr, optional.
_global_;; true to inject it into the global scope, false to encapsulate it
in a function, optional
*returns*;; The return value of the script. If the script is injected globally
inject always returns null. The return value is always converted to a string.
To return objects call JSON.parse on the return value. 


NOTE: If a script is injected from a loadStatus-callback the script must be
injected after LoadStatus.committed has been emitted.
On LoadStatus.committed the document 
hasn't been created, if the script modifies the DOM it should be injected when
LoadStatus.finished or documentLoaded is emitted.
If only LoadStatus.committed or loadFinished.committed are used it is better
to use the corresponding signals instead to reduce overhead. 
****

==== void wv.history(Number steps) 
****

Loads a history item steps away from the current history item

_steps_;; Number of steps, pass a negative value to go back in history
****

==== Deferred wv.loadString(String content, [String mimetype], [String encoding], [String baseUri], [Boolean extSource])

**** 

Loads a string in a webview

_content_;; The string to load
_mimeType_;; The MIME-type, if omitted or null text/html is assumed, optional
_encoding_;; The character encoding, if omitted or null UTF-8 is assumed, optional
_baseUri_;; The base uri, if present it must either use the uri-scheme
dwb-chrome: or file:, otherwise the request will be ignored, optional
_extSource_;; Whether external sources, e.g. scripts, are allowed, defaults to
false. If external resources are forbidden the function dwb can be called in the
webcontext to execute functions in the scripting context
*returns*;; A deferred that will be resolved if the webview has finished loading
the string and rejected if an error occured.
****

==== Boolean wv.loadUri(String uri, [Function callback]) 
****

Loads an uri in a webview. 

_uri_;; The uri to load
_callback_;; A callback function that will be called when the load status
changes, return true to stop the emission, optional
*returns*;; true if the uri is loaded
****

==== void wv.reload(void) 
****

Reloads a webview 
****


==== void wv.stopLoading() 
****

Stops any ongoing loading. 
****


==== Number wv.toPng(String filename, [Number width, Number height], [Boolean keepAspect]) 
****

Renders a webview to a png file.

_filename_;; The filename for the png.
_width_;; The width of the png, if width is < 0 and height is > 0 the image will
have the same aspect ratio as the original webview, optional.
_height_;; The height of the png, if height is < 0 and width is > 0 the image
will have the same aspect ratio as the original webview, optional, mandatory
if width is set. 
_keepAspect_;; Whether to keep the aspect ratio, if set to true the new
image will have the same aspect ratio as the original webview, width and
height are taken as maximum sizes and must both be > 0, optional.
*returns*;; A cairo_status_t (0 on success) or -1 if an error occured.
****


=== frame ===

A frame represents a frame or iframe. Due to same origin policy it
is not possible to inject scripts from a webview into iframes with a
different domain. For this purpose the frame object can be used. 

_frame.domain (String, read)_;; The domain name of the frame which is the
effective second level domain
_frame.host (String, read)_;; The host name of the frame

==== Boolean frame.inject(String script, [Boolean global])
****

Injects a script into a frame, see also webview.inject for details.
****


==== Deferred frame.loadString(String content, [String mimetype], [String encoding], [String baseUri], [Boolean extSource])

**** 

Loads a string in a frame

_content_;; The string to load
_mimeType_;; The MIME-type, if omitted or null text/html is assumed, optional
_encoding_;; The character encoding, if omitted or null UTF-8 is assumed, optional
_baseUri_;; The base uri, if present it must either use the uri-scheme
dwb-chrome: or file:, otherwise the request will be ignored, optional
_extSource_;; Whether external sources, e.g. scripts, are allowed, defaults to
false. If external resources are forbidden the function dwb can be called in the
webcontext to execute functions in the scripting context
*returns*;; A deferred that will be resolved if the webview has finished loading
the string and rejected if an error occured.
****


=== download ===

Corresponds to a WebKitDownload. 


==== new Download(String uri)
****

Constructs a new download

_uri_;; The uri of the download
****

==== Boolean download.start([Function callback])
****

Starts a download

_callback_;; A callback function that will be executed whenever the
DownloadStatus changes, return true to stop the emission, optional.
****


==== void download.cancel()
****

Cancels a download
****

=== historylist ===

Corresponds to a WebkitWebBackForwardList. 

_historylist.backLength_;; Number of items that precede the current item
_historylist.forwardLength_;; Number of items that succeed the current item

==== WebKitWebHistoryItem historylist.getItem([Number position])
****

Gets a WebKitWebHistoryItem. 

_position_;; The position of the item where 0 corresponds to the current item.
*returns*;; A WebKitWebHistoryItem.
****

== Gtk Widgets ==

It is possible to create new widgets but only widgets that are currently used by
dwb can be created, the widgets used by dwb can be found under 
link:http://portix.bitbucket.org/dwb/resources/layout.html[].

=== Constructor === 

==== new GtkWindow(String type)
****

Constructs a new widget

_type_;; The type of the widget, e.g. "GtkLabel"
****

=== Methods ===

All created widgets implement the following methods: 

==== void GtkWidget.add(GtkWidget widget)
****

Adds a widget as a child. Note that this function can only be called on widgets
derived from GtkContainer.

_widget_;; The widget to add.
****


==== void GtkWidget.destroy()
****

Destroys a widget. Note that only newly created widgets can be destroyed.

****

==== Array GtkWidget.getChildren() 
****

Gets all children of a GtkWidget. Note that this function can only be called on widgets
derived from GtkContainer.

*returns*;; An array of GtkWidgets or an empty array if the Widget has no
children.
****

==== void GtkWidget.remove(GtkWidget widget)
****

Removes a widget from it's parent. Note that this function can only be called on widgets
derived from GtkContainer.

_widget_;; The widget to remove.
****


Widgets that implement the GtkBox interface implement the following methods:

==== void GtkWidget.packEnd(GtkWidget child, boolean expand, boolean fill, int padding)
****

Adds a widget to a GtkBox.

_child_:: The child widget
_expand_:: Whether to expand the widget
_fill_:: Whether to fill the remaining space
_padding_:: Padding in the box
****

==== void GtkWidget.packStart(GtkWidget child, boolean expand, boolean fill, int padding)
****

Adds a widget to a GtkBox.

_child_:: The child widget
_expand_:: Whether to expand the widget
_fill_:: Whether to fill the remaining space
_padding_:: Padding in the box
****

==== void GtkWidget.reorderChild(GtkWidget child, int postion)
****

Moves a widget to a new position.

_child_:: The child widget
_position_:: The new position
****

Widgets derived from GtkContainer implement the following methods:

==== void GtkWidget.add(GtkWidget child)
****

Adds a widget to a GtkContainer.

_child_:: The child widget
****

==== Example 

------
var label = new GtkWidget("GtkLabel");
gui.statusBox.packStart(label, false, false, 0);
label.label = "foobar";
label.visible = true;
------

== SOUPURI ==

Represenst a SoupURI object.

=== Properties

_fragment (String, read)_;; The fragment part of the uri.
_host (String, read)_;; The host of the uri.
_password (String, read)_;; The password of the uri.
_path (String, read)_;; The path of the uri.
_port (String, read)_;; The port of the uri.
_query (String, read)_;; The query part of the uri.
_scheme (String, read)_;; The scheme of the uri.
_user (String, read)_;; The user part of the uri.

== SOUPHEADERS ==

Represents a header, to modify a request header the "resource" Signal can be
used. The requestheaders can be accessed via WebKitNetWorkRequests.


=== Methods ===


==== void SoupHeaders.append(String name, Strina value)
****

Appends a value to a header.

_name_:: Name of the header
_value_:: Value of the header
****

==== void SoupHeaders.clear()
****

Removes all headers.
****

==== String SoupHeaders.getList(String name)
****

Gets a comma seperated header list.

_name_:: Name of the header list
*returns*:: The header list or *null*.
****

==== String SoupHeaders.getOne(String name)
****

Gets a header.

_name_:: Name of the header
*returns*:: The header or *null*.
****

==== void SoupHeaders.remove(String name)
****

Removes a header.

_name_:: Name of the header
****

==== void SoupHeaders.replace(String name, String value)
****

Replaces a header.

_name_:: Name of the header
_value_:: New value of the header
****

==== Example 

----
Signal.connect("resource", function(wv, frame, request) {
    request.message.requestHeaders.remove("referer");
});
----


== SIGNALS ==

Execute code on certain events. dwb emits some signals, e.g. before a new site
is loaded, the signals object can be used to handle these signals. All events
are emitted on the signals object itself, for example "signals.keyPress =
function() { ... };" would connect to the keyPress signal but it is strongly
discouraged to use this pattern since it will only allow to connect one callback
to a certain signal. To handle signals Signal-objects can be used, it manages
signals, allows one to connect to more than one signal and also allows one to
easily disconnect/reconnect to signals.

There is just one convenient pattern that allows setting callbacks directly on
signals: if the signal name starts with "on" dwb will internally create a new
Signal and connect to it with the given callback function, i.e. using
signals.onResource = function () {...} allows one to connect more than one
callback to the "resource"-event, however it doesn't give you as much control as
creating a Signal. When connected with this pattern it is not possible to
disconnect from the signal with signals.onResource = null;, instead
Signal.disconnect must be used.


=== Emitted signals ===

Custom signals can be created by simply calling 

-----
var signal = new Signal("nameOfNewSignal", callbackFunction);
-----


Signals emitted by dwb are the following:

==== addCookie 

****
----
new Signal("addCookie", function(cookie));
----

Emitted when cookie has changed or a new cookie will be added to the cookie jar.
If the callback returns true the cookie won't be added to the jar. To change
the cookie the callback must return true and the cookie must be saved manually.

_cookie_;; The cookie that has been added or changed. 
****

==== buttonPress 

****
----
new Signal("buttonPress", function(webview, hittestresult, event));
----

Emitted when a button is pressed on the webview, return true to prevent
the default action

_webview_;; The webview which received the signal
_hittestresult_;; Hittestresult under the cursor
_event.button_;; The button that is pressed, usually a value between 1 and 5
_event.state_;; A bitmap of modifiers pressed, see Modifier
_event.time_;; The time in milliseconds when the button was pressed 
_event.type_;; A ClickType
_event.x_;; x-position relative to the window
_event.xRoot_;; x-position relative to the screen
_event.y_;; y-position relative to the window
_event.yRoot_;; y-position relative to the screen
****
  
==== buttonRelease 

****
----
new Signal("buttonRelease", function(webview, hittestresult, event));
----

Emitted when a button is released, return true to prevent the default action

_webview_;; The webview which received the signal
_hittestresult_;; Hittestresult under the cursor
_event_;; Same as buttonPress but without _event.type_
****

==== changeMode 

****
----
new Signal("changeMode", function(webview, mode));
----

Emitted when the mode changes, return true to prevent the change.

_webview_;; The focused webview
_mode_;; A mode, see also Modes for possible modes
****

==== close

****
----
new Signal("close", function());
----

Emitted when dwb is closed
****

==== closeTab
****

----
new Signal("closeTab", function(webview));
----

Emitted when a tab is closed

_webview_;; The webview that corresponds to the tab
****

==== createTab
****
----
new Signal("createTab", function(webview));
----

Emitted when a tab is created

_webview_;; The webview that corresponds to the created tab
****

==== documentLoaded
****
----
new Signal("documentLoaded",  function(webview, frame));
----

Emitted when a the DOM document of a frame has been loaded.

_webview_;; The webview that emitted the signal
_frame_;; The frame that contains the document
****

==== download
****
----
new Signal("download", function(webview, download, json));
----

Emitted before a download starts, before a file or action has been chosen,
return true if the signal was handled. 

_webview_;; The webview that emitted the signal
_download_;; The Download 
_json.referer_;; The referer
_json.mimeType_;; The mimetype of the file
****

==== downloadStart
****
----
new Signal("downloadStart", function(download, json));
----

Emitted before a download starts after a path or application has been chosen, 
return true if the signal was handled. Note that destinationUri has not been
set on the download.

_download_;; The Download 
_json.referer_;; The referer
_json.mimeType_;; The mimetype of the file
_json.destinationUri_;; The chosen destination path or null if an application was chosen.
_json.application_;; The chosen application or null if a path was chosen.
****


==== downloadStatus
****
----
new Signal("downloadStatus", function(download));
----

Emitted when the DownloadStatus changes. 

_download_;; The Download 
****

==== executeCommand
****
----
new Signal("executeCommand", function(commandinfo));
----

Emitted when a command is executed, return true to prevent execution.

_commandinfo.command_;; The command that is executed
_commandinfo.argument_;; An argument, if the command isn't executed from commandline this
will always be null.
_commandinfo.nummod_;; The numerical modifier.
****

==== followHint
****
----
new Signal("followHint", function(wv, resource));
----

Emitted before a hint is followed, return true to prevent following the hint

_wv_;; The webview that currently has focus
_resource_;; The resource of the hint, can be either a url or 
*@input*, *@textarea*, *@radio*, *@checkbox*, *@submit*, *@reset*, *@button*,
*@role*, *@unknown* or *@abort* if Escape was pressed.
****

==== frameCreated
****
----
new Signal("frameCreated", function(webview, frame));
----

Emitted when a frame is created

_webview_;; The webview the frame belongs to
_frame_;; The frame 
****

==== frameStatus
****
----
new Signal("frameStatus", function(webview, frame));
----

Emitted when the LoadStatus of a frame changes

_webview_;; The webview the frame belongs to
_frame_;; The frame 
****

==== keyPress
****
----
new Signal("keyPress", function(webview, json));
----

Emitted when a key is pressed, return true to prevent the default action

_webview_;; The focused webview
_json.isModifier_;; Whether or not the key is a modifier
_json.keyCode_;; Hardware keycode
_json.keyVal_;; Keycode as listed in gdkkeysyms.h 
_json.name_;; A string represantation of the key
_json.state_;; A bitmap of modifiers pressed, see Modifier
****

==== keyRelease
****
----
new Signal("keyRelease", function(webview, json));
----

Emitted when a key is released, return true to prevent the default action

_webview_;; The focused webview
_json_;; Same as keyPress
****


==== loadCommitted
****
----
new Signal("loadCommitted", function(webview));
----

Emitted when the load has just committed, no data has been loaded when this
signal is emitted. This is the preferred signal for injected scripts that do not
manipulate the DOM.

_webview_;; The webview that emitted the signal
****

==== loadFinished
****
----
new Signal("loadFinished", function(webview));
----

Emitted when the site has completely loaded. 

_webview_;; The webview that emitted the signal
****

==== loadStatus
****
----
new Signal("loadStatus", function(webview));
----

Emitted when the load status changes

_webview_;; The webview that emitted the signal
****

==== mimeType
****
----
new Signal("mimeType", function(webview, frame, request, json));
----

Decide whether or not to show a given mimetype. Return true to stop the request.

_webview_;; The webview that emitted the signal
_frame_;; The frames requires the decision 
_request_;; The network request
_json.mimeType_;; The mimetype
****

==== mouseMove
****
----
new Signal("mouseMove", function(webview, event));
----

Emitted when the pointer is moved.

_webview_;; The webview that emitted the signal
_event_;; Same as buttonRelease
****

==== navigation
****
----
new Signal("navigation", function(webview, frame, request, action));
----

Emitted before a new site is loaded, return true to stop the request.

_webview_;; The webview that emitted the signal
_frame_;; The frame that requires the navigation 
_request_;; The network request
_action_;; The navigation action
****

==== ready
****
----
new Signal("ready", function());
----

Emitted once when dwb has been fully initialized.
****

==== resource
****
----
new Signal("resource", function(webview, frame, request, response));
----

Emitted before a new resource is going to be loaded

_webview_;; The webview that emitted the signal
_frame_;;   The frame that dispatched the request
_request_;; The network request
_response_;; The network response
****

==== statusBarChange 
****
----
new Signal("statusBarChange", function(webview, data));
----

Emitted before the status bar is updated, if the callback returns true dwb will
not update the statusbar so it is possible to set the statusbar from the script.

_webview_;; The focused webview
_data.canGoBack_;; Whether it is possible to navigate back in the webview
_data.canGoForward_;; Whether it is possible to navigate forward in the webview
_data.isBookmarked_;; Whether the site is bookmarked
_data.isQuickmarked_;; Whether the site is quickmarked
_data.pluginsBlocked_;; Whether plugins are blocked
_data.scriptsBlocked_;; Whether scripts are blocked
_data.ssl_;; SSL-State of the page, can either be 'trusted', 'untrusted' or 'none'
_data.type_;; The type of the update, can be *status* and *uri*, status means
that statusLabel und uriLabel need to be updated, uri means that only the
uriLabel needs to be updated.
****

==== tabButtonPress 

****
----
new Signal("tabButtonPress", function(webview, tabwidget, event));
----

Emitted when a button is pressed on a tabwidget, return true to prevent the default action

_webview_;; The webview which received the signal
_tabwidget_;; The tabwidget
_event_;; Same as buttonPress
****

==== tabFocus
****
----
new Signal("tabFocus", function(webview, json));
----

Emitted when another tab gets focus, return true to stop the event

_webview_;; The new tab
_json.last_;; The number of the previously focused tab
****

== Signal

Object that can be used to connect to certain browser events.

=== Constructor 

==== new Signal(String name, [Function callback])
****

Constructs a new signal

_name_;; Name of the event
_callback_;; Callback function that is invoked when the signal is emitted.
****

=== Properties

_callback (Function, read|write)_;; The callback that will be called when the
signal is emitted, the context of the signal will be the signal itself (i.e.
this refers to the connected Signal).
_connected (Boolean, read)_;; Whether the signal is connected
_id (Number, read)_;; Unique id of the signal
_name (String, read)_;; Name of the event
_predicate_(Function, read|write)_;; A predicate function, the signal is only
emitted if the predicate function returns true. The predicate function is called
with the same arguments as the callback function

=== Methods

==== connect([Function callback])
****

Connects the signal to the event

_callback_;; Callback function that is invoked when the signal is emitted,
optional but mandatory if no callback was given during signal construction.
*returns*;; self
****

==== disconnect([Function callback])
****

Disconnects the signal from the event

*returns*;; self
****

==== toggle()
****

Toggles a signal, if it is connected it will be disconnected an vice versa.

*returns*;; true if the signal was connected, false otherwise
****

=== Static methods

==== Signal.connect(String name, Function callback)
****

Connects to an event

_signals_;; The event name
_callback_;; Callback function to connect to.
****

==== Signal.connectAll(Array signals, [Function callback])
****

Connects to more than one signal at once

_signals_;; Array of signals.
_callback_;; Callback function to connect to, optional.
****

==== Signal.connectWebView(String name, Function callback)
****

Connects all webviews to a GObject signal.

_name_;; The event name
_callback_;; A callback function the will be called when the signal is emitted,
the arguments of the callback correspond to the GObject callback with  the first
argument omitted, instead this refers to the object.
****

==== Signal.disconnect(Signal|Function object)
****

Either a Signal or the callback of a signal If a callback is passed to this
function and the same callback is connected multiple times only the first
matching callback will be disconnected, to disconnect all matching callbacks
call use Signal.disconnectAll

_object_;; The event name
*returns*;; the disconnected signal
****

==== Signal.disconnectAll(Function callback)
****

Disconnect from all signals with matching callback function

_callback_;; A callback function
*returns*;; An array of signal that were disconnected
****

==== Signal.emit(String name, ...)
****


Emits a signal, can be used to implement custom signals.

_name_;; The name of the event
_..._;; Variable number of arguments passed to the callback function of
Signal.connect.
*returns*;; The overall return value of all callback function, if one callback
function returns true the overall return value will be true
****

==== Signal.once(String name, Function callback)
****

Connects to an event once

_signals_;; The event name
_callback_;; Callback function to connect to.
*returns*;; The Signal that was connected. Calling connect() on the returned
signal will connect the Signal only once again. 
****

== ENUM OBJECTS ==
Enum objects are objects that have only readonly properties, mapping
gtk/webkit enums to javascript objects. 

=== ButtonContext
****
[source,javascript]
--------
const ButtonContext = {
  document   : 1 << 1,
  link       : 1 << 2,
  image      : 1 << 3,
  media      : 1 << 4,
  selection  : 1 << 5,
  editable   : 1 << 6
};
--------
****

=== ChecksumType

****
[source,javascript]
--------
const ChecksumType = {
  md5     : 0, 
  sha1    : 1, 
  sha256  : 2 
};
--------
****

=== ClickType
****

[source,javascript]
--------
const ClickType = {
  click       : 4,
  doubleClick : 5,
  tripleClick : 6
};
--------
****

=== DownloadStatus
****

[source,javascript]
-------
const DownloadStatus = {
  error       : -1,
  created     : 0,
  started     : 1, 
  cancelled   : 2,
  finished    : 3
};
-------
****

=== FileTest
****

[source,javascript]
-------
const FileTest = {
  regular    : 1 << 0,
  symlink    : 1 << 1,
  dir        : 1 << 2,
  executable : 1 << 3,
  exists     : 1 << 4
};
-------
****

=== LoadStatus

****
[source,javascript]
---------
const LoadStatus = { 
  provisional       : 0, 
  committed         : 1,
  finished          : 2,
  firstVisualLayout : 3,
  failed            : 4
};
---------
****

=== Modifier

****
[source,javascript]
--------
const Modifier = {
  Shift     : 1 << 0,
  Lock	    : 1 << 1,
  Control   : 1 << 2,
  Mod1	    : 1 << 3,
  Mod2	    : 1 << 4,
  Mod3	    : 1 << 5,
  Mod4	    : 1 << 6,
  Mod5	    : 1 << 7,
  Button1   : 1 << 8,
  Button2   : 1 << 9,
  Button3   : 1 << 10,
  Button4   : 1 << 11,
  Button5   : 1 << 12,
  Super     : 1 << 26,
  Hyper     : 1 << 27,
  Meta      : 1 << 28,
  Release   : 1 << 30,
  Modifier  : 0x5c001fff
};
--------
****

=== NavigationReason

****
[source,javascript]
--------
const NavigationReason = {
  linkClicked     : 0,
  formSubmitted   : 1,
  backForward     : 2,
  reload          : 3,
  formResubmitted : 4,
  other           : 5
};
--------
****

=== Modes

****
[source,javascript]
--------
const Modes = {
  NormalMode  : 1<<0,
  InsertMode  : 1<<1,
  CommandMode : 1<<2
  HintMode : 1<<2
};
--------
****

=== Selection

****
[source,javascript]
--------
const Selection = {
  primary   : 1,
  clipboard : 2
};
--------
****


== GLOBAL DATA == 
Since all scripts share the same execution context, they are encapsulated in a
function. To avoid conflicts with other scripts it is not allowed to set properties
on the global object, i.e. 

[source,javascript]
-------
#!javascript

// not allowed, the global object is readonly
number = 0;
io.out(number);     // undefined

var number2 = 0;
io.out(number2);    // 0

// not allowed
foo = function() 
{
  io.out("foo");
}
foo();  // fails
-------

For sharing data between scripts either signals or modules can be created.

=== script and this
In every script the variable *script* refers to *this*, the encapsulating
function, it has the following properties and methods:


_script.path (Object, read)_;; The path of the script.
_script._arguments (Object, read)_;; *arguments* object of the encapsulating function

==== void script.deletePrivate(Object object, String key)
****

Deletes a private property of an object previously set with *script.setPrivate*
and returns the private value.

_object_;; The object on which the value was set.
_key_;; The property name
*returns*;; The private value
****

==== void script.debug(Object params)
****

Same as io.debug but also prints additional information, e.g. if the object is
an Error, this method will also print the corresponding source of the error.
****

==== String script.generateId()
****

Generates a unique id.

*returns*;; A unique id.
****

==== void script.getPrivate(Object object, String key)
****

Gets a private property of an object previously set with *script.setPrivate*

_object_;; The object on which the value was set.
_key_;; The property name
*returns*;; The private value
****

==== void script.setPrivate(Object object, String key, String value)
****

Convenience function to set a private property on an object that doesn't conflict
with properties set in other scripts, it uses a random unique id to set
the property, so the property can most likely be only retrieved with
*script.getPrivate*. 
This is mostly useful for objects derived from GObject since GObjects are shared
between all scripts. 

_object_;; The object on which the value should be set.
_key_;; The property name
_value_;; The value to set.
****

== Modules == 

With modules it is possible to share objects between scripts. Modules are
defined with +provide+ and loaded with +require+.


.Defining modules
[source,javascript]
-------
#!javascript 

provide("myModule", {
  foo : 37, 
  doBar : function() {
    io.out("bar");
  }
});
provide("myOtherModule", {
  act : function (arg) {
    io.out(arg);
  }
});
-------

.Getting some modules
[source,javascript]
-------
#!javascript 

require(["myModule", "myOtherModule"], function(myModule, myOtherModule) {
  if (myModule.foo == 37) 
    myModule.doBar();

  myOtherModule.act("foo");
});
-------

.Getting all modules
[source,javascript]
-------
#!javascript 

require(null, function(modules) {
  if (modules.myModule.foo == 37) 
    modules.myModule.doBar();

  modules.myOtherModule.act("foo");
});
-------

It is also possible to specify a path in the name array. The name then follows
the format *name!path*:

[source,javascript]
-------
#!javascript 

require(["foo!/path/to/foo"], function(foo) {
  io.out(foo.bar); // 37
});
-------

./path/to/foo
[source,javascript]
-------
provide("foo", { bar : 37 });
-------

The resolution chain is as follows, first all modules defined with *provide* and
module names requested by *require* are stored. If all scripts have been loaded
the requirements are resolved. If a requirement contains a path and the module
isn't defined yet the module will be loaded, if it is already defined the path
is ignored and the stored module will be resolved:  

[source,javascript]
-------
#!javascript 

require(["foo!/path/to/foo"], function(foo) {
  io.out(foo.bar); // 42
});
provide("foo", { bar : 42 });
-------

[source,javascript]
-------
#!javascript 

require(["foo"], function(foo) {
  io.out(foo); // undefined
});
require(["foo!/path/to/foo"]);

require(["foo"], function(foo) {
  io.out(foo); // { bar : 37 }
});
-------


== EXTENSIONS ==
*dwb* provides the possibility to load extensions.
It is recommended to implement javascript-userscripts as an extension to have 
consistent configuration locations for scripts. One advantage of extension also
is that they can be loaded/unloaded on the fly.

=== Prepackaged extensions

==== formfiller

An extension that gets form data and fills forms with previously saved data.

*Configuration options*::
 
_formData_;; A path to a file where formdata will be saved, the default
                 path is *$XDG_CONFIG_HOME/dwb/forms*
_scGetForm_;; Shortcut that gets and saves form data, the default value is *efg*
_scFillForm_;; Shortcut that fills a form, the default value is *eff*
_useGPG_;; Whether to use gpg2 to encrypt the formData file with a password.
_GPGOptEncrypt_;; Additional options that will be passed to gpg2 for
                encryption, the default gpg2 options are:
                --passphrase <password> --batch --no-tty --yes -c --output <formData>
                default value: *""*
_GPGOptDecrypt_;; Additional options that will be passed to gpg2 for
                decryption, the default gpg2 options are 
                --passphrase <password> --batch --no-tty --yes -d <formData>
                default value: *""*

_keepPassword_;;  Whether to save the gpg password in memory, if set to false the
                user will be prompted for the password every time a form
                is filled or new data is saved, default value: *true*

_keepFormdata_;;  If useGPG is enabled and this value is set to true the
                  complete formdata will be kept in memory, if set to false
                  gpg2 will be called every time a form is filled, default
                  value: *false*

==== perdomainsettings

An extension that can be used for setting some settings on a domain basis. 
Valid settings are the properties of WebKitWebSettings but in camelcase, see 
the webkitgtk documentation for details.

*Configuration options*::

_domains_;;   Settings applied based on the effective second level domain

_hosts_;;   Settings applied based on host name, this option is
        an object of the format

_uris_;;   Settings applied based on the uri, this option is
        an object of the format

_defaults_;;  Default settings, for each setting in domains, hosts and uris a
             default-value should be specified

*Example configuration*::

Example using extensions.load:

[source,javascript]
----
extensions.load("perdomainsettings", { 
  domains : {                                                            
     "example.com" : {                                                   
          "enablePlugins"  : true                                        
     },                                                                  
     "example.uk.com" :  {                                               
          "enablePlugins"  : true,                                       
          "enableScripts"  : false                                       
     }                                                                   
  },                                                                     
  hosts : {                                                              
     "www.example1.com" :  {                                             
          "autoLoadImages" : true                                        
     }                                                                   
  },                                                                     
  uris : {                                                               
     "http://www.example2.com/login.php" :  {                            
          "autoLoadImages" : false                                       
     }                                                                   
  },                                                                     
  defaults : {                                                           
     "enablePlugins"   : false,                                          
     "autoLoadImages"  : false,                                          
     "enableScripts"   :  true                                           
  }                                                                      
});
----


==== requestpolicy

Extension that blocks requests from thirdparty domains with whitelisting
support, either permanently or just for the session.
It is also possible to block requests from certain domains on all sites, they
have highest precedence and will also be blocked on sites where 
thirdparty requests are allowed in general. 

*Configuration options*::

_shortcut_;; Shortcut to block / allow requests, default *"erp"*

_unblockCurrent_;; Shortcut to unblock always blocked requests, shows only
                 domains from the current site, default *"erC"*

_unblockAll_;;  Shortcut to unblock always blocked requests, shows all
                 blocked domains, default *"erA"*

_whiteList_;; A path to the whitelisting file, default is
                 *$XDG_CONFIG_HOME/dwb/<profile>/requestpolicy.json*

_autoreload_;; Whether to automatically reload the website after the
                 persistentList has changed, default *false*

_notify_;; Whether to notify about blocked request, default *false*

==== unique_tabs

Extension that allows one to remove duplicate tabs or avoids duplicate tabs
automatically.

*Configuration options*::

_shortcutRemoveDuplicates_;; Shortcut that removes duplicate tabs, default *null*

_commandRemoveDuplicates_;; Command that remove s duplicate tabs, default
*ut_remove_duplicates*

_autoFocus_;; Autofocus a tab if an url is already opened, if the url would be loaded in a
new tab the new tab is closed.  Setting this to true makes commandRemoveDuplicates and
shortcutRemoveDuplicates obsolete because there will be no duplicate tabs.
Default value: *true*

_shortcutToggleAutoFocus_;; Shortcut that enables/disables autofocus, default
*null*

_commandToggleAutoFocus_;;  Command that enables/disables autofocus, default
*ut_toggle_autofocus*


==== userscripts

Extension that loads userscripts and injects them into websites, this
extension is mostly greasemonkey compatible. Scripts can be loaded by either
passing an array of paths to extensions.load or by putting scripts into
$XDG_CONFIG_HOME/dwb/scripts/. 

*Configuration options*::

The only configuration option is an array of paths to scripts

*Example configuration*::

Example using extensions.load:

----
extensions.load("userscripts", [ "/path/to/script1", "/path/to/script2" ]);
----


=== Using extensions

Extensions can be loaded by an userscript 

[source,javascript]
------
#!javascript 

extensions.load("extension_1");
extensions.load("extension_2", { 
  configProp_1 : 22, 
  configProp_2 : "val2" 
});
------

To load/unload extensions on the fly *extensions.bind* can be used:

[source,javascript]
------
#!javascript 

var myConfig = { 
  prop_1 : 37, 
  prop_2 : true, 
  prop_3 : "foo"
};


extensions.bind("myExtension", "Control m", {
  command : "toggleMyExtension", 
  config : myConfig, 
  load : false
});

extensions.bind("mySecondExtension", "Control M");
------

The default searchpaths for extensions are $XDG_DATA_HOME/dwb/extensions/ and
/usr/share/dwb/extensions/.

=== Methods

==== void extensions.bind(String name, String shortcut, [Object options]) 
****
Bind an extension to a shortcut, the shortcut enables/disables the extension.

_name_;; Name of the extension
_shortcut_;; Name of the extension
_options_;; An optional object with options where possible options are 
options.load::: Whether to load the extension on startup, default true
options.config::: Config passed to extensions.load
options.command::: Command that can be used on command line
****

==== void extensions.disableAll() 
****
Disables all extensions.
****

==== void extensions.error(String name, String message) 
****

Print a consistent error message to stderr

_name_;; Name of the extension
_message_;; The message
****


==== Boolean extensions.load(String name, [Object config]) 
****
Loads an extension

_name_;; Name of the extension
_config_;; The config for the script, if omitted the config is read from
$XDG_CONFIG_HOME/dwb/extensionrc, optional
*returns*;;  True if the extension was loaded
****

==== Boolean extensions.toggle(String name, [Object config]) 
****
Toggles an extension

_name_;; Name of the extension
_config_;; The config for the extension.
optional
*returns*;;  True if the extension was loaded, false if it was unloaded.
****

==== Boolean extensions.unload(String name) 
****
Unloads an extension

_name_;; Name of the extension
*returns*;;  True if the extension was unloaded
****

==== void extensions.error(String name, String message|Error e, [String message]) 
****

Print an error message and call stack to stderr.

_name_;; Name of the extension
_message|e_;; The error message or an Error
_message_;; If the second parameter is an Error, an optional message can be
specified.
****

==== void extensions.message(String name, String message) 
****

Print a consistent message to stdout

_name_;; Name of the extension
_message_;; The message
****


==== void extensions.warning(String name, String message) 
****

Print a consistent warning to stderr

_name_;; Name of the extension
_message_;; The warning message
****


=== Writing extensions

The default searchpath for extensions is *$XDG_DATA_HOME/dwb/extensions* and
*SHARE_DIR/dwb/extensions* where  
SHARE_DIR being the share directory of the installation, most likely /usr/share.

The configuration for extensions is in *$XDG_CONFIG_HOME/dwb/extensionrc* and should
return a javascript object. 

Every extension must implement one function named init that takes one
argument, the config for the extension. The function should return true if the
extension was successfully loaded, false otherwise.
Every extension also may implement a function end that will be called when an
extension is unloaded. If an extension registers to signals and binds shortcuts
the extension should unregister all signals and unbind all shortcuts in this
function.
init and end should be returned from the extension.

Additionally the returned object can also have a _defaultConfig_-property and
an _exports_-property. _defaultConfig_
will be mixed into the config before calling the init function and
_exports_ can be used to define a public api that can be loaded as a module with
*require*.

==== Example

A extension called *foobar* in *$HOME/.local/share/dwb/extensions/foobar*:

[source,javascript]
--------
function foo(val) {
  ....
}
function bar(val) {
  ....
}
function loadStatusCallback(w) {
  ...
}
var myExtension = {
  defaultConfig : { foo : 37 },
  exports : {
    foo : foo, 
    bar : bar
  },
  init : function (config) {
    if (config.foo > 36) {
      bar(config.foo);
      foo(config.bar);
      bind("XX", bar, "dobar");
      Signal.connect("loadStatus", loadStatusCallback);
      return true;
    }

    return false;
  },

  end : function () {
    unbind("dobar");
    Signal.disconnect(loadStatusCallback);
    return true;
  }
};
return myExtension;
--------

==== Example extensionrc

[source,javascript]
--------
return {
  foobar : { bar : "X", foo : 37 }, // config for extension foobar
  barfoo : {  }                     // config for extension barfoo
  
};
--------


== SEE ALSO
*dwb*(1) *dwbem*(1)
