User Tools

Site Tools


doc:labeling

This is an old revision of the document!


Label formatting

Documentation | Other Specifications | Label formatting

A simple markup language is used for custom label formatting.

  Citizens: <b>{POPULATION}</b>

As you see, a simple HTML-like markup and field attribute embedding ({FIELD}) is possible. Furthermore, a custom attribute formatting like {MYVALUE:#.00} is possible. See Formatting attributes

  Difference is <b>{{GIS_AREA-(MEDIAN(GIS_AREA)}:#.0}</b>

Field declaration within additional {..} is treated as a formula. In this example, a formula GIS_AREA - MEDIAN(GIS_AREA) is used to calculate a field value. A formula can include layer statics values and virtual fields (e.g. GIS_AREA, GIS_LENGTH, etc.). (Formulas are available since v11.29.0).

Field content of text fields is interpreted as a HTML. Therefore, any occurrence of '<.' or '>' characters are interpreted as HTML markup:

  • to properly display '<' or '>' characters , refer to the field as {!FIELD}; an exclamation mark forces a field to not be interpreted as HTML (Available since v11.13.0),
  • alternatively express '<' as '&lt;', and '>' as '&gt;'.

Visual formatting

The Editor supports some of the standard HTML markers for visual formatting:

  • <B></B>
    text inside is displayed in bold font.
  • <BOL></BOL>
    equivalent of <B></B> supported for compatibility with other GIS products.
  • <I></I>
    text inside is displayed in italic font.
  • <U></U>
    text inside is underlined.
  • <HR>
    horizontal line.
  • <BR>
    line break.
  • <P></P>
    text inside is treated as a complete paragraph.
  • <STRONG></STRONG>
    text inside is displayed in extra bold font.
  • <FONT SIZE=“S” NAME=“F” COLOR=“C”></FONT>
    text inside is displayed in the F font (e.g. ARIAL, TIMES, TAHOMA, etc) of the size S and the C color (where C can be one of the following: BLACK, BLUE, FUCHSIA, GRAY, GREEN, LIME, MAROON, NAVY, OLIVE, PURPLE, RED, SILVER, TEAL, WHITE, YELLOW); the C color can be also given in the RGB representation #RRGGBB, where RR, GG, and BB are two-digit hexadecimal number representations of the red, green and blue color intensities.
  • &amp;
    the & sign.
  • &nbsp;
    forced insertion of space.
  • &gt;
    the > sign.
  • &lt;
    the < sign.

Example:

<U><FONT NAME="ARIAL" COLOR=#FF0000><I>value1</I></FONT>&nbsp;
<FONT NAME="ARIAL" COLOR=#0000FF><B>&lt;</B></FONT>&nbsp;
<FONT NAME="ARIAL" COLOR=#00FF00><BOL>value2</BOL></FONT></U>

will result in the following label: value1 < value2 .

Formatting attributes

The code {FIELD_NAME:FORMAT} inserts the value of an attribute named FIELD_NAME with format specification defined by the format string FORMAT. The format string is attribute type specific.

It is possible to specify the way of displaying an attribute by defining its formatting.

Numbers

Automatic formatting

Format character Format name Description
C or c Currency Integer next to the character defines the number of most significant digits to be displayed.
D or d Decimal Integer next to the character defines the minimum number of digits to be displayed; the number will be padded with zeroes if necessary; the non-integral value will be rounded first.
E or e Scientific (exponential) Integer next to the character defines the number of digits displayed after the decimal point (default is 2); number formatted as Scientific is always displayed in exponential form;
F or f Fixed-point Integer next to the character defines the number of digits displayed after the decimal point (default is 2).
G or g General The Editor tries to display the number in best-suited form; Integer next to the character defines the number of significant digits.
N or n Number Integer next to the character defines the number of digits displayed after the decimal point (default is 2); inserts thousand separators accordingly to the system settings.
P or p Percent The number is multiplied by 100; i defines the number of digits displayed after the decimal point (default is 2).
R or r Round-trip Equivalent of General (for .NET compatibility only); Integer next to the character is ignored.
X or x Hexadecimal Integer next to the character defines the minimum number of hexadecimal digits to be displayed; the number will be padded with zeroes if necessary; a non-integral value will be rounded first;

Custom formatting

Format character Name Description
# Digit placeholder Defines an optional position of a digit; if the corresponding digit does not exist the digit placeholder is neglected.
0 Zero placeholder Defines an obligatory position of a digit; if the corresponding digit does not exist the zero placeholder is replaced by '0'.
. Decimal point Defines the position of the decimal point.
[other] Other characters are displayed without any change.

Examples:

Code Attribute value Result string Note
{FIELD_NAME:#.###} 123.59 '123.59'
{FIELD_NAME:#.000} 123.59 '123.590'
{FIELD_NAME:#.####0} 123.59 '123.59000'
{FIELD_NAME:#####.###} -123.59 '-123.59'
{FIELD_NAME:00000.###} 123.59 '00123.59'
{FIELD_NAME:0-0-0-0-0} 123.59 '0-0-1-2-4' rounding
{FIELD_NAME:over #;below #;zero #} 123.59 'over 124' rounding
{FIELD_NAME:over #;below #;zero #} -123.59 'below 124' rounding, no minus sign
{FIELD_NAME:over #;below #;zero #} 0 'zero ' no zero sign
{FIELD_NAME:over #;below #;zero 0} 0 'zero 0'
{FIELD_NAME:;below #;zero#} 123.59 '' empty string
{FIELD_NAME:over #;;zero#} -123.59 '' empty string
{FIELD_NAME:over #;below #;} 0 '' empty string

Boolean

Automatic formatting

Code Attribute value Result string
{FIELD_NAME} True 'True'
{FIELD_NAME} False 'False'

Examples:

Code Attribute value Result Note
{FIELD_NAME:yes;no} True 'yes'
{FIELD_NAME:yes;no} False 'no'
{FIELD_NAME:yes} True 'yes'
{FIELD_NAME:yes} False '' empty string
{FIELD_NAME:;no} True '' empty string
{FIELD_NAME:yes;} False '' empty string
{FIELD_NAME:yes;no1;no2} False 'no1;no2'

Date

Note: character in brackets represents a string consisting of any number of this character.

Format string Format name Description
d Day Day as a number 1..31 (without trailing zero).
dd Day Day as a number 01..31 (with trailing zero).
ddd Day Day as an abbreviated name of the day of the week; depends on system regional settings.
dddd(d) Day Day as a full name of the day of the week; depends on system regional settings.
f Second fraction Most significant digit of the second fraction.
ff Second fraction Two most significant digits of the second fraction.
fff Second fraction Three most significant digits of the second fraction.
ffff Second fraction Four most significant digits of the second fraction.
fffff Second fraction Five most significant digits of the second fraction.
ffffff Second fraction Six most significant digits of the second fraction.
fffffff(f) Second fraction Seven most significant digits of the second fraction.
F Second fraction Most significant digit of the second fraction; if zero then nothing will be displayed.
FF Second fraction Two most significant digits of the second fraction; trailing zeros will be truncated.
FFF Second fraction Three most significant digits of the second fraction; trailing zeros will be truncated.
FFFF Second fraction Four most significant digits of the second fraction; trailing zeros will be truncated.
FFFFF Second fraction Five most significant digits of the second fraction; trailing zeros will be truncated.
FFFFFF Second fraction Six most significant digits of the second fraction; trailing zeros will be truncated.
FFFFFF(F) Second fraction Seven most significant digits of the second fraction; trailing zeros will be truncated.
g(g) Period or Era [not supported yet]
h Hour Hour as a number 1..12 (without trailing zero).
hh(h) Hour Hour as a number 01..12 (with trailing zero).
H Hour Hour as a number 1..24 (without trailing zero).
HH(H) Hour Hour as a number 01..24 (with trailing zero).
m Minute Minute as a number 0..59 (without trailing zero).
mm(m) Minute Minute as a number 00..59 (with trailing zero).
M Month Month as a number 1..12 (without trailing zero).
MM Month Month as a number 01..12 (with trailing zero).
MMM Month Month as an abbreviated name of the month; depends on system regional settings.
MMMM(M) Month Month as a full name of the month; depends on system regional settings.
s Seconds Seconds as a number 0..59 (without trailing zero).
ss(s) Seconds Seconds as a number 00..59 (with trailing zero).
t AM/PM First character of the 'AM' or 'PM' string; depends on system regional settings.
tt(t) AM/PM 'AM' or 'PM' string; depends on system regional settings.
y Year Year as a two digit number; if the year has less than two digits then one digit number will be displayed.
yy Year Year as a two digit number; if the year has less than two digits then result will be padded with zero.
yyy Year Year as a three digit number; if the year has less than three digits then result will be padded with zeros.
yyyy Year Year as a four-digit number; if the year has less than four digits then result will be padded with zeros.
yyyy(y) Year Year as a five-digit number; if the year has less than five digits then result will be padded with zeros.
z(z) GMT Offset [not supported yet]
[other] Other characters are displayed without any change.

Examples:

Code Attribute value Result string Note
{FIELD_NAME:d} 3rd of June 2008: 17:09:03.650, US English '3'
{FIELD_NAME:dd} 3rd of June 2008: 17:09:03.650, US English '03'
{FIELD_NAME:ddd} 3rd of June 2008: 17:09:03.650, US English 'Tue'
{FIELD_NAME:dddd} 3rd of June 2008: 17:09:03.650, US English 'Tuesday'
{FIELD_NAME:M} 3rd of June 2008: 17:09:03.650, US English '6'
{FIELD_NAME:MM} 3rd of June 2008: 17:09:03.650, US English '06'
{FIELD_NAME:MMM} 3rd of June 2008: 17:09:03.650, US English 'Jun'
{FIELD_NAME:MMMM} 3rd of June 2008: 17:09:03.650, US English 'June'
{FIELD_NAME:y} 3rd of June 2008: 17:09:03.650, US English '08'
{FIELD_NAME:yy} 3rd of June 2008: 17:09:03.650, US English '08'
{FIELD_NAME:yyy} 3rd of June 2008: 17:09:03.650, US English '008'
{FIELD_NAME:yyyy} 3rd of June 2008: 17:09:03.650, US English '2008'
{FIELD_NAME:yyyyy} 3rd of June 2008: 17:09:03.650, US English '02008'
{FIELD_NAME:h} 3rd of June 2008: 17:09:03.650, US English '5'
{FIELD_NAME:hh} 3rd of June 2008: 17:09:03.650, US English '05'
{FIELD_NAME:H} 3rd of June 2008: 17:09:03.650, US English '17'
{FIELD_NAME:HH} 3rd of June 2008: 17:09:03.650, US English '17'
{FIELD_NAME:t} 3rd of June 2008: 17:09:03.650, US English 'P'
{FIELD_NAME:tt} 3rd of June 2008: 17:09:03.650, US English 'PM'
{FIELD_NAME:m} 3rd of June 2008: 17:09:03.650, US English '9'
{FIELD_NAME:mm} 3rd of June 2008: 17:09:03.650, US English '09'
{FIELD_NAME:mmm} 3rd of June 2008: 17:09:03.650, US English '09' ignored 3rd 'm' in format string
{FIELD_NAME:s} 3rd of June 2008: 17:09:03.650, US English '3'
{FIELD_NAME:ss} 3rd of June 2008: 17:09:03.650, US English '03'
{FIELD_NAME:f} 3rd of June 2008: 17:09:03.650, US English '6'
{FIELD_NAME:ffff} 3rd of June 2008: 17:09:03.650, US English '6500'
{FIELD_NAME:FFFF} 3rd of June 2008: 17:09:03.650, US English '65'
{FIELD_NAME:yyyy/MM/dd HH/mm/ss.ffff} 3rd of June 2008: 17:09:03.650, US English '2008/06/03 17:09:03.6500'

String

Note: i is a placeholder for an integer number.

Format character Name Description
$ normal text Text displayed without any changes.
S uppercase Text displayed in uppercase.
s lowercase Text displayed in lowercase.
i [at the beginning] first character i>0 defines from which character (counting from the beginning of the string) the string should be displayed; if i<0 then the characters are counted from the end of the string.
i [at the end] last character i>0 defines up to which character (counting from the beginning of the string) the string should be displayed; if i<0 then the characters are counted from the end of the string.
H force HTML force HTML interpretation of <> symbols

Examples:

Code Attribute value Result string Note
{FIELD_NAME:$} 'Abcdefghij' 'Abcdefghij'
{FIELD_NAME:S} 'Abcdefghij' 'ABCDEFGHIJ'
{FIELD_NAME:s} 'Abcdefghij' 'abcdefghij'
{FIELD_NAME:1$-1} 'Abcdefghij' 'Abcdefghij'
{FIELD_NAME:1S3} 'Abcdefghij' 'ABC'
{FIELD_NAME:1s3} 'Abcdefghij' 'abc'
{FIELD_NAME:1$-3} 'Abcdefghij' 'Abcdefgh'
{FIELD_NAME:-3$-1} 'Abcdefghij' 'hij'
{FIELD_NAME:4$-4} 'Abcdefghij' 'defg'
{FIELD_NAME:8$-8} 'Abcdefghij' '' empty string
{FIELD_NAME:H} 'A<b>c' 'A&lt;b;&gt;c'
{FIELD_NAME:H$} 'A<b>c' 'A&lt;b;&gt;c'
{FIELD_NAME:HS} 'A<b>c' 'A&lt;B;&gt;C'
{FIELD_NAME:Hs} 'A<b>c' 'a&lt;b;&gt;c'
{FIELD_NAME:H1s3} 'A<b>c' 'a&lt;b'

Use in code

Preferred way to define labels within code is to use Params.Labels.Value. Using Params.Labels.Field is still possible as long as only label field is provided.

  Params.Labels.Value := 'This is by <b>{AGE}</b>' ;
  ...
  Params.Labels.Field := 'AGE' ;
2019/09/11 10:23