Provided by: dwb_20130503hg-2ubuntu1_amd64
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 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 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. 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
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 io The io object implements methods for input and output. 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.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.print(String text, [String stream]) Print text to stdout or stderr text the text to print stream pass "stderr" to print to stderr, optional 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 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, [Function stdout], [Function stderr], [Object environ]) Executes a shell command using the default search path command The command to execute stdout(String) Callback function for stdin, any strings returned from the callback are passed to stdin of the spawned process, pass null if only stderr is needed, optional stderr(String) Callback function for stderr, any strings returned from the callback are passed to stdin of the process, pass null if stderr is not needed and environment variables should be set, optional environ Object that can be used to add environment variables to the environment, optional. returns A deferred, it will be resolved if the child exits normally, it will be rejected if the child process exits abnormally, the first parameter of the reject function will be the status 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 environment, optional. returns An object that contains stdout, stderr and status. tabs The tabs object implements methods and properties to get webview objects. 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 webview tabs.nth(Number n) Gets the webview object of the nth tab n Number of the tab returns The corresponding webview net Network related functions 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 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. 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 Number 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.camelize(String text) Converts a non-camelcase string to a camelcase string. text A non-camelcase string returns The a camelcase string 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 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 event. event A GdkEventType modifier A Modifier keyval A keyval as listed in gdkkeysyms.h 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.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.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. Deferred Deferred objects can be used to manage asynchronous operations. It can trigger a callback function when an asynchrounous operation has finished, and allows one to 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 methods: 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.print(response); // Finished }, function(response) { io.print(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.print(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.print(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.print(response); // Prints "foo" after 2 seconds // Return a new Deferred, will replace the old one. return foo("bar"); } function callback2(response) { io.print(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. 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 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. 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.destroy() Destroys a widget. Note that only newly created widgets can be destroyed. 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;
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 to connect to more than one signal and also allows one to to easily disconnect/reconnect to signals. There is just one convenient pattern that allows one to 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 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: 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. 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 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 (Number, read) Name of the event 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
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.print(number); // undefined var number2 = 0; io.print(number2); // 0 // not allowed foo = function() { io.print("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.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.print("bar"); } }); provide("myOtherModule", { act : function (arg) { io.print(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.print(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.print(foo.bar); // 42 }); provide("foo", { bar : 42 }); #!javascript require(["foo"], function(foo) { io.print(foo); // undefined }); require(["foo!/path/to/foo"]); require(["foo"], function(foo) { io.print(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 per-domain-settings. Valid settings are the properties of WebKitWebSettings but in camelcase, see http://webkitgtk.org/reference/webkitgtk/unstable/WebKitWebSettings.html 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 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) 04/04/2013 DWB-JS(7)