<!-- clanlib header begin -->
<HTML>
<HEAD>
<TITLE>CL_TextStyler - ClanLib Game SDK</TITLE>
<STYLE TYPE="text/css"><!--
HTML BODY
{
font-family: verdana, helvetica, sans-serif;
font-size: 12px;
}
H1 { font-size: 22px; }
H2 { font-size: 18px; }
H3 { font-size: 16px; }
H4 { font-size: 14px; }
P { font-size: 12px; }
LI { font-size: 12px; }
--></STYLE>
</HEAD>
<body bgcolor=white text=black link=blue vlink=#800080>
<center>
<img src="http://clanlib.org/gfx/clanlib.png">
</center>
<!-- clanlib header end -->
<center>
<p>
<a href="http://clanlib.org/docs.html">Home</a> |
<a href="classes.html">All Classes</a> |
<a href="modules.html">Grouped Classes</a> |
<a href="index.html">Index</a> |
<a href="search.html">Search</a>
</p>
</center>
<h1>Class CL_TextStyler</h1>
<p> Draws specially formatted text in one or several fonts. <a href="#description">More...</a></p>
<p>Derived from:
<i>none</i>
<br>
Derived by:
<i>none</i>
<br>Group: Display (Fonts)</p>
<p>
#include <ClanLib/display.h>
<p>
<table border=0 width=100%>
</table>
<p><b>Construction:</b></p>
<table border=0 width=100%>
<tr><td width=30% valign=top><p><a href="CL_TextStyler__CL_TextStyler.html">CL_TextStyler</a></p></td><td valign=top><p> Constructs a text styler.</p></td></tr></table>
<p><b>Attributes:</b></p>
<table border=0 width=100%>
<tr><td width=30% valign=top><p><a href="CL_TextStyler__get_fonts.html">get_fonts</a></p></td><td valign=top><p> Returns a reference to the font map.</p></td></tr><tr><td width=30% valign=top><p><a href="CL_TextStyler__get_scale.html">get_scale</a></p></td><td valign=top><p> Returns scale for x and y.</p></td></tr><tr><td width=30% valign=top><p><a href="CL_TextStyler__get_alignment.html">get_alignment</a></p></td><td valign=top><p> Returns translation hotspot.</p></td></tr><tr><td width=30% valign=top><p><a href="CL_TextStyler__get_height.html">get_height</a></p></td><td valign=top><p> Returns the drawn height of some source text, or of the default font if no arguments passed.</p></td></tr><tr><td width=30% valign=top><p><a href="CL_TextStyler__get_width.html">get_width</a></p></td><td valign=top><p> Returns the drawn width of some source text.</p></td></tr><tr><td width=30% valign=top><p><a href="CL_TextStyler__get_size.html">get_size</a></p></td><td valign=top><p> Returns the drawn size of some source text.</p></td></tr><tr><td width=30% valign=top><p><a href="CL_TextStyler__bounding_rect.html">bounding_rect</a></p></td><td valign=top><p> Calculate the rectangle that would be occupied by a draw operation.</p></td></tr><tr><td width=30% valign=top><p><a href="CL_TextStyler__resource.html">resource</a></p></td><td valign=top><p> Resource owning this text styler, if any.</p></td></tr></table>
<p><b>Operations:</b></p>
<table border=0 width=100%>
<tr><td width=30% valign=top><p><a href="CL_TextStyler__operator =.html">operator =</a></p></td><td valign=top><p> Copy assignment</p></td></tr><tr><td width=30% valign=top><p><a href="CL_TextStyler__add_font.html">add_font</a></p></td><td valign=top><p> Adds a new font to the map</p></td></tr><tr><td width=30% valign=top><p><a href="CL_TextStyler__draw.html">draw</a></p></td><td valign=top><p> Draws text onto a graphics context.</p></td></tr><tr><td width=30% valign=top><p><a href="CL_TextStyler__draw_to_gb.html">draw_to_gb</a></p></td><td valign=top><p> Inserts data into a CL_GlyphBuffer, treating the glyphs already there as part of a previous draw_to_gb().</p></td></tr><tr><td width=30% valign=top><p><a href="CL_TextStyler__set_scale.html">set_scale</a></p></td><td valign=top><p> Set scale for x and y directions individually.</p></td></tr><tr><td width=30% valign=top><p><a href="CL_TextStyler__set_alignment.html">set_alignment</a></p></td><td valign=top><p> Sets translation hotspot.</p></td></tr></table>
<a name="#description"><p><b>Detailed description:</b></p>
!group=Display/Fonts!
!header=display.h!
<p> 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:</p>
<code> "Here's some text, <tt><tt><font color=blue>italic</font></tt></tt>isn't it <tt><tt><font color=blue>bold</font></tt></tt>amazing?{/bold}{/italic}" </code>
<p> 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.</p>
<p>There are also special tags which are bounded by [ and ].
These can be used for justification, scaling, color, and newlines.</p>
<p>Justification can be
either left, center, or right, shown by this example:</p>
<code> "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." </code>
<p>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:</p>
<code> "Regular size.[s 2.0 1.0]Double wide text.[/s][s 1.0 2.0]Double tall text." </code>
<p>Scaling tags are also cumulative, as shown by this example:</p>
<code> "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." </code>
<p>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.</p>
<code> "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]" </code>
<p>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:</p>
<code> "First line.[n]Second line." </code>
<p>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. <tt><tt><font color=blue>a</font></tt></tt><tt><tt><font color=blue>b</font></tt></tt>{/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. </p>
<p>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.</p>
<!-- clanlib footer begin -->
<center><br><br><font color="#a0a0a0">
Questions or comments, write to the <a href="http://clanlib.org/contact.html">ClanLib mailing list</a>.
</font></center>
</body>
</html>
<!-- clanlib footer end -->
