dwb-js(7) 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 __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 __assert__ is not actually a function but a macro, a ; is mandatory at the end of an __assert__ statement.

expression

An expression that evaluates to true or false.


void __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 __profile__ is a macro, a ; is mandatory at the end of a __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:

// 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:

// 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's process.

options.environment

Hash of environment variables that will be set in the child's 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 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:

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:

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.

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:

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

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.

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:

var webview = tabs.current
webview.zoomLevel = webview.zoomLevel * 2;

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

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 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 separated 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

const ButtonContext = {
  document   : 1 << 1,
  link       : 1 << 2,
  image      : 1 << 3,
  media      : 1 << 4,
  selection  : 1 << 5,
  editable   : 1 << 6
};

ChecksumType

const ChecksumType = {
  md5     : 0,
  sha1    : 1,
  sha256  : 2
};

ClickType

const ClickType = {
  click       : 4,
  doubleClick : 5,
  tripleClick : 6
};

DownloadStatus

const DownloadStatus = {
  error       : -1,
  created     : 0,
  started     : 1,
  cancelled   : 2,
  finished    : 3
};

FileTest

const FileTest = {
  regular    : 1 << 0,
  symlink    : 1 << 1,
  dir        : 1 << 2,
  executable : 1 << 3,
  exists     : 1 << 4
};

LoadStatus

const LoadStatus = {
  provisional       : 0,
  committed         : 1,
  finished          : 2,
  firstVisualLayout : 3,
  failed            : 4
};

Modifier

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

const NavigationReason = {
  linkClicked     : 0,
  formSubmitted   : 1,
  backForward     : 2,
  reload          : 3,
  formResubmitted : 4,
  other           : 5
};

Modes

const Modes = {
  NormalMode  : 1<<0,
  InsertMode  : 1<<1,
  CommandMode : 1<<2
  HintMode : 1<<2
};

Selection

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.

#!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.

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

Getting some modules.

#!javascript
require(["myModule", "myOtherModule"], function(myModule, myOtherModule) {
  if (myModule.foo == 37)
    myModule.doBar();
  myOtherModule.act("foo");
});

Getting all modules.

#!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:

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

/path/to/foo.

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:

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

#!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:

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

#!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:

#!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:

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

return {
  foobar : { bar : "X", foo : 37 }, // config for extension foobar
  barfoo : {  }                     // config for extension barfoo
};