Set Map Layer Gridline - MapBasic - 2023

This section describes how to set gridline functionality. Gridlines are the visual lines separating rows and columns in the Layout window. You would use a grid to align the position of layout frames in the Layout window.

Syntax

Set Map 
	[ Window window_id ] 
	[ Layer layer_id
	Gridline 
		[ Spacing
			[ [ Horizontal [ x_map ] [ Min x_paper Units x_paper_units ] ]
			[ Vertical [ y_map ] [ Min y_paper Units y_paper_units ] ] ] |
			[ Auto [ Horizontal x_paper Units x_paper_units ]
			[ Vertical y_paper Units y_paper_units ] ] ]
		[ Offset value Units paper_units ]
		[ Label [ Left | Right | Top | Bottom | None ] [ Directionality [ Compass | Plusminus ] ] ]

window_id is the integer window identifier of a Map window.

layer_id is a number identifying a map layer to modify, according to that layer's original position in the map, where 1 (one) is the top-most layer number (the layer which draws last, and therefore always appears on top).

x_map is a value, in paper units, to set exact horizontal gridline spacing that does not change as you zoom.

x_paper is a value, in paper units, for spacing the horizontal gridlines.

x_paper_units is a string representing a paper unit name: cm (centimeters), mm (millimeters), in (inches), pt (points), and pica.

y_map is a value, in paper units, to set exact vertical gridline spacing that does not change as you zoom.

y_paper is a value, in paper units, for spacing the vertical gridlines.

y_paper_units is a string representing a paper unit name: cm (centimeters), mm (millimeters), in (inches), pt (points), and pica.

value is in paper units and the default is 5 points.

paper_units is a string representing a paper unit name: cm (centimeters), mm (millimeters), in (inches), pt (points), and pica.

• 1 inch (in) = 2.54 centimeters , 254 millimeters, 6 picas, 72 points
• 1 point (pt) = 0.01389 inches, 0.03528 centimeters, 0.35278 millimeters, 0.08333 picas
• 1pica = 0.16667 inches, 0.42333 centimeters, 4.23333 millimeters, 12 points
• 1 centimeter (cm) = 0.39370 inches, 10 millimeters, 2.36220 picas, 28.34646 points
• 1 millimeter (mm) = 0.1 centimeters, 0.03937 inches, 0.23622 picas, 2.83465 points

Description

The Horizontal and Vertical clauses for map spacing are applied whether or not the Gridline clause is set for automatic (Auto) spacing. If Gridline is set for automatic spacing, then it gets an exact spacing value. It recalculates pixel spacing based on the actual map Gridline spacing and uses this for future map zooms. If Gridline is not set for automatic spacing, then the Horizontal and Vertical values become the new map spacing values to use.

If Min spacing values are entered, then automatic gridline spacing is turned off. If Auto is set, then automatic gridline spacing is turned on.

The Auto clause sets automatic spacing. Use its Horizontal and Vertical subclauses to supply spacing values in paper units. The function uses the paper spacing settings and the map at the current zoom to determine what map spacing to use. The Auto clause maintains the gridline spacing even when zooming.

For exact gridline spacing that does not change as you zoom, then use the x_map and y_map values instead of the Auto clause. However, this can generate closely spaced gridlines, such as when setting the spacing to work at the city level and then zooming out to see the entire country, and slows performance. To prevent an unusable map, because gridline spacing is too small when zooming out, gridlines are automatically adjusted to be further apart based on a minimum paper unit value.

The Offset value is the offset of the gridline label from the edge of the map (inwards). The value is in paper units and the default is five (5) points. This differs from the existing Label Offset, which is also used by gridline to offset the gridline label from the gridline itself (either above or below the horizontal gridline, or to the left or right of vertical gridlines).

The Label value sets where gridline labels display on the map using a position clause:

• Left labels horizontal gridlines on the left side of the map.
• Right labels horizontal gridlines on the right side of the map.
• Top labels vertical gridlines on the top of the map.
• Bottom labels vertical gridlines on the bottom of the map.
• None ensures that no labels display for gridlines.

Label Directionality applies to gridlines using a Latitude/Longitude coordinate system. Use the Compass clause for labels that have a compass direction, north (N), south (S), east (E), or west (W), appended to them to set the world hemisphere that they are in. Use the Plusminus clause to pre-append a minus sign to the label to set the hemisphere it is in.

Set Map Layer when the Gridline is a Layer

This section describes the functionality that exists with the Set Map Layer statement when the layer is a Gridline layer. All of the below subclauses are prefixed by:

Set Map [Window window_id] Layer layer_id

Layer

When working with Gridlines the following are:

• Editable { On | Off }

  Not allowed and generates an error.

• Selectable { On | Off }

  Not allowed and generates an error. All gridlines have their styles changed as a single unit.

• Zoom ( min_zoom, max_zoom ) [ Units dist_units ] [ { On | Off } ]

  Allowed and useful for non-automatic spaced Gridlines.

• Arrows { On | Off }

  Not allowed and produces an error.

• Centroids { On | Off }

  Not allowed and produces an error.

• Default Zoom

  Not allowed and produces an error.

• Nodes { On | Off }

  Not allowed and produces an error.

• Inflect num_inflections [ By Percent ] At color:value [ , color:value ]

  Not allowed, this only works for certain layer types (such as grid, raster, WMS, Tile Server) not Gridlines. It will do nothing or generate an error.

• Contrast contrast_value

  Not allowed, this only works for certain layer types not Gridlines. It will do nothing or generate an error.

• Brightness brightness_value

  Not allowed, this only works for certain layer types not Gridlines. It will do nothing or generate an error.

• Alpha alpha_value

  Translucency translucency_value

  Allowed.

Layer Label

When working with Gridlines the following are:

• Line { Simple | Arrow | None }

  Not allowed, this defaults to None and trying to set it generates an error.

• Position [ Center ] [ { Above | Below } ] [ { Left | Right } ]

  Allowed and it acts as it would for any label.

• Auto Retry { On | Off }

  Not allowed and generates an error.

• Font ...

  Allowed.

• Pen ...

  Allowed, but since there are no callouts this does nothing.

• With label_expr

  Not allowed and generates an error.

• Parallel { On | Off }

  Allowed. The vertical gridline labels rotate 90 degrees to be parallel with the Gridline.

• Follow Path [ BestPosition { On | Off } ] [ Percent Over percent ] [ Fallback { On | Off } ]

  Allowed.

• Visibility { On | Off | Zoom ( min_vis, max_vis ) [Units dist_unit  ] }

  Allowed and useful to also turn on or off custom labels.

• Auto { On | Off }

  Allowed. Only turns on or off automatic labels.

• Overlap { On | Off }

  Allowed. Overlapping labels for Gridlines is off by default.

• PartialSegments { On | Off }

  Not allowed and generates an error. Labels for partial segments is turned on by default. Labels are at the beginning of the line instead of the middle.

• Duplicates { On | Off }

  Not allowed and generates an error. It is set to on by default (allowing duplicates). Depending on the coordinate system, location on the Earth, and label formatting, horizontal gridline labels could be the same as vertical gridline labels. Also, you can enable labeling at both ends of a Gridline (both left and right edges, top and bottom edges), which always results in duplicates. You cannot turn duplicates off for Gridlines.

• Max [ number_of_labels ]

  Allowed.

• Offset offset_amount

  Allowed and is the default of 2 points (units are always points). This is the offset value for Gridline labels from the gridline itself: either above or below for horizontal gridlines, or to the left or right of vertical gridlines.

• Default

  Allowed, but does nothing for Gridlines. The operation removes custom labels and restores the default automatic label, but we do not allow custom labels for Gridlines.

• LabelAlpha alpha_value

  Allowed.

• AutoPosition { On | Off }

  AutoSizes { number_font_sizes | Default }

  SuppressIfNoFit { On | Off }

  AutoCallout { On | Off }

  Allowed for regions. These options have no effect on Gridline layers that are Polylines.

• Abbreviation { On | Off } Abbreviate with { field_expression }

  Not allowed and generates an error.

• Object

  (and anything that follows)

  Allowed and signifies a custom label. You cannot work with custom labels and Gridlines, doing so generates an error.