API-Version: 1.9

Members

<readonly> global :Object

Refers to the global object

Source:

<readonly> session :SoupSession

The webkit session

Source:

settings :Object

Object that can be used to get dwb's settings, to set dwb's settings use execute

Source:
Example
 
if (settings.enableScripts == true)
     execute("local_set enable-scripts false");

<readonly> version :Number

The api-version

Source:

Methods

__assert__(expression)

Prints an assertion message and removes all handles owned by the script. 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.

Parameters:
Name Type Description
expression Expression

An expression that evaluates to true or false.

Since:
  • 1.8
Source:
Example
 
//!javascript

var a = [];

// returns immediately
__assert__(a.length != 0);

__profile__(profiles)

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.

Parameters:
Name Type Description
profiles String...

Profiles that use this script

Since:
  • 1.8
Source:
Example
 
//!javascript

__profile__("default", "private");

// not reached if the profile isn't default or private

bind(shortcut, callback, command|override) → {Object}

Bind a function to a shortcut or commandline command, use unbind to remove the command

Parameters:
Name Type Argument Description
shortcut String

A shortcut, the syntax is the same as in dwb:keys, pass null if only a commandline command should be bound

callback bindCallback

A callback function that will be called if the shortcut is pressed or the command was executed from commandline

command|override String | OverrideKey <optional>

A command the can be used on dwb's commandline or an OverrideKey flag

Source:
Returns:

An handle that contains an id, handle.remove() or unbind(handle.id) will unbind this shortcut

Type
Object
Example
 
bind("Control U", function () { 
     execute("tabopen " + tabs.current.uri);
}, "tabopen_current");

execute(name) → {Boolean}

Executes a command, note that execute cannot be called in the global scope of a script or in a function that is called from the global scope of the script, i.e. it can only be called from functions that aren't executed when the script is first executed like signal callbacks or bind callbacks. If it is required call execute directly after dwb has been initialized the ready signal can be used.

Parameters:
Name Type Description
name String

A command, the command syntax is the same as the syntax on dwb's commandline

Source:
Returns:

true if execution was successful

Type
Boolean
Example
 
bind("Control x", function() {
     execute("tabopen www.example.com");
});

// Calling execute on startup
Signal.connect("ready", function() {
     execute("tabopen example.com");
});

exit()

Exit dwb

Source:

hint(shortcut, callback, command, selector)

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

Parameters:
Name Type Argument Description
shortcut String

A shortcut to start the hint mode

callback Function

The callback function, that will be called before the hint is followed, see signals~onFollowHint. 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 String

The command to start the hint mode

selector String <optional>

A css selector passed to querySelectorAll

Since:
  • 1.4
Source:

include(path, global) → {Object}

Includes a file. Note that included files are not visible in other scripts unless they are explicitly injected into the global scope. To use functions or variables from an included script the script can either return an object containing the public functions/variables or provide can be called in the included script.

Parameters:
Name Type Description
path String

The path to the script

global Boolean

Whether the script should be included into the global scope.

Source:
Returns:

The object returned from the included script

Type
Object
Example
// included script 
function foo()
{
    io.print("bar");
}
return {
     foo : foo
}

// including script
var x = include("/path/to/script"); 
x.foo();


// included script
provide("foo", {
     foo : function() 
     {
         io.print("bar");
     }
});

// including script
include("/path/to/script");
require(["foo"], function(foo) {
     foo.foo();
});

provide(name, module, overwrite)

Define a module that can be retrieved with require in other scripts

Parameters:
Name Type Argument Description
name String

The name of the module

module Object

The module

overwrite Boolean <optional>

Whether to overwrite existing module with the same name, default false

Source:
Example
 
provide("foo", {
   baz : 37, 
   bar : function() { ... }
});

require(names, callback) → {Object|undefined}

Load modules defined in other scripts.

Parameters:
Name Type Argument Description
names Array | String

Array of module names, a module name or null. If an array or null is passed require is called asynchronously, passing null will require all modules. If a string is passed to require it will be synchronous. The module must have been already defined if the synchronous version is used. If all modules are defined during startup all modules will be defined after the ready event has been emitted.

callback requireCallback <optional>

A callback function, the modules are passed as parameters to the callback, only used if require is used asynchronously

Source:
Returns:

The synchronous version returns the module, the asynchronous version returns nothing.

Type
Object | undefined
Example
 
// asynchronous
require(["foo", "bar"], function(foo, bar) {
   io.print(foo.baz);
});

// synchronous
var foo = require("foo");
io.print(foo.baz);

// ensuring that all modules have been defined for synchronous loading
Signal.connect("ready", function() {
    var foo = require("foo");
});

unbind(id|command|callback) → {Boolean}

Unbind a shortcut previously bound with bind

Parameters:
Name Type Description
id|command|callback Number | String | bindCallback

Either the handle id returned from bind or the function or the command passed to bind

Source:
Returns:

Whether the shortcut was found and unbound

Type
Boolean

xgettext(path) → {String}

Load a textfile from an archive. This function can only be called from scripts inside an archive.

Parameters:
Name Type Description
path String

Path of the file in the archive, if the path starts with a ~ dwb searches for the file in the archive, i.e. it doesn't have to be an absolute archive path but the filename has to be unique

Source:
Returns:

The content of the file

Type
String
Example
// Archive structure
//
// content/main.js
// content/bar.html
// content/foo.html
var bar = xgettext("content/bar.html"); 
var foo = xgettext("~foo.html");

xinclude(path) → {Object}

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 in 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.

Unlike include included archive-scripts cannot be included into the global scope.

Parameters:
Name Type Description
path String

Path of the file in the archive, if the path starts with a ~ dwb searches for the file in the archive, i.e. it doesn't have to be an absolute archive path but the filename has to be unique

Source:
Returns:

The object returned from the included file.

Type
Object
Example
// Archive structure
//
// main.js
// content/foo.js
// content/bar.js

// main.js
xinclude("content/foo.js");
// searches for bar.js in the archive
xinclude("~bar.js");

// content/foo.js
function getFoo() {
     return 37;
}
exports.getFoo = getFoo;

// content/bar.js
var x = exports.getFoo();

// using require/provide
// main.js
require(["foo" + exports.id], function(foo) {
     io.print(foo.bar);
});
xinclude("content/foo.js");

// content/foo.js
provide("foo" + exports.id, {
    bar : 37
});

xprovide(name, module, overwrite)

Same as provide, but can only be called from an archive. The module can only be required by the same archive inside an archive.

Parameters:
Name Type Argument Description
name String

The name of the module

module Object

The module

overwrite Boolean <optional>

Whether to overwrite existing module with the same name, default false

Source:

xrequire(name) → {Object}

Same as require, but can only be called from an archive and xrequire is always synchronous. Only modules provided in the same archive can be loaded with xrequire.

Parameters:
Name Type Description
name String

The name of the module

Source:
Returns:

The module

Type
Object

Type Definitions

bindCallback(arguments)

Callback that will be called when a shortcut or command was invoked that was bound with bind

Parameters:
Name Type Description
arguments Object
Properties
Name Type Argument Description
shortcut String

The shortcut that was pressed

modifier Number

The modifier

nummod Number

Numerical modifier that was used or -1 if no modifier was used.

arg Number <optional>

Argument if the callback was invoked from commandline and an argument was used on commanline

Source:

requireCallback(arguments)

Callback that will be called when all provided modules have been loaded

Parameters:
Name Type Description
arguments varargs | Object

Variable number of modules, for each module one argument, if null was passed to require the callback will only have one parameter that contains all modules.

Source:
Example
 
require(["foo", "bar"], function(foo, bar) {
     ...
});
require(null, function(modules) {
     var foo = modules.foo;
     var bar = modules.bar;
});