Provided by: dwb_20150419git-2build1_i386 
NAME
dwb-js - dwb's javascript api documentation
DESCRIPTION
dwb provides a javascript api that can be used to write userscripts or
extensions for dwb.
GETTING STARTED
Scripts that use the javascript api must be located in
$XDG_CONFIG_HOME/dwb/userscripts like any other script. Scripts that
use the javascript api must either start with
#!javascript
or with
//!javascript
All native javascript methods can be used in scripts, however there are
limitations:
· The execution context of userscripts is completely separated from
the web execution context. Due to security concerns it is not
possible to communicate with the web execution context, it is only
possible to inject scripts into the web context.
· In contrast to the global window object in the web execution
context, the global object is a readonly object, i.e. it is not
possible to set properties on the global object, see also Global
data for details.
GLOBAL
Properties
global (Object, read)
Refers to the global object
session (SoupSession, read)
The webkit session
Methods
void __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
};
SEE ALSO
dwb(1) dwbem(1)
06/20/2014 DWB-JS(7)