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.

Calling JSBridge

Before using JSBridge functions you must call it either directly or via import:

• Directly calling the interface

var KMeleon = Components.classes["@kmeleon/jsbridge;1"]
                         .getService(Components.interfaces["nsIJSBridge"]);

or

• Import KMeleon module

Components.utils.import("resource:///modules/KMeleon.jsm");

.

Kmeleon.js

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.

JSBridge functions

List of Functions

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)

Tested Functions

SetMenuCallback

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); });

Open

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);

Id

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');

SetMenu

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");

RebuildMenu

Syntax	RebuildMenu(menuName);
Result	Rebuild a menu.

Example:

KMeleon.RebuildMenu("my_Menu");

RegisterCmd

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');

SetCmdIcon

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')

SetButtonIcon

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')

UnregisterCmd

Syntax	UnregisterCmd(commandName);
Result	Unregister a command.

Example:

KMeleon.UnregisterCmd(CmdName);

AddButton

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.");

RemoveButton

Syntax	RemoveButton(toolbarName, commandName);
Result	Removes a button from a toolbar.

Example:

KMeleon.RemoveButton(Toolbar, CmdName);

SetAccel

Syntax	SetAccel(keys, command);
Result	Creates a keyboard accelerator or shortcut.

Example:

KMeleon.SetAccel('CTRL ALT SHIFT O', CmdName);

GetCmdList

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);

ShowMenu

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);}

LoadPlugin

Syntax	LoadPlugin(kplugin);
Result	Returns an error message if the kplugin is not in the user's plugins folder.

Example:

KMeleon.LoadPlugin('hotlist');

AddListener

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);}
        );

RemoveListener

Syntax	RemoveListener(function(){});
Result	Removes a callback created by AddListener.

Example:

KMeleon.RemoveListener(
        observe: function(subject, topic, data)
        {Services.console.logStringMessage(topic);}
        );

GetActiveBrowser

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);

GetCurrentWindow

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.

GetWindows

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.

Experimental Functions

SendMessage

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);

AddToolbar

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

CreateButton & CreateCallbackButton are defined in the kplugin but are not implemented.

Example Extensions

Modified for K-Meleon

AdBlock Classic

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.

NewsFox

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 .

Written for K-Meleon

"Hello world!"

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.

Adodupan's macro reference

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' Screenshot Tool

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.