XD 28 docs updates

Author: peterflynn

changes.md

@@ -1,5 +1,21 @@
 # Change Log
 
+XD Release 28.0.12 (March 2020)
+-------------------------------------
+XD 28 is a minor update for plugin developers:
+
+* `SceneNode.BLEND_MODE_*` constants for use with the [`SceneNode.blendMode`](./reference/scenegraph.md#SceneNode-blendMode) property (which was introduced in XD 27).
+* Quickly look up a scenenode by its GUID with [`scenegraph.getNodeByGUID()`](./reference/scenegraph.md#module_scenegraph-getNodeByGUID).
+* Easily check if a scenenode is currently in scope for editing with [`isInEditContext()`](./reference/selection.md#selection-isInEditContext).
+
+### Known Issues
+* XD 28 introduces two new types of interaction actions: audio-file playback, and "scroll to" actions. Interactions using these features are not visible to plugins yet (*speech*
+  playback interactions *are* exposed though). See the [interactions API documentation](./reference/interactions.md#module_interactions-allInteractions) for a complete list of
+  which interaction types are & aren't exposed to plugins at this time.
+
+[Read more about XD 28 new features for end users on the Adobe blog](https://theblog.adobe.com/xd-march-2020-audio-prototyping-anchor-links-more).
+
+
 XD Release 27.0.12 (February 2020)
 -------------------------------------
 XD 27 is a minor update for plugin developers, with one new added API:

known-issues.md

@@ -18,7 +18,7 @@
   - In the past, XD's renderer would fail asserts (possibly even crash) with 0-size objects. I couldn't repro that any more, but unless we're covering it well as an officially supported case, it could easily regress again. There are some other minor bugs though, e.g. sharing fails if you have any 0-width/height artboards and bitmap export fails if any of the top-level items you're trying to export are 0-width/height.
 - Longer plugin command names may be truncated in the menu on Windows
   - Workaround: keep your plugin command names short!
-- Keypress/gamepad, hover, and component state-transition interactions are not returned to plugins yet when requesting the list of interactions on a scenenode or the entire document.
+- Some types of interactions are not visible to plugins yet: keypress/gamepad, scrolling, hover, component state transitions, or non-speech audio playback.
 
 ## Assets Panel
 

reference/interactions.md

@@ -13,7 +13,10 @@ The `interactions` module and related APIs provide _read only_ information about
 * Properties that affect Artboard scrolling behavior: Artboard [`viewportHeight`](./scenegraph.md#Artboard-viewportHeight) and
   node [`fixedWhenScrolling`](./scenegraph.md#SceneNode-fixedWhenScrolling).
 
-**Since**: XD 19
+> **Tip**
+> Interactions are a **fast-changing area** in XD. APIs here have a higher likelihood of becoming deprecated, or lagging behind new XD features, than other parts of XD's plugin APIs.
+
+**Since**: XD 19+ (some APIs added later)
 
 **Example**
 ```js
@@ -190,7 +193,8 @@ specifies a `triggerNode` and the result of getting [`triggerNode.triggeredInter
 
 May include interactions that are impossible to trigger because the trigger node (or one of its ancestors) has `visible` = false.
 
-Note: currently, this API excludes all of the document's keyboard/gamepad, hover, and component state-transition interactions.
+> **Tip**
+> Currently, this API excludes some types of interactions: keypress/gamepad, scrolling, hover, component state transitions, or non-speech audio playback.
 
 **Kind**: static property of [<code>interactions</code>](#module_interactions)
 **Read only**: true

reference/scenegraph.md

@@ -92,6 +92,7 @@ These classes are not scenenode types, but are used extensively in the scenegrap
 
 * [selection](#module_scenegraph-selection) : \![<code>Selection</code>](./selection.md)
 * [root](#module_scenegraph-root) : \![<code>RootNode</code>](#RootNode)
+* [getNodeByGUID(guid)](#module_scenegraph-getNodeByGUID) ⇒ `?SceneNode`
 
 
 * * *
@@ -105,7 +106,6 @@ Object representing the current selection state and [edit context](./core/edit-c
 **Read only**: true
 **Since**: XD 14
 
-
 * * *
 
 <a name="module_scenegraph-root"></a>
@@ -117,6 +117,37 @@ Root node of the current document's scenegraph. Also available as the second arg
 **Read only**: true
 **Since**: XD 14
 
+* * *
+
+<a name="module_scenegraph-getNodeByGUID"></a>
+
+### *scenegraph.getNodeByGUID(guid)*
+**Since**: XD 28
+
+Returns the scenenode in this document that has the given [node GUID](#SceneNode-guid). Returns undefined if no such node exists connected
+to the scenegraph tree (detached/orphan nodes will not be found). This provides a fast way of persistently remembering a node across plugin
+operations and even across document open/closes.
+
+**Kind**: static method of [<code>scenegraph</code>](#module_scenegraph)
+**Returns**: `?SceneNode`
+
+| Param   | Type    | Description   |
+| ------- | ------- | ------------- |
+| guid    | string  | SceneNode GUID -- must be all lowercase, as returned by the [`guid` getter](#SceneNode-guid). |
+
+**Example**
+```js
+let node = scenegraph.selection.items[0];
+let guid = node.guid;
+
+// ...later on:
+let sameNode = scenegraph.getNodeByGUID(guid);
+if (sameNode) {
+    // ^ Always check if node still exists - user may have deleted it
+    console.log("Found node again!", sameNode);
+}
+```
+
 
 * * *
 
@@ -166,10 +197,14 @@ Base class of all scenegraph nodes. Nodes will always be an instance of some _su
 <a name="SceneNode-guid"></a>
 
 ### *sceneNode.guid : <code>string</code>*
-Returns a unique identifier for this node that stays the same when the file is closed & reopened, or if the node is moved to a different part of the document. Cut-Paste will result in a new guid, however.
+Returns a unique identifier for this node that stays the same when the file is closed & reopened, or if the node is moved to a different part of the document. Cut-Paste will result in a new GUID, however.
+
+The GUID is guaranteed unique _within_ the current document, but _other_ documents may contain the same GUID value. For example, if the user makes a copy of an XD file, both files will use the same GUIDs.
 
 The GUID of the [root node](#module_scenegraph-root) changes if the document is duplicated via Save As. See [`application.activeDocument.guid`](./application.md#module_application-activeDocument) for details.
 
+Node objects can be destroyed and recreated during operations such as Undo/Redo, so if you need to store a reference to a node even between operations in the _same_ session, it's best to store the GUID and then retrieve the node later via [`getNodeByGuid()`](#module_scenegraph-getNodeByGUID).
+
 **Kind**: instance property of [<code>SceneNode</code>](#SceneNode)
 **Read only**: true
 
@@ -267,9 +302,17 @@ Node's opacity setting. The overall visual opacity seen in the document is deter
 
 Blend mode determines how a node is composited onto the content below it.
 
+One of: `SceneNode.BLEND_MODE_PASSTHROUGH`, `BLEND_MODE_NORMAL`, `BLEND_MODE_MULTIPLY`, `BLEND_MODE_DARKEN`, `BLEND_MODE_COLOR_BURN`, `BLEND_MODE_LIGHTEN`, `BLEND_MODE_SCREEN`, `BLEND_MODE_COLOR_DODGE`, `BLEND_MODE_OVERLAY`, `BLEND_MODE_SOFT_LIGHT`,
+`BLEND_MODE_HARD_LIGHT`, `BLEND_MODE_DIFFERENCE`, `BLEND_MODE_EXCLUSION`, `BLEND_MODE_HUE`, `BLEND_MODE_SATURATION`, `BLEND_MODE_COLOR`, `BLEND_MODE_LUMINOSITY`.
+
 _Note:_ for leaf nodes (GraphicNode), the XD UI may show leaf nodes as blend mode "Normal" even when the underlying value is `BLEND_MODE_PASSTHROUGH`. This is because "Pass Through" and "Normal" are essentially equivalent for leaf nodes -- they only differ
 in appearance when a node has children.
 
+**Example**
+```js
+node.blendMode = scenegraph.SceneNode.BLEND_MODE_LUMINOSITY;
+```
+
 **Kind**: instance property of [<code>SceneNode</code>](#SceneNode)
 
 * * *
@@ -504,7 +547,7 @@ is an [Interaction object](./interactions.md#Interaction) which describes a gest
 
 Note: If this node (or one of its ancestors) has `visible` = false, tap and drag interactions on it will not be triggered.
 
-Currently, this API excludes any keyboard/gamepad, hover, and component state-transition interactions on this node.
+Currently, this API excludes some types of interactions: keypress/gamepad, scrolling, hover, component state transitions, or non-speech audio playback.
 
 **Example**
 ```js

reference/selection.md

@@ -45,9 +45,10 @@ You can also access this object from the [`scenegraph.selection`](./scenegraph.m
     * [.itemsIncludingLocked](#selection-itemsIncludingLocked) : <code>!Array&lt;!SceneNode&gt;</code>
     * [.hasArtwork](#selection-hasArtwork) : <code>boolean</code>
     * [.hasArtboards](#selection-hasArtboards) : <code>boolean</code>
-    * [.editContext](#selection-editContext) : <code>!SceneNode</code>
     * [.insertionParent](#selection-insertionParent) : <code>!SceneNode</code>
     * [.focusedArtboard](#selection-focusedArtboard) : <code>?Artboard</code>
+    * [.editContext](#selection-editContext) : <code>!SceneNode</code>
+    * [.isInEditContext(node)](#selection-isInEditContext) ⇒ `boolean`
 
 
 * * *
@@ -116,6 +117,29 @@ True if the selection isn’t empty and consists of one or more Artboards. Never
 
 * * *
 
+<a name="selection-insertionParent"></a>
+
+### selection.insertionParent : <code>\![SceneNode](scenegraph.md#SceneNode)</code>
+The preferred parent to insert newly added content into. Takes into account the current edit context as well as the "focused artboard" if in the root context.
+Typically this is the same parent where, for example, XD's shape drawing tools would add items.
+
+_Selected items are not necessarily all immediate children of the `insertionParent`._ They can be anywhere within the [edit context's](/reference/core/edit-context.md) scope.
+
+**Kind**: instance property of [<code>selection</code>](#selection)  
+**Read only**: true  
+
+* * *
+
+<a name="selection-focusedArtboard"></a>
+
+### selection.focusedArtboard : <code>?[Artboard](scenegraph.md#Artboard)</code>
+The artboard the user is currently most focused on (via recent selection or edit operations). May be null, for example if no artboards exist or if the user just deleted an artboard.
+
+**Kind**: instance property of [<code>selection</code>](#selection)  
+**Read only**: true  
+
+* * *
+
 <a name="selection-editContext"></a>
 
 ### selection.editContext : <code>\![SceneNode](scenegraph.md#SceneNode)</code>
@@ -137,26 +161,18 @@ operation ends:
 
 * * *
 
-<a name="selection-insertionParent"></a>
-
-### selection.insertionParent : <code>\![SceneNode](scenegraph.md#SceneNode)</code>
-The preferred parent to insert newly added content into. Takes into account the current edit context as well as the "focused artboard" if in the root context.
-Typically this is the same parent where, for example, XD's shape drawing tools would add items.
-
-_Selected items are not necessarily all immediate children of the `insertionParent`._ They can be anywhere within the [edit context's](/reference/core/edit-context.md) scope.
-
-**Kind**: instance property of [<code>selection</code>](#selection)  
-**Read only**: true  
-
-* * *
-
-<a name="selection-focusedArtboard"></a>
+<a name="selection-isInEditContext"></a>
 
-### selection.focusedArtboard : <code>?[Artboard](scenegraph.md#Artboard)</code>
-The artboard the user is currently most focused on (via recent selection or edit operations). May be null, for example if no artboards exist or if the user just deleted an artboard.
+### *selection.isInEditContext(node)*
+**Since**: XD 28
 
-**Kind**: instance property of [<code>selection</code>](#selection)  
-**Read only**: true  
+Returns true if the node is accessible for editing in the scope of the current edit context.
+If false, the node cannot be edited given the user's current selection.
+Nodes that are currently selected are always in the current edit context.
 
-* * *
+**Kind**: instance method of [<code>selection</code>](#selection)  
+**Returns**: `boolean`
 
+| Param  | Type    |
+| -------| ------- |
+| node   | !SceneNode |