Graphics interface between C++ and <class style="font-variant: small-caps">Scheme</class> (FSF GNU project)

Graphics interface between C++ and Scheme

Rationale

TeXmacs both implements a low-level part of the graphics in C++ and the high-level user interface in Scheme. This API describes how both parts interact.

The low-level C++ mainly takes care of transforming the graphical markup in a typesetted box. It also provides routines for translating between physical coordinates (relative to the window) into logical coordinates (the local coordinate system of the graphics) and routines for interacting with the typesetted boxes (finding the closest objects to a given point or region or projecting a point on a grid).

Definitions

Editor coordinates: The coordinates of the outermost typesetted box. Mouse events are typically passed in these coordinates. The corresponding data type is SI.
Graphics coordinates: The coordinates of the innermost graphics corresponding to the current cursor position.
Grid: The current grid relative to the graphics for editing objects (this grid may theoretically be different from the grid which is displayed). The current grid consists both of a mathematical type of grid (no grid, cartesian grid, polar grid, etc.), together with special points which correspond either to control points, intersections of curves with the grid, intersections of curves, or self-intersections of curves.
Grid point: A point on the grid is a triple (p distance type), where p is a point in graphics coordinates, distance its distance to the point which was projected on the grid (see grid-project below) and type the type of grid point with a potential origin. For instance, type can be plain or someting like (control t) for a control point corresponding to the tree t in the document.

Coordinate transformations

(editor->graphics p)

(get graphics coordinates)

Transform a point p of the form (x y) from the editor coordinates into the graphics coordinates.

(graphics->editor p)

(get editor coordinates)

Transform a point p of the form (x y) from the graphics coordinates into the editor coordinates.

Grid routines

(grid-project p)

(project point on grid)

Given a point p (in graphics coordinates), find its projection on the current grid, the distance part of the projection being the distance between p and its projection.

Note: the routine grid-project can also be used in order to find editable shapes and groups close to the current pointer position. Indeed, the corresponding control points are understood to lie on the grid in our sense.

(grid-point-pertinence<? p q)

(grid-point-pertinence<=? p q)

(order by pertinence)

Grid points are ordered by pertinence as a function of type and distance. For instance, control points have higher pertinence than plain grid points and closer grid points are considered better than farther ones.

Selection of shapes

(graphics-find-disk p r)

(search shapes in disk)

Return the list of all trees in the graphics which intersect a disk with center p and radius r (in graphics coordinates).

(graphics-find-rectangle p q)

(search shapes in rectangle)

Return the list of all trees in the graphics which intersect a rectangle with corners p and q (in graphics coordinates).

Computations with shapes

(box-info t)

(get bounding box for a shape)

Get a bounding box (and other information) about a shape t. t can be a tree or a scheme tree.

Remark 1. This section might be extended, since a lot of the graphical intelligence is implemented in the C++ code. For instance, we might want to compute the intersections of two curves inside the Scheme code. Also, when we will allow for user macros, we might want routines which return the graphical expansion of the macro (the constituent elementary shapes, i.e. polylines, splines, etc.).

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".