MS RFC 40: Support Label Text Transformations¶
thomas.bonfort at gmail.com
- Last Edited:
MapServer 5.0 supports «hard» text wrapping, where the wrap character is unconditionally treated as a newline. This RFC proposes the addition of:
conditional wrapping, i.e. newlines are only added when the current line length has met a user adjustable criteria
line alignment, i.e. text aligned per user request, namely right, center and left
These two additions are independent from one another, i.e. can be activated together or not.
A new keyword, MAXLENGTH is added to the label object, and interacts with the label WRAP parameter as follows:
the wrap character specifies what character can be replaced by a newline (no change w.r.t. the current meaning). Probably the most useful wrap character will become ‹ ‹ (i.e. the space character)
the MAXLENGTH value specifies the maximum number of characters that can compose a line before a newline is inserted. A value of 0 specifies the current «hard» wrapping. A positive value triggers wrapping at the WRAP character for lines longer than MAXLENGTH. A negative value triggers wrapping that is allowed to break words, i.e. not necessarily at the WRAP character.
The WRAP / MAXLENGTH combinations are summarized here:
maxlen > 0
maxlen < 0
wrap = ‹char›
conditional wrap if > maxlen
skip label if > maxlen
A new keyword ALIGN is added to the label object. It supports 3 values: left, center and right, and controls how text lines should be aligned w.r.t. the label bounding box. Precise placement of text can only be done at the renderer level, by exactly defining the starting pixel of the current line. While this approach could be taken, it would considerably burden the renderer code.
I propose to use a more generic though less precise way of doing, by padding the text lines with space characters to approximate indentation. The initial implementation could only rely on the number of characters in each text line:
loop through text lines to find the line with the most characters l_max
pad all the other lines with (l_max - l_cur)/2 space characters
A more advanced implementation will be to use the exact line lengths as returned by the renderers with the msGetLabelSize function:
compute the size in pixels of the « « string (two spaces, accounts for kerning): l_2space
loop through text lines to longest line of length pix_l_max
pad all the other lines with (pix_l_max - pix_l_cur)/2 * 1/(2*l_2space) space characters
‹››Limitations›››: aligning text to the right will produce ugly results using this method, unless using a monospace font.
Modifications to the source code¶
MAXLENGTH and ALIGN will be added to the LABEL object in map.h, in the mapfile parser/writer (mapfile.c) and in MapScript
msTransformLabelText() in maplabel.c will be updated to support the modifications proposed. No other modifications should be required as the text itself is modified to fit the user’s request (i.e. it is padded with spaces, and/or newlines are added to it)
The labelObj will have new maxlength property of type integer and align property (ms_align_*).
Backwards compatibility issues¶
+1: SteveL, SteveW
+0: FrankW, TomK
Questions/Comments from the review period¶
SteveW: allow preciser computation of line offsets when padding with spaces: done. The precise size of each line is calculated in pixels, and the closest number of space characters required for alignment is computed accordingly
DanielM: allow multiple characters to be used when wrapping lines: not addressed. Space characters can be replaced by a newline, while the hyphen character should generally be kept. Any idea how we can specify that some wrapping characters are to be kept while others are just markers for potential linebreaks?