 |
Low level graphics manipulation |  |
Rationale
TeXmacs provides a small low-level library for the manipulation of graphics on top of the usual tree interface. One particularity of graphics operations is that they usually concern a large number of continuous changes (as a function of mouse movement) to one or more objects (under construction or being edited). On the one hand, this means that not all movements have to be undoable. On the other hand, this implies that some optimizations may be necessary to obtain a reasonable speed.
For these reasons, the library allows the programmer to focus attention on one or several objects in a graphics and to quickly perform operations on these objects. Focus is mostly understood to be temporary: typically, the focus is released as soon as an operation has been completed, i.e. the construction of a polyline.
From the implementation point of view, the selected objects may either be removed from the document (current implementation), or kept in the document (future implementation), while displaying them on top of the other objects (if necessary).
Definitions
- Tree
- As in the main tree API. There are three main types of trees with graphical markup: graphics, shapes and groups.
- Enhanced tree
- Trees with graphical markup can be enhanced to provide additional properties for the markup by means of with tags. For instance, an "enhanced shape" (see below) might be a polyline together with a particular color and line width.
- Radical and properties
- In the case of an enhanced tree of the form (with props* object), object is called the radical of the enhanced tree and props* the properties of the enhanced tree. Notice that an enhanced tree is allowed to be reduced to its radical, in which case it has no properties.
- Graphics
-
This term corresponds to the main graphics, which is an ordered list of enhanced shapes or groups. Enhancements for the main graphics can be divided in two categories:
- Global properties for the graphics itself, e.g. rendering properties, or a background grid.
- Editing properties, which control the current editing behaviour of the graphics (polyline mode, current pen colour, etc.).
- Shape
- A shape is an atomic graphical markup primitive, such as a polyline. Typical enhancements for shapes are pen color, fill color, line width, arrow mode, etc.
- Group
- A group is an ordered list of enhanced shapes or groups. The possible enhancements for groups are the same as the ones for shapes (and, in this respect, groups therefore differ from graphics).
- Sketch
-
The current sketch corresponds to a single or ordered list of enhanced shapes or groups on which the graphical editor is currently operating. There are two main modes for the sketch:
- SELECTING
- the sketch corresponds to a selection of enhanced shapes or groups in the main document.
- MODIFYING
- the sketch corresponds to a single or ordered list of enhanced shapes or groups which are being constructed or modified. The trees in the sketch can be new trees or trees which correspond to marked (invisible) trees in the main document.
The current sketch is usually displayed on top of all other graphics, together with several control points.
Manipulation of enhanced trees
Given an enhanced tree t, return its radical.
Given a radical t, find its parent which corresponds to its largest enhancement. If t does not belong to a TeXmacs document, this routine returns #f.
(enhanced-tree-set! t p* u)
(enhanced-tree-ref t p*)
These routines are similar to tree-set, tree-set!, etc. except that they operate on the radical of the enhanced tree.
Given an enhanced tree t, overide its properties with the elements in the association list l.
Obtain an association list with all properties of the enhanced tree t.
Set the property var of an enhanced tree t to val.
Obtain the property var of an enhanced tree t.
Sketch manipulation
Return the current sketch tree.
Put a new tree in the sketch, which is not part of the document. This routine is typically called when starting the construction of a new enhanced shape.
Assign the sketch which a tree t which is part of the document (and maintain the correspondance between t and the sketch). This routine is typically called when editing an enhanced shape.
Assign the sketch with an empty group of objects. This routine is typically called before starting the selection of a group of objects.
When the sketch is an enhanced group, this routine toggles whether a tree t in the document belongs to the group (and we maintain the correspondance between t and the corresponding subtree in the sketch). This routine is typically called when selecting a group of objects.
Enter MODIFYING mode and potentially disable the counterparts of the trees in the sketch in the main document.
Commit changes made to the sketch in MODIFYING mode and return to SELECTING mode.
Cancel any changes made to the sketch in MODIFYING mode and return to the state of the document before the call of sketch-checkout.
Misscelaneous
Assign a list of markup objects with control ornaments to the current sketch. The ornaments are rendered on top of the sketch as a visial aid for the user. Typically, when editing a polyline, l consists of a list of control points.