Skip to content

Commit a19116a

Browse files
committed
XD 26 changelog and documentation updates
- Drag & drop - Chrome DevTools debugging - Polygon.starRatio (tweaks to docs in last commit)
1 parent f9e623e commit a19116a

File tree

4 files changed

+137
-60
lines changed

4 files changed

+137
-60
lines changed

changes.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,44 @@
11
# Change Log
22

3+
XD Release 26.0.12 (January 2020)
4+
-------------------------------------
5+
6+
### Drag & drop
7+
UXP now supports the [HTML5 Drag & Drop specification](https://html.spec.whatwg.org/multipage/dnd.html) for _some specific use cases_:
8+
9+
* **Drag & drop within your plugin's UI**
10+
* On the drag source in your UI, set the `draggable` attribute _and_ define a `dragstart` event handler that stores whatever data you want via `dataTransfer.setData()`.
11+
* On the drop target in your UI, defined `dragenter`, `dragover`, and `drop` event handlers that react appropriately.
12+
* **Drag from plugin panel UI into XD document**
13+
* Only bitmap images, SVG content, or text can be dropped into the document.
14+
* Provide the mimetype `text/uri-list` and populate it only with local file paths (see [`File.nativePath`](./reference/uxp/module/storage.md#module-storage-entry-nativepath)) and/or `data:` image URIs.
15+
* This will behave exactly the same as if the user had dropped files onto XD -- dropping an image onto a shape will use it as a mask, dropping multiline text onto a Repeat Grid text node will populate each grid cell with each line from the text content, etc.
16+
* It is not yet supported to drag content _onto_ your plugin from an outside source (e.g. dropping files on your plugin UI, or dragging images from another app into your plugin UI).
17+
18+
For more, [see this **sample plugin code**](https://github.com/AdobeXD/plugin-samples/tree/shotts/xd-26-prerelease/ui-panel-simple-drag-and-drop).
19+
20+
### Debugging with Chrome DevTools _(beta)_
21+
You can now use the Chrome DevTools UI (CDT) to debug your JS code -- and _to a limited extent_, inspect your UI DOM structure. **Read the updated [debugging tutorial](./tutorials/debugging/index.md)** for details.
22+
23+
**What works:**
24+
* Set breakpoints, pause & stop through code, inspect the values of variables
25+
* View objects and run code in the Console view
26+
* View and edit the "HTML" DOM structure of your plugin's UXP UI
27+
28+
**Important caveats:**
29+
* XD may be unstable while debugging a plugin. Don't debug when you have important XD documents open.
30+
* If you leave CDT on the Elements view, XD will crash the next time you open it. If this happens, keep CDT open after XD crashes and switch to a different tab. Then close CDT, restart XD, and begin debugging again.
31+
* Debugging on Windows requires some extra steps run with admin rights -- see tutorial for details.
32+
* Many features in the Elements tab do not work. You can view DOM structure, and view limited CSS information but not edit CSS rules. The "Select an element" button does nothing.
33+
* Error messages are often _missing_ from the Console view. Use the _Plugins > Development > Developer Console_ view in XD to be sure you are not missing any important information.
34+
* Other DevTools features such as the Network or Profiling tabs are not supported and may behave erratically if you attempt to use them.
35+
* XD will be partially frozen while paused on a JS breakpoint. Don't try to interact with XD while paused.
36+
* You may see a blank white panel to the left of the DevTools UI. Ignore this, as it does nothing.
37+
38+
### Other API updates
39+
* Polygon scenenodes can now take on a star shape - see [`Polygon.starRatio`](./reference/scenegraph.md#Polygon-starRatio)
40+
41+
342
XD Release 25.1.12 (December 2019)
443
-------------------------------------
544

known-issues.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,12 @@
8989
- Interactive elements do not support `Pointer%` events
9090
- `keypress` and `keyup` are not currently supported on macOS.
9191

92+
### Drag & Drop
93+
94+
- `drag` and `dragexit` are not supported, although other HTML5 drag/drop events do work.
95+
- Images and text are not implicitly draggable, unlike in HTML. You must provide a `dragstart` handler that calls `event.dataTransfer.setData()`.
96+
- Dragging files or other content _onto_ your plugin UI from an outside source is not supported.
97+
9298
## Network I/O
9399

94100
- On macOS, it is not possible to use self-signed certificates with secure Websockets.
@@ -100,3 +106,18 @@
100106
## File I/O
101107

102108
- `Blob` is not supported. Use `ArrayBuffer` instead.
109+
110+
## Debugging
111+
112+
* XD may be unstable while debugging a plugin. Don't debug when you have important XD documents open.
113+
* Debugging on Windows requires some extra steps run with admin rights -- see [tutorial](/tutorials/debugging/index.md) for details.
114+
* Elements tab:
115+
- If you leave CDT on the Elements tab, XD will crash the next time you open it. If this happens, keep CDT open after XD crashes and switch to a different tab. Then close CDT, restart XD, and begin debugging again.
116+
- The CSS pane on the right is missing some data and cannot be used to edit CSS.
117+
- Selecting/hovering elements does not highlight the corresponding region in the XD UI.
118+
- The "Select an element" button does nothing.
119+
* Error messages are often missing from the Console view. Use the _Plugins > Development > Developer Console_ view in XD to be sure you are not missing any important information.
120+
* Other DevTools features such as the Network or Profiling tabs are not supported and may behave erratically if you attempt to use them.
121+
* XD will be partially frozen while paused on a JS breakpoint. Don't try to interact with XD while paused.
122+
* You may see a blank white panel to the left of the DevTools UI. Ignore this, as it does nothing.
123+
* If debugging exposes any private fields and methods, do not attempt to use them. Plugins referring to private APIs will be rejected or removed from XD's plugin listing.

reference/scenegraph.md

Lines changed: 27 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1263,27 +1263,34 @@ True if the Ellipse is a circle (i.e., has a 1:1 aspect ratio).
12631263
**Kind**: class
12641264
**Extends**: [<code>GraphicNode</code>](#GraphicNode)
12651265

1266-
Leaf node shape that is a polygon with 3 or more sides. May also have rounded corners. The sides are not necessarily all equal in length:
1266+
Leaf node shape that is either a convex polygon _or_ a star shape. May have rounded corners. The sides are not necessarily all equal in length:
12671267
this is true only when the Polygon's width and height matches the aspect ratio of a regular (equilateral) polygon with the given number of
12681268
sides.
12691269

1270-
When unrotated, the Polygon always has its bottommost side as a perfectly horizontal line - with the exception of the 4-sided Polygon, which
1270+
When unrotated, a non-star Polygon always has its bottommost side as a perfectly horizontal line - with the exception of the 4-sided Polygon, which
12711271
is a diamond shape instead.
12721272

12731273
Like all shape nodes, has no size, fill, or stroke by default unless you set one.
12741274

12751275
**Example**
12761276
```js
1277-
// Add a red triangle to the document and select it
1277+
// Add a red triangle to the document
1278+
var polygon = new Polygon();
1279+
polygon.cornerCount = 3;
1280+
polygon.width = 50;
1281+
polygon.height = 100;
1282+
polygon.fill = new Color("red");
1283+
selection.insertionParent.addChild(polygon);
1284+
1285+
// Add a blue 5-pointed star with rounded corners
12781286
var polygon = new Polygon();
12791287
polygon.cornerCount = 5;
12801288
polygon.starRatio = 55;
1281-
polygon.setAllCornerRadii(15);
1289+
polygon.setAllCornerRadii(4);
12821290
polygon.width = 100;
1283-
polygon.height = 100;
1284-
polygon.fill = new Color("red");
1291+
polygon.height = 95;
1292+
polygon.fill = new Color("blue");
12851293
selection.insertionParent.addChild(polygon);
1286-
selection.items = [polygon];
12871294
```
12881295

12891296
* [Polygon](#Polygon)
@@ -1317,12 +1324,14 @@ selection.items = [polygon];
13171324
### polygon.cornerCount : <code>number</code> (integer &gt;= 3)
13181325
**Default**: 3
13191326

1320-
Number of corners (vertices), and also therefore number of sides.
1327+
For a non-star shape, defines the number of corners (vertices), and also therefore number of sides. For a star shape, defines the
1328+
number of star points -- there will be twice as many corners in total (the tips of the points _plus_ all the inside corners
1329+
between the points).
13211330

1322-
Setting cornerCount on an existing Polygon behaves in one of two different ways:
1331+
Setting `cornerCount` on an existing Polygon behaves in one of two different ways:
13231332
* If the shape's aspect ratio gives it equilateral sides, the sides remain equilateral while the size and aspect ratio of the
1324-
shape is changed to accomodate.
1325-
* Otherwise, the size and aspect ratio of the shape remains unchanged.
1333+
shape are automatically changed as needed.
1334+
* Otherwise, the size and aspect ratio of the shape remain unchanged.
13261335

13271336
This matches how changing the corner count in XD's UI behaves.
13281337

@@ -1368,19 +1377,16 @@ Set the corner radius of all corners of the Polygon to the same value.
13681377

13691378
<a name="Polygon-starRatio"></a>
13701379

1371-
### polygon.starRatio : <code>number</code> (number >= 1 && <= 100)
1372-
The star ratio percentage.
1373-
1374-
Ratio, expressed as a percentage, used to determine how much of a star is this polygon,
1375-
with values ranging between 1 and 100 percent.
1376-
A value of 100 percent gives us a star that looks like a convex polygon, while a value of
1377-
1 percent should give us something similar to lines drawn from the center.
1380+
### polygon.starRatio : <code>number</code> (1.0 to 100.0)
1381+
**Default**: `100`
1382+
**Since**: XD 26
13781383

1379-
The star inner vertices are placed on a circle. The ratio is the percentage of that circle
1380-
from the inscribed circle of the polygon formed from the star outer vertices.
1384+
Determines how prominent the shape's star points are. The default value of 100 is a normal convex polygon (not a star at all).
1385+
For a star shape, consider that the outer vertices at the tips of the points all lie on a circle and the inner vertices
1386+
between the points all lie on a second, smaller circle. The `starRatio` is the ratio of the smaller circle's diameter to the
1387+
outer circle's diameter, expressed as a percentage.
13811388

13821389
**Kind**: instance property of [<code>Polygon</code>](#Polygon)
1383-
**Since**: XD 26
13841390

13851391
* * *
13861392

tutorials/debugging/index.md

Lines changed: 50 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -2,78 +2,89 @@
22

33
Bugs happen! In this tutorial, you will learn how to debug your Adobe XD plugin.
44

5-
## Prerequisite
5+
### Prerequisite
66

77
At least one plugin in your `develop` folder (you can create one using our [Quick Start tutorial](/tutorials/quick-start)).
88

9+
### Debugging Options
910

10-
## Debugging Steps
11+
There are two ways you can debug an XD plugin:
1112

12-
During development, if your plugin is misbehaving, there are few things you can do to investigate the problem.
13+
* For **quick, simple debugging**, [use the Developer Console built into XD](#quick-debugging-with-developer-console)
14+
* For **in-depth debugging**, set up your plugin for [debugging with Chrome DevTools](#debugging-with-chrome-devtools-beta) _(beta)_
1315

14-
### 1. Look for errors in the developer console
1516

16-
You can see error messages your plugin may be causing with the XD developer console.
17+
## Quick debugging with Developer Console
1718

18-
The developer console can be opened from the _Plugins_ menu: _Plugins > Development > Developer Console_.
19+
### 1. Check the Developer Console
1920

21+
In XD, click _Plugins > Development > Developer Console_.
2022

21-
### 2. Try reloading the plugins
23+
This displays information similar to what you'd find in the JS debugger's console view:
24+
* Any `console.log()` output from your plugin
25+
* Any error messages from XD due to plugin misbehavior, or failure to load a plugin
26+
* Stack traces if your code throws an uncaught exception
2227

23-
You can reload all plugins in your `develop` folder from the _Plugins_ menu: _Plugins > Development > Reload Plugins_.
28+
The console output for _all_ installed XD plugins is mixed together in one single view here.
2429

25-
There's also a handy keyboard shortcut:
30+
### 2. Reload your plugin after making fixes
31+
32+
You can easily iterate on your plugin code without heaving to restart XD. Click _Plugins > Development > Reload Plugins_ to reload all plugins in your `develop` folder. This will reflect any changes in [manifest.json](/reference/structure/manifest.md) in addition to any changes to your JS code.
33+
34+
There's also a handy keyboard shortcut to make reloading easier:
2635

2736
| Platform | Keyboard shortcut |
2837
| ------------- | ------------- |
2938
| macOS | Shift-Cmd-R |
3039
| Windows | Ctrl-Shift-R |
3140

32-
If there are any errors blocking the plugin from loading, they will appear in the developer console on reload:
33-
34-
![reload-error.png](/images/reload-error.png)
35-
36-
### 3. Try logging messages to the developer console
41+
If there are any errors blocking the plugin from loading, they will appear in the Developer Console on reload:
3742

38-
The example code below does not appear to be creating the "Hello!" text as expected.
43+
![Error during reload](/images/reload-error.png)
3944

40-
Let's try adding a "start message" and an "end message" into `sayHello()` to double-check that the code is starting and running all the way to the end:
4145

42-
```js
43-
function sayHello(selection) {
44-
console.log("sayHello started!"); // log a message
46+
## Debugging with Chrome DevTools _(beta)_
4547

46-
const el = new Text();
47-
el.text = "Hello!";
48-
el.styleRanges = [
49-
{
50-
length: el.text.length,
51-
fill: new Color("#FFFFFF")
52-
}
53-
];
48+
### 1. Enable debugging on your plugin
5449

55-
selection.insertionParent.addChild(el);
56-
el.moveInParentCoordinates(100, 100);
50+
Navigate to the root folder of your plugin and **create a `debug.json` file**:
5751

58-
console.log("sayHello ran to the end!"); // log a message
52+
```json
53+
{
54+
"port": 9345,
55+
"breakOnStart": false
5956
}
6057
```
6158

62-
Your `console.log` messages will appear in the developer console:
59+
* Debugging is only supported for plugins in the **`develop` folder** (not plugins installed from the Plugin Manager UI).
60+
* Specify any port number you want.
61+
* Advanced: Set `breakOnStart` to true if you want the debugger to immediately pause on the first line of code in your plugin the moment it starts loading. This is useful since you won't have a chance to open DevTools _before_ this moment to set breakpoints before that initial code runs.
6362

64-
![start-message](/images/start-message.png)
63+
### 2. Launch Chrome DevTools
6564

66-
It looks like the function is running... maybe there is another problem.
65+
1. Windows only: _before_ launching XD, open an admin command prompt and run `CheckNetIsolation LoopbackExempt -is -n="Adobe.CC.XD.adky2gkssdxte"` -- do this _each time_ you want to debug a plugin.
66+
2. Open Google Chrome and navigate to **`chrome://inspect`** _(you must use Chrome)_
67+
3. One-time setup: ensure "Discover Network Targets" is enabled. Click the Configure button next to this and add `localhost:9345` (or whatever port number your `debug.json` file used).
68+
4. Click the "inspect" link under your plugin's ID.
6769

68-
![wrong-color](/images/wrong-color.png)
70+
### Beta: What works, what doesn't
6971

70-
Oops, the fill color set by the plugin is `#FFFFFF`, which is white: the same color as this artboard's background.
72+
Currently, you **can**...
73+
* Set breakpoints, pause & step through code, inspect the values of variables
74+
* View objects and run code in the Console view
75+
* View and edit the DOM structure of your plugin's UXP UI
7176

72-
You can verify this with a `console.log` message:
77+
Most other DevTools features are not supported and may behave erratically if you attempt to use them.
78+
79+
**Important caveats:**
80+
* XD may be unstable while debugging a plugin. Don't debug when you have important XD documents open.
81+
* Error messages are often _missing_ from the DevTools Console. Use the Developer Console within XD (see "Quick debugging" above) to be sure you are not missing any important information.
82+
* XD will be partially frozen while paused on a JS breakpoint. Don't try to interact with XD while paused.
83+
* You may see a blank white panel to the left of the DevTools UI. Ignore this, as it does nothing.
84+
* If debugging exposes any private fields and methods, do not attempt to use them. Plugins referring to private APIs will be rejected or removed from XD's plugin listing.
85+
86+
Read the [known issues](/known-issues.md#debugging) for more details.
7387

74-
```js
75-
console.log("el fill color =" + el.fill); // OUTPUT HERE
76-
```
7788

7889
## Next Steps
7990

0 commit comments

Comments
 (0)