Field

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 -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
  • localView — the iComponent for this element (might be None if this isn't a visual sheet)
  • enclosingFrame — the GLComponentWindow for this element (might be None if this isn't a visual sheet)
  • 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 BasicDrawingPlugin for a discussion of selecting and marking elements.

Defined by 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).
  • history — returns a history providing view of the element's (and dispatch graph's) properties. For example where _self.someProperty_v might have the value 5, _self.history.someProperty_v returns a of all previous values and VersionNodes (which contain information about date, copying history and commit messages). The objects returned by this are still very much in flux, see #7.
  • 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.banana=2 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).

Defined / Used in PythonPlugin(Editor)

(Note, PythonPluginEditor is loaded when the sheet is visible, otherwise you just get its superclass PythonPlugin)

  • 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. See EchoOndiskFile for an example use.
  • python_globals_ — set to the Globals object that tracks where (in which visual element) global variables are defined and automatically executes visual elements on demand that are needed to define these globals.
  • pythonScriptingSystem_ — set to the PythonScriptingSystem. This is the principle interface for actually executing python strings both in their correct environment (with all of their special variables set).
  • basicRunner_ — set to a BasicRunner at the root level. This is the principle class for interpreting the things that python can 'return' in order to have code execute for multiple time-slices. See VisualElementLifecycles.
  • 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 _.

Defined by AutoExecutePythonPlugin

  • 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.

Defined by SplineComputingOverride

  • lines — a list of CachedLines 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.
  • elaborates and elaboratedBy — bi-lateral connections between SplineComputingOverrides. The idea here is that one visual element can transform (elaborate) the "output" (the _self.lines of that-which-is-elaborated) of another. This means that you can write _self.elaborates[0].lines to get your "inputs".
  • tweak_v — python code that is executed when this visual element calls executeTweaks(). 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.
  • computed_drawingInstructions — a list of iUpdateables that are also executed when it's time to paint this iVisualElement.
  • computed_rect — set this to set the bounds of this element (rather than having it auto computed based on lines).

Used by InspectorPlugin

  • 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.

Defined in TopologyPlugin

  • topology_plugin — the plugin itself
  • defaultTopology_ — gets a iTopology<iVisualElement> that represents the topology made (through the use of the mouse and the modal topology tool, or through the right-click menus). See TopologyOverElements for more options.
  • 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) CachedLine that will be drawn instead. Edges are just another visual element — put code in and set properties on them as well!

Defined in HierarchyPlugin

This plugin helps govern the tool palette that you see in the default Field distribution. It contains helper classes for making ModalTools? that take over mouse input in the canvas. HierarchyHandler is a good starting place if you want to make such tools in Java, or HierarchyPlugin.dictAsHandler(...) for Python.

  • hierarchyPlugin — the plugin itself