API for other addons

This describes about Multiple Tab Handler 2.x API for other WebExtensions-based addons. See also old documentation about Legacy MTH 0.x (Japanese translation)

• Abstract
• Control Selection of Tabs
  • Set Selection
  • Get Selection
  • Clear Selection
• Extra selection menu items
  • Add selection menu item
  • Remove selection menu item
  • Invoke the command
• How to know when MTH become getting ready

Table of contents generated with markdown-toc

Abstract

To communicate with MTH, your addon can send messages to MTH via browser.runtime.sendMessage(). You need to specify MTH's internal ID multipletab@piro.sakura.ne.jp as the first argument of the method.

Any API message for MTH is an object with a string property named type, which indicates the type of the message. For example:

const kMTH_ID = 'multipletab@piro.sakura.ne.jp';
var success = await browser.runtime.sendMessage(kMTH_ID, {
  type: 'clear-tab-selection'
});

You'll receive returned value from MTH APIs as a promise.

Control Selection of Tabs

Set Selection

set-tab-selection message changes selection status of tabs in a window. For example:

var success = await browser.runtime.sendMessage(kMTH_ID, {
  type:     'set-tab-selection',
  unselect: '*',
  select:   [1, 2, 3]
});

Here is the list of parameters:

• select(Optional): A constant string "*" (means "all tabs in the window"), an integer tabs.Tab.id, or an array of tabs.Tab.ids. This specifies which tabs should be newly selected. Already selected tabs will stay selected. This parameter is processed after unselect is successfully processed.
• unselect(Optional): A constant string "*" (means "all tabs in the window"), an integer tabs.Tab.id, or an array of tabs.Tab.ids. This specifies which tabs should be unselected. This parameter is processed before select.
• window(Optional): An integer windows.Window.id. If you omit this parameter, tabs in the active window will be processed by default. Tabs specified via select or unselect in other windows are simply ignored.

Here are more valid examples:

• Select all tabs in the active window: { select: '*' }
• Unselect two tabs and select other three tabs in the active window: { unselect: [1, 2], select [5, 6, 8] }

Get Selection

This API is obsolete on MTH 3.0.7 and later, and you should use tabs.query({ highlighted: true }).

get-tab-selection message requests last selection status of tabs. For example:

var selected= await browser.runtime.sendMessage(kMTH_ID, {
  type: 'get-tab-selection'
});
console.log(selected); // [{id: 1, ...}, {id: 2, ...}, ...]

The returned response will be an array of tabs.Tabs which are selected on MTH 3.0.x and later. MTH 2.x returns an object with two properties: selected and unselected:

• selected: An array of tabs.Tabs which are selected.
• unselected: An array of tabs.Tabs which are not selected.

Note that this doesn't return selection in the active window, just returns last selection. In other words, if you select some tabs in a window and you open a new window, this API still returns the selection in previous window until selection status is updated.

Due to security reasons, on MTH 3.0.7 and later this API won't return tabs in private windows, and returned tabs won't have some sensitive properties: title, url, favIconUrl and cookieStoreId. To get full tab information you need to call tabs.get() or tabs.query().

Clear Selection

clear-tab-selection message clears last selection status of tabs completely. For example:

var success = await browser.runtime.sendMessage(kMTH_ID, {
  type: 'clear-tab-selection'
});

This message doesn't accept any optional parameter.

Extra selection menu items

Your addon can provide custom menu item for the selection menu of MTH.

Add selection menu item

add-tab-selection-command message registers an extra command to the selection menu. For example:

var success = await browser.runtime.sendMessage(kMTH_ID, {
  type:  'add-tab-selection-command',
  id:    'save-as-pdf',
  title: 'Save as PDF'
});

Here is the list of parameters:

• id(Required): A string to indicate unique ID of the command.
• title(Required): The name of the command which should appear as the label of its menu item.
• always(Optional): A boolean to indicate the command should appear even if there is no selection.

Remove selection menu item

remove-tab-selection-command message unregisters an extra command from the selection menu. For example:

var success = await browser.runtime.sendMessage(kMTH_ID, {
  type: 'remove-tab-selection-command',
  id:   'save-as-pdf'
});

Here is the list of parameters:

• id(Required): A string to indicate unique ID of the command.

Note that you need to remove items manually when your addon is going to be disabled or uninstalled. Otherwise ghost menu item will stay there even if your addon is unavailable.

Invoke the command

After you add your custom command, a tab-selection-command message will be delivered to your addon via browser.runtime.onMessageExternal. Here is an example to invoke command by the message:

browser.runtime.onMessageExternal.addListener(async (aMessage, aSender) => {
  switch (aSender.id) {
    case kMTH_ID:
      switch (aMessage.type) {
        case 'tab-selection-command':
          console.log(aMessage.selection.selected); // [{id: 1, ...}, {id: 2, ...}, ...]
          console.log(aMessage.selection.unselected); // [{id: 5, ...}, {id: 6, ...}, ...]
          ... // do something
          return Promise.resolve(true);
      }
      break;
  }
});

Here is the list of properties the delivered message will have:

• id: A string which is the ID of the command.
• windowId: An integer which is the ID of the window.
• selection: An object which have two properties: selected and unselected.
  • selected: An array of tabs.Tabs which are selected.
  • unselected: An array of tabs.Tabs which are not selected.

Due to security reasons, on MTH 3.0.7 and later this API won't return tabs in private windows, and returned tabs won't have some sensitive properties: title, url, favIconUrl and cookieStoreId. To get full tab information you need to call tabs.get() or tabs.query().

How to know when MTH become getting ready

Adding selection menu item will fail if your addon starts before MTH is completely initialized.

However, MTH caches the ID of the addon which successfully registers any selection menu item. MTH sends ready message to those addons on its startup process, so you'll re-register your selection menu item by the message. For example:

browser.runtime.onMessageExternal.addListener(async (aMessage, aSender) => {
  switch (aSender.id) {
    case kMTH_ID:
      switch (aMessage.type) {
        case 'ready':
          addMTHSelectionMenuItems(); // for second time and later
          return Promise.resolve(true);
      }
      break;
  }
});
addMTHSelectionMenuItems(); // for initial installation

Sadly MTH cannot broadcast such a ready message for unknown addons, so your addon's custom selection menu items won't be available until your addon is reloaded, if MTH is installed after your addon.