Param AsText syntax

Documentation | Other Specifications | AsText syntax

Styling parameters have a number of AsText properties like TGIS_ParamsLine.WidthAsText or TGIS_ParamsLine.ColorAsText, which are designed to easily define a parameter using common names, measurement units (like point, pixels, inches, etc.), and field values.

As the name suggests, the parameter value specification is in a textual form.

All parameter names are case-insensitive (except file names, which on a non-Windows machine can be case sensitive). So, the following code has the same meaning:

Layer.Labels.PositionAsText = "STOCK:upleft:upright"
Layer.Labels.PositionAsText = "stock:upleft:upright"
Layer.Labels.PositionAsText = "STOCK:UPLEFT:UPRIGHT"

Size parameters are parameters like TGIS_ParamsLine.WidthAsText property, TGIS_ParamsLabel.FontSizeAsText property, TGIS_ParamsMarker.SizeAsText property, etc.

There are two basic types of units: scalable and non-scalable:

• Non-scalable units are designated to specify features to be an exact size.
• Scalable parameters will scale upon map zooming. If the map scale = 1 and a feature is defined as 1cm, then the future on a screen will be rendered as 1cm.

Supported non-scalable units are:

• hair
  thinnest possible feature (hairline) to be used on a current device; should be used standalone (w/o any numeric value); this is a device dependent unit,
• px
  number of pixels; this is a device dependent unit,
• dip
  number of device independent pixels; 1 dip = 1 px on 96 DPI screen,
• twips
  number of twips; 1 twip = 1/1400 of an inch; this is a device independent unit,
• pt
  typographical point; 1 point = 1/72 of an inch; this is a device independent unit.

Supported scalable units are:

• in
  inch,
• ft
  U.S. survey foot,
• yd
  US survey yard,
• mi
  U.S. survey mile,
• mm
  millimeter,
• cm
  centimeter,
• m
  meter,
• km
  kilometer,
• nm
  nautical mile,
• mu
  map units; a special case - feature is not dependent on map scale but on map units; used mostly for CAD file rendering.

To specify values directly:

"SIZE:value"

Where:

• value
  is a definition of feature size.

For example:

// make a line 7.5 typographical point wide
Layer.Params.Line.WidthAsText = "SIZE:7.5 pt"
 
// make a line hairline width
Layer.Params.Line.WidthAsText = "SIZE:HAIRLINE"
 
// make a line on all devices to look like 4 pixels wide
Layer.Params.Line.WidthAsText = "SIZE:4 dip"
 
// make a line 3.3 inches wide and scalable
Layer.Params.Line.WidthAsText = "SIZE:3.3 in"
 
// spaces and text case is not significant
Layer.Params.Line.WidthAsText = "SIZE:3.3IN"

To specify that a feature should use the size from an attribute field:

"FIELD:field_name:base_value"

Where:

• field_name
  is the name of an attribute field,
• base_value
  is a definition for how 1 unit from the attribute field should be represented.

For example:

// read value from 'myfield' and multiply it by 0.6 pixels
Layer.Params.Line.WidthAsText = "FIELD:myfield:0.6 px"

To specify that a feature should use size attached by the renderer, simply:

Layer.Params.Line.WidthAsText = "RENDERER"

Measurement is quite similar to Size, but is designed for parameters like TGIS_ParamsSection.FalseZ property and TGIS_ParamsSectionVector.FalseM property.

Supported units are :

• in
  inch,
• ft
  U.S. survey foot,
• yd
  US survey yard,
• mi
  U.S. survey mile,
• mm
  millimeter,
• cm
  centimeter,
• m
  meter,
• km \ kilometer,
• nm
  nautical mile.

All units are not scalable.

To specify values directly:

"SIZE:value"

Where:

• value
  is a definition of feature size.

For example:

// make a FalseZ a 4.2 km 
Layer.Params.FalseZAsText = "SIZE:4.2 km"
 
// spaces and text case are not significant
Layer.Params.FalseZAsText = "SIZE:4.2KM"

To specify that a feature should use size from an attribute field:

"FIELD:field_name:base_value"

Where:

• field_name
  is the name of an attribute field,
• base_value
  is a definition for how 1 unit from the attribute field should be represented.

For example:

// read value from 'myfield' and multiply it by 15 feet
Layer.Params.FalseZAsText = "FIELD:15 ft"

Not supported.

Rotation parameters are parameters like TGIS_ParamsMarker.SymbolRotateAsText property or TGIS_ParamsLabel.RotateAsText property.

Supported units are:

• deg
  degrees,
• rad
  radians.

To specify values directly:

"ANGLE:value"

Where:

• value
  is a definition of a feature rotation.

For example:

// make symbol rotated by 45 degrees
Layer.Params.Marker.SymbolRotateAsText = "ANGLE:45 deg"
 
// spaces and text case are not significant
Layer.Params.Marker.SymbolRotateAsText = "ANGLE:45DEG"

To specify that a feature should use rotation from an attribute field:

"FIELD:field_name:base_value"

Where:

• field_name
  is the name of an attribute field,
• base_value
  is a definition for how 1 unit from the attribute field should be represented.

For example:

// read value from 'myfield' and multiply it by 0.1 radians
Layer.Params.Marker.SymbolRotateAsText = "FIELD:myfield:0.1 rad"

To specify that a feature should use rotation attached by the renderer, simply:

Layer.Params.Marker.SymbolRotateAsText = "RENDERER"

Color parameters are parameters like TGIS_ParamsFeature.ColorAsText property or TGIS_ParamsLabel.FontColorAsText property.

To specify values directly:

"ARGB:value"

Where:

• value
  is a definition of a color represented as hexadecimal AARRGGGBB (alpha-red-green-blue)

For example:

// make color yellow
Layer.Params.Area.ColorAsText = "ARGB:FFFFFF00"

To specify that a feature should use color from an attribute field:

"FIELD:field_name[:subtype]"

Where:

• field_name is the name of an attribute field,
• subtype is the optional color format (BGR, ARGB, ABGR, RGB, CSS)

For example:

// read BGR value from 'myfield'
Layer.Params.Area.ColorAsText = "FIELD:myfield"

// read ARGB value from 'myfield'
Layer.Params.Area.ColorAsText = "FIELD:myfield:ARGB"

To specify that a feature should use a color attached by the renderer, simply:

Layer.Params.Area.ColorAsText = "RENDERER"

Lines parameters are parameters like TGIS_ParamsLine.StyleAsText property.

To specify values directly:

"SYMBOL:symbol_definition"
"CODE:&line_symbology"
"STOCK:build_in_values"

Where:

• symbol_definition
  names of symbols are the same as in TGIS_SymbolList.Prepare(String) method,
• line_symbology
  line definition specified according to Extended line symbology,
• build_in_values
  predefined styles: SOLID, DASH, DOT, DASHDOT, DASHDOTDOT, and CLEAR.

For example:

// make a line from a font symbol (character code 65)
Layer.Params.Line.StyleAsText = "SYMBOL:Arial:65:BOLD:ITALIC:UNDERLINE"
 
// make a line advanced styled
Layer.Params.Line.StyleAsText = "CODE:&LINE(100%)GOTO(0%)MOVE(80S 0)FOR(100%)FILL(0 0 -80S -40S 0 80S 80S -40S)MOVE(240S 0)END()"
 
// make a line dotted
Layer.Params.Line.StyleAsText = "STOCK:DOT"

To specify that a feature should use a line style from an attribute field:

"FIELD:field_name"

Where:

• field_name
  is the name of an attribute field,

For example:

// read value value from 'myfield'
Layer.Params.Line.StyleAsText = "FIELD:myfield"

Supported values are limited to stock values: SOLID, DASH, DOT, DASHDOT, DASHDOTDOT, and CLEAR.

Not supported.

Fill parameters are parameters like TGIS_ParamsFeature.PatternAsText property or TGIS_ParamsFeature.PatternAsText property .

"SYMBOL:symbol_definition"
"STOCK:build_in_values"
"TEXTURE:texture_file_name"

Where:

• symbol_definition
  names of symbols are the same as in TGIS_SymbolList.Prepare(String) method,
• build_in_values
  predefined styles: SOLID, BDIAGONAL, FDIAGONAL, CROSS, DIAGCROSS, HORIZONTAL, VERTICAL and TRANSPARENT,
• texture_file_name
  texture file name.

For example:

// make an area to be filled with a SVG symbol
Layer.Area.PatternAsText = "SYMBOL:mysymbol.svg"
 
// make an area to be filled with a cross pattern
Layer.Area.PatternAsText = "STOCK:CROSS"
 
// make an area to be filled with a bitmap
Layer.Area.PatternAsText = "TEXTURE:mybitmap.bmp"

Not supported.

Not supported.

Marker style parameters are specific only to TGIS_ParamsMarker.StyleAsText property.

Where:

• symbol_definition
  names of symbols are the same as in TGIS_SymbolList.Prepare(String) method,
• build_in_values
  predefined styles: BOX, CIRCLE, CROSS, DIAGCROSS, TRIANGLEUP, TRIANGLEDOWN, TRIANGLELEFT, and TRIANGLERIGHT.

For example:

// make a marker to be rendered as a SVG symbol
Layer.Marker.StyleAsText = "SYMBOL:mysymbol.svg"
 
// make a marker to be rendered as a circle
Layer.Marker.StyleAsText = "STOCK:CIRCLE"
 
// make a marker to be rendered from ther LIBSVG library
Layer.Marker.StyleAsText = "SYMBOL:LIBSVG:std:Apartment01"

Not supported.

Not supported.

Label position are specific only to |.

"STOCK:built_in_values"

Where:

• built_in_values
  predefined values: UPLEFT, UPCENTER, UPRIGHT, MIDDLELEFT, MIDDLECENTER, MIDDLERIGHT, DOWNLEFT, DOWNCENTER, DOWNRIGHT, FLOW, and ANY;
  any combination of predefined values cane used, like UPLEFT:UPCENTER:UPRIGHT.

For example:

// make a label on the left or on the right
Layer.Labels.PositionAsText = "STOCK:UPLEFT:UPRIGHT"

To specify that a feature should use label position setup from an attribute field:

"FIELD:field_name"

Where:

• field_name
  is the name of an attribute field,

For example:

// read value from 'myfield'
Layer.Labels.PositionAsText = "FIELD:myfield"

Supported values are limited to stock values: UPLEFT, UPCENTER, UPRIGHT, MIDDLELEFT, MIDDLECENTER, MIDDLERIGHT, DOWNLEFT, DOWNCENTER, DOWNRIGHT, FLOW, and ANY.

Not supported.

NEW (available from version 103)

ColorRamp strings are used in properties such as TGIS_ParamsRender.ColorRampAsText property, TGIS_ParamsRender.ColorRampExAsText property, TGIS_ParamsPixel.ColorRampAsText property, etc.

"COLORRAMP:ramp_name[ramp_definition]:color_map_mode:sub_class:reverse:map_type"

Where:

• ramp_name
  (required) Name of a built-in color ramp (from TGIS_Utils.GisColorRampList property), or a custom ramp name if ramp_definition is provided.
• ramp_definition
  (optional) Color ramp definition in the string format of the TGIS_ColorMapArray type, or empty. If ramp_name refers to a custom ramp, ramp_definition must be provided. For built-in ramps, this parameter should be empty.
  
  

  [index1|color1|index2|color2|...|indexN|colorN] 

  • index
    A position along the color ramp range, normalized to the 0–100 scale. For example, 0 = start color, 100 = end color. Decimals (e.g., 33.3) are allowed.
  • color
    Color corresponding to the given index. Colors can be defined in any string format supported by the TGIS_Color.FromString method.

• color_map_mode
  (optional) Determines how the ramp is generated by the TGIS_GradientMap.RealizeColorMap method. See the TGIS_GradientMap.DefaultColorMapMode property.
  Possible values: Continuous (default), Discrete, or empty (use default).
• sub_class
  (optional) Number of colors used from the built-in color ramp. Default is 0, which uses the ramp's default representation. See the TGIS_GradientMap.DefaultSubClass property.
• reverse
  (optional) Reverse flag. If True, the color ramp colors are reversed. See the TGIS_GradientMap.DefaultReverse property.
  Possible values: False (default), True, or empty (use default).
• map_type
  (optional) Color scheme of the color ramp. Only used with custom ramps. Ignored for built-in ramps. See the TGIS_GradientMap.MapType property.
  Possible values: Miscellaneous (default), Diverging, Qualitative, Sequential, or empty (use default).

For example:

// Built-in color ramp with default parameters
layerVector.Params.Render.ColorRampAsText = 'COLORRAMP:Oranges';
 
// Built-in color ramp with ColorMapMode=Discrete, SubClass=8, Reverse=True
layerVector.Params.Render.ColorRampAsText = 'COLORRAMP:ACCENT:DISCRETE:8:TRUE';
 
// The same built-in color ramp with only Reverse=True; other parameters left empty to use default values
layerVector.Params.Render.ColorRampAsText = 'COLORRAMP:ACCENT:::TRUE';
 
// Built-in color ramp with ColorMapMode=Discrete, SubClass=3, Reverse=True
layerVector.Params.Render.ColorRampExAsText = 'colorramp : bluegreen : discrete : 3 : true';
 
// Custom color ramp (with name) made of 3 colors: red, lime, and #0000FF with ColorMapMode=Continuous, SubClass=0, Reverse=False, and MapType=Sequential
layerVector.Params.Render.ColorRampExAsText = 'COLORRAMP:Custom[0|red|50.123456789|lime|100.0000|#0000FF]:Continuous:0:false:Sequential';
 
// Unassign ColorRamp property (no ramp)
layerVector.Params.Render.ColorRampAsText = '';
 
// Custom color ramp (without name) made of 2 colors: black and white with ColorMapMode=Discrete
layerPixel.Params.Pixel.ColorRampAsText = 'COLORRAMP:[0|black|100|white]:Discrete';
 
// The same custom color ramp but with only MapType=Qualitative; other parameters left empty to use default values
layerPixel.Params.Pixel.ColorRampAsText = 'COLORRAMP:[0|black|100|white]::::Qualitative';

Not supported.

Not supported.