From cabc7655c69c31bfcd2af3b466f68542d6d2343a Mon Sep 17 00:00:00 2001 From: Stefan Bolte Date: Sat, 13 Apr 2013 22:35:11 +0200 Subject: Remove api doc, dwbem.1.html --- doc/api/jsapi.txt | 3985 ----------------------------------------------------- 1 file changed, 3985 deletions(-) delete mode 100644 doc/api/jsapi.txt (limited to 'doc/api') diff --git a/doc/api/jsapi.txt b/doc/api/jsapi.txt deleted file mode 100644 index e155da19..00000000 --- a/doc/api/jsapi.txt +++ /dev/null @@ -1,3985 +0,0 @@ -= dwb's JavaScript API documentation = - -== DEPRECATED == -This documentation is deprecated, -the new api documentation can be found under -link:http://portix.bitbucket.org/dwb/api/[] - -== Abstract == - -*dwb* can be extended with different types of userscripts. -This api documentation describes the javascript interface. - -== 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 seperated 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 <> for details. - -:numbered!: -:caption: - - -== Global == - -=== Properties === - -**** -[float] -==== *global* ==== - -[source,javascript] ----- -global object read ----- - -Refers to the global object. -**** - -**** -[float] -==== *session* ==== - -[source,javascript] ----- -session SoupSession read ----- - -The webkit session. -**** - -=== Methods === - - -**** -[[bind]] -[float] -==== *bind()* ==== - -[source,javascript] ----- -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 -**** - -**** -[[checksum]] -[float] -==== *checksum()* ==== - -[source,javascript] ----- -String checksum(String data, [ChecksumType type]) ----- - -Computes a checksum for given data. - - :: - -_shortcut_;; The to compute the checksum for. -_type_;; The type of the checksum, optional, defaults to ChecksumType.sha256 -_returns_;; The checksum -**** - - -**** -[[execute]] -[float] -==== *execute()* ==== - -[source,javascript] ----- -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 -**** - -**** -[[exit]] -[float] -==== *exit()* ==== - -[source,javascript] ----- -Boolean exit() ----- - -Exit dwb, must be called if the script is running from commandline. -**** - - -**** -[[include]] -[float] -==== *include()* ==== - -[source,javascript] ----- -Value 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 -**** - -**** -[[provide]] -[float] -==== *provide()* ==== - -[source,javascript] ----- -void provide(String name, Object module) ----- - -Defines a module that can be used in other scripts, see <> for details. - - :: - -_name_;; Name of the module -_module_;; The module -**** - -**** -[[replace]] -[float] -==== *replace()* ==== - -[source,javascript] ----- -void replace(String name, Object module) ----- - -Same as <> but replaces the module if it was already defined. -Same as <> 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. -**** - -**** -[[require]] -[float] -==== *require()* ==== - -[source,javascript] ----- -void require(Array names, Function callback) ----- - -Load modules defined with <>. - - :: - -_names_;; An array of module names or null to get all modules, a module name can -also contain a path, the path must be seperated with a +!+ from the module name, -see also <> 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 <> for examples. -**** - -**** -[[sendRequest]] -[float] -==== *sendRequest()* ==== - -[source,javascript] ----- -void sendRequest(String uri, Function callback, [String method]) ----- - -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. -**** - -**** -[[sendRequestSync]] -[float] -==== *sendRequestSync()* ==== - -[source,javascript] ----- -Object 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. -**** - -**** -[[tabComplete]] -[float] -==== *tabComplete()* ==== - -[source,javascript] ----- -void 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. -**** - -**** -[[timerStart]] -[float] -==== *timerStart()* ==== - -[source,javascript] ----- -Number timerStart(Number interval, Function func) ----- - -Executes a function repeatedly until the function returns +false+ or -<> 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 -**** - -**** -[[timerStop]] -[float] -==== *timerStop()* ==== - -[source,javascript] ----- -Number timerStop(Number id) ----- - -Stops a timer started by <> - - :: - -_id_;; The id returned from <> -_returns_;; +true+ if the timer was stopped -**** - -**** -[[unbind]] -[float] -==== *unbind()* ==== - -[source,javascript] ----- -Number unbind(Function func|String name) ----- - -Unbind a shortcut that was previously bound with <> - - :: - -_func_ or _name_;; Either the function or the optional name passed to <>. -_returns_;; +true+ if the function was unbound -**** - -====== -.Example -[source,javascript] ---------------------------------- -execute("tabopen ixquick.com"); - -// Execute a function once, similar to window.setTimeout() -timerStart(2000, function() { - tabs.current.inject("alert('Hello world')"); - return false; -}); ---------------------------------- -====== - -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: - -====== -[source,javascript] ---------------------------------- -// 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: - -====== -[source,javascript] ---------------------------------- -// 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 -}) ---------------------------------- -====== - - - -[[Globalobjects]] -== Global Objects == - -[[data]] -=== 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 -**** - -==== -.Example -[source,javascript] ---------------------------------- -// Get contents of the currently used bookmark file -var bookmarks = io.read(data.bookmarks); --------------------------------- -==== - -[[io]] -=== io === -The +io+ object implements methods for input and output. - -**** -[[debug]] -[float] -==== *debug()* ==== - -[source,javascript] ----- -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 -**** - -**** -[[dirNames]] -[float] -==== *dirNames()* ==== - -[source,javascript] ----- -Array io.dirNames(String path) ----- - -Get directory entries. - - :: - -_path_;; A path to a directory -_returns_;; An array with the directory names -**** - -**** -[[error]] -[float] -==== *error()* ==== - -[source,javascript] ----- -void io.error(String text) ----- - -Shows an error message in the browser window. - - :: - -_text_;; The message to show -**** - -**** -[[notify]] -[float] -==== *notify()* ==== - -[source,javascript] ----- -void io.notify(String text) ----- - -Shows a message in the browser window. - - :: - -_text_;; The message to show -**** - -**** -[[print]] -[float] -==== *print()* ==== - -[source,javascript] ----- -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 -**** - -**** -[[prompt]] -[float] -==== *prompt()* ==== - -[source,javascript] ----- -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+ -**** - -**** -[[read]] -[float] -==== *read()* ==== - -[source,javascript] ----- -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 -**** - -**** -[[write]] -[float] -==== *write()* ==== - -[source,javascript] ----- -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 -**** - - -==== -.Example -[source,javascript] ---------------------------------- -var text = io.read("/home/foo/textfile.txt"); -io.print(text); --------------------------------- -==== - -[[system]] -=== system === - -The +system+ object implements system methods. - -**** -[[fileTest]] -[float] -==== *fileTest()* ==== - -[source,javascript] ----- -Boolean system.fileTest(String path, FileTest flags) ----- - -Checks for <> 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 -**** - -**** -[[getEnv]] -[float] -==== *getEnv()* ==== - -[source,javascript] ----- -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 -**** - -**** -[[mkdir]] -[float] -==== *mkdir()* ==== - -[source,javascript] ----- -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 -**** - -**** -[[spawn]] -[float] -==== *spawn()* ==== - -[source,javascript] ----- -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 childs -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. -**** - -**** -[[spawnSync]] -[float] -==== *spawnSync()* ==== - -[source,javascript] ----- -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 childs -environment, optional. -_returns_;; An object that contains +stdout+, +stderr+ and +status+. -**** - -==== -.Example -[source,javascript] ------------- -var home = system.getEnv("HOME"); -// asynchronous wrapped read -function asyncread(filename) { - system.spawn("cat " + filename, function (response) { - ... - }); -} -asyncread(home + "/.bashrc"); ------------- -==== - - -[[tabs]] -=== tabs === -The +tabs+ object implements methods and properties to get +webview+ objects. - -==== Properties ==== - -**** -[float] -==== *current* ==== - -[source,javascript] ----- -tabs.current webview read ----- - -The currently focused webview -**** - -**** -[float] -==== *length* ==== - -[source,javascript] ----- -tabs.length Number read ----- - -Total number of tabs -**** - -**** -[float] -==== *number* ==== - -[source,javascript] ----- -tabs.number Number read ----- - -Number of the currently focused tab -**** - - - - -==== Methods ==== - -**** -[float] -==== *nth()* ==== - -[source,javascript] ----- -webview tabs.nth(Number n) ----- - -Gets the webview object of the nth tab - - :: - -_n_;; Number of the tab -_returns_;; The corresponding <> -**** - -==== -.Example -[source,javascript] ----- -var c = tabs.current; -tabs.nth(2).loadUri(c.uri); ----- -==== - - -[[util]] -=== util === - -The +util+ object implements helper methods. - -**** -[float] -==== *getBody()* ==== - -[source,javascript] ----- -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 -**** - -**** -[float] -==== *getMode()* ==== - -[source,javascript] ----- -Number util.getMode() ----- - -Gets the the current mode. - -_returns_;; The mode, see <> for possible modes. -**** - - - -**** -[[domainFromHost]] -[float] -==== *domainFromHost()* ==== - -[source,javascript] ----- -String util.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 -**** - -**** -[[getSelection]] -[float] -==== *getSelection()* ==== - -[source,javascript] ----- -String util.getSelection() ----- - -Get selected text from the focused webview. - - :: - -_returns_;; The selection or null if no text was selected. -**** - - -**** -[[markupEscape]] -[float] -==== *markupEscape()* ==== - -[source,javascript] ----- -String util.markupEscape(String text) ----- - -Escapes text for usage with pango markup. - -_text_;; A text to escape -_returns_;; The escaped text or 'null'; -**** - -dwb also adds additional methods to builtin objects - -**** -[[forEach]] -[float] -==== *Object.forEach()* ==== -[source,javascript] ----- -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 -**** - -**** -[[fastIndexOf]] -[float] -==== *Array.fastIndexOf()* ==== -[source,javascript] ----- -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. -**** - -**** -[[fastLastIndexOf]] -[float] -==== *Array.fastLastIndexOf()* ==== -[source,javascript] ----- -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. -**** - -**** -[[fastLastIndexOf]] -[float] -==== *Function.debug()* ==== -[source,javascript] ----- -void Function.debug([Object scope]) ----- - -A wrapper method for debugging callbacks, especially useful if it is combined -with <>. - - :: - -_scope_;; *script* or *this*, optional -_returns_;; A new function that calls script.debug on errors. -**** - -**** -.Example -[source,javascript] ----- -bind("x", function() { ... }.debug(script)); -// or equivalently -bind("x", script.debug(function() { ... })); - -// is a shorthand for - -bind("x", function () { - try { - ... - } - catch (e) { - script.debug(e); - } -}); ----- -**** - -[[clipboard]] -=== clipboard === - -**** -[[clipboardget]] -[float] -==== *get()* ==== -[source,javascript] ----- -[void|String] clipboard.get(Selection selection, [Function callback]) ----- - -Gets the X11 clipboard. - - :: - -_selection_;; The <> 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. -**** - -**** -[[clipboardset]] -[float] -==== *set()* ==== -[source,javascript] ----- -void clipboard.set(Selection selection, String text) ----- - -Sets the X11 clipboard. - - :: - -_selection_;; The <> to set -_text_;; Text that will be stored in the clipboard. -**** - -[[gui]] -=== gui === -Most gtk-widgets used by dwb can be accessed from scripts, an overview of the -layout can be found under -link:http://portix.bitbucket.org/dwb/resources/layout.html[]. - -**** -[float] -==== *window* ==== - -[source,javascript] ----- -gui.window GtkWindow read ----- - -The main window. -**** - -**** -[float] -==== *mainBox* ==== - -[source,javascript] ----- -gui.mainBox GtkBox read ----- - -The the main container, child of *gui.window*. -**** - -**** -[float] -==== *tabBox* ==== - -[source,javascript] ----- -gui.tabBox GtkBox read ----- - -The box used for tab labels, child of *gui.mainBox*. -**** - -**** -[float] -==== *contentBox* ==== - -[source,javascript] ----- -gui.contentBox GtkBox read ----- - -The box used for the main content, it contains all -webviews, child of *gui.mainBox*. -**** - -**** -[float] -==== *statusWidget* ==== - -[source,javascript] ----- -gui.statusWidget GtkEventBox read ----- - -The outmost statusbar widget, used for setting -the statusbars colors, child of *gui.mainBox*. -**** - -**** -[float] -==== *statusAlignment* ==== - -[source,javascript] ----- -gui.statusAlignment GtkAlignment read ----- - -Used for the statusbar alignment, child -of *gui.statusWidget*. -**** - -**** -[float] -==== *statusBox* ==== - -[source,javascript] ----- -gui.statusBox GtkBox read ----- - -The box that contains the statusbar widgets, -grandchild of *gui.statusAlignment*. -**** - -**** -[float] -==== *messageLabel* ==== - -[source,javascript] ----- -gui.messageLabel GtkBox read ----- - -Label used for notifications, first child of -*gui.statusBox*. -**** - -**** -[float] -==== *entry* ==== - -[source,javascript] ----- -gui.entry GtkEntry read ----- - -The entry, second child of *gui.statusBox*. -**** - -**** -[float] -==== *uriLabel* ==== - -[source,javascript] ----- -gui.uriLabel GtkLabel read ----- - -The entry, second child of *gui.statusBox*. -**** - -**** -[float] -==== *statusLabel* ==== - -[source,javascript] ----- -gui.statusLabel GtkLabel read ----- - -Label used for status information, fourth child of *gui.statusBox*. -**** - -[[Deferred]] -=== 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 methods: - -**** -[float] -==== *always()* ==== - -[source,javascript] ----- -Deferred 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. -**** - -**** -[float] -==== *done()* ==== - -[source,javascript] ----- -Deferred 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. -**** - -**** -[float] -==== *fail()* ==== - -[source,javascript] ----- -void 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. -**** - -**** -[float] -==== *reject()* ==== - -[source,javascript] ----- -void Deferred.reject(arguments) ----- - -Rejects a deferred, the fail-chain is called when a deferred is rejected. - - :: - -_arguments_;; Arguments passed to the _fail_ callbacks. -**** - -**** -[float] -==== *resolve()* ==== - -[source,javascript] ----- -Deferred Deferred.resolve(arguments) ----- - -Resolves a deferred, the done-chain is called when a deferred is resolved. - - :: - -_arguments_;; Arguments passed to the _done_ callbacks. -**** - -**** -[float] -==== *then()* ==== - -[source,javascript] ----- -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: - -**** -[float] -==== *when()* ==== - -[source,javascript] ----- -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. -**** - - -==== *Examples* ==== - -The builtin function system.spawn returns a deferred: -[source,javascript] ---------------------------------- -system.spawn("command").then( - function() - { - /* called when execution was successful */ - }, - function(errorcode) - { - /* called when execution wasn't successful */ - } -); ---------------------------------- - -Simple usage of a deferred: -[source,javascript] ---------------------------------- -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: - -[source,javascript] ---------------------------------- -function foo() -{ - var d = new Deferred(); - timerStart(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. -[source,javascript] ---------------------------------- -function foo() -{ - var d = new Deferred(); - timerStart(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().done(onResponse).fail(onResponse); -foo().fail(onResponse).done(onResponse); ---------------------------------- - -Changing the deferred in a callback chain: - -[source,javascript] ---------------------------------- -function foo(message) -{ - var d = new Deferred(); - timerStart(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 - -[source,javascript] ---------------------------------- -function asyncOperation() { - var d = new Deferred(); - .... - return d; -} -function syncOperation() -{ - var result = {}; - .... - return result; -} -Deferred.when(asyncOperation(), function() {...}); -Deferred.when(syncOperation(), function() {...}); ---------------------------------- - -[[Glob]] -=== 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 "\\"; - -==== Constructor ==== - -**** -[float] -==== *Glob()* ==== -[source,javascript] ----- -new Glob(String pattern) ----- - -Constructs a new Glob - - :: -_pattern_;; The pattern to match against -**** - -==== Methods ==== - -**** -[float] -==== *match()* ==== - -[source,javascript] ----- -Boolean Glob.match(String string) ----- - -Matches against a string - - :: - -_string_;; The string to match against. -_returns_;; True if the string matches the Glob. -**** - -**** -[float] -==== *toString()* ==== - -[source,javascript] ----- -String Glob.toString() ----- - -Converts a Glob to string. - - :: - -_returns_;; A string represantation of the Glob. -**** - -.Example - -==== -[source,javascript] ---------------------------------- -var glob = new Glob("foo*ba?"); -glob.match("foobarbaz"); // true -glob.match("foobaz"); // true -glob.match("foobarbazx"); // false -glob.match("fooba"); // false ---------------------------------- -==== - -[[settings]] -=== 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. - -.Example - -==== -[source,javascript] ---------------------------------- -if (settings.enablePrivateBrowsing == true) - execute("set enable-private-browsing false"); ---------------------------------- -==== - - -[[Webkitobjects]] -== 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+: - -==== -[source,javascript] ---------------------------------- -var webview = tabs.current -webview.zoomLevel = webview.zoomLevel * 2; ---------------------------------- -==== - -To check if an object is derived from GObject the instanceof operator can be -used: - -==== -[source,javascript] ---------------------------------- -if (myObject instanceof GObject) -{ - ... -} ---------------------------------- -==== - -All Objects derived from GObjets implement the following methods. - -//Webkit objects should not be compared using +==+, since it may happen that the -//same gobject is represented by different javascript objects, instead every -//webkit object implements an equals method, all Objects derived from GObjets -//implement the following functions. -// -//**** -//[float] -//==== *equals()* ==== -// -//[source,javascript] -//---- -//Boolean object.equals(Object compareObject) -//---- -// -//Compare two webkit objects -// -// :: -// -//_compareObject_;; The object to compare -//_returns_;; +true+ if the the corresponding gobjects are equal -//**** - -**** -[float] -==== *blockSignal()* ==== - -[source,javascript] ----- -Number object.blockSignal(Number signalid) ----- - -Blocks emission of a gobect signal. - - :: - -_signalid_;; The signalid returned from *object.connect* -**** - - -**** -[float] -==== *connect()* ==== - -[source,javascript] ----- -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. -**** - -**** -[float] -==== *connectBlocked()* ==== - -[source,javascript] ----- -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. -**** - -**** -[float] -==== *disconnect()* ==== - -[source,javascript] ----- -Boolean object.disconnect(Number id) ----- - -Disconnect from a gobject-signal. - - :: - -_id_;; The signal id obtained from <> -_returns_;; +true+ if the signal was disconnected -**** - -**** -[float] -==== *notify()* ==== - -[source,javascript] ----- -Number object.notify(String name, Function callback, [Boolean after]) ----- - -Wrapper function for property-change notification but with signal blocking, same as -_object.connect("notify::" + name, callback, after);_. - - :: - -_name_;; The property name to connect to, 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. -_returns_;; The signal id of the signal. -**** - -**** -[float] -==== *notifyBlocked()* ==== - -[source,javascript] ----- -Number object.notifyBlocked(String name, Function callback, [Boolean after]) ----- - -Wrapper function for property-change notification but with signal blocking, same as -_object.connectBlocked("notify::" + name, callback, after);_. - - :: - -_name_;; The property name to connect to, 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. -_returns_;; The signal id of the signal. -**** - - -**** -[float] -==== *unblockSignal()* ==== - -[source,javascript] ----- -Number object.unblockSignal(Number signalid) ----- - -Unblocks a signal previously blocked with *object.blockSignal*. - - :: - -_signalid_;; The signalid returned from *object.connect* -**** - - -==== -[float] -==== *Examples* ==== - -Connect to signals: - -[source,javascript] ------------- -tabs.current.connect("notify::load-status", function() { - io.print("Status changed"); -}); -tabs.current.notify("loadStatus", function() { - io.print("Status changed"); -}); -tabs.current.notify("load-status", function() { - io.print("Status changed"); -}); - -// Similar to signals.connect("navigation", ...) -signals.connect("createTab", function(wv) { - wv.connect("navigation-policy-decision-requested", function(wv, frame, request, action, policy) { - // block google.com - if (/google\.com/.test(request.uri)) - return true; - }); -}); ------------- -==== - - - - -//An exception is the webview object, for webview objects +==+ always gives the -//same result as +equals+. - - -[[webview]] -=== webview === -The +webview+ object represents the widget that actually displays the site -content. - -==== Properties ==== - -The properties correspond to the gobject properties in camelcase. Additional -properties are - -**** -[float] -==== *allFrames* ==== - -[source,javascript] ----- -wv.allFrames array of frames read ----- - -All frames of a webview including the mainframe -**** - -**** -[float] -==== *focusedFrame* ==== - -[source,javascript] ----- -wv.focusedFrame frame read ----- - -The focused frame of the webview -**** - -**** -[float] -==== *historyList* ==== - -[source,javascript] ----- -wv.historyList historylist read ----- - -The history of the webview -**** - - -**** -[float] -==== *mainFrame* ==== - -[source,javascript] ----- -wv.mainFrame frame read ----- - -The main frame of the webview -**** - -**** -[float] -==== *number* ==== - -[source,javascript] ----- -wv.number Number read ----- - -The number of the webview, starting at 0 -**** - -**** -[float] -==== *scrolledWindow* ==== - -[source,javascript] ----- -wv.scrolledWindow GtkScrolledWindow read ----- - -The parent widget of every webview, it -is used for scrolling the webview. -**** - -**** -[float] -==== *tabWidget* ==== - -[source,javascript] ----- -wv.tabWidget GtkEventBox read ----- - -The main widget for tab labels, used for coloring -tabs, child of *gui.tabBox*. -**** - -**** -[float] -==== *tabBox* ==== - -[source,javascript] ----- -wv.tabBox GtkBox read ----- - -Horizontal box, child of *wv.tabWidget*. -**** - -**** -[float] -==== *tabIcon* ==== - -[source,javascript] ----- -wv.tabIcon GtkImage read ----- - -Favicon widget, child of *wv.tabBox*. -**** - -**** -[float] -==== *tabLabel* ==== - -[source,javascript] ----- -wv.tabLabel GtkLabel read ----- - -Text label of a tab, child of *wv.tabBox*. -**** - -==== Methods ==== - -**** -[float] -[[inject]] -==== *inject()* ==== - -[source,javascript] ----- -String wv.inject([String code|Function code], [Object arg], [Number line], [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. -**** - -==== -.Example -[source,javascript,src_numbered] ------- -//!javascript - -function injectMe() { - var text = arguments[0]; - document.body.innerHTML = text; - text = y; - var d = document.createElement("div"); - document.body.appendChild(d); -} -signals.connect("documentLoaded", function(wv) { - wv.inject(injectMe, "foo", 4); -}); ------- - -The debugging message will be as follows: - -[source,txt] ------- -DWB SCRIPT EXCEPTION: An error occured injecting injectMe. -DWB SCRIPT EXCEPTION: in line 6: Can't find variable: y -==> DEBUG [SOURCE] - ... - 5 > document.body.innerHTML = text; ---> 6 > text = y; - 7 > var d = document.createElement("div"); - ... ------- -==== - -**** -[float] -==== *history()* ==== - -[source,javascript] ----- -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 -**** - -**** -[float] -==== *loadUri()* ==== - -[source,javascript] ----- -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 -**** - - -**** -[float] -==== *reload()* ==== - -[source,javascript] ----- -void wv.reload(void) ----- - -Reload a webview -**** - -**** -[float] -==== *stopLoading()* ==== - -[source,javascript] ----- -void wv.stopLoading(void) ----- - -Stops any ongoing loading. -**** - -**** -[float] -==== *toPng()* ==== - -[source,javascript] ----- -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 ascpect 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. -**** - - - - -==== -[float] -==== *Example* ==== -[source,javascript] ------------- -var wv = tabs.current; - -wv.loadUri("http://www.example.com", function() { - if (wv.loadStatus == LoadStatus.finished) { - wv.inject("alert('Hello ' + wv.uri + '!!!');"); - return true; - } -}); ------------- -==== - - -NOTE: If a script is injected from a <>-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. - - -[[frame]] -=== frame === - -A frame represents a +frame+ or +iframe+. Due to same origin policy it -is not possible to inject scripts from a <> into iframes with a -different domain. For this purpose the +frame+ object can be used. - -==== Properties ==== - -The properties correspond to the gobject properties in camelcase. -Additional properties are - -**** -[float] -==== *domain* ==== - -[source,javascript] ----- -frame.domain String read ----- - -The domain name of the frame which is the effective second level domain -**** - -**** -[float] -==== *host* ==== - -[source,javascript] ----- -frame.host String read ----- - -The host name of the frame -**** - -==== -To get the domain or hostname of a webview -[source,javascript] ----- -webview.mainFrame.domain -webview.mainFrame.host ----- -can be used. -==== - - - -==== Methods ==== - -**** -[float] -==== *inject()* ==== - -[source,javascript] ----- -Boolean frame.inject(String script, [Object argument], [Boolean global]) ----- - -Injects a script into a frame, see also <> for details. -**** - - -[[Download]] -=== download === - -Corresponds to a +WebKitDownload+. - -==== Constructor ==== - -**** -[float] -==== *Download()* ==== -[source,javascript] ----- -new Download(String uri) ----- - -Constructs a new download - - :: -_uri_;; The uri of the download -**** - -==== Methods ==== - -**** -[float] -==== *start()* ==== - -[source,javascript] ----- -Boolean download.start([Function callback]) ----- - -Starts a download - - :: - -_callback_;; A callback function that will be executed whenever the -<> changes, return +true+ to stop the emission, optional. -**** - - -**** -[float] -==== *cancel()* ==== - -[source,javascript] ----- -void download.cancel() ----- - -Cancels a download -**** - -==== -.Example -[source,javascript] ------- -var download = new Download("http://www.example.org/foo.pdf"); -var filename = "/tmp/" + download.suggestedFilename; -download.destinationUri = "file://" + filename; -download.start(function () { - if (download.status == DownloadStatus.finished) { - system.spawn("xpdf " + filename); - } -}); ------- -==== - -[[HistoryList]] -=== historylist === -Corresponds to a +WebkitWebBackForwardList+. - -==== Properties ==== - -**** -[float] -==== *backLength* ==== - -[source,javascript] ----- -historylist.backLength Number read ----- -Number of items that precede the current item -**** - -**** -[float] -==== *forwardLength* ==== - -[source,javascript] ----- -historylist.forwardLength Number read ----- -Number of items that succeed the current item -**** - -==== Methods ==== - -**** -[float] -==== *getItem()* ==== - -[source,javascript] ----- -WebKitWebHistoryItem historylist.getItem(Number position) ----- - -Gets a WebKitWebHistoryItem. - - :: - -_position_;; The position of the item where 0 corresponds to the current item. -_returns_;; A WebKitWebHistoryItem. -**** - -[[GtkWidgets]] -== 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 -link:http://portix.bitbucket.org/dwb/resources/layout.html[]. - -New widgets can be created with -**** -[float] -==== *GtkWidget()* ==== -[source,javascript] ----- -new GtkWidget(String type) ----- - -Constructs a new widget - - :: -_name_;; The type of the widget, e.g. "GtkLabel" -**** - - -All created widgets implement the following methods: - -**** -[float] -==== *destroy()* ==== - -[source,javascript] ----- -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: - -**** -[float] -==== *packEnd()* ==== - -[source,javascript] ----- -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 -**** - -**** -[float] -==== *packStart()* ==== - -[source,javascript] ----- -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 -**** - -**** -[float] -==== *reorderChild()* ==== - -[source,javascript] ----- -void GtkWidget.reorderChild(GtkWidget child, Number position) ----- - -Moves a widget to a new position. - - ;; - -_child_:: The child widget -_position_:: The new position -**** - -Widgets derived from GtkContainer implement the following methods: - -**** -[float] -==== *add()* ==== - -[source,javascript] ----- -void GtkWidget.add(GtkWidget child) ----- - -Adds a widget to a GtkContainer. - - ;; - -_child_:: The child widget -**** - -==== -.Example -[source,javascript] ------- -var label = new GtkWidget("GtkLabel"); -gui.statusBox.packStart(label, false, false, 0); -label.label = "foobar"; -label.visible = true; ------- -==== - - -== Signals == -With the +signals+ object *dwb* communicates with the script on certain events. -To connect to a signal one can call the connect method that is implemented by -the signals object, that takes 2 arguments, the name of the signal and a -callback function. - -The callback function has a varying number of parameters. -The last paramter is always a json-object which might be empty or contain -additional data relevant to the signal. -A callback function should either return +true+ or +false+ or nothing which is -equivalent to +false+. -If multiple callbacks are connected to the same signal and one callback -function returns +true+ the overall return value will be +true+. - -*dwb* only emits signals as long as one callback is connected to a signal. To -reduce overhead one should disconnect from signals when no longer -needed. - -The +signals+ object is not a readonly object, properties can be added to the -object which are visible in all scripts but it should be avoided to add -properties on the +signals+ object. +signals+ should only be used to connect to -signals or define custom signals. - -The +signals+ object implements the following methods - -=== Methods === - -[[connect]] -[float] -==== *connect()* ==== - -**** -[source,javascript] ----- -Number signals.connect(String signal, Function callback) ----- -Connect to a signal - - :: - -_signal_;; The signal to connect to -_callback_;; The callback function which will be called when the signal is emitted -_returns_;; Unique id for this connection, can be passed to <> -**** - -[[connect]] -[float] -==== *connectWebView()* ==== - -**** -[source,javascript] ----- -void signals.connectWebView(String signal, Function callback) ----- -Connect all webviews to a GObject signal - - :: - -_signal_;; The signal to connect to -_callback_;; The callback function which will be called when the signal is -emitted, the arguments of the callback function correspond to the GObject -callback -**** - - -**** -[[emit]] -[float] -==== *emit()* ==== - -[source,javascript] ----- -Boolean signals.emit(String signal, ...) ----- - -Emits a signal with a variable number of arguments passed to the callback -function - - :: - -_signal_;; The signal to emit -_..._;; Objects passed to the callback function -_returns_;; Overall return value from all connected callback functions -**** - -**** -[[disconnect]] -[float] -==== *disconnect()* ==== - -[source,javascript] ----- -void signals.disconnect(Number id|Function callback) ----- - -Disconnect from a signal - - :: - -_id|callback_;; The id returned from <> or the callback function passed -to <>. Note that if the same callback is used more than once -the signal must be disconnected by id, otherwise the behaviour is undefined. -**** - -**** -[[disconnectByName]] -[float] -==== *disconnectByName()* ==== - -[source,javascript] ----- -Boolean signals.disconnectByName(String signal) ----- - -disconnect from all signals with matching name, -It should be avoided to call +disconnectByName+ -on signals implemented by dwb since it will completely stop the emission of the -signal in all scripts. - - :: - -_signal_;; The callback function passed to <> -_returns_;; +true+ if signals were disconnected, +false+ if no signal -was disconnected -**** - -=== Emitted signals === - -Custom signals can be created by simply calling - -[source,javascript] ------ -signals.connect("nameOfNewSignal", callbackFunction); ------ - - - -Signals emitted by dwb are the following: - - -**** -[[buttonPress]] -[float] -==== *buttonPress* ==== - -[source,javascript] ----- -Boolean callback(webview, hittestresult, event) ----- - -Emitted when a button is pressed on the <>, return +true+ to prevent -the default action - - :: - -_webview_;; The <> 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 <> -_event.time_;; The time in milliseconds when the button was pressed -_event.type_;; A <> -_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]] -[float] -==== *buttonRelease* ==== - -[source,javascript] ----- -Boolean callback(webview, hittestresult, event) ----- - -Emitted when a button is released, return +true+ to prevent the default action - - :: - -_webview_;; The <> which received the signal -_hittestresult_;; Hittestresult under the cursor -_event_;; Same as <> but without _event.type_ -**** - -**** -[[changeMode]] -[float] -==== *changeMode* ==== - -[source,javascript] ----- -Boolean callback(webview, mode) ----- - -Emitted when the mode changes, return true to prevent the change. - - :: - -_webview_;; The focused webview -_mode_;; A mode, see also <> for possible modes -**** - -**** -[[close]] -[float] -==== *close* ==== - -[source,javascript] ----- -Boolean callback() ----- - -Emitted when dwb is closed -**** - -**** -[[createTab]] -[float] -==== *createTab* ==== - -[source,javascript] ----- -Boolean callback(webview) ----- - -Emitted when a tab is created - - :: - -_webview_;; The <> that corresponds to the created tab -**** - -**** -[[closeTab]] -[float] -==== *closeTab* ==== - -[source,javascript] ----- -Boolean callback(webview) ----- - -Emitted when a tab is closed - - :: - -_webview_;; The <> that corresponds to the tab -**** - -**** -[[documentLoaded]] -[float] -==== *documentLoaded* ==== - -[source,javascript] ----- -void callback(webview, frame) ----- - -Emitted when a the dom document of an frame has loaded. - - :: - -_webview_;; The <> that emitted the signal -_frame_;; The frame that contains the document -**** - -**** -[[download]] -[float] -==== *download* ==== - -[source,javascript] ----- -Boolean callback(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 <> that emitted the signal -_download_;; The <> -_json.referer_;; The referer -_json.mimeType_;; The mimetype of the file -**** - -**** -[[downloadStart]] -[float] -==== *downloadStart* ==== - -[source,javascript] ----- -Boolean callback(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 <> -_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]] -[float] -==== *downloadStatus* ==== - -[source,javascript] ----- -Boolean callback(download) ----- - -Emitted when the <> changes. - - :: - -_download_;; The <> -**** - -**** -[[executeCommand]] -[float] -==== *executeCommand* ==== - -[source,javascript] ----- -Boolean callback(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]] -[float] -==== *frameCreated* ==== - -[source,javascript] ----- -void callback(webview, frame) ----- - -Emitted when the frame is created - - :: - -_webview_;; The webview the frame belongs to -_frame_;; The frame -**** - -**** -[[frameStatus]] -[float] -==== *frameStatus* ==== - -[source,javascript] ----- -void callback(webview, frame) ----- - -Emitted when the <> of a frame changes - - :: - -_webview_;; The webview the frame belongs to -_frame_;; The frame -**** - -**** -[[keyPress]] -[float] -==== *keyPress* ==== - -[source,javascript] ----- -Boolean callback(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 <> -**** - -**** -[[keyRelease]] -[float] -==== *keyRelease* ==== - -[source,javascript] ----- -Boolean callback(webview, json) ----- - -Emitted when a key is released, return +true+ to prevent the default action - - :: - -_webview_;; The focused webview -_json_;; Same as <> -**** - - -**** -[[loadCommitted]] -[float] -==== *loadCommitted* ==== - -[source,javascript] ----- -void callback(webview) ----- - -Emitted when the load has just 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. - - :: - -_webview_;; The webview that emitted the signal -**** - -**** -[[loadFinished]] -[float] -==== *loadFinished* ==== - -[source,javascript] ----- -Boolean callback(webview) ----- - -Emitted when the site has completely loaded. - - :: - -_webview_;; The webview that emitted the signal -**** - -**** -[[loadStatus]] -[float] -==== *loadStatus* ==== - -[source,javascript] ----- -void callback(webview) ----- - -Emitted when the load status changes - - :: - -_webview_;; The webview that emitted the signal -**** - -**** -[[mimeType]] -[float] -==== *mimeType* ==== - -[source,javascript] ----- -Boolean callback(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]] -[float] -==== *mouseMove* ==== - -[source,javascript] ----- -Boolean callback(webview, event) ----- - -Emitted when the pointer is moved. - - :: - -_webview_;; The webview that emitted the signal -_event_;; Same as <> -**** - -**** -[[navigation]] -[float] -==== *navigation* ==== - -[source,javascript] ----- -Boolean callback(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]] -[float] -==== *resource* ==== - -[source,javascript] ----- -Boolean callback(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]] -[float] -==== *statusBarChange* ==== - -[source,javascript] ----- -Boolean callback(webview, json) ----- - -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]] -[float] -==== *tabButtonPress* ==== - -[source,javascript] ----- -Boolean callback(webview, tabwidget, event) ----- - -Emitted when a button is pressed on a tabwidget, return true to prevent the default action - - :: - -_webview_;; The <> which received the signal -_tabwidget_;; The tabwidget -_event_;; Same as buttonPress -**** - - -**** -[[tabFocus]] -[float] -==== *tabFocus* ==== - -[source,javascript] ----- -Boolean callback(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 -**** - - - -==== -.Example -[source,javascript] ------- -// Prevent example.com from being loaded -function navigationCallback(wv, frame, request, action) { - if (/.*\.example\.com.*/.test(request.uri)) { - return true; - } -} -signals.connect("navigation", navigationCallback); ------- -==== - -== Enum objects == -Enum objects are objects that have only readonly properties, mapping -gtk/webkit enums to javascript objects. - -**** -[[ButtonContext]] -[float] -==== *ButtonContext* ==== - -[source,javascript] --------- -const ButtonContext = { - document : 1 << 1, - link : 1 << 2, - image : 1 << 3, - media : 1 << 4, - selection : 1 << 5, - editable : 1 << 6 -}; --------- -**** - -**** -[[ChecksumType]] -[float] -==== *ChecksumType* ==== - -[source,javascript] --------- -const ChecksumType = { - md5 : 0, - sha1 : 1, - sha256 : 2 -}; --------- -**** - -**** -[[ClickType]] -[float] -==== *ClickType* ==== - -[source,javascript] --------- -const ClickType = { - click : 4, - doubleClick : 5, - tripleClick : 6 -}; --------- -**** - -**** -[[DownloadStatus]] -[float] -==== *DownloadStatus* ==== - -[source,javascript] -------- -const DownloadStatus = { - error : -1, - created : 0, - started : 1, - cancelled : 2, - finished : 3 -}; -------- -**** - -**** -[[FileTest]] -[float] -==== *FileTest* ==== - -[source,javascript] -------- -const FileTest = { - regular : 1 << 0, - symlink : 1 << 1, - dir : 1 << 2, - executable : 1 << 3, - exists : 1 << 4 -}; -------- -**** - -**** -[[LoadStatus]] -[float] -==== *LoadStatus* ==== - -[source,javascript] ---------- -const LoadStatus = { - provisional : 0, - committed : 1, - finished : 2, - firstVisualLayout : 3, - failed : 4 -}; ---------- -**** - -**** -[[Modifier]] -[float] -==== *Modifier* ==== - -[source,javascript] --------- -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]] -[float] -==== *NavigationReason* ==== - -[source,javascript] --------- -const NavigationReason = { - linkClicked : 0, - formSubmitted : 1, - backForward : 2, - reload : 3, - formResubmitted : 4, - other : 5 -}; --------- -**** - -**** -[[Modes]] -[float] -==== *Modes* ==== -[source,javascript] --------- -const Modes = { - NormalMode : 1<<0, - InsertMode : 1<<1, - CommandMode : 1<<2 -}; --------- -**** - -**** -[[Selection]] -[float] -==== *Selection* ==== -[source,javascript] --------- -const Selection = { - primary : 1, - clipboard : 2 -}; --------- -**** - - -[[Globaldata]] -== Global data == -Since all scripts share the same execution context, every script is encapsulated -in a function. To avoid conflicts between scripts, e.g. with duplicate -variables, it is not allowed to set properties on the global object: - -[source,javascript] -------- -#!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. - -[[scriptandthis]] -=== script and this === -In every script the variable *script* refers to *this*, the encapsulating -function, it has the following properties and methods: - - -**** -[float] -==== *path* ==== - -[source,javascript] ----- -script.path string read ----- - -The path of the script. -**** - -**** -[float] -==== *_arguments* ==== - -[source,javascript] ----- -script._arguments string read ----- - -*arguments* object of the encapsulating function -**** - -**** -[[thisdebug]] -[float] -==== *debug()* ==== - -[source,javascript] ----- -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. -**** - -**** -[[generateId]] -[float] -==== *generateId()* ==== - -[source,javascript] ----- -String script.generateId() ----- - -Generates a unique id. - - :: - -_returns_;; A unique id. -**** - -**** -[[getPrivate]] -[float] -==== *getPrivate()* ==== - -[source,javascript] ----- -Object script.getPrivate(Object object, String key, Object value) ----- - -Gets a private property of an object previously set with -<>. - - :: - -_object_;; The object on which the value was set. -_key_;; The property name -_returns_;; The private value -**** - - -**** -[[setPrivate]] -[float] -==== *setPrivate()* ==== - -[source,javascript] ----- -void script.setPrivate(Object object, String key, Object 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 only be retrieved with -<>. -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. -**** - - -.Example -**** -[source,javascript] -------- -#!javascript - -try -{ - var x = {}; - var y = x.foo.bar; - var z = 33; -} -catch(e) -{ - script.debug(e); -} -------- - -Will produce the following output: - ------- -==> DEBUG [IN FILE] : /path/to/userscript -==> DEBUG [ERROR] : Exception in line 6: 'undefined' is not an object - (evaluating 'x.foo.bar') -==> DEBUG [STACK] : [anonymous] [[native code]] -==> DEBUG [SOURCE] : - ... - 5 > var x = {}; ---> 6 > var y = x.foo.bar; - 7 > var z = 33; - ... ------- - -Setting/getting private values: - -[source,javascript] ------------- -var self = this; -signals.connect("loadCommitted", function(wv) { - script.setPrivate(wv, "foo", "bar"); -}); -signals.connect("loadFinished", function(wv) { - io.print(script.getPrivate(wv, "foo")); -}); ------------- - -**** - - -[[Modules]] -== Modules == - -With modules it is possible to share objects between scripts. Modules are -defined with +provide+ and loaded with +require+. - -.Defining modules -[source,javascript] -------- -#!javascript - -provide("myModule", { - foo : 37, - doBar : function() { - io.print("bar"); - } -}); -provide("myOtherModule", { - act : function (arg) { - io.print(arg); - } -}); -------- - -.Getting some modules -[source,javascript] -------- -#!javascript - -require(["myModule", "myOtherModule"], function(myModule, myOtherModule) { - if (myModule.foo == 37) - myModule.doBar(); - - myOtherModule.act("foo"); -}); -------- - -.Getting all modules -[source,javascript] -------- -#!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+: - -[source,javascript] -------- -#!javascript - -require(["foo!/path/to/foo"], function(foo) { - io.print(foo.bar); // 37 -}); -------- - -./path/to/foo -[source,javascript] -------- -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: - -[source,javascript] -------- -#!javascript - -require(["foo!/path/to/foo"], function(foo) { - io.print(foo.bar); // 42 -}); -provide("foo", { bar : 42 }); -------- - -[source,javascript] -------- -#!javascript - -require(["foo"], function(foo) { - io.print(foo); // undefined -}); -require(["foo!/path/to/foo"]); - -require(["foo"], function(foo) { - io.print(foo); // { bar : 37 } -}); -------- - - -[[Extensions]] -== 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. - -=== 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 --batch --no-tty --yes -c --output - default value: *""* -_GPGOptDecrypt_;; Additional options that will be passed to gpg2 for - decryption, the default gpg2 options are - --passphrase --batch --no-tty --yes -d - 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 - -[source,javascript] ----- -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//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 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 - -[source,javascript] ----- -extensions.load("userscripts", [ "/path/to/script1", "/path/to/script2" ]); ----- - - -=== Using extensions - -Extensions can be loaded by an userscript - -[source,javascript] ------- -#!javascript - -extensions.load("extension_1"); -extensions.load("extension_2", { - configProp_1 : 37, - configProp_2 : "val2" -}); ------- - -To load/unload extensions on the fly *extensions.bind* can be used: - -[source,javascript] ------- -#!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/+. - -The +extensions+ object has the following functions - -=== Methods === - -**** -[[extensionsbind,bind]] -[float] -==== *bind()* ==== - -[source,javascript] ----- -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 commandline -**** - -**** -[[extensiondisableAll,disableAll]] -[float] -==== *disableAll()* ==== - -[source,javascript] ----- -void extensions.disableAll() ----- - -Disables all extensions. -**** - -**** -[[extensionsGetConfig,getConfig]] -[float] -==== *getConfig* ==== - -[source,javascript] ----- -Object extensions.getConfig(Object config, Object defaultConfig) ----- -Parses config with given default config. Checks for each property of -defaultConfig if the corresponding property of config is valid. - -_config_;; The configuration object -_defaultConfig_;; The default configuration for the extension -_returns_;; The parsed config -**** - -**** -[[extensionload,load]] -[float] -==== *load()* ==== - -[source,javascript] ----- -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 -**** - -**** -[[extensiontoggle,toggle]] -[float] -==== *toggle()* ==== - -[source,javascript] ----- -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. -**** - -**** -[[extensionload,unload]] -[float] -==== *unload()* ==== - -[source,javascript] ----- -Boolean extensions.unload(String name) ----- -Unloads an extension - - :: - -_name_;; Name of the extension -_returns_;; True if the extension was unloaded -**** - -**** -[[error]] -[float] -==== *error()* ==== - -[source,javascript] ----- -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. -**** - -**** -[[message]] -[float] -==== *message()* ==== - -[source,javascript] ----- -void extensions.message(String name, String message) ----- - -Print a consistent message to stderr - - :: - -_name_;; Name of the extension -_message_;; The message -**** - - -**** -[[warning]] -[float] -==== *warning()* ==== - -[source,javascript] ----- -void extensions.warning(String name, String message) ----- - -Print a consistent warning to stderr - - :: - -_name_;; Name of the extension -_message_;; The warning message -**** - - -.Example - -[source,javascript] --------- -#!javascript - -extensions.load("foobar"); --------- - -=== Writing extensions - -The default searchpath for extensions isn +$XDG_DATA_HOME/dwb/extensions+ and -+SHARE_DIR/dwb/extensions+ where the -+SHARE_DIR+ with sharedirectory 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 an +defaultConfig+-property, the -value will be passed to extensions.getConfig before calling the init function. - -.Example - -A extension called *foobar* in +$HOME/.local/share/dwb/extensions/foobar+. - -[source,javascript] --------- -function foo(val) { - .... -} -function bar(val) { - .... -} -function loadStatusCallback(w) { - ... -} -return { - defaultConfig : { foo : 37 }, - - init : function (config) { - if (config.foo > 36) { - bar(config.foo); - foo(config.bar); - bind("XX", bar, "dobar"); - signals.connect("loadStatus", loadStatusCallback); - return true; - } - - return false; - }, - - end : function () { - unbind(bar); - signals.disconnect(loadStatusCallback); - return true; - } -}; --------- - -==== -.Example extensionrc -[source,javascript] --------- -return { - foobar : { bar : "X", foo : 37 }, // config for extension foobar - barfoo : { } // config for extension barfoo - -}; --------- -==== - -Extensions that provide a public api can use provide or replace using the name of the extension. - -==== -[source,javascript] --------- -var myPublicFunction = function() -{ - ... -}; - -return { - init : function(config) - { - provide("myExtensionName", - { - config : config, - method : myPublicFunction - }); - }, - end : function() - { - replace("myExtensionName"); - } -}; --------- -==== - -== Snippets == - -Some example snippets can be found link:../snippets/snippets.html[here]. - - -// vim: set ft=asciidoc: -- cgit v1.2.3