Field basic user interface — the Palette

After The Canvas and The Text Editor the final piece of principle user interface for Field is the Palette. It's hard to give a complete documentation for the contents of the Palette, for exactly what it contains is governed by whatever Plugins you have added to Field. But there is a set of core plugins that you'll end up interacting with on a day to day basis, and on this page we'll give an overview of what they add to the Palette.

The Inspector

The Inspector shows you information about the visual element that's currently selected in the canvas. Specifically, it displays, in various orders information about the properties that are stored in the visual element.

1. Plugin tab bar

Not part of the Inspector — this is a set of tabs for the Palette. In general, each Plugin that wants to present UI makes it's own tab.

2. Values

The Inspector is really just a hierarchical table view of an element's properties. Simple properties, like the name and so on, are editable directly inside this inspector — just double-click on the value.

Some properties, like _self.frame and _self.name are important enough to get special presentation. Other properties, are rather more obscure (and concern the inner workings of Field) so they get bundled up inside an additional level of the tree. How does one manipulate this order? Two things govern how properties are presented. Firstly, properties with _i appended to their name, appear in a special spot — so you can use this to pull up particularly important properties for your elements. Secondly you can execute:

InspectorPlugin.addInspectableProperty("mySpecialProperty", "My Special Property")

And any visual element that has _self.mySpecialProperty set on it, will have this displayed in the inspector by default.

3. Properties & Ubiquitous Hyperlinks

Throughout the Palette you'll see text that's underlined. This isn't (just) a strange typographical decision on the part of the Field developers, rather they indicate the presence of hyperlinks embedded in the text. These hyperlinks, when clicked, popup menus that let you do things with the piece of text you clicked on. In the case of the Property names, you can copy them to the clipboard. Some values offer up the ability to open themselves in the object browser — especially useful when their textual descriptions don't offer much. Both these features bridge the gap between the inspector's traditional GUI presentation and code you'd write to manipulate the properties themselves.

The Event viewer

The Event viewer lets you interact with events that occur while Field is executing.

1. Hierarchical event view

The main part of the window is devoted to an hierarchical view of recent events. Expect all kinds of events to be displayed here, at least by default — for example: property access, global variable access, text fragment execution, visual element execution and so on. Many events open up information windows when you select them (to provide information like stack traces). Embedded hyperlinks let you select visual elements that are mentioned in the transcript, open other objects in the object browser?, and copy various pieces of text to the clipboard.

2. On / Off / Errors only

However, you are likely not to see these things scrolling by by default. Logging, and updating this display is expensive, and costs Field framerate. So there's a button that toggles between "errors only", "paused" or "on". It's "errors only" by default.

3 & 4. The contextual menu

Field's palette uses these button based contextual menus rather than adding menus to the menu bar. While things that you select in the window may offer up right-click menus of their own, the button contextual menu effects the contents of the window themselves. In the case of the event window, this menu lets you select two things: how many and what events to keep and show, and what hierarchical organization of these events you'd like to see. Events can be filtered and grouped in a growing number of ways (grouped by the property that they access, by the element that was executing when the event occurred, and so on).

Ultimately, we foresee two things for the event viewer in the future. Firstly a simple, Python-based interface to accessing and filtering these events that allow visual elements to offer their own views over the even transcript (#48) and secondly, the Event viewer really ought to become the place that Field gets it's undo functionality — it's almost there, many of the events that are there are actually undo-able (#47).

5. The search bar

Perhaps the easiest way of filtering the contents of the event transcript is the search bar. Which will eliminate all events that don't contain the text entered into it. This way you can quickly find out who and when a variable was set, a element executed, and so on...

The History viewer

1 & 2. Hierarchical history view

The History palette allows you to interact with the repository that stores historical information about the sheet and it's visual elements. It tracks the selection in the canvas — if nothing is selected, you are looking at the history of the sheet; if one element is selected you are looking at it's specific history — the title bar (2) reminds you what you are looking at. The historical information can take a moment to load.

The view is hierarchical, but only to compress long periods of time into something more manageable. The view shows the dates that the sheet or element was saved (strictly, saved with changes) and any log messages that accompanied the save. Also present is any copy history — if this sheet or element was "saved as..." at some point then copies from and to are shown.

For element views, clicking on historical moments will show you what the text for the main python property at that point in time.

3. Contextual menu

The contextual menu in the history view allows you to interact with the sheet / element and its history. "Save-with-tag" is here, which is useful for tagging a sheet with a special name (that will appear in the history view from now on). Names like "working, just before I tried to get clever..." are commonplace... Also the opposite: various kinds of "Rollback" options are here (either by element or the sheet as a whole) so you can rollback to the point just before you messed things up.

Most importantly: in the unlikely event that a Field / Java crash crashes so hard that your auto-saved Field sheet is corrupt and doesn't load, this is where you want to go to roll back to the last known working version.

4. The Search bar

Finally, there's a search bar, just like the event window. This lets you, say, quickly find out where a piece of text first appeared in the code.

The Selection manager

The selection manager concerns itself with two things: what is selected right now, and what might be selected next.

1. The selection tree

The main part of the selection manager offers you a view onto the ways of selecting and grouping visual elements. At any given time, the elements that are currently selected are grouped together under the first branch of this windows tree view. Selecting elements (any element) in this tree marks the element in the canvas (you'll see the elements surrounded by a red box). In code, you can access this group of marked elements using marked() which returns a list of elements.

Finally two shortcuts: 1) double-clicking on anything in this tree selects it, and pans the canvas over to center on it. 2) right-clicking on any visual element gives you the same menu that you'd get if you right clicked on it in the canvas.

2. The selection axis

But in Field elements can be connected to other elements in a variety of ways. A selection axis captures these kinds of relationships. For example, some elements might set global variables that other elements end up using; of there might be a non-trivial dispatch ordering of elements When selected. A selection axis does two things: one, it offers up other things that can be selected "under" the current selection in the tree and two, it can also draw over the canvas to denote relationships.

3. Selection history

Buttons here allow you to move forward and back in the history of what object has been selected — much like a web browser.

4. Element classes

The bottom part of the selection manager tree contains all of the elements of the tree (selected or otherwise) grouped by their 'kind', and sorted alphabetically by name within each group. This is the place to look if you lose-track of where something is and need to select it.

5. Saved selection sets

Using the contextual gear-button menu in this window allows you to save the current selection as a named set — these are persisted with the Sheet.

6. Selection Lock

Often, in very complex drawings where visual elements might be hard to select, you might want to lock the selection. You can do this by pressing this lock icon or using the ` (backtick) keyboard shortcut. This shortcut pops up a menu of things underneath the mouse cursor. Selecting one locks the selection to that until you press '`' again (or the 'unlock' icon).

The Plugin and Extension manager

The Plugin manager helps maintain Field's extensions directory which is where java Jar files go, Python files (which are executed or imported on startup) and manifest files (which let you point Field at your own code-base). Right clicking on a file will let you enable or disable it (a restart of field will be needed) and you can open up the hierarchy to get things like documentation and errors from plugins that are installed.

All filenames are actually hyperlinks — they lead to popup menus (much in the style of the Inspector above) that reveal these paths in the Finder. This includes the extensions directory itself.

This palette is also were you can toggle Field's JDK. On the Mac you get to choose between the fast but less compatible Java 6 and and the slower and compatible with everything Java 5. The key difference is that Java 6 supports only 64-bit native libraries. Many third party native libraries have only been compiled as 32 bit binaries (and some can't even be compiled as 64 bit libraries because they depend on parts of OS X that remain 32-bit only — most notably Qucktime and vDSP). If you are suddenly experiencing linker errors and "library not found" issues this is the first place to look. As we move forward we will try to continue to support Field on both platforms.

Most importantly of all, the Plugin manager is where you can link Field to your own personal codebase:

You have the option to add a .jar file, add a path to the classpath, copy a .jar file into the application bundle or add a path where Python will search for Python libraries. Don't forget to add something to your source path as well if you can — it improves the auto-complete considerably. Even if you don't have JavaDocs? in your source, at the very least it gives you method parameter names (and, in the case of short methods, the java-source itself).

Finally, there's also an option (in the little palette-wide gear menu) to dump the description of all of the plugins, extensions and so-forth: ideal for filing bug reports, and verifying that you've got everything you need before you 'travel'.

Other Plugins

Other plugins might register panels as part of their initialization. Of most note is the ProcessingPlugin :

This panel tells us three things: Firstly, that a valid Processing installation has been successfully located (and integrated into Field); secondly, that you have the option of injecting the contents of the Processing "Applet" into the global namespace of Field (either one, always or not-at-all). See SimpleProcessingTutorial for more information. Finally, there are some options concerning the size of the Applet window upon startup.