Element: compound.autotext, gstructure.autotext

Type

callback

Syntax

<class>.autotext = "{"
   <name> = <value>
   ...
"}"

Description

This element is not strictly a callback but is a set of rules describing how a compound (or gstructure) entity object should be auto-annotated. It is invoked by a graphic window's auto-annotation procedure (window.annotate).

Autotext definitions are defined at a class level, rather than on individual compound or gstructure objects. When auto-annotation is invoked for a graphic window it is applied to one or more entity groups. Each group is traversed for entities which are candidates for labelling. Only compound and gstructures are examined, and only those whose class has a .autotext definition become candidates. The .autotext definition is then evaluated for each candidate, i.e. a compound (or gstructure) object. The result of the evaluation process then determines whether the object is to be labelled, what the label text is, and what its symbology is. It is then drawn.

A.autotext definition comprises a set of assignments in the form of name=value statements. The assignments set properties which together determine the labelling process for the object.

Unlike other language callbacks, there are no macro statements in the definition, but the assigment values can contain function references which themselves may contain macro code. However for optimum performance, there should be as few references to the object (available via the this identifier) as possible, and function macro calls should be avoided. Assignments containing this are evaluated for every compound/gstructure object being labelled, other assignments are evaluated once only for each entity group being processed.

Before discussing the individual assignment options, here is a simple example which labels objects of a compound class:

# Define the class
atable maps
compound ~maps.park_t {
   entity e[]
   string name
}
# Define a textstyle
font ~maps.fntPark,'Arial,10',-sys,-var;# -var specified for scalable/rotatable text
textstyle ~maps.tsPark,-fo=~maps.fntPark,-su='p'
# Define how an object of this class is labelled
~maps.park_t.autotext = {
   text = this.name          ;# Evaluated for every object
   textstyle = ~maps.tsPark  ;# Evaluated once
   text_height = 10          ;# Evaluated once
}

The fewer assignments that are evaluated for every object (only 1 in our example), the quicker the auto-annotation process.

Options

All options are in the form of assignments: name=value.

Objects may be labelled with text and/or a symbol. The 2 rules determining this are as follows:

The object is labelled with text only if the text option is present and its value is not an empty string.

A symbol is displayed over the object if the symbol_text option is present. If a symbol is required without text, the symbol_text value should be a single space. The symbol is rendered using markerstyle symbol and the text (if any) is rendered over the symbol.

If neither of these rules are satisfied no labelling is performed.

Available options are as follows:

Example

Consider the following example to auto-annotate a road class:

road_t.autotext = {
# How to label road features
   text=this.m_street_name
   textstyle=tsRoad ;# a textstyle
   text_height=8
   line_position='m'
   clash_test=1
   symbol=^(road_markerstyle(this));# a string function returning a markerstyle name
   symbol_text=his.m_highway_number
   symbol_text_height=8
   symbol_textstyle=tsHighwaySignText;# a textstyle
}

Note that the values for text, symbol_text and symbol will be evaluated for every entity.

See Also

Commands:

font, markerstyle, textstyle,

Identifiers:

label_window

Structures:

layer.label_thresholds, window.annotate