Next / Previous / Contents / TCC Help System / NM Tech homepage

6.1. Canvas concepts

Before we discuss the methods on canvases, we need to define some terms:

6.1.1. Canvas and window coordinates

Because the canvas may be larger than the window, and equipped with scrollbars to move the overall canvas around in the window, there are two coordinate systems for each canvas:

  • The window coordinates of a point are relative to the top left corner of the area on the display where the canvas appears.

  • The canvas coordinates of a point are relative to the top left corner of the total canvas.

6.1.2. The display list; “above” and “below”

The display list refers to the sequence of all the objects on the canvas, from background (the “bottom” of the display list) to foreground (the “top”).

If two objects overlap, the one above the other in the display list means the one closer to the foreground, which will appear in the area of overlap and obscure the one below. By default, new objects are always created at the top of the display list (and hence in front of all other objects), but you can re-order the display list.

6.1.3. Object ID

The object ID of an object on the canvas is the value returned by the constructor for that object. All object ID values are simple integers, and the object ID of an object is unique within that canvas.

6.1.4. Canvas tags

A tag is a string that you can associate with objects on the canvas.

  • A tag can be associated with any number of objects on the canvas, including zero.

  • An object can have any number of tags associated with it, including zero.

Tags have many uses. For example, if you are drawing a map on a canvas, and there are text objects for the labels on rivers, you could attach the tag "riverLabel" to all those text objects. This would allow you to perform operations on all the objects with that tag, such as changing their color or deleting them.

6.1.5. Canvas tagOrId arguments

A tagOrId argument specifies one or more objects on the canvas.

  • If a tagOrId argument is an integer, it is treated as an object ID, and it applies only to the unique object with that ID.

  • If such an argument is a string, it is interpreted as a tag, and selects all the objects that have that tag (if there are any).