This class is used as a tool to print formated text.
The text is formated using HTML markups. Yet, few commands are implemented. <i>, <b>, <u> can be used to change the style of the font to, respectively, italic, bold and undelined. Text can be aligned to the left, to the right, centered or even justified with the command <align>. The command <font> can be used to change the font's face, font's colour and font's size. The command <br> can be used to break lines (as well as the common \n). A customizable horizontal rule can be used to divide parts of a text with the command <hr>. Images can also be incorporated within the text with the command <img>.
In addition to theses standard commands, the command <pens> allows management of 4 additionnal pens used to produce effects such as emboss, ghost, glow... The command <spacing> can be used to modify the spacing (in pixels) between two or several lines.
FM_TextDisplay_Setup
FM_TextDisplay_Cleanup
FM_TextDisplay_Draw
FA_TextDisplay_Contents
FA_TextDisplay_PreParse
FA_TextDisplay_Font
FA_TextDisplay_Height
FA_TextDisplay_Width
FA_TextDisplay_UnderShort
IFEELIN F_Do(Obj, FM_TextDisplay_Draw, FRect *Rect);
This method render the text into the Render object provided during the Setup method.
The space used to render the text is restricted to the area defined by the Rect parameter. If the text doen't fit in the available display space, the lines are truncated and three dots added e.g. 'Hel...'. If even dots don't fit, nothing is displayed.
This rectangle describes the region where the text is allowed to be drawn. If text is longer then available space it's truncated and three dots "..." are drawn instead of characters that cannot fit in the available space. If (Rect->x2 < Rect->x1) or (Rect->y2 < Rect->y1) then nothing is drawn.
void drawtext(FObject TD, int16 x, int16 y, uint16 w, uint16 h)
{
FRect r;
r.x1 = x; r.x2 = x + w - 1;
r.y1 = y; r.y2 = y + h - 1;
IFEELIN F_Do(TD, FM_TextDisplay_Draw, &r);
}
The method returns the width of the biggest line drawn.
IFEELIN F_Do(Obj, FM_TextDisplay_Setup, FRender *Render);
You need to setup the object before drawing can be performed. Use this method to setup the object.
When the object is setup, text is parsed, lines and chunks are created, fonts opened, colors allocated, images created and rendered...
A FRender structure needed to obtain environnement information and to perform renderings. The structure must remains valid until the Cleanup method is called.
IFEELIN F_Do(Obj, FM_TextDisplay_Cleanup);
This method is used free the object's ressources.
Text is formated using markups, they delimit formating elements. Most elements are identified in a document as a start-tag, which gives the element name and attributes, followed be the content, followed be the end-tag. Start-tags are delimited by '<' and '>'; end-tags are delimited by '</' and '>'. An example is:
<b>Text is bold</b> Text is not bold.
Some elements only have start-tag without end-tag. For example, to create a line break, use the '<br>' tag.
In a start-tag, white space and attributes are allowed between the element name and the closing delimiter. An attribute specification typically consists of an attribute name, an equal sign, and a value. White space is allowed around the equal sing. In my implementation, tag names and attribute names are case sensitive, they must be in lower case.
In this example, 'img' is the element name, 'src' is the attribute name, and 'myface.png' is the attribute value:
<img src="myface.png">
These all require start and end tags e.g.
This has some <b>bold text</b>.
Text level elements must be properly nested - the following is an error:
This has some <b>bold and <i></b>italic text</i>.
'b' bold text style.
'i' italic text style.
'u' underlined text style.
Requires start and end tags. This allows you to change the alignment of the enclosed text. Possible values are: left: text lines are rendered flush left; center: text lines are centered; right: text lines are rendered flush right; justify: text lines are justified to both margins.
<align="center">Hello World !</align>
Used to force a line break. This is an empty element so the end tag is forbidden. For example:
Pease porridge hot<br> Pease porridge cold<br> Pease porridge in the pot<br> Nice days old.
Requires start and end tags. This allows you to change the font size and/or color for the enclosed text. Font sizes are given in terms of a scalar range or pixel size.
size · This sets the font size for the contents of the font element. You can set size to an integer for an absolute font size e.g. <font size=12px>, or specify a relative percent value e.g. <font size=150%> or <font size=50%>.
color · Used to set the color to stroke the text. You can use the same color specifications as those handled by the Spec attribute of the ImageDisplay class.
face · Name of the font that should be used to render text. e.g <font face="helvetica">
The 'hr' element is a divider between sections of text; typically a full width horizontal rule or equivalent graphic. For example:
<hr> Text between lines <hr>
The 'hr' element is not a container so the end-tag is forbidden. The attributes are:
align · This determines whether the rule is placed at the left, center or right of the space between the current left and right margin for <hr align=left>, <hr align=center> or <hr align=right> respectively. By default, the rule is centered.
noshade · The attribute the rule to be rendered in a solid color rather than the traditional two colour groove. <hr noshade=true> or <hr noshade=yes> disable the groove style. The solid color used can be defined with the 'shine' attribute. By default, the rule is shaded (noshade=false).
shadow · The shadow pen used to draw the shadow part of the groove style. Use one of the defined color scheme pens : shine, halfshine, fill, halfshadow, shadow, halfdark, dark, text and highlight. By default the rule's shadow pen is shadow.
shine · The shine pen used to draw the shine part of the "groove" style. Use one of the defined color scheme pens : shine, halfshine, fill, halfshadow, shadow, halfdark, dark, text and highlight. By default the rule's shine pen is shine.
size · This can be used to set the height of the rule in pixels. You can use decimal values (e.g. <hr size=3>) as pixel values (e.g. <hr size=3px>). By default the rule is 2 pixel high (<hr size=2px>).
width · This can be used to set the width of the rule in pixel (e.g. <hr width=100> or <hr width=100px>) or as the percentage between the current left and right margins (e.g. <hr width=50%>). The default is 100% (<hr width=100%>).
Used to insert images. 'img' is an empty element and so the end tag is forbidden. 'img' elements support the following attributes:
src · This attribute is required for every 'img' element. It specifies the address of the image resource (e.g. "images/icon.png").
height · Specifies the intended height of the image in pixels. If the value is not defined, the image's height is obtained from the image object.
width · Specifies the intended width of the image in pixels. If the value is not defined, the image's width is obtained from the image object.
Requires start and end tags. This allows you to manage text pen and 4 addition pens to create stylish text effect such as emboss, glow... Don't mix up pen and colour, especially for text. A pen is one of the available colours from the Feelin's color scheme, which are shine, halfshine, fill, halfshadow, shadow, halfdark, dark, text and highlight, or any specification decodable with the FM_Display_DecodeColor method. The following attributes are defined:
up · Use this attribute to define the pen to use to draw text at 'text_x - 1' 'text_y - 1' over the standard text.
down · Use this attribute to define the pen to use to draw text at 'text_x + 1' 'text_y + 1' over the standard text.
light · Use this attribute to define the pen to use to draw text at 'text_x - 1' 'text_y - 1' behind the standard text.
shadow · Use this attribute to define the pen to use to draw text at 'text_x + 1' 'text_y + 1' behind the standard text.
text · Use this attribute to define the pen to use to draw text. Note: If the command is encapsulated in a <font>...</font> section and a colour has been defined for this section (.e.g <font color="#FF0000">), defining the pen has no effect, because the <font> markup is prioritary.
style · Use this attribute to use one of the available style that will define for you the approriate pens. The available styles are : emboss · "text=text up=shine"; ghost · "text=halfshadow shadow=halfshine"; glow · "text=text light=shine shadow=halfshadow"; light · "text=text light=shine" and shadow · "text=text shadow=halfshadow".
Disable formating engine for the enclosed section. Although this element requires start and end tags it is not nested, you should pay attention to this.
Note that the text suplied with the Contents attribute is not cloned. The string must remains valid until you set the attribute to NULL or you dispose the object.
String containing format definitions to be parsed before the text from FA_TextDisplay_Contents is printed.
Using this tag, you can easily define different formats, colors and styles without modifying the original string. This string must remains valid until you set it to NULL or dispose the object.
...
FA_TextDisplay_PreParse, "<align=center><i>", // centered and italics FA_TextDisplay_Contents, "foobar",
...
Defines the base font to draw with.
This attribute must be defined, otherwise text won't be setuped and drawing will be impossible.
FM_TextDisplay_Draw · FM_TextDisplay_Setup
This attribute is use to set (limit) text's height, and to get real text's height.
Text is adjusted, according to limits given by FA_TextDisplay_Width and FA_TextDisplay_Height, when the object is setup or one of the attributes FA_TextDisplay_Contents, FA_TextDisplay_PreParse, FA_TextDisplay_Shortcut, FA_TextDisplay_Font, FA_TextDisplay_Width or FA_TextDisplay_Height is modified. Text is also adjusted if the dimension of the rectangle given width FM_TextDisplay_Draw differs from the one given by FA_TextDisplay_Width and FA_TextDisplay_Height.
Set this attribute to TRUE (default) if you want the underscore character (shortcut) to be handled. Getting this attribute will return the underscored character (shortcut). Only the first underscore found will stand as shortcut.
Setting this attribute to FALSE will disable underscore handling, all underscores will be simple characters.
This attribute is use to set (limit) text's width, and to get real text's width.
Text is adjusted, according to limits given by FA_TextDisplay_Width and FA_TextDisplay_Height, when the object is setup or one of the attributes FA_TextDisplay_Contents, FA_TextDisplay_PreParse, FA_TextDisplay_Shortcut, FA_TextDisplay_Font, FA_TextDisplay_Width or FA_TextDisplay_Height is modified. Text is also adjusted if the dimension of the rectangle given width FM_TextDisplay_Draw differs from the one given by FA_TextDisplay_Width and FA_TextDisplay_Height.