Remove api doc, dwbem.1.html

author: Stefan Bolte <sbolte@lavabit.com> 2013-04-13 22:35:11 +0200
committer: Stefan Bolte <sbolte@lavabit.com> 2013-04-13 22:35:11 +0200
commit: cabc7655c69c31bfcd2af3b466f68542d6d2343a (patch)
tree: aea466aed3b87640b916063ec327ca7706f97ace /doc/api
parent: cdf3b69d0369130bd92c42261700c617fabccb39 (diff)
download: dwb-cabc7655c69c31bfcd2af3b466f68542d6d2343a.zip
1 files changed, 0 insertions, 3985 deletions
diff --git a/doc/api/jsapi.txt b/doc/api/jsapi.txt
deleted file mode 100644
index e155da19..00000000
--- a/doc/api/jsapi.txt
+++ /dev/null
@@ -1,3985 +0,0 @@
-= dwb's JavaScript API documentation =
-
-== DEPRECATED ==
-This documentation is deprecated, 
-the new api documentation can be found under 
-link:http://portix.bitbucket.org/dwb/api/[]
-
-== Abstract == 
-
-*dwb* can be extended with different types of userscripts. 
-This api documentation describes the javascript interface. 
-
-== 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 seperated 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 <<Globaldata,global data>> for details.
-
-:numbered!:
-:caption:
-
-
-== Global ==
-
-=== Properties ===
-
-****
-[float]
-==== *global* ====
-
-[source,javascript]
-----
-global        object     read
-----
-
-Refers to the global object.
-****
-
-****
-[float]
-==== *session* ====
-
-[source,javascript]
-----
-session        SoupSession     read
-----
-
-The webkit session.
-****
-
-=== Methods ===
-
-
-****
-[[bind]]
-[float]
-==== *bind()* ==== 
-
-[source,javascript]
-----
-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 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
-****
-
-****
-[[checksum]]
-[float]
-==== *checksum()* ==== 
-
-[source,javascript]
-----
-String 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
-****
-
-
-****
-[[execute]]
-[float]
-==== *execute()* ==== 
-
-[source,javascript]
-----
-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
-****
-
-****
-[[exit]]
-[float]
-==== *exit()* ==== 
-
-[source,javascript]
-----
-Boolean exit()
-----
-
-Exit dwb, must be called if the script is running from commandline. 
-****
-
-
-****
-[[include]]
-[float]
-==== *include()* ==== 
-
-[source,javascript]
-----
-Value 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
-****
-
-****
-[[provide]]
-[float]
-==== *provide()* ==== 
-
-[source,javascript]
-----
-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
-****
-
-****
-[[replace]]
-[float]
-==== *replace()* ==== 
-
-[source,javascript]
-----
-void replace(String name, Object module)
-----
-
-Same as <<provide>> but replaces the module if it was already defined. 
-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.
-****
-
-****
-[[require]]
-[float]
-==== *require()* ==== 
-
-[source,javascript]
-----
-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 seperated 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.
-****
-
-****
-[[sendRequest]]
-[float]
-==== *sendRequest()* ==== 
-
-[source,javascript]
-----
-void sendRequest(String uri, Function callback, [String method])
-----
-
-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.
-****
-
-****
-[[sendRequestSync]]
-[float]
-==== *sendRequestSync()* ==== 
-
-[source,javascript]
-----
-Object 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. 
-****
-
-****
-[[tabComplete]]
-[float]
-==== *tabComplete()* ==== 
-
-[source,javascript]
-----
-void 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.
-****
-
-****
-[[timerStart]]
-[float]
-==== *timerStart()* ==== 
-
-[source,javascript]
-----
-Number timerStart(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
-****
-
-****
-[[timerStop]]
-[float]
-==== *timerStop()* ==== 
-
-[source,javascript]
-----
-Number timerStop(Number id)
-----
-
-Stops a timer started by <<timerStart>>
-
- ::
-
-_id_;; The id returned from <<timerStart>>
-_returns_;; +true+ if the timer was stopped
-****
-
-****
-[[unbind]]
-[float]
-==== *unbind()* ==== 
-
-[source,javascript]
-----
-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
-****
-
-======
-.Example
-[source,javascript]
----------------------------------
-execute("tabopen ixquick.com");
-
-// Execute a function once, similar to window.setTimeout()
-timerStart(2000, function() { 
-  tabs.current.inject("alert('Hello world')");
-  return false;
-});
----------------------------------
-======
-
-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: 
-
-======
-[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
-})
----------------------------------
-======
-
-
-
-[[Globalobjects]]
-== Global Objects ==
-
-[[data]] 
-=== 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 
-****
-
-====
-.Example
-[source,javascript]
----------------------------------
-// Get contents of the currently used bookmark file
-var bookmarks = io.read(data.bookmarks);
---------------------------------
-====
-
-[[io]]
-=== io ===
-The +io+ object implements methods for input and output. 
-
-****
-[[debug]]
-[float]
-==== *debug()* ==== 
-
-[source,javascript]
-----
-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
-****
-
-****
-[[dirNames]]
-[float]
-==== *dirNames()* ==== 
-
-[source,javascript]
-----
-Array io.dirNames(String path)
-----
-
-Get directory entries.
-
- :: 
-
-_path_;; A path to a directory
-_returns_;; An array with the directory names
-****
-
-****
-[[error]]
-[float]
-==== *error()* ==== 
-
-[source,javascript]
-----
-void io.error(String text)
-----
-
-Shows an error message in the browser window.
-
- :: 
-
-_text_;; The message to show
-****
-
-****
-[[notify]]
-[float]
-==== *notify()* ==== 
-
-[source,javascript]
-----
-void io.notify(String text)
-----
-
-Shows a message in the browser window.
-
- :: 
-
-_text_;; The message to show
-****
-
-****
-[[print]]
-[float]
-==== *print()* ==== 
-
-[source,javascript]
-----
-void io.print(String text, [String stream])
-----
-
-Print text to +stdout+ or +stderr+ 
-
- :: 
-
-_text_;; the text to print
-_stream_;; pass +"stderr"+ to print to stderr, optional
-****
-
-****
-[[prompt]]
-[float]
-==== *prompt()* ==== 
-
-[source,javascript]
-----
-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+
-****
-
-****
-[[read]]
-[float]
-==== *read()* ==== 
-
-[source,javascript]
-----
-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
-****
-
-****
-[[write]]
-[float]
-==== *write()* ==== 
-
-[source,javascript]
-----
-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
-****
-
-
-====
-.Example
-[source,javascript]
----------------------------------
-var text = io.read("/home/foo/textfile.txt");
-io.print(text);
---------------------------------
-====
-
-[[system]]
-=== system ===
-
-The +system+ object implements system methods.
-
-****
-[[fileTest]]
-[float]
-==== *fileTest()* ==== 
-
-[source,javascript]
-----
-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
-****
-
-****
-[[getEnv]]
-[float]
-==== *getEnv()* ==== 
-
-[source,javascript]
-----
-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
-****
-
-****
-[[mkdir]]
-[float]
-==== *mkdir()* ==== 
-
-[source,javascript]
-----
-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 
-****
-
-****
-[[spawn]]
-[float]
-==== *spawn()* ==== 
-
-[source,javascript]
-----
-Deferred system.spawn(String command, [Function stdout], [Function stderr], [Object environ])
-----
-
-Executes a shell command using the default search path
-
- ::
-
-_command_;; The command to execute
-_stdout(String)_;; Callback function for stdin, any strings returned from the
-callback are passed to stdin of the spawned process, pass +null+ if only stderr
-is needed, optional 
-_stderr(String)_;; Callback function for stderr, any strings returned from the
-callback are passed to stdin of the process, pass +null+ if stderr is not needed
-and environment variables should be set, optional
-_environ_;; Object that can be used to add environment variables to the childs
-environment, optional.
-_returns_;; A deferred, it will be resolved if the child exits
-normally, it will be rejected if the child process exits abnormally, the first
-parameter of the reject function will be the status code of the child process. 
-****
-
-****
-[[spawnSync]]
-[float]
-==== *spawnSync()* ==== 
-
-[source,javascript]
-----
-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 childs
-environment, optional.
-_returns_;; An object that contains +stdout+, +stderr+ and +status+.
-****
-
-====
-.Example
-[source,javascript]
-------------
-var home = system.getEnv("HOME");
-// asynchronous wrapped read
-function asyncread(filename) {
-  system.spawn("cat " + filename, function (response) {
-      ...
-  });
-}
-asyncread(home + "/.bashrc");
-------------
-====
-
-
-[[tabs]]
-=== tabs ===
-The +tabs+ object implements methods and properties to get +webview+ objects. 
-
-==== Properties ====
-
-****
-[float]
-==== *current* ====
-
-[source,javascript]
-----
-tabs.current        webview     read
-----
-
-The currently focused webview
-****
-
-****
-[float]
-==== *length* ====
-
-[source,javascript]
-----
-tabs.length         Number      read
-----
-
-Total number of tabs
-****
-
-****
-[float]
-==== *number* ==== 
-
-[source,javascript]
-----
-tabs.number         Number      read
-----
-
-Number of the currently focused tab
-****
-
-
-
-
-==== Methods ====
-
-****
-[float]
-==== *nth()* ====
-
-[source,javascript]
-----
-webview tabs.nth(Number n) 
-----
-
-Gets the webview object of the nth tab
-
- ::
-
-_n_;; Number of the tab
-_returns_;; The corresponding <<webview>>
-****
-
-====
-.Example
-[source,javascript]
-----
-var c = tabs.current;
-tabs.nth(2).loadUri(c.uri);
-----
-====
-
-
-[[util]]
-=== util ===
-
-The +util+ object implements helper methods.
-
-****
-[float]
-==== *getBody()* ====
-
-[source,javascript]
-----
-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
-****
-
-****
-[float]
-==== *getMode()* ====
-
-[source,javascript]
-----
-Number util.getMode() 
-----
-
-Gets the the current mode.
-
-_returns_;; The mode, see <<Modes>> for possible modes.
-****
-
-
-
-****
-[[domainFromHost]]
-[float]
-==== *domainFromHost()* ==== 
-
-[source,javascript]
-----
-String util.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 
-****
-
-****
-[[getSelection]]
-[float]
-==== *getSelection()* ====
-
-[source,javascript]
-----
-String util.getSelection()
-----
-
-Get selected text from the focused webview.
-
- :: 
-
-_returns_;; The selection or null if no text was selected.
-****
-
-
-****
-[[markupEscape]]
-[float]
-==== *markupEscape()* ==== 
-
-[source,javascript]
-----
-String util.markupEscape(String text)
-----
-
-Escapes text for usage with pango markup.
-
-_text_;; A text to escape
-_returns_;; The escaped text or 'null';
-****
-
-dwb also adds additional methods to builtin objects 
-
-****
-[[forEach]]
-[float]
-==== *Object.forEach()* ==== 
-[source,javascript]
-----
-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
-****
-
-****
-[[fastIndexOf]]
-[float]
-==== *Array.fastIndexOf()* ==== 
-[source,javascript]
-----
-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.
-****
-
-****
-[[fastLastIndexOf]]
-[float]
-==== *Array.fastLastIndexOf()* ==== 
-[source,javascript]
-----
-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.
-****
-
-****
-[[fastLastIndexOf]]
-[float]
-==== *Function.debug()* ==== 
-[source,javascript]
-----
-void Function.debug([Object scope])
-----
-
-A wrapper method for debugging callbacks, especially useful if it is combined
-with <<scriptandthis,script>>. 
-
- :: 
-
-_scope_;; *script* or *this*, optional
-_returns_;; A new function that calls script.debug on errors.
-****
-
-****
-.Example
-[source,javascript]
-----
-bind("x", function() { ... }.debug(script));
-// or equivalently 
-bind("x", script.debug(function() { ... }));
-
-// is a shorthand for
-
-bind("x", function () { 
-    try { 
-        ... 
-    }
-    catch (e) { 
-        script.debug(e); 
-    }
-});
-----
-****
-
-[[clipboard]]
-=== clipboard ===
-
-****
-[[clipboardget]]
-[float]
-==== *get()* ==== 
-[source,javascript]
-----
-[void|String] 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.
-****
-
-****
-[[clipboardset]]
-[float]
-==== *set()* ==== 
-[source,javascript]
-----
-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]]
-=== gui ===
-Most gtk-widgets used by dwb can be accessed from scripts, an overview of the
-layout can be found under
-link:http://portix.bitbucket.org/dwb/resources/layout.html[].
-
-****
-[float]
-==== *window* ====
-
-[source,javascript]
-----
-gui.window        GtkWindow     read
-----
-
-The main window.
-****
-
-****
-[float]
-==== *mainBox* ====
-
-[source,javascript]
-----
-gui.mainBox        GtkBox     read
-----
-
-The the main container, child of *gui.window*. 
-****
-
-****
-[float]
-==== *tabBox* ====
-
-[source,javascript]
-----
-gui.tabBox        GtkBox     read
-----
-
-The box used for tab labels, child of *gui.mainBox*.
-****
-
-****
-[float]
-==== *contentBox* ====
-
-[source,javascript]
-----
-gui.contentBox        GtkBox     read
-----
-
-The box used for the main content, it contains all
-webviews, child of *gui.mainBox*.
-****
-
-****
-[float]
-==== *statusWidget* ====
-
-[source,javascript]
-----
-gui.statusWidget      GtkEventBox     read
-----
-
-The outmost statusbar widget, used for setting
-the statusbars colors, child of *gui.mainBox*. 
-****
-
-****
-[float]
-==== *statusAlignment* ====
-
-[source,javascript]
-----
-gui.statusAlignment      GtkAlignment     read
-----
-
-Used for the statusbar alignment, child
-of *gui.statusWidget*. 
-****
-
-****
-[float]
-==== *statusBox* ====
-
-[source,javascript]
-----
-gui.statusBox      GtkBox     read
-----
-
-The box that contains the statusbar widgets,
-grandchild of *gui.statusAlignment*.
-****
-
-****
-[float]
-==== *messageLabel* ====
-
-[source,javascript]
-----
-gui.messageLabel      GtkBox     read
-----
-
-Label used for notifications, first child of
-*gui.statusBox*.
-****
-
-****
-[float]
-==== *entry* ====
-
-[source,javascript]
-----
-gui.entry      GtkEntry     read
-----
-
-The entry, second child of *gui.statusBox*.
-****
-
-****
-[float]
-==== *uriLabel* ====
-
-[source,javascript]
-----
-gui.uriLabel      GtkLabel     read
-----
-
-The entry, second child of *gui.statusBox*.
-****
-
-****
-[float]
-==== *statusLabel* ====
-
-[source,javascript]
-----
-gui.statusLabel      GtkLabel     read
-----
-
-Label used for status information, fourth child of *gui.statusBox*.
-****
-
-[[Deferred]]
-=== 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 methods: 
-
-**** 
-[float]
-==== *always()* ==== 
-
-[source,javascript]
-----
-Deferred 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. 
-****
-
-**** 
-[float]
-==== *done()* ==== 
-
-[source,javascript]
-----
-Deferred 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. 
-****
-
-**** 
-[float]
-==== *fail()* ==== 
-
-[source,javascript]
-----
-void 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. 
-****
-
-**** 
-[float]
-==== *reject()* ==== 
-
-[source,javascript]
-----
-void Deferred.reject(arguments) 
-----
-
-Rejects a deferred, the fail-chain is called when a deferred is rejected. 
-
- ::
-
-_arguments_;; Arguments passed to the _fail_ callbacks.
-****
-
-****
-[float]
-==== *resolve()* ==== 
-
-[source,javascript]
-----
-Deferred Deferred.resolve(arguments) 
-----
-
-Resolves a deferred, the done-chain is called when a deferred is resolved. 
-
- ::
-
-_arguments_;; Arguments passed to the _done_ callbacks.
-****
-
-****
-[float]
-==== *then()* ==== 
-
-[source,javascript]
-----
-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: 
-
-****
-[float]
-==== *when()* ==== 
-
-[source,javascript]
-----
-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.
-****
-
-
-==== *Examples* ====
-
-The builtin function system.spawn returns a deferred: 
-[source,javascript]
----------------------------------
-system.spawn("command").then(
-    function() 
-    {
-        /* called when execution was  successful */
-    }, 
-    function(errorcode) 
-    {
-        /* called when execution wasn't successful */
-    }
-);
----------------------------------
-
-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.print(response); // Finished
-    }, 
-    function(response) {
-        io.print(response); // Failed
-    }
-);
----------------------------------
-
-Chaining of a deferred: 
-
-[source,javascript]
----------------------------------
-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);
----------------------------------
-
-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();
-    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);
-}
-
-// Only the fail will be executed
-
-foo().done(onResponse).fail(onResponse);
-foo().fail(onResponse).done(onResponse);
----------------------------------
-
-Changing the deferred in a callback chain:
-
-[source,javascript]
----------------------------------
-function foo(message) 
-{
-    var d = new Deferred();
-    timerStart(2000, function() {
-        d.resolve(message);
-    });
-    return d;
-}
-function callback1(response) 
-{
-    io.print(response); // Prints "foo" after 2 seconds
-
-    // Return a new Deferred, will replace the old one.
-    return foo("bar");
-}
-function callback2(response) 
-{
-    io.print(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]]
-=== 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 "\\";
-
-==== Constructor ====
-
-****
-[float]
-==== *Glob()* ==== 
-[source,javascript]
-----
-new Glob(String pattern)
-----
-
-Constructs a new Glob
-
- ::
-_pattern_;; The pattern to match against
-****
-
-==== Methods ====
-
-****
-[float]
-==== *match()* ==== 
-
-[source,javascript]
-----
-Boolean Glob.match(String string)
-----
-
-Matches against a string
-
- ::
-
-_string_;; The string to match against.
-_returns_;; True if the string matches the Glob.
-****
-
-****
-[float]
-==== *toString()* ==== 
-
-[source,javascript]
-----
-String Glob.toString()
-----
-
-Converts a Glob to string.
-
- ::
-
-_returns_;; A string represantation of the Glob.
-****
-
-.Example 
-
-====
-[source,javascript]
----------------------------------
-var glob = new Glob("foo*ba?");
-glob.match("foobarbaz");       // true
-glob.match("foobaz");          // true
-glob.match("foobarbazx");      // false
-glob.match("fooba");           // false
----------------------------------
-====
-
-[[settings]] 
-=== 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.
-
-.Example
-
-====
-[source,javascript]
----------------------------------
-if (settings.enablePrivateBrowsing == true)
-    execute("set enable-private-browsing false");
----------------------------------
-====
-
-
-[[Webkitobjects]]
-== 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) 
-{
-  ...
-}
----------------------------------
-====
-
-All Objects derived from GObjets implement the following methods. 
-
-//Webkit objects should not be compared using +==+, since it may happen that the
-//same gobject is represented by different javascript objects, instead every
-//webkit object implements an equals method, all Objects derived from GObjets
-//implement the following functions. 
-//
-//****
-//[float]
-//==== *equals()* ==== 
-//
-//[source,javascript]
-//----
-//Boolean object.equals(Object compareObject) 
-//----
-//
-//Compare two webkit objects
-//
-// ::
-//
-//_compareObject_;; The object to compare
-//_returns_;; +true+ if the the corresponding gobjects are equal
-//****
-
-****
-[float]
-==== *blockSignal()* ==== 
-
-[source,javascript]
-----
-Number object.blockSignal(Number signalid)
-----
-
-Blocks emission of a gobect signal.
-
- ::
-
-_signalid_;; The signalid returned from *object.connect*
-****
-
-
-****
-[float]
-==== *connect()* ==== 
-
-[source,javascript]
-----
-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.
-****
-
-****
-[float]
-==== *connectBlocked()* ==== 
-
-[source,javascript]
-----
-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.
-****
-
-****
-[float]
-==== *disconnect()* ==== 
-
-[source,javascript]
-----
-Boolean object.disconnect(Number id) 
-----
-
-Disconnect from a gobject-signal.
-
- ::
-
-_id_;; The signal id obtained from <<connect>>
-_returns_;; +true+ if the signal was disconnected
-****
-
-****
-[float]
-==== *notify()* ==== 
-
-[source,javascript]
-----
-Number object.notify(String name, Function callback, [Boolean after]) 
-----
-
-Wrapper function for property-change notification but with signal blocking, same as 
-_object.connect("notify::" +  name, callback, after);_.
-
- ::
-
-_name_;; The property name to connect to, 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.
-_returns_;; The signal id of the signal.
-****
-
-****
-[float]
-==== *notifyBlocked()* ==== 
-
-[source,javascript]
-----
-Number object.notifyBlocked(String name, Function callback, [Boolean after]) 
-----
-
-Wrapper function for property-change notification but with signal blocking, same as 
-_object.connectBlocked("notify::" +  name, callback, after);_.
-
- ::
-
-_name_;; The property name to connect to, 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.
-_returns_;; The signal id of the signal.
-****
-
-
-****
-[float]
-==== *unblockSignal()* ==== 
-
-[source,javascript]
-----
-Number object.unblockSignal(Number signalid)
-----
-
-Unblocks a signal previously blocked with *object.blockSignal*.
-
- ::
-
-_signalid_;; The signalid returned from *object.connect*
-****
-
-
-====
-[float]
-==== *Examples* ====
-
-Connect to signals:
-
-[source,javascript]
-------------
-tabs.current.connect("notify::load-status", function() {
-  io.print("Status changed");
-});
-tabs.current.notify("loadStatus", function() {
-  io.print("Status changed");
-});
-tabs.current.notify("load-status", function() {
-  io.print("Status changed");
-});
-
-// Similar to signals.connect("navigation", ...)
-signals.connect("createTab", function(wv) { 
-    wv.connect("navigation-policy-decision-requested", function(wv, frame, request, action, policy) {
-        // block google.com
-        if (/google\.com/.test(request.uri))
-            return true;
-    });
-});
-------------
-====
-
-
-
-
-//An exception is the webview object, for webview objects +==+ always gives the
-//same result as +equals+.
-
-
-[[webview]]
-=== webview ===
-The +webview+ object represents the widget that actually displays the site
-content. 
-
-==== Properties ====
-
-The properties correspond to the gobject properties in camelcase. Additional
-properties are
-
-****
-[float]
-==== *allFrames* ====
-
-[source,javascript]
-----
-wv.allFrames        array of frames     read
-----
-
-All frames of a webview including the mainframe
-****
-
-****
-[float]
-==== *focusedFrame* ====
-
-[source,javascript]
-----
-wv.focusedFrame        frame     read
-----
-
-The focused frame of the webview
-****
-
-****
-[float]
-==== *historyList* ====
-
-[source,javascript]
-----
-wv.historyList        historylist     read
-----
-
-The history of the webview
-****
-
-
-****
-[float]
-==== *mainFrame* ====
-
-[source,javascript]
-----
-wv.mainFrame        frame     read
-----
-
-The main frame of the webview
-****
-
-****
-[float]
-==== *number* ====
-
-[source,javascript]
-----
-wv.number        Number     read
-----
-
-The number of the webview, starting at 0
-****
-
-****
-[float]
-==== *scrolledWindow* ====
-
-[source,javascript]
-----
-wv.scrolledWindow        GtkScrolledWindow     read
-----
-
-The parent widget of every webview, it
-is used for scrolling the webview.
-****
-
-****
-[float]
-==== *tabWidget* ====
-
-[source,javascript]
-----
-wv.tabWidget        GtkEventBox     read
-----
-
-The main widget for tab labels, used for coloring
-tabs, child of *gui.tabBox*.
-****
-
-****
-[float]
-==== *tabBox* ====
-
-[source,javascript]
-----
-wv.tabBox        GtkBox     read
-----
-
-Horizontal box, child of *wv.tabWidget*.
-****
-
-****
-[float]
-==== *tabIcon* ====
-
-[source,javascript]
-----
-wv.tabIcon        GtkImage     read
-----
-
-Favicon widget, child of *wv.tabBox*.
-****
-
-****
-[float]
-==== *tabLabel* ====
-
-[source,javascript]
-----
-wv.tabLabel        GtkLabel     read
-----
-
-Text label of a tab, child of *wv.tabBox*.
-****
-
-==== Methods ====
-
-****
-[float]
-[[inject]]
-==== *inject()* ==== 
-
-[source,javascript]
-----
-String wv.inject([String code|Function code], [Object  arg], [Number line], [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. 
-****
-
-====
-.Example 
-[source,javascript,src_numbered]
-------
-//!javascript
-
-function injectMe() {
-    var text = arguments[0];
-    document.body.innerHTML = text;
-    text = y;
-    var d = document.createElement("div");
-    document.body.appendChild(d);
-}
-signals.connect("documentLoaded", function(wv) {
-    wv.inject(injectMe, "foo", 4);
-});
-------
-
-The debugging message will be as follows: 
-
-[source,txt]
-------
-DWB SCRIPT EXCEPTION: An error occured injecting injectMe.
-DWB SCRIPT EXCEPTION: in line 6: Can't find variable: y
-==> DEBUG [SOURCE]
-    ...
-    5 >     document.body.innerHTML = text;
---> 6 >     text = y;
-    7 >     var d = document.createElement("div");
-    ...
-------
-====
-
-****
-[float]
-==== *history()* ====
-
-[source,javascript]
-----
-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
-****
-
-****
-[float]
-==== *loadUri()* ==== 
-
-[source,javascript]
-----
-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
-****
-
-
-****
-[float]
-==== *reload()* ====
-
-[source,javascript]
-----
-void wv.reload(void) 
-----
-
-Reload a webview 
-****
-
-****
-[float]
-==== *stopLoading()* ====
-
-[source,javascript]
-----
-void wv.stopLoading(void) 
-----
-
-Stops any ongoing loading.
-****
-
-****
-[float]
-==== *toPng()* ====
-
-[source,javascript]
-----
-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 ascpect 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.
-****
-
-
-
-
-====
-[float]
-==== *Example* ====
-[source,javascript]
-------------
-var wv = tabs.current;
-
-wv.loadUri("http://www.example.com", function() {
-  if (wv.loadStatus == LoadStatus.finished) {
-    wv.inject("alert('Hello ' + wv.uri + '!!!');");
-    return true;
-  }
-});
-------------
-====
-
-
-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. 
-
-
-[[frame]]
-=== 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. 
-
-==== Properties ====
-
-The properties correspond to the gobject properties in camelcase.
-Additional properties are 
-
-****
-[float]
-==== *domain* ====
-
-[source,javascript]
-----
-frame.domain        String     read
-----
-
-The domain name of the frame which is the effective second level domain
-****
-
-****
-[float]
-==== *host* ====
-
-[source,javascript]
-----
-frame.host          String     read
-----
-
-The host name of the frame
-****
-
-====
-To get the domain or hostname of a webview 
-[source,javascript]
-----
-webview.mainFrame.domain
-webview.mainFrame.host
-----
-can be used.
-====
-
-
-
-==== Methods ====
-
-****
-[float]
-==== *inject()* ==== 
-
-[source,javascript]
-----
-Boolean frame.inject(String script, [Object argument], [Boolean global])
-----
-
-Injects a script into a frame, see also <<inject,webview.inject>> for details.
-****
-
-
-[[Download]]
-=== download ===
-
-Corresponds to a +WebKitDownload+. 
-
-==== Constructor ====
-
-****
-[float]
-==== *Download()* ==== 
-[source,javascript]
-----
-new Download(String uri)
-----
-
-Constructs a new download
-
- ::
-_uri_;; The uri of the download
-****
-
-==== Methods ====
-
-****
-[float]
-==== *start()* ==== 
-
-[source,javascript]
-----
-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.
-****
-
-
-****
-[float]
-==== *cancel()* ==== 
-
-[source,javascript]
-----
-void download.cancel()
-----
-
-Cancels a download
-****
-
-====
-.Example 
-[source,javascript]
-------
-var download = new Download("http://www.example.org/foo.pdf");
-var filename = "/tmp/" + download.suggestedFilename;
-download.destinationUri = "file://" + filename;
-download.start(function () {
-  if (download.status == DownloadStatus.finished) {
-    system.spawn("xpdf " + filename);
-  }
-});
-------
-====
-
-[[HistoryList]]
-=== historylist ===
-Corresponds to a +WebkitWebBackForwardList+. 
-
-==== Properties ====
-
-****
-[float]
-==== *backLength* ====
-
-[source,javascript]
-----
-historylist.backLength          Number     read
-----
-Number of items that precede the current item
-****
-
-****
-[float]
-==== *forwardLength* ====
-
-[source,javascript]
-----
-historylist.forwardLength          Number     read
-----
-Number of items that succeed the current item
-****
-
-==== Methods ====
-
-****
-[float]
-==== *getItem()* ==== 
-
-[source,javascript]
-----
-WebKitWebHistoryItem historylist.getItem(Number position)
-----
-
-Gets a WebKitWebHistoryItem. 
-
- ::
-
-_position_;; The position of the item where 0 corresponds to the current item.
-_returns_;; A WebKitWebHistoryItem.
-****
-
-[[GtkWidgets]]
-== 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[].
-
-New widgets can be created with
-****
-[float]
-==== *GtkWidget()* ==== 
-[source,javascript]
-----
-new GtkWidget(String type)
-----
-
-Constructs a new widget
-
- ::
-_name_;; The type of the widget, e.g. "GtkLabel"
-****
-
-
-All created widgets implement the following methods: 
-
-****
-[float]
-==== *destroy()* ==== 
-
-[source,javascript]
-----
-void GtkWidget.destroy()
-----
-
-Destroys a widget. Note that only newly created widgets can be destroyed.
-****
-
-Widgets that implement the GtkBox interface implement the following methods:
-
-****
-[float]
-==== *packEnd()* ==== 
-
-[source,javascript]
-----
-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
-****
-
-****
-[float]
-==== *packStart()* ==== 
-
-[source,javascript]
-----
-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
-****
-
-****
-[float]
-==== *reorderChild()* ==== 
-
-[source,javascript]
-----
-void GtkWidget.reorderChild(GtkWidget child, Number position)
-----
-
-Moves a widget to a new position.
-
- ;;
-
-_child_:: The child widget
-_position_:: The new position
-****
-
-Widgets derived from GtkContainer implement the following methods:
-
-****
-[float]
-==== *add()* ==== 
-
-[source,javascript]
-----
-void GtkWidget.add(GtkWidget child)
-----
-
-Adds a widget to a GtkContainer.
-
-    ;;
-
-_child_:: The child widget
-****
-
-====
-.Example 
-[source,javascript]
-------
-var label = new GtkWidget("GtkLabel");
-gui.statusBox.packStart(label, false, false, 0);
-label.label = "foobar";
-label.visible = true;
-------
-====
-
-
-== Signals ==
-With the +signals+ object *dwb* communicates with the script on certain events. 
-To connect to a signal one can call the connect method that is implemented by
-the signals object, that takes 2 arguments, the name of the signal and a
-callback function. 
-
-The callback function has a varying number of parameters.
-The last paramter is always a json-object which might be empty or contain
-additional data relevant to the signal. 
-A callback function should either return +true+ or +false+ or nothing which is
-equivalent to +false+.
-If multiple callbacks are connected to the same signal and one callback
-function returns +true+ the overall return value will be +true+.
-
-*dwb* only emits signals as long as one callback is connected to a signal. To
-reduce overhead one should disconnect from signals when no longer
-needed. 
-
-The +signals+ object is not a readonly object, properties can be added to the
-object which are visible in all scripts but it should be avoided to add
-properties on the +signals+ object. +signals+ should only be used to connect to
-signals or define custom signals. 
-
-The +signals+ object implements the following methods
-
-=== Methods ===
-
-[[connect]]
-[float]
-==== *connect()* ====
-
-****
-[source,javascript]
-----
-Number signals.connect(String signal, Function callback) 
-----
-Connect to a signal
-
- ::
-
-_signal_;; The signal to connect to 
-_callback_;; The callback function which will be called when the signal is emitted
-_returns_;;  Unique id for this connection, can be passed to <<disconnect>>
-****
-
-[[connect]]
-[float]
-==== *connectWebView()* ====
-
-****
-[source,javascript]
-----
-void signals.connectWebView(String signal, Function callback) 
-----
-Connect all webviews to a GObject signal
-
- ::
-
-_signal_;; The signal to connect to 
-_callback_;; The callback function which will be called when the signal is
-emitted, the arguments of the callback function correspond to the GObject
-callback
-****
-
-
-****
-[[emit]]
-[float]
-==== *emit()* ==== 
-
-[source,javascript]
-----
-Boolean signals.emit(String signal,  ...)
-----
-
-Emits a signal with a variable number of arguments passed to the callback
-function
-
- :: 
-
-_signal_;; The signal to emit
-_..._;; Objects passed to the callback function
-_returns_;; Overall return value from all connected callback functions
-****
-
-****
-[[disconnect]]
-[float]
-==== *disconnect()* ==== 
-
-[source,javascript]
-----
-void signals.disconnect(Number id|Function callback) 
-----
-
-Disconnect from a signal 
-
- ::
-
-_id|callback_;; The id returned from <<connect>> or the callback function passed
-to <<connect>>. Note that if the same callback is used more than once
-the signal must be disconnected by id, otherwise the behaviour is undefined. 
-****
-
-****
-[[disconnectByName]]
-[float]
-==== *disconnectByName()* ==== 
-
-[source,javascript]
-----
-Boolean signals.disconnectByName(String signal) 
-----
-
-disconnect from all signals with matching name,
-It should be avoided to call +disconnectByName+
-on signals implemented by dwb since it will completely stop the emission of the
-signal in all scripts. 
-
- ::
-
-_signal_;; The callback function passed to <<connect>>
-_returns_;; +true+ if signals were disconnected, +false+ if no signal
-was disconnected
-****
-
-=== Emitted signals ===
-
-Custom signals can be created by simply calling 
-
-[source,javascript]
------
-signals.connect("nameOfNewSignal", callbackFunction);
------
-
-
-
-Signals emitted by dwb are the following:
-
-
-****
-[[buttonPress]]
-[float]
-==== *buttonPress* ==== 
-
-[source,javascript]
-----
-Boolean callback(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]]
-[float]
-==== *buttonRelease* ==== 
-
-[source,javascript]
-----
-Boolean callback(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]]
-[float]
-==== *changeMode* ==== 
-
-[source,javascript]
-----
-Boolean callback(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]]
-[float]
-==== *close* ==== 
-
-[source,javascript]
-----
-Boolean callback() 
-----
-
-Emitted when dwb is closed
-****
-
-****
-[[createTab]]
-[float]
-==== *createTab* ==== 
-
-[source,javascript]
-----
-Boolean callback(webview) 
-----
-
-Emitted when a tab is created
-
- ::
-
-_webview_;; The <<webview>> that corresponds to the created tab
-****
-
-****
-[[closeTab]]
-[float]
-==== *closeTab* ==== 
-
-[source,javascript]
-----
-Boolean callback(webview) 
-----
-
-Emitted when a tab is closed
-
- ::
-
-_webview_;; The <<webview>> that corresponds to the tab
-****
-
-****
-[[documentLoaded]]
-[float]
-==== *documentLoaded* ==== 
-
-[source,javascript]
-----
-void callback(webview, frame) 
-----
-
-Emitted when a the dom document of an frame has loaded.
-
- ::
-
-_webview_;; The <<webview>> that emitted the signal
-_frame_;; The frame that contains the document
-****
-
-****
-[[download]]
-[float]
-==== *download* ==== 
-
-[source,javascript]
-----
-Boolean callback(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]]
-[float]
-==== *downloadStart* ==== 
-
-[source,javascript]
-----
-Boolean callback(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]]
-[float]
-==== *downloadStatus* ==== 
-
-[source,javascript]
-----
-Boolean callback(download) 
-----
-
-Emitted when the <<DownloadStatus>> changes. 
-
- ::
-
-_download_;; The <<Download>> 
-****
-
-****
-[[executeCommand]]
-[float]
-==== *executeCommand* ==== 
-
-[source,javascript]
-----
-Boolean callback(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.
-****
-
-
-****
-[[frameCreated]]
-[float]
-==== *frameCreated* ==== 
-
-[source,javascript]
-----
-void callback(webview, frame) 
-----
-
-Emitted when the frame is created
-
- ::
-
-_webview_;; The webview the frame belongs to
-_frame_;; The frame 
-****
-
-****
-[[frameStatus]]
-[float]
-==== *frameStatus* ==== 
-
-[source,javascript]
-----
-void callback(webview, frame) 
-----
-
-Emitted when the <<LoadStatus>> of a frame changes
-
- ::
-
-_webview_;; The webview the frame belongs to
-_frame_;; The frame 
-****
-
-****
-[[keyPress]]
-[float]
-==== *keyPress* ==== 
-
-[source,javascript]
-----
-Boolean callback(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]]
-[float]
-==== *keyRelease* ==== 
-
-[source,javascript]
-----
-Boolean callback(webview, json) 
-----
-
-Emitted when a key is released, return +true+ to prevent the default action
-
- ::
-
-_webview_;; The focused webview
-_json_;; Same as <<keyPress>>
-****
-
-
-****
-[[loadCommitted]]
-[float]
-==== *loadCommitted* ==== 
-
-[source,javascript]
-----
-void callback(webview) 
-----
-
-Emitted when the load has just commited, 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]]
-[float]
-==== *loadFinished* ==== 
-
-[source,javascript]
-----
-Boolean callback(webview) 
-----
-
-Emitted when the site has completely loaded. 
-
- ::
-
-_webview_;; The webview that emitted the signal
-****
-
-****
-[[loadStatus]]
-[float]
-==== *loadStatus* ==== 
-
-[source,javascript]
-----
-void callback(webview) 
-----
-
-Emitted when the load status changes
-
-  ::
-
-_webview_;; The webview that emitted the signal
-****
-
-****
-[[mimeType]]
-[float]
-==== *mimeType* ==== 
-
-[source,javascript]
-----
-Boolean callback(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]]
-[float]
-==== *mouseMove* ==== 
-
-[source,javascript]
-----
-Boolean callback(webview, event) 
-----
-
-Emitted when the pointer is moved.
-
- ::
-
-_webview_;; The webview that emitted the signal
-_event_;; Same as <<buttonRelease>>
-****
-
-****
-[[navigation]]
-[float]
-==== *navigation* ==== 
-
-[source,javascript]
-----
-Boolean callback(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
-****
-
-****
-[[resource]]
-[float]
-==== *resource* ==== 
-
-[source,javascript]
-----
-Boolean callback(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]]
-[float]
-==== *statusBarChange* ==== 
-
-[source,javascript]
-----
-Boolean callback(webview, json) 
-----
-
-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]]
-[float]
-==== *tabButtonPress* ==== 
-
-[source,javascript]
-----
-Boolean callback(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]]
-[float]
-==== *tabFocus* ==== 
-
-[source,javascript]
-----
-Boolean callback(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
-****
-
-
-
-====
-.Example 
-[source,javascript]
-------
-// Prevent example.com from being loaded
-function navigationCallback(wv, frame, request, action) {
-  if (/.*\.example\.com.*/.test(request.uri)) {
-    return true;
-  }
-}
-signals.connect("navigation", navigationCallback);
-------
-====
-
-== Enum objects ==
-Enum objects are objects that have only readonly properties, mapping
-gtk/webkit enums to javascript objects. 
-
-****
-[[ButtonContext]]
-[float]
-==== *ButtonContext* ====
-
-[source,javascript]
---------
-const ButtonContext = {
-  document   : 1 << 1,
-  link       : 1 << 2,
-  image      : 1 << 3,
-  media      : 1 << 4,
-  selection  : 1 << 5,
-  editable   : 1 << 6
-};
---------
-****
-
-****
-[[ChecksumType]]
-[float]
-==== *ChecksumType* ====
-
-[source,javascript]
---------
-const ChecksumType = {
-  md5     : 0, 
-  sha1    : 1, 
-  sha256  : 2 
-};
---------
-****
-
-****
-[[ClickType]]
-[float]
-==== *ClickType* ====
-
-[source,javascript]
---------
-const ClickType = {
-  click       : 4,
-  doubleClick : 5,
-  tripleClick : 6
-};
---------
-****
-
-****
-[[DownloadStatus]]
-[float]
-==== *DownloadStatus* ====
-
-[source,javascript]
--------
-const DownloadStatus = {
-  error       : -1,
-  created     : 0,
-  started     : 1, 
-  cancelled   : 2,
-  finished    : 3
-};
--------
-****
-
-****
-[[FileTest]]
-[float]
-==== *FileTest* ====
-
-[source,javascript]
--------
-const FileTest = {
-  regular    : 1 << 0,
-  symlink    : 1 << 1,
-  dir        : 1 << 2,
-  executable : 1 << 3,
-  exists     : 1 << 4
-};
--------
-****
-
-****
-[[LoadStatus]]
-[float]
-==== *LoadStatus* ====
-
-[source,javascript]
----------
-const LoadStatus = { 
-  provisional       : 0, 
-  committed         : 1,
-  finished          : 2,
-  firstVisualLayout : 3,
-  failed            : 4
-};
----------
-****
-
-****
-[[Modifier]]
-[float]
-==== *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]]
-[float]
-==== *NavigationReason* ====
-
-[source,javascript]
---------
-const NavigationReason = {
-  linkClicked     : 0,
-  formSubmitted   : 1,
-  backForward     : 2,
-  reload          : 3,
-  formResubmitted : 4,
-  other           : 5
-};
---------
-****
-
-****
-[[Modes]]
-[float]
-==== *Modes* ====
-[source,javascript]
---------
-const Modes = {
-  NormalMode  : 1<<0,
-  InsertMode  : 1<<1,
-  CommandMode : 1<<2
-};
---------
-****
-
-****
-[[Selection]]
-[float]
-==== *Selection* ====
-[source,javascript]
---------
-const Selection = {
-  primary   : 1,
-  clipboard : 2
-};
---------
-****
-
-
-[[Globaldata]]
-== Global data == 
-Since all scripts share the same execution context, every script is encapsulated
-in a function. To avoid conflicts between scripts, e.g. with duplicate
-variables, it is not allowed to set properties on the global object:
-
-[source,javascript]
--------
-#!javascript
-
-// not allowed, the global object is readonly
-number = 0;
-io.print(number);     // undefined
-
-var number2 = 0;
-io.print(number2);    // 0
-
-// not allowed
-foo = function() 
-{
-  io.print("foo");
-}
-foo();  // fails
--------
-
-For sharing data between scripts either signals or modules can be created.
-
-[[scriptandthis]]
-=== script and this ===
-In every script the variable *script* refers to *this*, the encapsulating
-function, it has the following properties and methods:
-
-
-****
-[float]
-==== *path* ====
-
-[source,javascript]
-----
-script.path        string     read
-----
-
-The path of the script.
-****
-
-****
-[float]
-==== *_arguments* ====
-
-[source,javascript]
-----
-script._arguments        string     read
-----
-
-*arguments* object of the encapsulating function
-****
-
-****
-[[thisdebug]]
-[float]
-==== *debug()* ==== 
-
-[source,javascript]
-----
-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.
-****
-
-****
-[[generateId]]
-[float]
-==== *generateId()* ==== 
-
-[source,javascript]
-----
-String script.generateId()
-----
-
-Generates a unique id.
-
- ::
-
-_returns_;; A unique id.
-****
-
-****
-[[getPrivate]]
-[float]
-==== *getPrivate()* ==== 
-
-[source,javascript]
-----
-Object script.getPrivate(Object object, String key, Object value)
-----
-
-Gets a private property of an object previously set with
-<<setPrivate,script.setPrivate>>.
-
- ::
-
-_object_;; The object on which the value was set.
-_key_;; The property name
-_returns_;; The private value
-****
-
-
-****
-[[setPrivate]]
-[float]
-==== *setPrivate()* ==== 
-
-[source,javascript]
-----
-void script.setPrivate(Object object, String key, Object 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 only be retrieved with
-<<getPrivate,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.
-****
-
-
-.Example 
-****
-[source,javascript]
--------
-#!javascript
-
-try 
-{
-    var x = {};
-    var y = x.foo.bar;
-    var z = 33;
-}
-catch(e) 
-{
-    script.debug(e);
-}
--------
-
-Will produce the following output: 
-
-------
-==> DEBUG [IN FILE]    : /path/to/userscript
-==> DEBUG [ERROR]      : Exception in line 6: 'undefined' is not an object
-                         (evaluating 'x.foo.bar') 
-==> DEBUG [STACK]      : [anonymous] [[native code]]
-==> DEBUG [SOURCE]     : 
-    ...
-    5 >      var x = {};
---> 6 >      var y = x.foo.bar;   
-    7 >      var z = 33;
-    ...
-------
-
-Setting/getting private values:
-
-[source,javascript]
-------------
-var self = this;
-signals.connect("loadCommitted", function(wv) {
-  script.setPrivate(wv, "foo", "bar");
-});
-signals.connect("loadFinished", function(wv) {
-  io.print(script.getPrivate(wv, "foo"));
-});
-------------
-
-****
-
-
-[[Modules]]
-== 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.print("bar");
-  }
-});
-provide("myOtherModule", {
-  act : function (arg) {
-    io.print(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.print(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.print(foo.bar); // 42
-});
-provide("foo", { bar : 42 });
--------
-
-[source,javascript]
--------
-#!javascript 
-
-require(["foo"], function(foo) {
-  io.print(foo); // undefined
-});
-require(["foo!/path/to/foo"]);
-
-require(["foo"], function(foo) {
-  io.print(foo); // { bar : 37 }
-});
--------
-
-
-[[Extensions]] 
-== 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. 
-
-=== 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 per-domain-settings. Valid settings are
-the properties of WebKitWebSettings but in camelcase, see 
-http://webkitgtk.org/reference/webkitgtk/unstable/WebKitWebSettings.html
-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 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 
-
-[source,javascript]
-----
-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 : 37, 
-  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/+.
-
-The +extensions+ object has the following functions
-
-=== Methods ===
-
-****
-[[extensionsbind,bind]]
-[float]
-==== *bind()* ==== 
-
-[source,javascript]
-----
-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 commandline
-****
-
-****
-[[extensiondisableAll,disableAll]]
-[float]
-==== *disableAll()* ====
-
-[source,javascript]
-----
-void extensions.disableAll() 
-----
-
-Disables all extensions.
-****
-
-**** 
-[[extensionsGetConfig,getConfig]]
-[float]
-==== *getConfig* ====
-
-[source,javascript]
-----
-Object extensions.getConfig(Object config, Object defaultConfig) 
-----
-Parses config with given default config. Checks for each property of
-defaultConfig if the corresponding property of config is valid.
-
-_config_;; The configuration object
-_defaultConfig_;; The default configuration for the extension
-_returns_;; The parsed config
-****
-
-****
-[[extensionload,load]]
-[float]
-==== *load()* ====
-
-[source,javascript]
-----
-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
-****
-
-****
-[[extensiontoggle,toggle]]
-[float]
-==== *toggle()* ====
-
-[source,javascript]
-----
-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.
-****
-
-****
-[[extensionload,unload]]
-[float]
-==== *unload()* ====
-
-[source,javascript]
-----
-Boolean extensions.unload(String name) 
-----
-Unloads an extension
-
- ::
-
-_name_;; Name of the extension
-_returns_;;  True if the extension was unloaded
-****
-
-****
-[[error]]
-[float]
-==== *error()* ====
-
-[source,javascript]
-----
-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.
-****
-
-****
-[[message]]
-[float]
-==== *message()* ====
-
-[source,javascript]
-----
-void extensions.message(String name, String message) 
-----
-
-Print a consistent message to stderr
-
- ::
-
-_name_;; Name of the extension
-_message_;; The message
-****
-
-
-****
-[[warning]]
-[float]
-==== *warning()* ====
-
-[source,javascript]
-----
-void extensions.warning(String name, String message) 
-----
-
-Print a consistent warning to stderr
-
- ::
-
-_name_;; Name of the extension
-_message_;; The warning message
-****
-
-
-.Example
-
-[source,javascript]
---------
-#!javascript 
-
-extensions.load("foobar");
---------
-
-=== Writing extensions
-
-The default searchpath for extensions isn +$XDG_DATA_HOME/dwb/extensions+ and
-+SHARE_DIR/dwb/extensions+ where the 
-+SHARE_DIR+ with sharedirectory 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 an +defaultConfig+-property, the
-value will be passed to extensions.getConfig before calling the init function.
-
-.Example
-
-A extension called *foobar* in +$HOME/.local/share/dwb/extensions/foobar+.
-
-[source,javascript]
---------
-function foo(val) {
-  ....
-}
-function bar(val) {
-  ....
-}
-function loadStatusCallback(w) {
-  ...
-}
-return {
-  defaultConfig : { foo : 37 },
-
-  init : function (config) {
-    if (config.foo > 36) {
-      bar(config.foo);
-      foo(config.bar);
-      bind("XX", bar, "dobar");
-      signals.connect("loadStatus", loadStatusCallback);
-      return true;
-    }
-
-    return false;
-  },
-
-  end : function () {
-    unbind(bar);
-    signals.disconnect(loadStatusCallback);
-    return true;
-  }
-};
---------
-
-====
-.Example extensionrc
-[source,javascript]
---------
-return {
-  foobar : { bar : "X", foo : 37 }, // config for extension foobar
-  barfoo : {  }                     // config for extension barfoo
-  
-};
---------
-====
-
-Extensions that provide a public api can use provide or replace using the name of the extension. 
-
-====
-[source,javascript]
---------
-var myPublicFunction = function() 
-{
-  ...
-};
-
-return {
-  init : function(config) 
-  {
-    provide("myExtensionName", 
-    {
-      config : config, 
-      method : myPublicFunction
-    });
-  },
-  end : function() 
-  {
-    replace("myExtensionName");
-  }
-};
---------
-====
-
-== Snippets == 
-
-Some example snippets can be found link:../snippets/snippets.html[here].
-
-
-// vim: set ft=asciidoc:
author	Stefan Bolte <sbolte@lavabit.com>	2013-04-13 22:35:11 +0200
committer	Stefan Bolte <sbolte@lavabit.com>	2013-04-13 22:35:11 +0200
commit	cabc7655c69c31bfcd2af3b466f68542d6d2343a (patch)
tree	aea466aed3b87640b916063ec327ca7706f97ace /doc/api
parent	cdf3b69d0369130bd92c42261700c617fabccb39 (diff)
download	dwb-cabc7655c69c31bfcd2af3b466f68542d6d2343a.zip