diff options
| -rw-r--r-- | api/Makefile | 10 | ||||
| -rw-r--r-- | api/dwb-js.7 | 196 | ||||
| -rw-r--r-- | api/jsapi.7.txt | 191 | ||||
| -rw-r--r-- | api/jsapi.txt | 119 | ||||
| -rw-r--r-- | scripts/lib/extensions.js | 14 | ||||
| -rw-r--r-- | src/scripts.c | 2 |
6 files changed, 346 insertions, 186 deletions
diff --git a/api/Makefile b/api/Makefile index 535afd94..1de004e8 100644 --- a/api/Makefile +++ b/api/Makefile @@ -1,11 +1,11 @@ +all: web man + web: jsapi.html -man: dwbscript.7 +man: dwb-js.7 jsapi.html: jsapi.txt - @echo gen $@ - @asciidoc -b html5 -a toc2 $< + asciidoc -b html5 -a toc2 $< dwb-js.7: jsapi.7.txt - @echo gen $@ - @a2x --doctype manpage --format manpage $< + a2x --doctype manpage --format manpage $< diff --git a/api/dwb-js.7 b/api/dwb-js.7 index 817e8e74..6f1d681c 100644 --- a/api/dwb-js.7 +++ b/api/dwb-js.7 @@ -128,7 +128,15 @@ a dwb command to execute, will be parsed the same way as if executed from comman .RS 4 true if execution was successful .RE +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 \fBBoolean exit()\fR +.RS 4 .sp Exit dwb, must be called if the script is running from commandline\&. .RE @@ -253,7 +261,7 @@ Object that contains the response body, the response headers and the http status .nr an-break-flag 1 .br .ps +1 -\fBvoid tabComplete(String label, Array items, Function callback)\fR +\fBvoid tabComplete(String label, Array items, Function callback, [Boolean readonly])\fR .RS 4 .sp Initiates tab completion\&. @@ -272,6 +280,11 @@ An array of objects, each object can have 2 properties, left which will be the l .RS 4 Callback function, the first argument will be the returned string from the url bar\&. .RE +.PP +\fIreadonly\fR +.RS 4 +Whether the items are readonly, default false, optional\&. +.RE .RE .sp .it 1 an-trap @@ -429,7 +442,7 @@ Searchengines .RE .SS "io" .sp -The io object implements Methods for input and output\&. +The io object implements methods for input and output\&. .sp .it 1 an-trap .nr an-no-space-flag 1 @@ -605,7 +618,7 @@ true if writing was successful .RE .SS "system" .sp -The system object implements system Methods\&. +The system object implements system methods\&. .sp .it 1 an-trap .nr an-no-space-flag 1 @@ -733,7 +746,7 @@ An object that contains stdout, stderr and status\&. .RE .SS "tabs" .sp -The tabs object implements Methods and properties to get webview objects\&. +The tabs object implements methods and properties to get webview objects\&. .PP \fItabs\&.current (webview, read)\fR .RS 4 @@ -772,7 +785,7 @@ The corresponding webview .RE .SS "util" .sp -The util object implements helper Methods\&. +The util object implements helper methods\&. .sp .it 1 an-trap .nr an-no-space-flag 1 @@ -845,7 +858,7 @@ The property value .PP \fIthis\fR .RS 4 -The object the forEach is called on +The object forEach is called on .RE .RE .sp @@ -854,14 +867,14 @@ The object the forEach is called on .nr an-break-flag 1 .br .ps +1 -\fBNumber Array.fastIndexOf(Object value))\fR +\fBNumber Array.fastIndexOf(Object object)\fR .RS 4 .sp This method is basically the same as Array\&.indexOf but without type checking\&. .PP -\fIvalue\fR +\fIobject\fR .RS 4 -The value to search for +The object to search for .RE .PP \fIreturns\fR @@ -994,7 +1007,7 @@ The return value of the script\&. If the script is injected globally inject alwa .ps -1 .br .sp -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\(cqt been created, if the script modifies the DOM it should be injected on LoadStatus\&.finished of using the documentLoaded signal\&. If only LoadStatus\&.committed or loadFinished\&.committed are used it is better to use the corresponding signals instead to reduce overhead\&. +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\(cqt 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\&. .sp .5v .RE .RE @@ -1032,16 +1045,12 @@ The uri to load .PP \fIcallback\fR .RS 4 -A callback function that will be called when the load status changes, return -true -to stop the emission, optional +A callback function that will be called when the load status changes, return true to stop the emission, optional .RE .PP \fIreturns\fR .RS 4 - -true -if the uri is loaded +true if the uri is loaded .RE .RE .sp @@ -1077,7 +1086,7 @@ The host name of the frame \fBBoolean frame.inject(String script, [Boolean global])\fR .RS 4 .sp -Injects a script into a frame, also see webview\&.inject for details\&. +Injects a script into a frame, see also webview\&.inject for details\&. .RE .SS "download" .sp @@ -1125,12 +1134,6 @@ A callback function that will be executed whenever the DownloadStatus changes, r .sp Cancels a download .RE -.SS "request" -.sp -Corresponds to a WebKitNavigationRequest\&. -.SS "navigationAction" -.sp -Corresponds to a WebKitWebNavigationAction\&. .SH "SIGNALS" .sp With the signals object \fBdwb\fR communicates with the script on certain events\&. To connect to a signal one can call the connect function that is implemented by the signals object, that takes 2 arguments, the name of the signal and a callback function\&. @@ -1141,7 +1144,7 @@ The callback function has a varying number of parameters\&. The last paramter is .sp 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\&. .sp -The signals object implements the following Methods +The signals object implements the following methods .SS "Methods" .sp .it 1 an-trap @@ -1213,11 +1216,7 @@ The id returned from connect .PP \fIreturns\fR .RS 4 - -true -if the signal was disconnected, -false -if the signal wasn\(cqt found or was already disconnected\&. +true if the signal was disconnected, false if the signal wasn\(cqt found or was already disconnected\&. .RE .RE .sp @@ -1238,11 +1237,7 @@ The callback function passed to connect .PP \fIreturns\fR .RS 4 - -true -if signals were disconnected, -false -if no signal was disconnected +true if signals were disconnected, false if no signal was disconnected .RE .RE .sp @@ -1263,11 +1258,7 @@ The callback function passed to connect .PP \fIreturns\fR .RS 4 - -true -if signals were disconnected, -false -if no signal was disconnected +true if signals were disconnected, false if no signal was disconnected .RE .RE .SS "Emitted signals" @@ -1406,7 +1397,7 @@ Same as buttonPress but without .RS 4 .\} .nf -Boolean signals\&.connect("close", function()); +signals\&.connect("close", function()); .fi .if n \{\ .RE @@ -1485,7 +1476,7 @@ signals\&.connect("documentLoaded", function(webview, frame)); .RE .\} .sp -Emitted when a the dom document of an frame has loaded\&. +Emitted when a the DOM document of a frame has been loaded\&. .PP \fIwebview\fR .RS 4 @@ -1629,7 +1620,7 @@ signals\&.connect("frameCreated", function(webview, frame)); .RE .\} .sp -Emitted when the frame is created +Emitted when a frame is created .PP \fIwebview\fR .RS 4 @@ -1700,16 +1691,12 @@ The webview that emitted the signal .PP \fIjson\&.uri\fR .RS 4 -The uri of the link or -null -if there is no link under the pointer, i\&.e\&. the pointer left a link +The uri of the link or null if there is no link under the pointer, i\&.e\&. the pointer left a link .RE .PP \fIjson\&.title\fR .RS 4 -The link\(cqs title or -null -if the pointer left a link +The link\(cqs title or null if the pointer left a link .RE .RE .sp @@ -2029,7 +2016,7 @@ The number of the previously focused tab .SH "ENUM OBJECTS" .sp Enum objects are objects that have only readonly properties, mapping gtk/webkit enums to javascript objects\&. -\fBButtonContext\fR +.SS "ButtonContext" .sp .if n \{\ .RS 4 @@ -2047,7 +2034,7 @@ const ButtonContext = { .if n \{\ .RE .\} -\fBChecksumType\fR +.SS "ChecksumType" .sp .if n \{\ .RS 4 @@ -2062,7 +2049,7 @@ const ChecksumType = { .if n \{\ .RE .\} -\fBClickType\fR +.SS "ClickType" .sp .if n \{\ .RS 4 @@ -2077,7 +2064,7 @@ const ClickType = { .if n \{\ .RE .\} -\fBDownloadStatus\fR +.SS "DownloadStatus" .sp .if n \{\ .RS 4 @@ -2094,7 +2081,7 @@ const DownloadStatus = { .if n \{\ .RE .\} -\fBFileTest\fR +.SS "FileTest" .sp .if n \{\ .RS 4 @@ -2111,7 +2098,7 @@ const FileTest = { .if n \{\ .RE .\} -\fBLoadStatus\fR +.SS "LoadStatus" .sp .if n \{\ .RS 4 @@ -2128,7 +2115,7 @@ const LoadStatus = { .if n \{\ .RE .\} -\fBModifier\fR +.SS "Modifier" .sp .if n \{\ .RS 4 @@ -2158,7 +2145,7 @@ const Modifier = { .if n \{\ .RE .\} -\fBNavigationReason\fR +.SS "NavigationReason" .sp .if n \{\ .RS 4 @@ -2176,7 +2163,7 @@ const NavigationReason = { .if n \{\ .RE .\} -\fBSpawnError\fR +.SS "SpawnError" .sp .if n \{\ .RS 4 @@ -2264,7 +2251,7 @@ return { .sp One exception is include, scripts that are explicitly included into the global scope setting the second parameter to true are visible in every script\&. .PP -\fBfoo\fR. +\fBScript foo\fR. .sp .if n \{\ .RS 4 @@ -2312,6 +2299,54 @@ return { .SH "EXTENSIONS" .sp \fBdwb\fR 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\&. +.SS "Using extensions" +.sp +Extensions can be loaded by an userscript +.sp +.if n \{\ +.RS 4 +.\} +.nf +#!javascript + +extensions\&.load("extension_1"); +extensions\&.load("extension_2", { + configProp_1 : 22, + configProp_2 : "val2" +}); +.fi +.if n \{\ +.RE +.\} +.sp +To load/unload extensions on the fly \fBextensions\&.bind\fR can be used: +.sp +.if n \{\ +.RS 4 +.\} +.nf +#!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"); +.fi +.if n \{\ +.RE +.\} +.sp +The default searchpaths for extensions are $XDG_DATA_HOME/dwb/extensions/ and /usr/share/dwb/extensions/\&. .SS "Properties" .PP \fIextensions\&.enableDebugging (Boolean, read, write)\fR @@ -2325,6 +2360,47 @@ Whether to enable debugging messages\&. .nr an-break-flag 1 .br .ps +1 +\fBvoid extensions.bind(String name, String shortcut, [Object options])\fR +.RS 4 +.sp +Bind an extension to a shortcut, the shortcut enables/disables the extension\&. +.PP +\fIname\fR +.RS 4 +Name of the extension +.RE +.PP +\fIshortcut\fR +.RS 4 +Name of the extension +.RE +.PP +\fIoptions\fR +.RS 4 +An optional object with options where possible options are +.PP +options\&.load +.RS 4 +Whether to load the extension on startup, default true +.RE +.PP +options\&.config +.RS 4 +Config passed to extensions\&.load +.RE +.PP +options\&.command +.RS 4 +Command that can be used on command line +.RE +.RE +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 \fBvoid extensions.debug(String name, String message)\fR .RS 4 .sp @@ -2511,7 +2587,7 @@ The warning message .sp The default searchpath for extensions is \fB$XDG_DATA_HOME/dwb/extensions\fR and \fBSHARE_DIR/dwb/extensions\fR where SHARE_DIR being the share directory of the installation, most likely /usr/share\&. .sp -The configuration for extensions is in $$XDG_CONFIG_HOME/dwb/extensionsrc$ and should return a javascript object\&. +The configuration for extensions is in \fB$XDG_CONFIG_HOME/dwb/extensionrc\fR and should return a javascript object\&. .sp 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\&. .sp @@ -2523,7 +2599,7 @@ Every extension must implement one function named init that takes one argument, \fBExample\fR .RS 4 .sp -A extension called \fBfoobar\fR in \fB$HOME/\&.local/share/dwb/extensions/foobar\fR\&. +A extension called \fBfoobar\fR in \fB$HOME/\&.local/share/dwb/extensions/foobar\fR: .sp .if n \{\ .RS 4 diff --git a/api/jsapi.7.txt b/api/jsapi.7.txt index c550c033..ca0aa6fc 100644 --- a/api/jsapi.7.txt +++ b/api/jsapi.7.txt @@ -58,8 +58,8 @@ _returns_;; true if the function was binded successfully **** ==== Boolean execute(String command) -**** +**** Executes a dwb command _command_;; a dwb command to execute, will be parsed the same way as if executed @@ -67,7 +67,7 @@ from commandline _returns_;; true if execution was successful **** -.Boolean exit() +==== Boolean exit() **** Exit dwb, must be called if the script is running from commandline. @@ -91,7 +91,6 @@ invisible, even in the including script. To use an included script it can return an object with its public objects: ====== -[source,javascript] --------------------------------- // included script @@ -133,7 +132,7 @@ the http status code of the request. **** -==== void tabComplete(String label, Array items, Function callback) +==== void tabComplete(String label, Array items, Function callback, [Boolean readonly]) **** Initiates tab completion. @@ -144,6 +143,7 @@ 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. **** ==== Number timerStart(Number interval, Function func) @@ -176,7 +176,6 @@ _returns_;; true if the function is unbinded **** - == Global Objects == === data === @@ -204,7 +203,7 @@ _data.searchEngines_;; Searchengines === io === -The io object implements Methods for input and output. +The io object implements methods for input and output. ==== void io.debug(String message | Error error, [Error error]) **** @@ -285,7 +284,7 @@ _returns_;; true if writing was successful === system === -The system object implements system Methods. +The system object implements system methods. ==== Boolean system.fileTest(String path, FileTest flags) **** @@ -338,7 +337,7 @@ _returns_;; An object that contains stdout, stderr and status. **** === tabs === -The tabs object implements Methods and properties to get webview objects. +The tabs object implements methods and properties to get webview objects. _tabs.current (webview, read)_;; The currently focused webview @@ -358,7 +357,7 @@ _returns_;; The corresponding webview === util === -The util object implements helper Methods. +The util object implements helper methods. ==== String util.getBody(Function func) **** @@ -392,15 +391,15 @@ Array.forEach. _func_;; The function to execute _key_;; The property name _value_;; The property value -_this_;; The object the forEach is called on +_this_;; The object forEach is called on **** -==== Number Array.fastIndexOf(Object value)) +==== Number Array.fastIndexOf(Object object) **** This method is basically the same as Array.indexOf but without type checking. -_value_;; The value to search for +_object_;; The object to search for _returns_;; The index in the array or -1 if the Object wasn't found. **** @@ -445,7 +444,7 @@ _returns_;; true if the signal was disconnected **** === webview === -The +webview+ object represents the widget that actually displays the site +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 @@ -469,8 +468,8 @@ 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 on -LoadStatus.finished of using the documentLoaded signal. +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. **** @@ -490,8 +489,8 @@ Load 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 +changes, return true to stop the emission, optional +_returns_;; true if the uri is loaded **** @@ -503,9 +502,9 @@ Reload a webview === frame === -A frame represents a +frame+ or +iframe+. Due to same origin policy it +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. +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 @@ -514,13 +513,13 @@ _frame.host (String, read)_;; The host name of the frame ==== Boolean frame.inject(String script, [Boolean global]) **** -Injects a script into a frame, also see webview.inject for details. +Injects a script into a frame, see also webview.inject for details. **** === download === -Corresponds to a +WebKitDownload+. +Corresponds to a WebKitDownload. ==== new Download(String uri) @@ -547,14 +546,6 @@ DownloadStatus changes, return true to stop the emission, optional. Cancels a download **** -=== request === - -Corresponds to a WebKitNavigationRequest. - -=== navigationAction === - -Corresponds to a WebKitWebNavigationAction. - == Signals == With the signals object *dwb* communicates with the script on certain events. To connect to a signal one can call the connect function that is implemented by @@ -578,7 +569,7 @@ 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 +The signals object implements the following methods === Methods === @@ -607,7 +598,7 @@ _returns_;; Overall return value from all connected callback functions disconnect from a signal _id_;; The id returned from connect -_returns_;; +true+ if the signal was disconnected, +false+ if the signal +_returns_;; true if the signal was disconnected, false if the signal wasn't found or was already disconnected. **** @@ -617,7 +608,7 @@ wasn't found or was already disconnected. disconnect from all signals with matching callback function _callback_;; The callback function passed to connect -_returns_;; +true+ if signals were disconnected, +false+ if no signal +_returns_;; true if signals were disconnected, false if no signal was disconnected **** @@ -625,12 +616,12 @@ was disconnected **** disconnect from all signals with matching name, -It should be avoided to call +disconnectByName+ +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 connect -_returns_;; +true+ if signals were disconnected, +false+ if no signal +_returns_;; true if signals were disconnected, false if no signal was disconnected **** @@ -654,7 +645,7 @@ Signals emitted by dwb are the following: signals.connect("buttonPress", function(webview, hittestresult, json)); ---- -Emitted when a button is pressed on the webview, return +true+ to prevent +Emitted when a button is pressed on the webview, return true to prevent the default action _webview_;; The webview which received the signal @@ -676,7 +667,7 @@ _json.yRoot_;; y-position relative to the screen signals.connect("buttonRelease", function(webview, hittestresult, json)); ---- -Emitted when a button is released, return +true+ to prevent the default action +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 @@ -687,7 +678,7 @@ _json_;; Same as buttonPress but without _json.type_ **** ---- -Boolean signals.connect("close", function()); +signals.connect("close", function()); ---- Emitted when dwb is closed @@ -722,7 +713,7 @@ _webview_;; The webview that corresponds to the tab signals.connect("documentLoaded", function(webview, frame)); ---- -Emitted when a the dom document of an frame has loaded. +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 @@ -779,7 +770,7 @@ _download_;; The Download signals.connect("frameCreated", function(webview, frame)); ---- -Emitted when the frame is created +Emitted when a frame is created _webview_;; The webview the frame belongs to _frame_;; The frame @@ -807,8 +798,8 @@ signals.connect("hoveringOverLink", function(webview, json)); Emitted when the mouse is over a link _webview_;; The webview that emitted the signal -_json.uri_;; The uri of the link or +null+ if there is no link under the pointer, i.e. the pointer left a link -_json.title_;; The link's title or +null+ if the pointer left a link +_json.uri_;; The uri of the link or null if there is no link under the pointer, i.e. the pointer left a link +_json.title_;; The link's title or null if the pointer left a link **** ==== keyPress @@ -817,7 +808,7 @@ _json.title_;; The link's title or +null+ if the pointer left a link signals.connect("keyPress", function(webview, json)); ---- -Emitted when a key is pressed, return +true+ to prevent the default action +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 @@ -833,7 +824,7 @@ _json.state_;; A bitmap of modifiers pressed, see Modifier signals.connect("keyRelease", function(webview, json)); ---- -Emitted when a key is released, return +true+ to prevent the default action +Emitted when a key is released, return true to prevent the default action _webview_;; The focused webview _json_;; Same as keyPress @@ -881,7 +872,7 @@ _webview_;; The webview that emitted the signal signals.connect("mimeType", function(webview, frame, request, json)); ---- -Decide whether or not to show a given mimetype. Return +true+ to stop the request. +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 @@ -923,7 +914,7 @@ _response_;; The network response signals.connect("tabFocus", function(webview, json)); ---- -Emitted when another tab gets focus, return +true+ to stop the event +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 @@ -934,11 +925,8 @@ _json.last_;; The number of the previously focused tab 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, @@ -951,11 +939,9 @@ const ButtonContext = { -------- **** -**** -[float] -==== *ChecksumType* ==== +=== ChecksumType -[source,javascript] +**** -------- const ChecksumType = { md5 : 0, @@ -965,11 +951,9 @@ const ChecksumType = { -------- **** +=== ClickType **** -[float] -==== *ClickType* ==== -[source,javascript] -------- const ClickType = { click : 4, @@ -979,9 +963,8 @@ const ClickType = { -------- **** +=== DownloadStatus **** -[float] -==== *DownloadStatus* ==== [source,javascript] ------- @@ -995,9 +978,8 @@ const DownloadStatus = { ------- **** +=== FileTest **** -[float] -==== *FileTest* ==== [source,javascript] ------- @@ -1011,11 +993,9 @@ const FileTest = { ------- **** -**** -[float] -==== *LoadStatus* ==== +=== LoadStatus -[source,javascript] +**** --------- const LoadStatus = { provisional : 0, @@ -1027,11 +1007,9 @@ const LoadStatus = { --------- **** -**** -[float] -==== *Modifier* ==== +=== Modifier -[source,javascript] +**** -------- const Modifier = { Shift : 1 << 0, @@ -1056,11 +1034,9 @@ const Modifier = { -------- **** -**** -[float] -==== *NavigationReason* ==== +=== NavigationReason -[source,javascript] +**** -------- const NavigationReason = { linkClicked : 0, @@ -1073,10 +1049,9 @@ const NavigationReason = { -------- **** +=== SpawnError + **** -[float] -==== *SpawnError* ==== -[source,javascript] -------- const SpawnError = { success : 0, @@ -1113,13 +1088,12 @@ io.print(bar); // undefined ------- For sharing data between scripts either signals can be created or the -+globals+-object can be used. To share data with the globals object securely when the -scripts are loaded the script can return an +init+ function that will be called +globals-object can be used. To share data with the globals object securely when the +scripts are loaded the script can return an init function that will be called after all scripts have been initialized: .Script 1 -[source,javascript] ------- #!javascript @@ -1128,7 +1102,6 @@ globals.foo = "bar"; ------- .Script 2 -[source,javascript] ------- #!javascript @@ -1148,15 +1121,13 @@ return { One exception is include, scripts that are explicitly included into the global scope setting the second parameter to true are visible in every script. -.foo -[source,javascript] +.Script foo ------- var foo = "bar"; ------- .Script 1 -[source,javascript] ------- #!javascript @@ -1164,7 +1135,6 @@ include("/path/to/foo", true); // visible in every script ------- .Script 2 -[source,javascript] ------- #!javascript @@ -1182,12 +1152,63 @@ 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. +=== 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/. + === Properties _extensions.enableDebugging (Boolean, read, write)_;; Whether to enable debugging messages. === 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.debug(String name, String message) **** Prints a debug message and the call stack to stdout, enableDebugging must be @@ -1272,7 +1293,7 @@ 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/extensionsrc$ and should +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 @@ -1286,7 +1307,7 @@ init and end should be returned from the extension. ==== Example -A extension called *foobar* in *$HOME/.local/share/dwb/extensions/foobar*. +A extension called *foobar* in *$HOME/.local/share/dwb/extensions/foobar*: [source,javascript] -------- diff --git a/api/jsapi.txt b/api/jsapi.txt index 5ecc9e92..bbbc8718 100644 --- a/api/jsapi.txt +++ b/api/jsapi.txt @@ -35,9 +35,9 @@ properties on the global object, see also <<Globaldata,global data>> for details == Global == -Functions from the global object. +methods from the global object. -=== Functions === +=== Methods === **** @@ -167,7 +167,7 @@ the request. [source,javascript] ---- -void tabComplete(String label, Array items, Function callback) +void tabComplete(String label, Array items, Function callback, [Boolean readonly]) ---- Initiates tab completion. @@ -180,6 +180,7 @@ 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. **** **** @@ -316,7 +317,7 @@ var bookmarks = io.read(data.bookmarks); [[io]] === io === -The +io+ object implements functions for input and output. +The +io+ object implements methods for input and output. **** [[debug]] @@ -480,7 +481,7 @@ io.print(text); [[system]] === system === -The +system+ object implements system functions. +The +system+ object implements system methods. **** [[fileTest]] @@ -595,7 +596,7 @@ asyncread(home + "/.bashrc"); [[tabs]] === tabs === -The +tabs+ object implements functions and properties to get +webview+ objects. +The +tabs+ object implements methods and properties to get +webview+ objects. ==== Properties ==== @@ -638,7 +639,7 @@ Number of the currently focused tab -==== Functions ==== +==== Methods ==== **** [float] @@ -671,7 +672,7 @@ tabs.nth(2).loadUri(c.uri); [[util]] === util === -The +util+ object implements helper functions. +The +util+ object implements helper methods. **** [float] @@ -730,7 +731,7 @@ Array.forEach. _func_;; The function to execute _key_;; The property name _value_;; The property value -_this_;; The object the forEach is called on +_this_;; The object forEach is called on **** **** @@ -739,14 +740,14 @@ _this_;; The object the forEach is called on ==== *Array.fastIndexOf()* ==== [source,javascript] ---- -Number Array.fastIndexOf(Object value)) +Number Array.fastIndexOf(Object object) ---- This method is basically the same as +Array.indexOf+ but without type checking. :: -_value_;; The value to search for +_object_;; The object to search for _returns_;; The index in the array or +-1+ if the Object wasn't found. **** @@ -754,7 +755,7 @@ _returns_;; The index in the array or +-1+ if the Object wasn't found. [[Webkitobjects]] == Webkit objects == -All webkit objects correspond to gobject objects, i.e. they have the same +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+: @@ -767,7 +768,7 @@ webview.zoomLevel = webview.zoomLevel * 2; --------------------------------- ==== -All Objects derived from GObjets implement the following functions. +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 @@ -901,7 +902,7 @@ wv.number frame read The number of the webview, starting at 0 **** -==== Functions ==== +==== Methods ==== **** [float] @@ -994,8 +995,8 @@ wv.loadUri("http://www.example.com", function() { 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 on -+LoadStatus.finished+. +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. @@ -1048,7 +1049,7 @@ can be used. -==== Functions ==== +==== Methods ==== **** [float] @@ -1059,7 +1060,7 @@ can be used. Boolean frame.inject(String script, [Boolean global]) ---- -Injects a script into a frame, also see <<inject,webview.inject>> for details. +Injects a script into a frame, see also <<inject,webview.inject>> for details. **** @@ -1084,7 +1085,7 @@ Constructs a new download _uri_;; The uri of the download **** -==== Functions ==== +==== Methods ==== **** [float] @@ -1132,19 +1133,9 @@ download.start(function () { ==== -[[request]] -=== request === - -Corresponds to a +WebKitNavigationRequest+. - -[[navigationAction]] -=== navigationAction === - -Corresponds to a +WebKitWebNavigationAction+. - == Signals == With the +signals+ object *dwb* communicates with the script on certain events. -To connect to a signal one can call the connect function that is implemented by +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. @@ -1165,9 +1156,9 @@ 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 functions +The +signals+ object implements the following methods -=== Functions === +=== Methods === [[connect]] [float] @@ -1960,6 +1951,44 @@ return { It is recommended to implement javascript-userscripts as an extension to have consistent configuration locations for scripts. +=== 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 properties and functions === Properties === @@ -1976,7 +2005,27 @@ extensions.enableDebugging Boolean read Whether to enable debugging messages. **** -=== 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 +**** **** [[extensiondebug,debug]] @@ -2137,14 +2186,14 @@ _message_;; The warning message extensions.load("foobar"); -------- -.Writing extensions +=== 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/extensionsrc+ and should +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 diff --git a/scripts/lib/extensions.js b/scripts/lib/extensions.js index 499d3332..1fb8b496 100644 --- a/scripts/lib/extensions.js +++ b/scripts/lib/extensions.js @@ -184,6 +184,20 @@ return true; } } + }, + "bind" : { + value : function(name, shortcut, options) { + if (!name || !shortcut) + return; + if (options.load === undefined || options.load) + extensions.load(name, options.config); + bind(shortcut, function () { + if (extensions.toggle(name, options.config)) + io.notify("Extension " + name + " enabled"); + else + io.notify("Extension " + name + " disabled"); + }, options.command); + } } }); })(); diff --git a/src/scripts.c b/src/scripts.c index eb0687e4..d7fa89ea 100644 --- a/src/scripts.c +++ b/src/scripts.c @@ -608,7 +608,7 @@ global_unbind(JSContextRef ctx, JSObjectRef function, JSObjectRef thisObject, si g_free(name); } else if (JSValueIsObject(ctx, argv[0])) { - for (l = dwb.keymap; l && argv[0] != ((KeyMap*)l->data)->map->arg.p; l=l->next); + for (l = dwb.keymap; l && !JSValueIsEqual(ctx, argv[0], ((KeyMap*)l->data)->map->arg.arg, exc); l=l->next); } if (l != NULL) { m = l->data; |