AddAnnotation()

Summary

Adds an annotation to a map or layout window.

Changes

Added Temporary option to Version 6.0/2012. Removed Label option in Version 2018.

Syntax

id = AddAnnotation(string window_spec, string type, array spec)

Argument	Contents
window_spec	The type and name of the window containing the annotation
type	Annotation type
spec	An array of name-value pairs that define the annotation

Annotation Type	Window Type	Valid Specifications
Bitmap	Layout, map	Color, Editable, File, Location (2 coords on a layout, a scope on a map)
Circle	Layout, map	Editable, Fill Color, Fill Style, Line Color, Line Style, Line Width, Location (a circle)
Compass	Map	Color, Editable, Font, Index, Location (a scope)
Container	Layout	Editable, Location (2 coords)
Editor	Layout	Color, Drop Shadow, Editable, Font, Grid, Line Color, Line Style, Line Width, Location (2 coords), Shadow Color
Ellipse	Layout, map	Angle, Editable, Fill Color, Fill Style, Line Color, Line Style, Line Width, Location (2 coords on a layout, a scope on a map)
Figure	Layout	Drop Shadow, Figure, Line Color, Line Style, Line Width, Location (2 coords), Shadow Color, Wysiwyg
Font Character	Layout, map	Angle, Color, Editable, Font, Index, Location (a coord)
Legend	Layout, map	Editable, Location (a coord on a layout, a scope on a map), Name
Map	Layout	Always Redraw, Drop Shadow, Editable, Fixed Scale, Line Color, Line Style, Line Width, Location (2 coords), Map, Scope, Shadow Color, Wysiwyg
Polygon	Layout, map	Editable, Fill Color, Fill Style, Line Color, Line Style, Line Width, Points or Polygons
Polyline	Layout, map	Editable, From Arrow, Line Color, Line Style, Line Width, Points, Smooth, To Arrow
Rectangle	Layout, map	Angle, Editable, Fill Color, Fill Style, Line Color, Line Style, Line Width, Location (2 coords on a layout, a scope on a map), Rounded
Splined Text	Layout, map	Editable, Points, Font, Color, Text
Text	Layout, map	Angle, Color, Editable, Font, Framed, Frame Border Color, Frame Border Style, Frame Border Width, Frame Fill Color, Frame Fill Style, Frame Shield, Frame Type, Location (2 coords on layout, a scope on map or, for non-scaling text, a coord and an alignment string on map), Text
View	Layout	(Same as Editor, accepted for historical compatibility)

Specification	Type	Contents
Always Redraw	Boolean	Indicates whether to redraw a map annotation in a layout in response to layout changes (defaults to "False")
Angle	Real	The counterclockwise rotation angle from horizontal (defaults to 0)
Color	Color	The foreground color
Drop Shadow	Boolean	Indicates whether a drop shadow is displayed (defaults to "False")
Editable	Boolean	Indicates whether the annotation can be edited (defaults to "False")
Figure	String	The name of the figure
File	String	The path to the file containing the annotation
Fill Color	Color	The fill color
Fill Style	Fillstyle	The fill style
Fixed Scale	Boolean	Indicates whether the same map scale is used as in the original map window (defaults to "False")
Font	String	The name and size of the font
Framed	Boolean	Indicates whether a text item is displayed with a frame (defaults to "False")
Frame Border Color	Color	The frame border color
Frame Border Style	Linestyle	The frame border style
Frame Border Width	Real	The frame border width in points
Frame Fill Color	Color	The frame background color
Frame Fill Style	Fillstyle	The frame background fill style
Frame Shield	Array	The highway shield definition (string font_name, array of (integer index, color))
Frame Type	String	"Rectangle", "Rounded Rectangle", "Ellipse", "Shield"
From Arrow	Boolean	Indicates whether an arrow is drawn at the start of the polyline (defaults to "False")
Grid	Boolean	Indicates whether a grid is displayed (defaults to "False")
ID	Integer	ID of the feature to label
Index	Integer	The character value from the font; note that GetIcon() returns a real value for the Index array element that must be converted to an integer for use with this option
Layer	String	Name of the geographic layer containing the feature
Line Color	Color	The line or border color
Line Style	Linestyle	The line or border style
Line Width	Real	The line or border width in points
Location	Array	See table below
Map	String	The name of the map
Name	String	The name of the legend, a map (view) name that must be a map in the current layout
Points	Array	An array of coordinates, X and Y on a layout or longitude and latitude on a map
Polygons	Array	A 3-element array {integer num_polygons, array num_points, array coords} in the same format as the array to the AddArea() function
Rounded	Boolean	Indicates whether the rectangle has rounded corners (defaults to "False")
Scope	Scope	The scope of the map
Shadow Color	Color	The color of the drop shadow
Smooth	Boolean	Indicates whether the polyline is smoothed by fitting a spline (defaults to "False")
Temporary	Boolean	Indicates whether the annotation is temporary; When set to "True" the annotation will not be saved as part of the map or workspace nor be replicated with DuplicateMap() (defaults to "False")
Text	String	The actual text of a text annotation
To Arrow	Boolean	Indicates whether an arrow is drawn at the end of the polyline (defaults to "False")
Wysiwyg	Boolean	Indicates whether the contents of the map or figure added to the layout window are resized to look identical to the original map window (defaults to "True"); setting this to "False" is equivalent to using the "Use actual point sizes" option when inserting the map or figure into the layout

Location Type	Window Type	Comments
Scope	Map	A compound variable with a center, width, and height; the angle is ignored. Use Scope() or ClickRectScope() to create a scope
2 coords	Layout	Compound variables with an X and Y. Use Coord() to create a coord or ClickRect() to create a rectangle of 2 coords
A coord	Layout, map	A compound variable with an X and Y on a layout or a lon and lat on a map. Use Coord() or ClickCoord() to create a coord
A coord and an alignment string	Map	The coord is a compound variable with an X and Y on a layout or a lon and lat on a map; use Coord() to create a coord. The alignment string can be NW, N, NE, W, C, E, SW, S or SE
A circle	Layout, map	A compound variable with a radius and center. Use Circle() or ClickCircle() to create a circle

Returns

The integer id of the new annotation.

Notes

When adding annotations to a map, Location is in longitude and latitude values.
When adding annotations to a layout, Location is in X and Y values measured in hundredths of a printer's point (1/7200ths of an inch) from the upper-left hand corner of the layout.
Bitmaps are scaled to fit within the Location coordinates.
The annotation type of Bitmap can add JPEG files.
It is recommended that you keep the Always Redraw option set to "False" unless you find it essential to have the map redrawn, as this can be very time consuming depending on the size of the map and layout.
Circle annotations are converted and stored as Ellipses.
View annotations are returned with the type Editor and their font color is returned with the Font Color specification.
The Name specification for the Legend annotation type refers to a map (view) name, and it must be a map in the current layout. You can get the exact map name with GetAnnotations() or GetAnnotation().
For a full list of GISDK functions for annotations, see Freehand Items (Annotations).

Examples

id = AddAnnotation("Map|" + GetMap(), "Bitmap",

{{"File", "c:\\Program Files\\Maptitude\\bmp\\HABOUT.bmp"},

{"Location", GetMapScope(GetMap())}

})

window_name = "Map|" + GetMap()

option_array = {{"Location", Coord(-75000000,43000000)},

{"Font","Caliper Cartographic|14"},{"Index",53},

{"Color",ColorRGB(0,0,65535)}}

annotation_id = AddAnnotation(window_name,"Font Character",option_array)

Error Codes

Error Type	Meaning
NotFound	The specified window does not exist
Error	The annotation type or specification is invalid

Function	Summary
DropAnnotation()	Removes an annotation from a map or layout window
DropAnnotations()	Removes annotations from a map or layout window
DuplicateAnnotation()	Creates a copy of an annotation
GetAnnotation()	Returns the definition of an annotation
GetAnnotations()	Return the IDs of all annotations in a map or layout window
MoveAnnotation()	Moves an annotation to a new location
SetAnnotation()	Modifies an existing annotation in a map or layout window