Element: graphic_window.annotate ( )

Syntax

<window>.annotate(<group> {, <group>...})

Type

procedure

Description

A procedure to add annotation text (also known as labels) to graphic primitives. This is typically called within the window's post-redraw callback. This is a manual method of invoking autotext. There is an automatic autotext system which has improved performance, see window.annotation_layer

Text items drawn by this procedure are not held persistently, but of course remain on the window's save-under until the window is next refreshed, at which point the post-redraw callback will again invoke the procedure.

The procedure takes as parameters one or more entity groups, the contents of which are to be annotated according to class rules. The annotation of groups is done in the parameter order, irrespective of where the groups are in the window's group order.

With this method auto-annotation will always be performed. In contrast, when groups are annotated via the window.annotation_layer a check is made to see if any of the groups to be annotated have associated vector layers. For those which do, the current window meter scale is checked against the layer's label thresholds, and only if the current meter scale is within these thresholds will the group member entities be labelled.

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.

The code of the function cannot be redefined. Since it is a procedure, this function has no return value.

Parameters

The function may be called in one of two ways:

# Assume mywin is the graphic window identifier, streets and parks are groups
window.annotate(mywin,streets,parks)

or

mywin.annotate(streets,parks)

Example

Imagine a graphic window which displays a map of parks, rivers and streets. The following sequence of commands might be used to annotate it. The autotext definitions, which when evaluated help the system decide what is going to be labelled and where, have not been included in the code.

# Create the graphic window
window gw = wgraphic
group parks,rivers,streets,-lay
# Indicate the vector layers, by defining the group order
gw.group_order = <parks,rivers,streets>
# Specify the order of autotext annotation
gw.post_redraw = {
   args w=window
   w.annotate(streets,rivers,parks)
}

An alternative method, using the window's annotation layer will improve performance:

# Create the graphic window
window gw = wgraphic
group parks,rivers,streets,-lay
# Indicate the vector layers, by defining the group order
gw.group_order = <parks,rivers,streets>
# Specify the order of autotext annotation
gw.annotation_layer.group_order = <streets,rivers,parks>