Field

Text editor, Introduction and Features

Field is an environment for experimenting with code, fast. As such it has a text editor that is geared to quickly navigating, rewriting and executing code. Some of the features here will take a while to get "under your fingers" but most of them have been carefully designed to save the improvisatory coder typing, mousing and numbing repetition. Often there are places deep inside Field where you can extend the editor to add functionality that's specially crafted to your work — put buttons into the toolbar, add "browesable" objects and so on. These are marked in the text below when they arise.

1 — Property selector & tool bar

This combo box allows you to select which property you are editing. Most of the time it will be python_source_v, but some overrides and plugins respond to others (for example python_autoExec gets executed when the sheet loads. This is the code that gets executed when a visual element is "run". (You can run visual elements by option clicking on them, hitting them with time sliders, and so on....). But other properties are available, and the text editor can edit potentially any property that contains a String. This property selector will automatically swap to non-empty properties when elements are selected in the canvas (it will flash red briefly to alert you.)

Extension point : You can add buttons to this toolbar which you can get from PythonPluginEditor.getToolbar() (for all visual elements), or you can add buttons to this toolbar for specific (groups) of visual elements by populating the property PythonPluginEditor.python_customToolbar. This property currently takes Pairs of <String, iUpdateable>. See EchoOndiskFile for an example.

  • Keyboard shortcut: =

Use this key to cycle between available properties without lifting the mouse. Extension point: PythonPluginEditor.knownPythonProperties map adds properties that can be selected from this menu.

2 — Main text input area

This is where you craft your code, it's an increasingly "fully featured" code text editor with some interesting twists. But the basics first, in order of importance:

Execution

  • Keyboard shortcut: return — executes the current line or current selection (if there is a selection). You'll be pushing this a lot.
  • Keyboard shortcut: ⇧return —executes the current line or current selection (if there is a selection) in a generator environment, asynchronously — see GeneratorExamples for a long, cross-cutting documentation on the use of generators in Field (or PythonGeneratorStack for the nitty-gritty details). The short form is that you can write what would be Python generator bodies but execute them directly.

In both cases, tab-indentations are intelligently stripped from the selection (should you want to execute just the body of a function).

  • Keyboard shortcut: 0 —executes everything in the window.

In all three of the above cases hold down, additionally, ⌥ will clear the output window (see 3 below) before executing anything, giving you a blank output slate to work with.

As well as executing things from the keyboard, you can execute all of the python_source_v code using the mouse — option-clicking on visual elements and dragging time sliders over them. See VisualElementLifecycles.

Finally you should be aware that elements are automatically executed to resolve undefined global variables. That is, should element 'A' be known to have set global variable globalVar in the past and some other element require the value of globalVar element 'A' will be automatically evaluated. This makes it easy to write small library functions in separate elements or define global data structures on demand. You can get a better idea what is going on by turning on (un-pausing) logging in the logging window. See ScopingInField, python_autoExec_v and Globals for more information.

Completion

Field offers various kinds of autocomplete and inspection. For much more information about a feature you'll be using a lot, see CompletionAndInspection.

  • Keyboard shortcut: . — offers autocomplete based on the results of executing the left hand side expression. This is clearly dangerous in some cases (for example a foolhardy attempt to autocomplete the result of System.exit().‹‹.›› would cause your program to exit altogether). It does however allow Field to offer generally excellent completion of Java and Python objects. It pulls parameter names from searching the source paths given to it by java.source.paths and parsing the java source directly. (See ExtensionsDirectory for how to add to this runtime variable).
  • Keyboard shortcut: i — offers autocomplete for "importing" things. To access java code in Python first it must be imported. Field tries to guess what it is you want to import with this completion. When you select something, it will add the necessary import to the top of this property (and execute that import).
  • Keyboard shortcut: " — offers autocomplete for filenames.
  • Keyboard shortcut: / — is equivalent to executing the current line/selection but with print in front of it. This is useful for rapidly inspecting the value of an object.
  • Keyboard shortcut: ⇧/ — opens a browser on the results of evaluated the expression to the left. The browser knows about Python: for example, you could browse into a list of maps, select an element, select a key and then (right-click) insert the code that would get you to that point back into the text editor. Extension Point: for adding elements that can get browsed, see list BrowserTools.handlers.
  • Keyboard shortcut: ⌃/ —prints the left-hand-side expression, but after filtering it through some pretty-printing. Extension Point: for adding pretty-printers see OutputPrinter.handlers. See 7 below for a pretty printed list.

Tabs

Python is whitespace sensitive. While Python doesn't care about the difference between tabs and spaces (as long as you pick just one of them), Field wants you to use tabs for indentation. Note the subliminal horizontal lines in the editor, those are tabs.

  • Keyboard shortcut: ] — indents line or selection.
  • Keyboard shortcut: [ — un-indents line or selection

Proportional Font

Yes, that's a proportional font for writing code in. Many people have commented on how strange this is; others quite like it. We should make it an option: you should start with BaseTextEditor2 and Constants.

Error highlighting

if it can Field will highlight lines that threw exceptions with red background ink. It's often not possible to work out where a line threw an exception, if it's something more "runtime" than a syntax error, in which case you still get the error in the output window.

3,7 — Output Window

The results of executing code go here, together with a print of the code that has caused it. Errors and exceptions too. Note the pretty printing result (see 2 above) and the tiny thumb mark that lets you move the split-point between input and output.

4,5 — Embedded GUI elements

Field can embedded GUI elements directly inside the code itself. You get these from the right-click contextual menu. Extension Point: to add your own GUI elements add to the list CustomInsertSystem.possibleComponents. These elements masquerade as text, and flow with the text. There's an increasing variety of input (sliders, color pickers), output (places to draw historgrams), and data selection (trees and combo boxes) elements becoming available. These can also be placed in the TheCanvas (see OutputInsertsOnSheet , #6) and "printed" to the output window (OutputInserts).

  • The area above label '4' has a slider and a color well assigned to two variables. These are exactly equivalent as far as Python is concerned to saying clock = 0.256*100 or color = Vector4(1,0,0,0.5). But some sliders &c return more esoteric objects that promote lazy evaluation, LazyFunctionalHelpers.
  • Currently the slider (but soon the others) can automatically execute the line that they are on. Right click on them to get a contextual menu with these options.
  • The area marked by someBlock is a labeled block. The labels are just comments, and usually come in pairs — "n. name" and "\n. name" where n is a number. These can be nested, and if an end marker is missing, the bottom of the property is used instead. However, and here's the point: inside a block Keyboard shortcut: n executes the block, as does option clicking on the start marker. Further block markers, referred to as Text Transformation markers, can transform the code inside them, and they have been used for hosting foreign languages - MayaIntegration for example.

Embedded GUI elements are one of the most instantly recognizable features of Field. More on this subject here.

6 — Syntax highlighting

Field makes an attempt at highlighting the syntax of your file; its parser is very basic. It also tries to distinguish properties with and without trailing '_', since those are significant.

8 — Ruler selector

Right now Field offers three 'rulers' that display implicit information about the use of the editor — "Edit History, "Execution History" and Line Numbers (the last of these should be self explanatory).

Edit History

The edit history shows you which elements have been added, changed, when, how much and how contiguously. It takes its data from the Mercurial database associated with the property. Time goes from left (now) back to the right (the first creation of this property). Mousing over various points shows you what that piece of text looked like back then.

The edit history ruler's user interface is still very much in flux (in a good way). For more information, see the history ruler's page.

Execution History

Selecting and executing with the mouse is slow and doing it over and over again while you experiment with a number, a slider or even a rhythm is tedious. Setting up labelled blocks (see 4,5 above) might be too explicit. Enter the execution history ruler. Executing (via return) leaves bracketed-traces. Option-clicking on these groups executes them again. Shift-Option-clicking on them executes the group in a "generator environment" (see VisualElementLifecycles). The red traces are paths that have been previously followed after executing the block you just executed, and thus guide you back through what it was you did (before you crashed, or changed something) or common loops. (Eventually, this data will be "unrolled" into different forms, #18, and available for introspection).

Execution "traces" can be resized vertically with the mouse (just grab hold of the top or the bottom of them). Via their contextual menus they can have keyboard shortcuts assigned to them (all starting with ⌃); the can be deleted, or they can be "promoted" (moved to the far left).

Finally, there are two highly useful keyboard shortcuts that are always available that re-execute execution traces that the text editor cursor just happens to be in:

  • Keyboard shortcut: ← — executes the left-most region that encloses the current insertion point.
  • Keyboard shortcut: → — executes the right-most region that encloses the current insertion point.

9 — Window decoration

This minimize button turns the window into a strip, and double clicking on the title bar maximizes the window vertically. A violation of Apple's human interface guidelines, maybe; better than covering the entire screen with a single window, yes.

10 — Right-click menu

Embedded GUI elements live here, but also note the shortcuts for wrapping a selection in a block (you'll only get this option if you have a substantial selection); for looking up the text in Eclipse (via AppleScript and Eclipse's T search); for searching this Trac site; for deciding to run this text at the startup of Field (a useful way to build your library).