Home | All Classes | Grouped Classes | Index | Search

Class CL_TextStyler

Draws specially formatted text in one or several fonts. More...

Derived from: none
Derived by: none
Group: Display (Fonts)

#include <ClanLib/display.h>

Construction:

Constructs a text styler.

Attributes:

get_fonts	Returns a reference to the font map.
get_scale	Returns scale for x and y.
get_alignment	Returns translation hotspot.
get_height	Returns the drawn height of some source text, or of the default font if no arguments passed.
get_width	Returns the drawn width of some source text.
get_size	Returns the drawn size of some source text.
bounding_rect	Calculate the rectangle that would be occupied by a draw operation.
resource	Resource owning this text styler, if any.

Operations:

operator =	Copy assignment
add_font	Adds a new font to the map
draw	Draws text onto a graphics context.
draw_to_gb	Inserts data into a CL_GlyphBuffer, treating the glyphs already there as part of a previous draw_to_gb().
set_scale	Set scale for x and y directions individually.
set_alignment	Sets translation hotspot.

Detailed description:

!group=Display/Fonts! !header=display.h!

A CL_TextStyler consists of a collection of named CL_Fonts. When passed a string to draw, it uses vaguely HTMLish tags to select which font to draw text in. For example:

"Here's some text, italicisn't it boldamazing?{/bold}{/italic}"

CL_TextStyler does not have any mechanisms on its own for bold and italic text, so in order for this to work, there must be fonts named 'bold' and 'italic' that it knows of. Text outside font tags is drawn in the font named 'default', if it exists. No blending or anything like that is performed with nested fonts; the innermost font is the one used, and the nesting is for convienence.

There are also special tags which are bounded by [ and ]. These can be used for justification, scaling, color, and newlines.

Justification can be either left, center, or right, shown by this example:

 "This line is left justified.\n[j center]This line is center
  justified.\n[j right]This line is right justified.\n[/j][/j]Back to
  left justification."

Scaling tags affect both x and y scaling the same amount when given a single number, but can be given two numbers to affect both:

"Regular size.[s 2.0 1.0]Double wide text.[/s][s 1.0 2.0]Double tall text."

Scaling tags are also cumulative, as shown by this example:

 "This text is at regular size.[s 2.0]This text is at double size.[s 2.0]This text is at quadruple
  size.[/s]Double size again.[/s]Regular size again."

Color tags allow specification of RGB and RGBA values, as well as use of named colors (see CL_Color's documentation for a reference). The color overrides the font's existing color entirely, and does not blend with it. Be sure that the blending functions of a font are set properly before using that font in a TextStyler with color tags.

 "This text is in whatever the font's default color is.[c blue]This text is blue.[c red]This text
  is red, not blue-red; there's no blending between nested colors.[/c][/c][c 0 255 0]This text is green.[/c]
  [c 255 0 255 175]This text is translucent purple; the fourth number is the alpha value, which
  is set to opaque (255) if unspecified.[/c]"

Newline tags are only helpful when loading TextStyler-intented strings from XML resource files, where there's no easy way to insert an actual newline character:

"First line.[n]Second line."

To draw a real a left brace or left square bracket and not start a tag, just escape it by putting two of the characters in a row; right braces and right square brackets don't need to be escaped, and CL_TextStyler will take them literally if they don't seem to end an open tag. References to fonts which are not in the CL_TextStyler's font map will be silently ignored. Using bad nesting order is also allowed (i.e. ab{/a}{/b}). However, you can't have a partial tag in the string (that is, "blah blah {tag doesnt end"), and you are not allowed to put any of the four tag opening/closing characters inside a tag, or in a font name, even if they're escaped.

Like with CL_Font, scaling affects the calculation of any bounding rectangles (such as the result returned by draw() or bounding_rect(), or the rectangle calculated internally by draw() for alignment). This is because scaling the CL_TextStyler is effectively just changing the point size of the glyphs, and that affects all sorts of things, such as word wrapping.

Questions or comments, write to the ClanLib mailing list.