K-Meleon
The JSBridge Plugin provides a javascript interface between the cross-platform user-interface language (XUL) and K-Meleon's core. K-Meleon supports XUL-based extensions, distributed as .xpi files. XUL-based extensions were designed for Mozilla applications which used XUL for the browser's interface. K-Meleon creates its lightweight interface using the native win32 APIs, so JSBridge is necessary to create K-Meleon menu items, toolbars, and buttons from within Mozilla-style extensions.
Before using JSBridge functions you must call it either directly or via import:
var KMeleon = Components.classes["@kmeleon/jsbridge;1"] .getService(Components.interfaces["nsIJSBridge"]);
or
Components.utils.import("resource:///modules/KMeleon.jsm");
.
Kmeleon.js is a javascript file that K-Meleon will automatically load from the top-level of an xpi file. You can add K-Meleon-specific interface elements into this file, and they will not impact how the extension functions in other browsers.
function | (arguments) |
SetMenuCallback | (menu, label, function() {}, before) |
SetMenu | (menuName, itemType, itemName, command, location) |
RebuildMenu | (menuName) |
AddToolbar | (toolbarName, width, height) |
AddButton | (toolbarName, command, menuName, tooltipText) |
RemoveButton | (toolbarName, command) |
Id | (null, commandID); |
GetCmdList | (length) |
RegisterCmd | (commandName, statusbarText, function() {}, chrome://yourExtension/yourIcon.png, COLD[, HOT[, DEAD]], enabled, checked) |
UnregisterCmd | (commandName) |
SetCmdIcon | (commandName, chrome://yourExtension/yourIcon.png, COLD[, HOT[, DEAD]] ) |
SetButtonIcon | (toolbarName, command, chrome://yourExtension/yourIcon.png, COLD[, HOT[, DEAD]] ) |
SetAccel | (keys, command) |
Open | (url , state) |
GetActiveBrowser | () |
GetCurrentWindow | () |
GetWindows | (length) |
AddListener | (observe: function() {}) |
RemoveListener | (observe: function() {}) |
LoadPlugin | (kplugin) |
ShowMenu | (commandName, bool) |
Syntax | SetMenuCallback(menu, label, function() {}, before); |
Result | Set \ create Menu items , which will call Javascript function when menu is activated. Before is optional. |
Example:
KMeleon.SetMenuCallback("&Tools", "open pref",function(mode) {KMeleon.Open('chrome://kmprefs/content/pref.xul', KMeleon.OPEN_NEWTAB); });
Syntax | Open(url, state); |
Result | Open a local a external address in a new tab/window. |
States | OPEN_NORMAL, OPEN_NEW ,OPEN_BACKGROUND, OPEN_NEWTAB, OPEN_BACKGROUNDTAB, or OPEN_CLONE |
Example:
var url='chrome://kmprefs/content/pref.xul'; KMeleon.Open(url, KMeleon.OPEN_NEW);
Syntax | id(null, commandID); |
Result | Open Command IDs. |
Macros | Id can trigger Kplugins including all macros via the macros() Kplugin. The function can pass a parameter to a macro using the $ARG variable. For example, macros(kmPrefs(toolbars)) would pass the "toolbars" value as $ARG to the "kmPrefs" macro in the main.kmm module. Refer to the Macro Language page for more details. |
Example:
KMeleon.id(null,'ID_PASSWORDS_VIEWER');
Syntax | SetMenu(menuName, itemType, itemName, command, location); |
Result | Create a new menu item. Location is optional. All items are not required to build menu entries, but all items must be present to display icons from SetCmdIcon. |
itemType | inline, popup, separator, command, macro, or plugin |
Example:
KMeleon.SetMenu("&Tools", "macro", "my macro", "my_function");
Syntax | RebuildMenu(menuName); |
Result | Rebuild a menu. |
Example:
KMeleon.RebuildMenu("my_Menu");
Syntax | RegisterCmd(commandName, statusbarText, function() {}, chrome://yourExtension/yourIcon.png, COLD[, HOT[, DEAD]], enabled, checked); |
Result | Register a command to be called. Icon, enabled, and checked are optional. |
Example:
KMeleon.RegisterCmd(CmdName, 'Hello World', function(wind, mode, arg) { popupAlert('Alert', 'Hello World!'); }, 'chrome://helloworld/content/icon.png');
Syntax | SetCmdIcon(commandName, chrome://yourExtension/yourIcon.png, COLD[, HOT[, DEAD]]); |
Result | Set the icon associated with a command. Only one image is required; separate cold/hot/dead icons are optional. |
Example:
KMeleon.SetCmdIcon(CmdName, 'chrome://helloworld/content/icon.png')
Syntax | SetButtonIcon(toolbarName, command, chrome://yourExtension/yourIcon.png, COLD[, HOT[, DEAD]]); |
Result | Set the icon associated with a button. This can overwrite the icons for existing commands including kplugin commands. Only one image is required; separate cold/hot/dead icons are optional. |
Example:
KMeleon.SetButtonIcon('&Main Bar', 'navBack', 'chrome://helloworld/content/icon.png')
Syntax | UnregisterCmd(commandName); |
Result | Unregister a command. |
Example:
KMeleon.UnregisterCmd(CmdName);
Syntax | AddButton(toolbarName, commandName, menuName, tooltipText); |
Result | Adds a button to an existing toolbar. The tooltip and menu are both optional. |
Example:
KMeleon.AddButton('Browser Con&figuration', CmdName, "", "Hello World demo.");
Syntax | RemoveButton(toolbarName, commandName); |
Result | Removes a button from a toolbar. |
Example:
KMeleon.RemoveButton(Toolbar, CmdName);
Syntax | SetAccel(keys, command); |
Result | Creates a keyboard accelerator or shortcut. |
Example:
KMeleon.SetAccel('CTRL ALT SHIFT O', CmdName);
Syntax | GetCmdList(length); |
Result | Returns an array of all accelerators for all commands. Length is an optional integer. Array size is length. |
Example:
KMeleon.GetCmdList(1);
Syntax | ShowMenu(commandName, bool); |
Result | Send a command to show a menu. Useful for creating a popup menu on left-click. Boolean value is optional. |
Example:
CmdName: function () {KMeleon.ShowMenu(my_Menu, true);}
Syntax | LoadPlugin(kplugin); |
Result | Returns an error message if the kplugin is not in the user's plugins folder. |
Example:
KMeleon.LoadPlugin('hotlist');
Syntax | AddListener(function(){}); |
Result | Adds a callback which is invoked whenever the media query status (whether or not the document matches the media queries in the list) changes. |
Example:
KMeleon.AddListener( observe: function(subject, topic, data) {Services.console.logStringMessage(topic);} );
Syntax | RemoveListener(function(){}); |
Result | Removes a callback created by AddListener. |
Example:
KMeleon.RemoveListener( observe: function(subject, topic, data) {Services.console.logStringMessage(topic);} );
Syntax | GetActiveBrowser(); |
Result | Returns nsIWebBrowser object. Refer to the Mozilla documentation archived on UDN for more information. |
Services.console.logStringMessage(Kmeleon.GetActiveBrowser().contentDOMWindow.document.URL);
Syntax | GetCurrentWindow(); |
Result | Returns current kmIWindow object comparable to nsIWindow object from Firefox and SeaMonkey. Refer to the Mozilla documentation archived on UDN for more information. |
Syntax | GetWindows(length); |
Result | Returns array of all kmIWindow objects comparable to nsIWindow objects from Firefox and SeaMonkey. Length is optional. Refer to the Mozilla documentation archived on UDN for more information. |
Syntax | SendMessage(to,from,subject,data1,data2); |
Result | Connect with plugins.* |
Macro | Macro file in string form. |
Issues | *This only works with the macro plugin. It only works on v76.X. Some macros may crash the browser. |
Example:
KMeleon.SendMessage("macros", "kmAddon", "RunMacro", macro);
This command does not have the same effect as the "AddToolbar" macro command and cannot be used in a XUL-based extension. Width and height are both optional. It can be used from the Error Console. Copy and paste the example below to overwrite the Configuration toolbar in new windows:
Example:
Components.utils.import('resource://gre/modules/Services.jsm'); const JSB = Components.classes['@kmeleon/jsbridge;1'].getService(Components.interfaces.nsIJSBridge); JSB.AddToolbar('Browser Con&figuration');
CreateButton & CreateCallbackButton are defined in the kplugin but are not implemented.
AdBlock Classic is a fork of ABPrime and AdBlock Plus. To see an example of JSBridge functions, extract the .xpi file and examine the K-Meleon.js file in the root directory. This is how K-Meleon is creating menus for AdBlock Classic. It provides a clear example of how to use localization files.
K-Meleon version 74 can run a macro from inside a .xpi file ( with the name 'load.kmm' ) or run a startup function from a javascript file ( with the name 'kmeleon.js' ) inside a .xpi file too.
The startup function can create K-Meleon menu items using the SetMenuCallback function, which means that those menu items could run javascript functions or macros if you need it.
Note: In K-Meleon 74, if you want to try this method, add the component "kmAddon.js" to K-Meleon with the modified versions of "jsbridge.xpt" & "JSBridge.dll" & "macros.dll" below:
Example: newsfox_test2.zip .
The hello world reference extensions use JSBridge in a variety of ways. You can test-install them on your browser to see how their process works. Extract the extensions with any archive like 7-Zip, Winzip, or PeaZip. You can open the program files in any text editor like Notepad, Notepad++, or Notepad2. Note that only the XUL-based extensions will use JSBridge.
See Forum
This uses SendMessage to add a menu line for calling a macro (incidentally also named "howtousejsbridge", but can be any other too) to the context menu of a xul page. For example, the URL "about:config" was chosen in chrome.manifest.
Adodupan posted this in 2019, saying that it works in KM74, crashed in KM75-76, and now works again since KM-Goanna76.
Howto change the text in the menu item: edit file howtousejsbridge.dtd
Howto call another macro: edit pref extensions.howtousejsbridge.macro
Kris_88's screenshot tool is a fully functional extension that creates whole page screenshots. It uses JSBridge extensively. It's a native K-Meleon extension that runs entirely from a single .xpi and supports K-Meleon versions 74 and up.