Layers for Developers

XD scenegraph exploration panel

Layers for Developers is a plugin that shows the current Adobe XD scenegraph selection, the whole document, or the current edit context root, as a dynamically updated, explorable set of nested objects, displaying the API-level properties belonging to the selected items.

It’s invaluable to be able to see what’s really going on with scenegraph object internals as you develop plugins, or are just curious about the structure of your XD document.

The end-user Layers panel displays the scenegraph object tree in a somewhat idealized (not to say fictional) manner; Layers for Developers shows the selection/root in exactly the form a plugin would see.

(The name comes from an analogy to the XD Layers panel, which shows the scenegraph objects, including nesting, to a normal user.)

Usage

The Layers for Developers (hereafter, “Devlayers”) panel has three sections: controls at top, a Layers panel-like hierarchical object exploration section (“layers panel”, note the lower-case “L” vs the upper-case “L” built-in Layers panel) and a SceneNode details panel (“details”).

Exploring

Your basic exploring choices are the current selection (Selection), the whole document (Root), or the current edit context root given the current selection (Edit context), selected by the appropriate radio button.

Layers

Whichever exploration choice you make, you’re presented with a set of objects in the layers panel, from which you can select one at a time to be viewed in the details panel.

Any node in the current selection (SceneNode.selected) has a light blue accent to indicate it’s selected (like the official Layers panel), while the node being viewed in the details panel has a light red accent with its name in bold (in case you have trouble distinguishing colors). If a node is both selected and being viewed, it has a light purple accent (blue and red combined). If a node isn’t in the artwork tree, its name is struck-out [not working yet], and if a node is invisible, its name is grayed out as in the official Layers panel.

The set of objects in the layers panel is exactly as presented to a plugin via scenegraph.selection (one or more objects) or scenegraph.root (a list of top-level objects in the current document), including the order as shown in the layers panel (the gray numbers on each object). The current edit context root node as presented doesn’t come directly from the scenegraph, but is computed by Devlayers from the selection, according to the scenegraph documentation.

You can navigate the layers panel just like the Layers panel: click on the icon for a container object (like a Group or a RepeatGroup) to open or close that object–the cursor turns to a cross-hair when over an expand/collapse icon, and container icons change from closed (solid color) to open (outline only). This panel only grows to about 25% of the overall panel height (so it won’t overwhelm the details panel), so if are inspecting more than a dozen objects, you’ll have to scroll within the panel to see it all.

As you click around in the actual document, changing the selection, the layers panel contents will update, displaying the first object in the new selection to start. You can then click on any other object shown in the layers panel to inspect it, without changing the document selection. As you make property changes to the currently-selected object in XD (moving, resizing, rotating, or making any kind of change in the main properties panel), you can see those changes reflected immediately in the Devlayers details.

A very useful technique is to click back and forth among several objects to compare their internal properties. If they’re similar types of objects, the details panel will (by design) maintain its scroll position and detail structure, updating the various properties in place so you can compare visually (easy for the human eye, which is designed to detect small changes).

Details

Click on any object’s name in the layers panel (container or not) to show that object’s full details (all documented elements). Each object is shown as 2 or 3 property groups, based on its class. All objects are comprised of one highest-level object class, some are GraphicNode objects, and all are SceneGraph objects. For example, a Rectangle has its own highest-level object properties, then all the GraphicNode properties, and then the SceneNode properties at the bottom. A Group has its own high-level properties and then the SceneNode properties, as it is not a GraphicsNode superclass.

(Note that unlike the Layers panel, clicking on any object in the layers panel doesn’t change the document’s current selection. It just shows the details of that object and nothing more. I.e., it’s non-invasive.)

Within the details, you can expand or contract sections based on what properties you’d like to inspect, and those choices are remembered for the whole XD session. You can control both the larger sections (for specific node types, GraphicNode, and SceneNode display) and nested structures within the properties.

By default, most large substructures (like text node styleRanges and the various SceneNode matrix/bounds properties) are closed, but you can open them and they’ll stay opened, and vice versa. (The one exception being GraphicsNode.pathData, which is potentially expensive to display.)

So you can tailor the details panel to show what’s relevant to your current task (e.g., comparing SceneNode transformation/bounds), and hide a lot of what’s irrelevant (such as all GraphicNode properties).

(Note that you can click on an expandable value line, anywhere after the open/close arrow.)

Less important properties with default values aren’t shown unless you check Defaults. Some fairly obscure properties (such as a node’s guid) aren’t shown at all, unless you check All.

Examples

Here’s a screenshot showing Devlayers inspecting a rectangle (whose name happens to be “rectangle”, since it’s an icon for a rectangle, as used in Devlayers itself). It’s the first (and only) object in the selection, and thus is numbered “0”. It’s highlighted to indicate which object is being shown in the details section.

Note the three separate details sections, Rectangle, GraphicNode, and SceneNode, any of which can be displayed or not, under your control.

And here’s a screenshot with 3 objects selected in the document, which show up in the layers section, and from which we’ve selected the middle object (#1, an ellipse) to show its object properties in the details section. These objects were selected in the order shown (rectangle, then ellipse, then polygon); if we had selected them in the reverse order, they would show up in the selection in reverse order, just as XD presents them to the plugin.

Using the levels slider

One of the main controls is a “display level” slider, that goes from “manual” to 1, 2, 3, etc to infinity (quickly).

In manual mode, you control all node hierarchy expansion. And Devlayers remembers which nodes have been opened or closed, for the whole XD session. So if you revisit a sub-tree in the layers section, it will be displayed the last way you left it.

With a display level set from 1 to infinity (unlimited), that many levels of object hierarchy are opened for you, and you have no manual control of what’s open or not. (You can tell because there’s no cross-hair cursor on the usual open/close icons.)

Of course, if you have thousands of objects in your document, viewing the Root and slamming the display level to infinity may not be a good idea. Better to use manual mode, and explore the list of root objects separately as needed, or just select the group of objects of interest in the document itself, and use a fully-open display level for those. (Someday we’ll probably virtualize the layer panel, and it won’t matter.)

Notes

Devlayers works best with a wider-than-minimal panel, so give it a little breathing room. It can function at the minimum width, but it’s fairly squeezed for even simple layer panel tree display.

When exploring the edit context root, Devlayers doesn’t currently stop the exploration at non-standard sub-groups, as the real edit context would enforce. We’ll add that, though, just to make it more helpful.

Devlayers attempts to cover all documented SceneNode and superclass properties, plus the helper types (ImageFill, etc.). If you find missing (documented) properties, please let us know and we’ll add it.

If you arrange the display a sub-structure in a complex array object (like a styleRange or LinearGradientFill), you’ll have to close and re-open the overall array to see all the other elements take the same shape.

The official Layers panel shows selected objects in a different order than is given to plugins (and as we thus display); it appears to be doing some Z-order juggling that a plugin probably couldn’t even do.

The GraphicNode.pathData property (when present) is generally not displayed by default, since it can involve some serious memory and computing resources to calculate (it’s computed on demand for most objects). E.g., a long text object can have megabytes of path data. We don’t actually ask for its value until you expand the property, to avoid potential performance issues.

If you’re inspecting the whole document (Root), and then make a new selection in the document, Devlayers will automatically switch back to showing the newly-selected objects. (Principle of least surprise.)

Devlayers only shows up to 2 decimal places for numeric values, the same as the XD UI (except for path elements, which it doesn’t touch). And it only shows up to 512 characters of a textual value like Text.text and SceneNode.pathData.

Ideas

We’re always looking for ideas for improvement. Here are some we already have–if any of these resonate, let us know.

  • Make the layers/details panels into a split view so you can choose the boundary between the two, and scroll them independently. (The only drawback would be that you couldn’t scroll up and give the whole panel height to the details portion, as you can now.)

  • Virtualize the layers display, to make it wildly more efficient for large trees of nodes.

  • Make preferences persistent over XD sessions.

  • Search for objects by name/type.

  • Add tree clambering: UI controls for going right/left/up/down (to first child) in tree.

  • Add node viewing history, so you can move back and forth easily among a few nodes, which may be far apart in the tree and tedious to navigate among.

  • Show a node’s child index in its parent. Optionally, show a node’s path to the top of the tree (usually its containing artboard, or the root, if on the pasteboard).

WordPress.org

© 2010 Em Software - Business WordPress Theme by ThemeShift