API-Version: 1.9

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 to connect to more than one signal and also allows 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 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.

To connect a single webview to an event the callback can directly be set on the webview, see WebKitWebView for a list of signals that can be set on WebKitWebViews. More than one callback function can be set on the same webview. Note that is is only possible to disconnect from signals directly set on a webview by calling this.disconnect(); in the callback function or calling Signal.disconnect(callback);.

Source:

Example

 
function onNavigation(wv, frame, request) 
{
     ... 
     if (request.uri == "http://www.example.com")
         this.disconnect();
}
// Connect to the navigation event
// this is the preferred way.
var s = new Signal("navigation", onNavigation).connect();
// or equivalently, gi
signals.onNavigation = onNavigation;

// Connect the current tab to an event
tabs.current.onButtonPress = function(webview, result, event) {
     io.print(event);
}
// Connect the current tab once to an event
tabs.current.onceDocumentLoaded = function(wv) {
     io.print("document load finished");
}

Type Definitions

onAddCookie(cookie) → {Boolean}

Callback when a cookie is added to the session cookie jar. If expiration of the cookie is in the future and persistent cookies are allowed or the cookie is whitelisted it will also be added to the persistent cookie jar.

Parameters:
Name Type Description
cookie Cookie

The copy of the cookie that will be added to the jar

Since:
  • 1.5
Source:
Returns:

If the function returns true the original cookie won't be added to the jar. To change a cookie this function must return true and the copy of the cookie can be added to the jar using save

Type
Boolean
Example
// Make the cookie a session cookie
Signal.connect("addCookie", function(cookie) {
     cookie.setMaxAge(-1);
     cookie.save();
     return true;
});

onButtonPress(webview, result, event) → {Boolean}

Callback called when a mouse button was pressed on a webview

Parameters:
Name Type Description
webview WebKitWebView

The webview that emitted the signal

result WebKitHitTestResult

A hit test result

event Object
Properties
Name Type Description
button Number

The button that was pressed, usually a value between 1 and 5

state Modifier

A bitmask of Modifiers pressed

time Number

The time in milliseconds when the button was pressed

type ClickType

A ClickType

x Number

x-position relative to the window

xRoot Number

x-position relative to the screen

y Number

y-position relative to the window

yRoot Number

y-position relative to the screen

Source:
Returns:

Return true to prevent the default action

Type
Boolean

onButtonRelease(webview, result, event) → {Boolean}

Callback called when a mouse button was released

Parameters:
Name Type Description
webview WebKitWebView

The webview that emitted the signal

result WebKitHitTestResult

The hit test result

event Object
Properties
Name Type Description
button Number

The button that was pressed, usually a value between 1 and 5

state Modifier

A bitmask of Modifiers pressed

time Number

The time in milliseconds when the button was pressed

x Number

x-position relative to the window

xRoot Number

x-position relative to the screen

y Number

y-position relative to the window

yRoot Number

y-position relative to the screen

Source:
Returns:

Return true to prevent the default action

Type
Boolean

onChangeMode(new, mode) → {Boolean}

Callback called before the mode changes

Parameters:
Name Type Description
new WebKitWebView

The webview that currently has focus

mode Modes

A Mode

Source:
Returns:

Return true to prevent changing mode

Type
Boolean

onClose()

Callback called when dwb is closed

Source:

onCloseTab(webview)

Callback called when a tab is closed

Parameters:
Name Type Description
webview WebKitWebView

The corresponding WebKitWebView

Source:

onContextMenu(webview, menu)

Callback called when the load of a site has just been committed.

Parameters:
Name Type Description
webview WebKitWebView

The webview that emitted the signal

menu GtkMenu

The menu.

Source:

onCreateTab(webview, data)

Callback called when a tab is created

Parameters:
Name Type Description
webview WebKitWebView

The webview that was created

data Object
Properties
Name Type Description
uri Object

The uri that will be loaded or null if an empty tab or the startpage will be loaded

Source:

onDocumentLoaded(webview, frame)

Callback called when the document of a frame has been loaded.

Parameters:
Name Type Description
webview WebKitWebView

The webview that contains the frame

frame WebKitWebFrame

The frame that emitted the signal

Source:

onDownload(webview, frame, data)

Callback called before a download starts, will be called before the a path/application was chosen

Parameters:
Name Type Description
webview WebKitWebView

The webview emitted the signal

frame WebKitDownload

The download

data Object
Properties
Name Type Description
referer String

The referer

mimeType String

The mime type of the download

Source:

onDownloadStart(download, data) → {Boolean}

Callback called when the download status changes

Parameters:
Name Type Description
download WebKitDownload

The download

data Object
Properties
Name Type Description
application String

The application that will be spawned when the download has finished or null if no application will be spawned.

destinationUri String

The destination uri of the download or null if an application is spawned when the download has finished

mimeType String

The mimetype of the download

referer String

The referer

Source:
Returns:

Return true to stop dwb from handling the download

Type
Boolean

onDownloadStatus(download) → {Boolean}

Callback called when the download status changes

Parameters:
Name Type Description
download WebKitDownload

The download

Source:
Returns:

Return true to stop dwb from handling the download when the download has finished

Type
Boolean

onError(webview, frame, error) → {Boolean}

Callback called when the load-status of a WebKitWebView changes

Parameters:
Name Type Description
webview WebKitWebView

The webview that emitted the signal

frame WebKitWebFrame

The webframe that emitted the signal

error Object

The error

Properties
Name Type Description
message String

The error message

code Number

The error code

Source:
Returns:

Return true to prevent the default action

Type
Boolean

onExecuteCommand(detail, command, argument, nummod) → {Boolean}

Callback called before a command is executed

Parameters:
Name Type Description
detail Object
command String

The command

argument String

An argument that was used on commandline or null

nummod String

A numerical modifier or -1 if no modifier was used

Source:
Returns:

Return true to prevent the command from being executed

Type
Boolean

onFollowHint(wv, resource) → {Boolean}

Callback called before a hint will be followed

Parameters:
Name Type Description
wv WebKitWebView

The webview that currently has focus

resource String

The resource of the hint, can be a url, @input, @textarea, @radio, @checkbox, @submit, @reset, @button, @role, @unknown or @abort if Escape was pressed.

Since:
  • 1.4
Source:
Returns:

Return true to prevent following the hint

Type
Boolean

onFrameCreated(webview, frame)

Callback called when a WebKitWebFrame is created

Parameters:
Name Type Description
webview WebKitWebView

The webview that contains the frame

frame WebKitWebFrame

The created frame

Source:

onFrameStatus(webview, frame)

Callback called when the load-status of a WebKitWebFrame changes

Parameters:
Name Type Description
webview WebKitWebView

The webview that contains the frame

frame WebKitWebFrame

The frame that emitted the signal

Source:

onKeyPress(webview, event) → {Boolean}

Callback called whenever a key is pressed

Parameters:
Name Type Description
webview WebKitWebView

The currently focused webview

event Object

The event

Properties
Name Type Description
isModifier Boolean

Whether the key is a modifier

keyCode Number

The hardware keycode

keyVal Number

The keycode as listed in gdkkeysyms.h

name String

A string representation of the key

state Modifier

A bitmask of Modifier pressed

Source:
Returns:

Return true to stop emission of the signal, will also prevent dwb from handling the signal.

Type
Boolean

onKeyRelease(webview, event) → {Boolean}

Callback called whenever a key is pressed

Parameters:
Name Type Description
webview WebKitWebView

The currently focused webview

event Object

The event

Properties
Name Type Description
isModifier Boolean

Whether the key is a modifier

keyCode Number

The hardware keycode

keyVal Number

The keycode as listed in gdkkeysyms.h

name String

A string representation of the key

state Modifier

A bitmask of Modifier pressed

Source:
Returns:

Return true to stop emission of the signal, will also prevent dwb from handling the signal.

Type
Boolean

onLoadCommitted(webview)

Callback called when the load of a site has just been committed.

Parameters:
Name Type Description
webview WebKitWebView

The webview that emitted the signal

Source:

onLoadFinished(webview)

Callback called when a site has completely loaded

Parameters:
Name Type Description
webview WebKitWebView

The webview that emitted the signal

Source:

onLoadStatus(webview)

Callback called when the load-status of a WebKitWebView changes

Parameters:
Name Type Description
webview WebKitWebView

The webview that emitted the signal

Source:

onMimeType(webview, frame, request, data) → {Boolean}

Callback called when a mimetype decision has to be made

Parameters:
Name Type Description
webview WebKitWebView

The webview that contains the frame

frame WebKitWebFrame

The frame that emitted the signal

request WebKitNetworkRequest

The network request

data Object
Properties
Name Type Description
canShowMimeType Boolean

Whether the webview can show the mimetype

mimeType String

The mime type

Source:
Returns:

Return true to ignore the request

Type
Boolean

onMouseMove(webview, event) → {Boolean}

Callback called when the mouse was moved

Parameters:
Name Type Description
webview WebKitWebView

The webview that emitted the signal

event Object
Properties
Name Type Description
button Number

The button that was pressed, usually a value between 1 and 5

state Modifier

A bitmask of Modifiers pressed

time Number

The time in milliseconds when the button was pressed

x Number

x-position relative to the window

xRoot Number

x-position relative to the screen

y Number

y-position relative to the window

yRoot Number

y-position relative to the screen

Source:
Returns:

Return true to prevent the movement

Type
Boolean

onNavigation(webview, frame, request, action) → {Boolean}

Callback called before a new navigation starts

Parameters:
Name Type Description
webview WebKitWebView

The webview that contains the frame, to check if a new site will be loaded check if == frame

frame WebKitWebFrame

The frame that emitted the signal

request WebKitNetworkRequest

The network request

action WebKitWebNavigationAction

A navigation action that started the request

Source:
Returns:

Return true to stop the emission and prevent the site from being loaded

Type
Boolean

onReady()

Callback called when dwb has been fully initialized

Source:

onResource(webview, frame, request, response)

Callback called before a resource is loaded

Parameters:
Name Type Description
webview WebKitWebView

The webview that contains the requesting frame

frame WebKitWebFrame

The frame that requested the resource

request WebKitNetworkRequest

The request, setting request.uri to "about:blank" will prevent the request from being loaded.

response WebKitNetworkResponse

The response, note that response will always be null unless the request comes from a redirect

Source:

onScroll(webview, event) → {Boolean}

Callback called when the webview is scrolled using the mouse

Parameters:
Name Type Description
webview WebKitWebView

The webview that emitted the signal

event Object
Properties
Name Type Description
direction String

The scroll direction

state Modifier

A bitmask of Modifiers pressed

time Number

The time in milliseconds when the button was pressed

x Number

x-position relative to the window

xRoot Number

x-position relative to the screen

y Number

y-position relative to the window

yRoot Number

y-position relative to the screen

Source:
Returns:

Return true to prevent the default action

Type
Boolean

onStatusBarChange(webview, data) → {Boolean}

Callback called before dwb updates the status bar If the callback returns true dwb will not update the statusbar so it is possible to set the statusbar from the script.

Parameters:
Name Type Description
webview WebKitWebView

The focused webview

data Object

Data

Properties
Name Type Description
canGoBack boolean

Whether it is possible to navigate back in the webview

canGoForward Boolean

Whether it is possible to navigate forward in the webview

isBookmarked Boolean

Whether the site is bookmarked

isQuickmarked Boolean

Whether the site is quickmarked

pluginsBlocked Boolean

Whether plugins are blocked

scriptsBlocked Boolean

Whether scripts are blocked

ssl String

SSL-State of the page, can either be "trusted", "untrusted" or "none"

type String

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.

Source:
Returns:

Return true to prevent dwb to update the statusbar

Type
Boolean

onTabButtonPress(webview, tabwidget, event) → {Boolean}

Callback called when a button was pressed on a tablabel

Parameters:
Name Type Description
webview WebKitWebView

The webview that emitted the signal

tabwidget GtkEventBox

The tabwidget

event Object
Properties
Name Type Description
button Number

The button that was pressed, usually a value between 1 and 5

state Modifier

A bitmask of Modifiers pressed

time Number

The time in milliseconds when the button was pressed

type ClickType

A ClickType

x Number

x-position relative to the window

xRoot Number

x-position relative to the screen

y Number

y-position relative to the window

yRoot Number

y-position relative to the screen

Source:
Returns:

Return true to prevent the default action

Type
Boolean

onTabFocus(new, last, data) → {Boolean}

Callback called before a tab gets focus

Parameters:
Name Type Description
new WebKitWebView

The webview that will get focus

last WebKitWebView

The webview that has focus

data Object
Properties
Name Type Description
event String

The event either a command name button_press, tab_button_press, close_tab or new_tab

Source:
Returns:

Return true to prevent the focus

Type
Boolean

Events

addCookie

Emitted when a cookie will be added to the session cookie jar

Parameters:
Name Type Description
callback signals~onAddCookie

Callback function that will be called when the signal is emitted

Since:
  • 1.5
Source:

buttonPress

Emitted when a mouse button was pressed

Parameters:
Name Type Description
callback signals~onButtonPress

Callback function that will be called when the signal is emitted

Source:

buttonRelease

Emitted when a mouse button was released

Parameters:
Name Type Description
callback signals~onButtonRelease

Callback function that will be called when the signal is emitted

Source:

changeMode

Emitted before the mode changes

Parameters:
Name Type Description
callback signals~onChangeMode

Callback function that will be called when the signal is emitted

Source:

close

Emitted when dwb is closed

Parameters:
Name Type Description
callback signals~onClose

Callback function that will be called when the signal is emitted

Source:

closeTab

Emitted when a tab is closed

Parameters:
Name Type Description
callback signals~onCloseTab

Callback function that will be called when the signal is emitted

Source:

contextMenu

Emitted before the context menu is shown, can be used to add custom items.

Parameters:
Name Type Description
callback signals~onContextMenu

Callback function that will be called when the signal is emitted

Source:

createTab

Emitted when a tab is created

Parameters:
Name Type Description
callback signals~onCreateTab

Callback function that will be called when the signal is emitted

Source:

documentLoaded

Emitted when a document of a frame has been loaded. Use this event to inject scripts that need a fully populated DOM-tree

Parameters:
Name Type Description
callback signals~onDocumentLoaded

Callback function that will be called when the signal is emitted

Source:

download

Emitted before a download starts

Parameters:
Name Type Description
callback signals~onDownload

Callback function that will be called when the signal is emitted

Source:

downloadStart

Emitted before a download starts, after the user has chosen a path or application

Parameters:
Name Type Description
callback signals~onDownloadStart

Callback function that will be called when the signal is emitted

Source:

downloadStatus

Emitted when the status of a download handled by dwb changes.

Parameters:
Name Type Description
callback signals~onDownloadStatus

Callback function that will be called when the signal is emitted

Source:

error

Emitted when an error occurs dureing a page load

Parameters:
Name Type Description
callback signals~onError

Callback function that will be called when the signal is emitted

Source:

executeCommand

Emitted before a command is executed

Parameters:
Name Type Description
callback signals~onExecuteCommand

Callback function that will be called when the signal is emitted

Source:

followHint

Emitted when a hint will be followed

Parameters:
Name Type Description
callback signals~onFollowHint

Callback function that will be called when the signal is emitted

Since:
  • 1.4
Source:

frameCreated

Emitted when a frame is created

Parameters:
Name Type Description
callback signals~onFrameCreated

Callback function that will be called when the signal is emitted

Source:

frameStatus

Emitted when the load status of a frame changes

Parameters:
Name Type Description
callback signals~onFrameStatus

Callback function that will be called when the signal is emitted

Source:

keyPress

Emitted when a key was pressed

Parameters:
Name Type Description
callback signals~onKeyPress

Callback function that will be called when the signal is emitted

Source:

keyRelease

Emitted when a key was released

Parameters:
Name Type Description
callback signals~onKeyRelease

Callback function that will be called when the signal is emitted

Source:

loadCommitted

Emitted when the load has just been commited, no data has been loaded when this signal is emitted. This is the preferred signal for injected scripts that do not manipulate the DOM.

Parameters:
Name Type Description
callback signals~onLoadCommitted

Callback function that will be called when the signal is emitted

Source:

loadFinished

Emitted when the site has completely loaded.

Parameters:
Name Type Description
callback signals~onLoadFinished

Callback function that will be called when the signal is emitted

Source:

loadStatus

Emitted whenever the loadstatus changes

Parameters:
Name Type Description
callback signals~onLoadStatus

Callback function that will be called when the signal is emitted

Source:

mimeType

Emitted when a mime type decision is requested

Parameters:
Name Type Description
callback signals~onMimeType

Callback function that will be called when the signal is emitted

Source:

mouseMove

Emitted when the mouse was moved

Parameters:
Name Type Description
callback signals~onMouseMove

Callback function that will be called when the signal is emitted

Source:

navigation

Emitted before a new site or a new frame is loaded

Parameters:
Name Type Description
callback signals~onNavigation

Callback function that will be called when the signal is emitted

Source:

ready

Emitted once after dwb has been fully initialized. some functions can only be called after this signal has been emitted, e.g. execute.

Parameters:
Name Type Description
callback signals~onReady

Callback function that will be called when the signal is emitted

Source:

resource

Emitted before a resource is loaded

Parameters:
Name Type Description
callback signals~onResource

Callback function that will be called when the signal is emitted

Source:

scroll

Emitted when the webview is scrolled using the mouse

Parameters:
Name Type Description
callback signals~onScroll

Callback function that will be called when the signal is emitted

Source:

statusBarChange

Emitted before the status bar is updated.

Parameters:
Name Type Description
callback signals~onStatusBarChange

Callback called when the signal is emitted

Source:

tabButtonPress

Emitted when the mouse was pressed on a tab label

Parameters:
Name Type Description
callback signals~onTabButtonPress

Callback function that will be called when the signal is emitted

Source:

tabFocus

Emitted before a tab gets focus

Parameters:
Name Type Description
callback signals~onTabFocus

Callback function that will be called when the signal is emitted

Source: