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
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
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
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
callback
name
returns
Executes a dwb command
command
returns
Exit dwb, must be called if the script is running from commandline.
Adds a custom hintmode, similar to bind but executes the function before the hint will be followed, use unbind to remove the hintmode
shortcut
callback
command
selector
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
global
returns
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:
void __assert__(Expression expression)
Note
// 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 })
Defines a module that can be used in other scripts, see MODULES for details.
name
module
Same as provide but replaces the module if it was already defined.
name
module
Load modules defined with provide.
names
callback
Unbind a shortcut that was previously bound with bind
func or name
returns
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
returns
void provide(String name, Object module)
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
Parses data into an array
prompt
returns
Array data.parse(String name)
io
The io object implements methods for input and output.
Shows a confirmation prompt.
prompt
returns
Prints a debug message and the call stack to stderr.
detail
detail.message
detail.error
detail.arguments
Get directory entries.
path
returns
Print text to stderr
text
...
Shows an error message in the browser window.
text
Shows a message in the browser window.
text
Print text to stdout
text
...
Gets user input synchronously.
text
visible
returns
Read from a file.
path
returns
Write to a file
path
mode
text
returns
void io.confirm(String prompt)
Boolean io.write(String path, String mode, String text)
system
The system object implements system methods.
Checks for FileTest flags on a file.
path
flags
returns
Get a system environment variable
name
returns
Get the current process id of the instance.
returns
Creates a directory and all parent directories.
path
mode
returns
Executes a shell command using the default search path
command
options
options.onStdout
options.cacheStdout
options.onStderr
options.cacheStderr
options.onFinished
options.stdin
options.environment
returns
Executes a shell command synchronously using the default search path
command
environment
returns
Boolean system.fileTest(String path, FileTest flags)
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
Gets all cookies from the cookie jar.
returns
Removes all cookies from the cookie jar
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
returns
Checks if two domain match, also checking for .tld which matches all top level domains.
domain
pattern
returns
Checks if two hosts match, also checking for .tld which matches all top level domains.
domain
pattern
returns
Parses an uri to a SoupURI object, see also SOUPURI.
domain
returns
Gets all persistent cookies from the cookie jar.
returns
Sends a http-request.
uri
callback
method
data
data.contentType
data.data
returns
Sends a http-request synchronously.
uri
method
returns
Gets all session cookies from the cookie jar.
returns
Array[Cookie] net.allCookies()
Array[Cookie] net.sessionCookies()
timer
Functions for timed execution
Executes a function repeatedly until the function returns false or timerStop is called on the id returned from this function
interval
func
returns
Stops a timer started by timerStart
id
returns
Number timer.start(Number interval, Function func)
util
The util object implements helper methods.
Decodes a base64-encoded string to a string.
text
returns
Encodes a string to base64.
text
returns
Converts a non-camelcase string to a camelcase string.
text
returns
Computes a checksum for given data.
shortcut
type
returns
Clones an object, circular references are not supported.
object
returns
Gets the body of a function, useful for scripts that will be injected into sites.
func
returns
Dispatches a keyboard or mouse event.
object
object.type
returns
Gets the the current mode.
returns
Get selected text from the focused webview.
returns
Creates a multiline string.
doc
Escapes text for usage with pango markup.
text
returns
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
Object...
returns
Initiates tab completion.
label
items
callback
readonly
Initializes filename completion.
callback
label
initialPath
dirOnly
Converts camel-case string for usage with GObject properties to a non-camel-case String
text
returns
dwb also adds additional methods to builtin objects
Executes a function for each enumarable property of this similar to Array.forEach.
func
key
value
this
This method is basically the same as Array.indexOf but without type checking.
object
returns
This method is basically the same as Array.lastIndexOf but without type checking.
object
returns
A wrapper method for debugging callbacks, especially useful if it is combined with script.
scope
returns
String util.base64Decode(String text)
String util.hereDoc(Function doc)
String util.markupEscape(String text)
String util.mixin(Object self, Object ...)
void util.tabComplete(String label, Array items, Function callback, [Boolean readonly])
void util.pathComplete(Function callback, [String label], [String initialPath], [Boolean dirOnly])
void util.uncamelize(String text)
void Object.forEach(Function func(String key, Object value, Object this))
Number Array.fastIndexOf(Object object)
Number Array.fastLastIndexOf(Object object)
void Function.debug([Object scope])
clipboard
Gets the X11 clipboard.
selection
callback
returns
Sets the X11 clipboard.
selection
text
void clipboard.get(Selection selection, [Function callback])
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:
Deletes a cookie from the jar
Saves a cookie to the jar
Sets the maximum age of a cookie
seconds
void Cookie.delete()
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.
Registers a function for then done and fail chain.
callback
returns
Registers a function for the done-chain.
callback
returns
Registers a function for the fail-chain.
callback
returns
Rejects a deferred, the fail-chain is called when a deferred is rejected.
arguments
Resolves a deferred, the done-chain is called when a deferred is resolved.
arguments
Registers a function for the done and fail chain.
ondone
onfail
returns
Deferred also implements a static method:
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
ondone
onfail
returns
Simple usage of a deferred:
void Deferred.always(Function callback)
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 "\\";
Constructs a new Glob.
pattern
Matches against a string
string
returns
Converts a Glob to string.
returns
new Glob(String pattern)
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
Blocks emission of a gobect signal.
signalid
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
callback
after
returns
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
callback
after
returns
Disconnect from a gobject-signal.
id
returns
Wrapper function for property-change notification, the same as object.connect("notify::" + name, callback, after);.
name
callback
after
returns
Wrapper function for property-change notification, the same as object.connectBlocked("notify::" + name, callback, after);.
name
callback
after
returns
Unblocks a signal previously blocked with object.blockSignal.
signalid
void object.blockSignal(Number signalid)
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.
Injects a script into a webview
code
arg
line
global
returns
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.
Loads a history item steps away from the current history item
steps
Loads a string in a webview
content
mimeType
encoding
baseUri
extSource
returns
Loads an uri in a webview.
uri
callback
returns
Reloads a webview
Stops any ongoing loading.
Renders a webview to a png file.
filename
width
height
keepAspect
returns
String wv.inject([String code|Function code], [Object arg], [Boolean global])
Note
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
Injects a script into a frame, see also webview.inject for details.
Loads a string in a frame
content
mimeType
encoding
baseUri
extSource
returns
Boolean frame.inject(String script, [Boolean global])
download
Corresponds to a WebKitDownload.
Constructs a new download
uri
Starts a download
callback
Cancels a download
new Download(String uri)
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
Gets a WebKitWebHistoryItem.
position
returns
WebKitWebHistoryItem historylist.getItem([Number position])
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
Constructs a new widget
type
new GtkWindow(String type)
Methods
All created widgets implement the following methods:
Adds a widget as a child. Note that this function can only be called on widgets derived from GtkContainer.
widget
Destroys a widget. Note that only newly created widgets can be destroyed.
Gets all children of a GtkWidget. Note that this function can only be called on widgets derived from GtkContainer.
returns
Removes a widget from it's parent. Note that this function can only be called on widgets derived from GtkContainer.
widget
Widgets that implement the GtkBox interface implement the following methods:
Adds a widget to a GtkBox.
child
expand
fill
padding
Adds a widget to a GtkBox.
child
expand
fill
padding
Moves a widget to a new position.
child
position
Widgets derived from GtkContainer implement the following methods:
Adds a widget to a GtkContainer.
child
void GtkWidget.add(GtkWidget widget)
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
Appends a value to a header.
name
value
Removes all headers.
Gets a comma separated header list.
name
returns
Gets a header.
name
returns
Removes a header.
name
Replaces a header.
name
value
void SoupHeaders.append(String name, Strina value)
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
Constructs a new signal
name
callback
new Signal(String name, [Function callback])
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
Connects the signal to the event
callback
returns
Disconnects the signal from the event
returns
Toggles a signal, if it is connected it will be disconnected an vice versa.
returns
connect([Function callback])
Static methods
Connects to an event
signals
callback
Connects to more than one signal at once
signals
callback
Connects all webviews to a GObject signal.
name
callback
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
returns
Disconnect from all signals with matching callback function
callback
returns
Emits a signal, can be used to implement custom signals.
name
...
returns
Connects to an event once
signals
callback
returns
Signal.connect(String name, Function callback)
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
Deletes a private property of an object previously set with script.setPrivate and returns the private value.
object
key
returns
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.
Generates a unique id.
returns
Gets a private property of an object previously set with script.setPrivate
object
key
returns
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
key
value
void script.deletePrivate(Object object, String key)
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
An extension that gets form data and fills forms with previously saved data.
Configuration options
formData
scGetForm
scFillForm
useGPG
GPGOptEncrypt
GPGOptDecrypt
keepPassword
keepFormdata
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
hosts
uris
defaults
Example configuration
formfiller
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
}
});
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
unblockCurrent
unblockAll
whiteList
autoreload
notify
Extension that allows one to remove duplicate tabs or avoids duplicate tabs automatically.
Configuration options
shortcutRemoveDuplicates
commandRemoveDuplicates
autoFocus
shortcutToggleAutoFocus
commandToggleAutoFocus
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
Example configuration
requestpolicy
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
Bind an extension to a shortcut, the shortcut enables/disables the extension.
name
shortcut
options
options.load
options.config
options.command
Disables all extensions.
Print a consistent error message to stderr
name
message
Loads an extension
name
config
returns
Toggles an extension
name
config
returns
Unloads an extension
name
returns
Print an error message and call stack to stderr.
name
message|e
message
Print a consistent message to stdout
name
message
Print a consistent warning to stderr
name
message
void extensions.bind(String name, String shortcut, [Object options])
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.
A extension called foobar in $HOME/.local/share/dwb/extensions/foobar:
Example
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
};