Archive for July, 2009

Can We Offer Some Assistance?

Improving the scripting experience has been a major theme for the next release of Designer. While the core focus of development work on improving the scripting experience has been around the action builder and the validation functionality, I happily was able to find a bit of time to improve the Object Assist functionality in the Script Editor. I thought I would share some of the improvements that you can look forward to in the next version of Designer.

This is the current Object Assist experience:
ObjectAssist-Old.bmp

This is the new & improved Object Assist window:
ObjectAssist-New.bmp

I’ll outline the major changes below.

New Icons

The Object Assist dialog now displays icons next to each entry. There are four possible icons:

ObjectAssist-Icons.bmp

The first icon is used to denote methods.
The second icon is used to denote attributes.
The third icon represents a deprecated method.
The fourth icon is used for deprecated attributes.

This functionality is useful to tell “at a glance” what the various items in the list mean.

Note that we no longer italicize any of the entries in the listbox. The italics were meant to denote methods and attributes that are XFA Plugin (i.e. HTML) compatible. That information has now moved into the help text for each entry.

Improved Help

The help box that used to be gray and contain very brief descriptions of the various APIs has had a huge facelift. The help box is now a rich text control and can therefore be used to show information in a richer way. The box is also bigger, since we now have much more information to display.

I hadn’t realized how cumbersome it must be to get the API information for the XFA scripting model… Internally, we have a Flex application that acts as an XFA API reference. It’s pretty cool, and fairly easy to use. While not as practical as inline help, the Flex XFA API tool is quite an acceptable way to get API help easily. However, when I did a bit of research, I discovered that we don’t publicly release that tool (it was built by one of our great coop students.) I was horrified to think that everyone has to go to the script reference PDF every time they want to know more about an API call! As a programmer myself, I can imagine how inconvenient that must be.

It turns out that the Flex API application hooks into the same code that the Object Assist does to query the API data. So all the information was there, we just had to pull it out and format it correctly. So that’s what we did. Here’s a description of the information the improved Object Assist will be showing:

For all entries:

  • The description text of the entry (this is all that we used to show).
  • The version of XFA for which the entry is supported (i.e. 2.1, 2.6, etc.)
  • The availability of the entry (Core XFA, Acrobat, XFA Subset (HTML), XFAF, Dynamic Documents or deprecated.) Note that the availability can be a combination of options.

For attributes:

ObjectAssist-Attribute.bmp

  • The attribute type (string, int, object, bool, etc.)
  • The attribute access (get, set or get and set).

For methods:

ObjectAssist-Method.bmp

  • The complete method signature
  • Description text for each parameter
  • Description text for the return value
  • Noting of optional parameters

Function Completion

We’ve also added functionality that will auto-insert the parameter brackets and parameter arguments into the Script Editor when you choose a method from the list. Our Function button already does this, so it’s not very different from how some stuff already works.

For example, choosing “deleteItem” from the Object Assist list will insert deleteItem(n1) into the editor.

Choosing “assignNode” will insert assignNode(s1[, s2][, n3]).

The parameter names are actually type abbreviations. We use “s” for string, “n” for int, “d” for double, “b” for bool, “e” for exception and “o” for object. In the examples above, deleteItem expects an integer, and assignNode expects a string and optionally a second string and an integer.

If you absolutely hate this functionality, and want the old way back, we’ve added a checkbox to Tools | Options | Worskpace called “Add Statement Completion Method Signatures”. Just uncheck that box, and the signatures will not be auto-inserted.

ObjectAssist-Options.bmp

Improved Usability

We’ve essentially re-written the keyboard and mouse handling for the Object Assist from scratch. Note that the Object Assist no longer has an edit control:

ObjectAssist-WithEdit.bmp

ObjectAssist-WithoutEdit.bmp

The edit control was complicating the keyboard handling and generally impeding the implementation of several more “natural” or “usable” keyboard shortcuts.

We’ve also made lots of little changes to the how various keys (like HOME, END, PAGE_DOWN, PAGE_UP, etc.) behave and improved the functionality for “searching” in the function list while typing.