Important Properties and their Plugins / Overrides

Here's a list, by defining Plugin, of the important properties floating around the Field system — how they are used and how you might encounter them. They are listed by Plugin or Override that defines them or principally uses them and ordered within each category from the every-day to the obscure, from "things you'll use while working with Field" through "things you should be aware of" to "things that you might encounter deep in the Java code". Most of the naming conventions for properties are evident here: a trailing _ prevents attempts to save the value of this property to disk, a _v version controls this property (upon save). Others are defined by the plugins themselves below.

'''Note: much of this information is readily available from within Field itself — just ask for autocompletion (that is command-period) on _self. inside the text editor and you'll see most of this. It even updates as you type to narrow down on a selection. '''

Basic Properties

  • name — the name of the visual element.
  • dirty — set this to 1 to cause a repaint of the canvas
  • doNotSave — set this to 1 to make this element not persist
  • overrides — the overrides for this element
  • selectionGroup and markingGroup — are set (at the root level) to be the SelectionGroup instances that are responsible for maintaining the currently selected , or "marked" set of elements. See Basic Drawing for a discussion of selecting and marking elements.
  • localView — the iComponent instance for this element.
  • enclosingFrame — the GLComponentWindow for this element

Directories of Note

The following properties point to directories that are of interest to Field:

  • workspaceFolder — the workspace.
  • dataFolder — a folder called 'data' in the workspace.
  • sheetFolder — the .field 'file' that is the current sheet.
  • sheetDataFolder — a folder called 'data' inside this .field package. If any of these directories do not exist, they are created on demand when these properties are accessed.

Defined by the PseudoPropertiesPlugin

(Note, writing to these properties is currently unsupported. These are pseudo-properties because they are not actually stored in any element, they are computed, on demand, by overrides in the plugin).

  • frame — the Rect of this element (to set things simply write statements like _self.frame.x=10).
  • where — returns the iVisualElement that defines a property. For example: _self.where.banana will return the iVisualElement that is actually storing banana when you access it through _self.banana
  • superproperties — searches properties, just as normal, but skips this element. For example, if _self.root.banana#3 and _self.banana2 then (assuming there's no other banana) _self.superproperties.banana will =3.
  • subelements — a Map<String, iVisualElement> by name of all elements "below" this element in the dispatch graph.
  • superelements — a Map<String, iVisualElement> by name of all elements "above" this element in the dispatch graph.
  • root the root of the sheet. Useful for storing things that are "global" but you either want to persist, and/or locally override.
  • all — a List<iVisualElement> of all elements in the sheet that are below the root element
  • find — an Map-like-object that looks up elements by regular-expression over their names. For example _self.find["banana.*"] might be a list that contains elements banana1, bananas and banana_element. This is actually a special kind of list that knows when to pretend it isn't a list, see LazyFunctionalHelpers. Essentially this means that you can ignore it's list status, and pretend it's a single object.

And three that are associated with executing and running code (specifically python_source_v):

  • begin — a function you can call that starts the running of this element
  • end — a function you can call that end the running of this element, that's been started with begin
  • () — you can also just "call" visual elements directly as in (watch for an infinite loop!) _self() or _self.find["banana.*"][0](). As an added bonus, someElement("1") executes only the area numbered '1' (see TextEditor and EmbeddingGui for more on labelled blocks).

Source code

  • python_plugin_ — set to this plugin.
  • python_source_v — defines the principle Python code that's run when the visual element is "executed".
  • python_isExecuting_ — set to true when this box begins to execute.
  • python_currentlyEditingProperty_ — set to track changes to what the editor is currently editing.
  • python_noEdit — set this to non-zero to lock the text editor for this object. Note, the best way to do this is to command-click to mark a set of elements and then do something like for n in marked(): n.python_noEdit=1.
  • python_customToolbar_} — set or add to a List of Pair<String, iUpdateable> to add buttons to the text editor toolbar for elements.
  • xxxx_m_ — defines a menu item that appears in the context menu for this (and other elements below it). Set it to be a Python function that accepts an iVisualElement as a parameter, or an iUpdatable. Note that neither of the these in general can persist, hence the trailing _.

Running things on startup

  • python_autoExec — defines python code that will be automatically executed whenever the sheet is opened. You can edit this by changing what property is currently being edited in the text editor (look at the combo-box at the top). This is useful for setting up things like imports, default properties, user interface elements &c.

Drawing

  • lines — a list of FLines that should be drawn as this element is drawn.
  • globalOpacity — a number that modulates the opacity of all of the geometry produced by this element. If it's set to 1.0, there's no change, to 0.0 this element is invisible.
  • tweak_v — python code that is executed when this visual element calls _self.tweaks(). This code is automatically generated (although it can be edited in the text editor as well) by edits performed with the mouse to lines.
  • onChange_v — python code executed when one of the things that this element elaborates changes (correctly handles elaboration loops). You can edit this by changing what property is currently being edited in the text editor.
  • onFrameChange_v — python code executed when the frame of this element changes. Editable in the text editor.
  • onSelection_v — python code executed when the element becomes selected. isSelected_ is set to the new state.
  • shouldAutoComputeRect — set to true if you want the frame of this visual element to be automatically computed given the contents of lines.

The Inspector

  • xxxx_i — anything ending with _i is presented in its own group in the Inspector Plugin's window. It's best, for the moment at least, to use strings for these properties.

Topology

  • topology_plugin — the plugin itself
  • defaultTopology_ — gets an iTopology object` that represents the topology made (through the use of the mouse and the modal topology tool, or through the right-click menus). See TopologyAndControlFlow
  • line_decorate_ — set this to a function to be called to help draw edges in the topology. This function should accept one argument which is the line connecting the two visual elements and return a (potentially new) FLine that will be drawn instead. Edges are just another visual element — put code in and set properties on them as well!