The Canvas

1,8 — The window itself

This is the window where you will create, select, organize, manipulate, resize and delete visual elements of various kinds. The right-click contextual menu will get you started with creating some simple visual elements.

• Selection is by left-click / shift-left click for multiple selections; Dragging a box around repositions it; dragging with Caps-lock lit gives you guides for alignment; holding 'command' while releasing causes any activated guides to become constraints (see 8, in the diagram above — these two elements are constrained to share a common left edge).

• Marking is by -left-clicking. Since selecting a visual element makes it the thing you are editing, selection is useless for indicating other elements you'd like to talk about in code. Marked elements are highlighted in red, and a list of them can be obtained at any time (in code) by writing marked(). A list of elements that are marked in all open sheets can be obtained by writing allMarked(). You can also mark elements by selecting them in the Selection manager.

• Duplicating is by shift--dragging. This will duplicate all selected elements.

• Pan using the middle-mouse button (or two finger drag gestures on a laptop trackpad); Scale using shift-middle-mouse.

• Deleting is by delete (that is, -forward-delete, not backspace).

• keyboard shortcut: f1 — resets view
• keyboard shortcut: f2 — toggles "preview mode" (removes all lines with ignoreInPreview set, see iLinearGraphicsContext and BasicDrawing.
• keyboard shortcut: ~ — offers a menu of selectable objects under the mouse, choosing one locks the selection to that object until a subsequence press of ~. See the Selection Manager

• contextual menu items come by dispatching over menuItemsFor (see and DelegationAndVisualElements and SelfAndProperties). PythonPluginEditor also injects properties with _m suffices (see ImportantPlugins).

Finally, all of these things are up for overriding by tools installed by plugins. You'll find a "modal tools palette" open should a plugin in do this (by default, there are tools that let you change how elements communicate and let you add connections between elements, see SelfAndProperties).

2 — A plain visual element

This is a plain, default, "visual element" (specifically, under the hood, this is a DraggableComponent / VisualElement / DefaultOverride combination). You get one by right-clicking and saying 'new visual element here'.

3 — An executing visual element

Visual elements contain python code and data stored in their properties. This code can, of course, be executed. Execution is provoked in a variety of ways — most simply in the TextEditor (you can enter, shift-enter, 0 etc.). Executing all of the "main code" in an element also happens if you option-click on an element, hit the element with a time slider (see 4 below) &c.

• However, visual elements can have more interesting life-cycles than this. If, upon execution in response to an option-click or a time slider, the script sets the special variable _r this variable is interpreted as the "return value" of that code. This variable 'r' is subsequently interpreted, see VisualElementLifecycles.

• If you want to execute an element and keep executing it using the mouse, select 'continue running...' from the fly-over that appears when you option click on the element. To stop it, option-click again to get a fly-over that says 'stop'. See OptionClicking.

4 — The "Time Slider"

Time sliders execute elements that they cross. (They get their behavior and appearance from TemporalSliderOverrides). You can drag them around with the mouse, or you can drag them around in code.

• In code, you have two options. Firstly _self.timeSlider will get you the Time Slider element that created by default for the sheet. It's just a visual element, so you can write _self.timeSlider.frame.x=10 on it; obviously, you shouldn't worry too much about the width, height, or y placement. Time Sliders are careful enough to execute elements that they end up jumping over completely, so in the case that the slider moves monotonically from left to right, the elements executed, and the order that they are executed in is independent of the timing over how the time slider changes.

• Secondly, you can attach the Time slider to the ''TimeSystem'' which is a more complex object that helps manipulate the flow of time — right click and select one of the Time Slider options. Now in code you can write to the special variable _now. For example

  now.value = 300 # sets the time to be 300
  now.line = [200, 500] 
  # sets the time to be 500, over the course of the next 200 frames
  now.end = 100 
  # sets the time to be (just passed the) end of the current element, over the course of the next 100 frames
  now.start = 100 
  # sets the time to be (just passed the) start of the current element, over the course of the next 100 frames
  
  now.endOf = [100, "some marker"] # equivalent to 
  now.endOf = [100, _self.find["some marker"][0]] 
  # sets the time to be (just passed) the end of the element called "some marker", over the course of 100 frames
  now.endOf = "some marker" # equivalent to 
  now.endOf = _self.find["some marker"] 
  # sets the time to be (just passed) the end of the element called "some marker", instantly.
  
  #now.startOf works the same way
  

There are many other things you can do with a TimeSystem directly that can come in handy when "performing" timelines. But the above elements should be enough to handle loops and basic time control structures.

• Finally you can create additional time sliders programatically, and, in doing so, make the default slider ignore certain code boxes, see SubTimeSliders.

There is also a plugin that connects timelines to Connexion 3d controllers for live performance scrubbing — the ScrubberPlugin. When installed you'll get menu options on the right-click menu for any code box that allows you to scrub based on one of the axes of the controller. In the future, we might do the same based on these as well.

5 — Some "Time Markers"

Time "markers", visually, are simply vertical points in the canvas that you want to mark. But they also can have keyboard shortcuts assigned to them, and durations governing how long the time slider will take to get there: see their "inspectable properties" in the Inspector window. See the SimpleProcessingTutorial for some examples.

Note that by default their "durations" are in frames, but they can also be in seconds (that is, in real time). When a timeline is animating, the caps lock key can be used to slow down (to a third) the speed of the process. For better live control, see the ScrubberPlugin.

6 — A "mixed" element

See BasicDrawing. This is an element that has multiple kinds of behavior "mixed in", it's both a plain visual element and one with some spline drawing help installed. This, and some of your own library functions for decorating things, is a good way of making notational systems.

7 — Embedded GUI elements

Just as you can embed GUI elements inside the TextEditor, you can also embed sliders &c inside the canvas itself — see EmbeddingGuiOnCanvas. (For developers, the source is OutputInsertsOnSheet).