Element: graphic_window.annotation_layer

Type

layer

Description

The layer containing any autotext annotation for the window. This layer, like all layers, is a member of the window.layers[] array, and it follows all vector layers in the layer order. Its position in the layer order may be changed if required. It is created automatically when a window is created.

The annotation layer contains a list of groups to be annotated when the window is repainted. When the layer is painted each group in the list is processed and enitries within it are annotated according to entity class rules. Each group in the group list must correspond to a group in a preceding vector layer. If there is a group in the list for which there is no vector layer, or if its vector layer follows the annotation layer in the layer order, the group is ignored (not annotated).

New graphic windows have an empty annotation group list, implying no autotext annotation is required.

When a graphic primitive (an entity) within a group is auto-annotated, its class is checked for a .autotext definition. If such a definition is found it is evaluated. The evaluation will determine what the label text (if any) is for the entity, and whether there are any rules or hints for its positioning. If an entity has no class .autotext definition, it is not labelled. Only entities which are user-structures (compounds or gstructures) can be auto-annotated. Simple entities cannot be auto-annotated.

Sometimes the evaluation of an .autotext definition requires a reference to the window being annotated. A system identifier label_window is available specifically for this purpose.

Text items drawn by the autotext annotation process are not held persistently, but of course remain on the window's save-under until the window is next refreshed.

Painting of an annotation layer may be suppressed either by marking the layer as suppressed, or by setting label viewing thresholds on individual vector layers so that annotation is done only within specified window scales, see layer.label_thresholds.

Groups may also be auto-annotated manually via the window.annotate procedure, typically called within a window's post-redraw callback. With this manual method no scale checking is done, and any group (not only vector layers) may be processed, but the manual method is slower in performance.

See Also