add overlay files to match current version (#40)

.gitignore

@@ -1,3 +1,2 @@
 _build
 chrome_settings_overrides.rst
-overlay/*.rst

contacts.rst

@@ -9,6 +9,11 @@ The `Address Books`__ sample extension uses this API.
 
 __ https://github.com/thundernest/sample-extensions/tree/master/addressBooks
 
+Permissions
+===========
+
+- addressBooks "Read and modify your address books and contacts"
+
 .. note::
 
   The permission ``addressBooks`` is required to use ``contacts``.

index.rst

@@ -133,6 +133,7 @@ as well. The APIs listed in the following table are known to work with Thunderbi
   mailTabs
   menus
   messageDisplay
+  messageDisplayAction
   messages
   tabs
   windows
@@ -145,13 +146,6 @@ as well. The APIs listed in the following table are known to work with Thunderbi
   how-to/messageLists
   how-to/experiments
 
-.. toctree::
-  :glob:
-  :hidden:
-  :caption: Changes to APIs
-
-  changes/*
-
 Where To Get Help
 =================
 

mailingLists.rst

@@ -8,6 +8,11 @@ The `Address Books`__ sample extension uses this API.
 
 __ https://github.com/thundernest/sample-extensions/tree/master/addressBooks
 
+Permissions
+===========
+
+- addressBooks "Read and modify your address books and contacts"
+
 .. note::
 
   The permission ``addressBooks`` is required to use ``mailingLists``.

overlay/accounts.rst

@@ -0,0 +1,7 @@
+========
+accounts
+========
+
+The accounts API first appeared in Thunderbird 66 (see `bug 1488176`__).
+
+__ https://bugzilla.mozilla.org/show_bug.cgi?id=1488176

overlay/addressBooks.rst

@@ -0,0 +1,9 @@
+============
+addressBooks
+============
+
+The address books API, also including the :doc:`contacts` and :doc:`mailingLists` namespaces, first appeared in Thunderbird 64.
+
+The `Address Books`__ sample extension uses this API.
+
+__ https://github.com/thundernest/sample-extensions/tree/master/addressBooks

overlay/browserAction.rst

@@ -0,0 +1,11 @@
+=============
+browserAction
+=============
+
+The browserAction and :doc:`composeAction` APIs first appeared in Thunderbird 64.
+They are very similar to Firefox's `browserAction API`__.
+
+Many of our `sample extensions`__ use a browserAction.
+
+__ https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction
+__ https://github.com/thundernest/sample-extensions

overlay/cloudFile.rst

@@ -0,0 +1,14 @@
+=========
+cloudFile
+=========
+
+The cloudFile (a.k.a. fileLink) API first appeared in Thunderbird 64, and was uplifted to
+Thunderbird 60.4 ESR.
+
+From Thunderbird 68.2.1 (Thunderbird 71 beta), an extension can choose to receive data for upload
+as a ``File`` object rather than as an ``ArrayBuffer``. You **should** specify which you want as
+the default may change in a future version.
+
+The `DropBox Uploader`__ sample extension uses this API.
+
+__ https://github.com/thundernest/sample-extensions/tree/master/dropbox

overlay/commands.rst

@@ -0,0 +1,7 @@
+========
+commands
+========
+
+The commands API first appeared in Thunderbird 66. It's more or less the same as the `Firefox commands API`__.
+
+__ https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/commands

overlay/compose.rst

@@ -0,0 +1,7 @@
+=======
+compose
+=======
+
+This message composition window API first appeared in Thunderbird 67 (see `bug 1503423`__).
+
+__ https://bugzilla.mozilla.org/show_bug.cgi?id=1503423

overlay/composeAction.rst

@@ -0,0 +1,8 @@
+=============
+composeAction
+=============
+
+The :doc:`browserAction` and composeAction APIs first appeared in Thunderbird 64.
+They are very similar to Firefox's `browserAction API`__.
+
+__ https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction

overlay/contacts.rst

@@ -0,0 +1,10 @@
+========
+contacts
+========
+
+The address books API, also including the :doc:`addressBooks` and :doc:`mailingLists` namespaces, first appeared in Thunderbird 64.
+The quickSearch function was added in Thunderbird 68.
+
+The `Address Books`__ sample extension uses this API.
+
+__ https://github.com/thundernest/sample-extensions/tree/master/addressBooks

overlay/folders.rst

@@ -0,0 +1,8 @@
+=======
+folders
+=======
+
+The folders API first appeared in Thunderbird 68 (see `bug 1531591`__) as a part of the
+:doc:`accounts` API. They were later moved here.
+
+__ https://bugzilla.mozilla.org/show_bug.cgi?id=1531591

overlay/mailTabs.rst

@@ -0,0 +1,12 @@
+========
+mailTabs
+========
+
+The messages API first appeared in Thunderbird 66 (see `bug 1499617`__).
+
+__ https://bugzilla.mozilla.org/show_bug.cgi?id=1499617
+
+The `Filter`__  and `Layout`__ sample extensions use this API.
+
+__ https://github.com/thundernest/sample-extensions/tree/master/filter
+__ https://github.com/thundernest/sample-extensions/tree/master/layout

overlay/mailingLists.rst

@@ -0,0 +1,9 @@
+============
+mailingLists
+============
+
+The address books API, also including the :doc:`addressBooks` and :doc:`contacts` namespaces, first appeared in Thunderbird 64.
+
+The `Address Books`__ sample extension uses this API.
+
+__ https://github.com/thundernest/sample-extensions/tree/master/addressBooks

overlay/menus.json

@@ -0,0 +1,21 @@
+[
+  {
+    "namespace": "menus",
+    "types": [
+      {
+        "id": "OnClickData",
+        "properties": {
+          "displayedFolder": {
+            "description": "The displayed folder, if the context menu was opened in the message list. The ``accountsRead`` permission is required."
+          },
+          "selectedFolder": {
+            "description": "The selected folder, if the context menu was opened in the folder pane. The ``accountsRead`` permission is required."
+          },
+          "selectedMessages" : {
+            "description": "The selected messages, if the context menu was opened in the message list. The ``messagesRead`` permission is required."
+          }
+        }
+      }
+    ]
+  }
+]

overlay/menus.rst

@@ -0,0 +1,10 @@
+=====
+menus
+=====
+
+The menus API first appeared in Thunderbird 66 (see `bug 1503421`__).
+It is basically the same as the `Firefox menus API`__, but modified to suit Thunderbird.
+Note that the similar ``contextMenus`` API will not be added to Thunderbird.
+
+__ https://bugzilla.mozilla.org/show_bug.cgi?id=1503421
+__ https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/menus

overlay/messageDisplay.rst

@@ -0,0 +1,12 @@
+==============
+messageDisplay
+==============
+
+The message display API first appeared in Thunderbird 70 and was backported to Thunderbird 68.2.
+
+A message can be displayed in either a 3-pane tab, a tab of its own, or in a window of its own.
+All are referenced by ``tabId`` in this API. Display windows are considered to have exactly one
+tab, which has limited functionality compared to tabs from the main window.
+
+More functions are planned for this API for adding to the user interface, as well as a message
+display action (similar to :doc:`browserAction` and :doc:`composeAction`).

overlay/messageDisplayAction.rst

@@ -0,0 +1,9 @@
+====================
+messageDisplayAction
+====================
+
+The messageDisplayAction API was added in Thunderbird 71, and was uplifted to Thunderbird 68.3
+ESR. It is similar to Firefox's `browserAction API`__ and can be combined with the
+:doc:`messageDisplay` API to determine the currently displayed message.
+
+__ https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction

overlay/messages.rst

@@ -0,0 +1,16 @@
+========
+messages
+========
+
+The messages API first appeared in Thunderbird 66.
+
+.. note::
+
+  When the term ``messageId`` is used in these documents, it *doesn't* refer to the Message-ID
+  email header. It is an internal tracking number that does not remain after a restart. Nor does
+  it follow an email that has been moved to a different folder.
+
+.. warning::
+
+  Some functions in this API potentially return *a lot* of messages. Be careful what you wish for!
+  See :doc:`how-to/messageLists` for more information.

overlay/windows.json

@@ -0,0 +1,24 @@
+[
+  {
+    "namespace": "windows",
+    "types": [
+      {
+        "id": "WindowType",
+        "enumChanges": {
+          "addressBook": {
+            "added": 70,
+            "backported": "68.1.1"
+          },
+          "messageCompose": {
+            "added": 70,
+            "backported": "68.1.1"
+          },
+          "messageDisplay": {
+            "added": 70,
+            "backported": "68.1.1"
+          }
+        }
+      }
+    ]
+  }
+]

overlay/windows.rst

@@ -0,0 +1,9 @@
+=======
+windows
+=======
+
+.. note::
+
+  These APIs are for the main Thunderbird windows which can contain webpage tabs and also other
+  window types like composer or address books that cannot contain webpage tabs.  Make sure your
+  code interacts with windows appropriately, depending on their type.

tabs.rst

@@ -49,7 +49,7 @@ Creates a new tab.
 
   - [``active``] (boolean) Whether the tab should become the active tab in the window. Does not affect whether the window is focused (see :ref:`windows.update`). Defaults to ``true``.
   - [``index``] (integer) The position the tab should take in the window. The provided value will be clamped to between zero and the number of tabs in the window.
-  - [``selected``] (boolean) **Deprecated.** Whether the tab should become the selected tab in the window. Defaults to ``true``
+  - [``selected``] (boolean) **Unsupported.** Whether the tab should become the selected tab in the window. Defaults to ``true``
   - [``url``] (string) The URL to navigate the tab to initially. Fully-qualified URLs must include a scheme (i.e. 'http://www.google.com', not 'www.google.com'). Relative URLs will be relative to the current page within the extension. Defaults to the New Tab Page.
   - [``windowId``] (integer) The window to create the new tab in. Defaults to the current window.
 
@@ -302,7 +302,7 @@ object
 - ``active`` (boolean) Whether the tab is active in its window. (Does not necessarily mean the window is focused.)
 - ``highlighted`` (boolean) Whether the tab is highlighted. Works as an alias of active
 - ``index`` (integer) The zero-based index of the tab within its window.
-- ``selected`` (boolean) **Deprecated.** Whether the tab is selected.
+- ``selected`` (boolean) **Unsupported.** Whether the tab is selected.
 - [``favIconUrl``] (string) The URL of the tab's favicon. This property is only present if the extension's manifest includes the ``"tabs"`` permission. It may also be an empty string if the tab is loading.
 - [``height``] (integer) The height of the tab in pixels.
 - [``id``] (integer) The ID of the tab. Tab IDs are unique within a browser session. Under some circumstances a Tab may not be assigned an ID. Tab ID can also be set to :ref:`tabs.TAB_ID_NONE` for apps and devtools windows.