Purpose

Adds a text object to the manager

Protoype

void CTextMngr::AddText (string str_text_id, string str_text, string str_font_id, int i_font_size, int i_xpos, 
                         int i_ypos, RGB_SET rgb_fore, RGB_SET rgb_back, bool b_show, int i_delay_ms, bool b_center, 
                         bool b_repeat, int i_font_style = TTF_STYLE_NORMAL, int i_ttype = TTYPE_NORMAL, int i_clip_w = 0, 
                         int i_clip_h = 0, string str_select = "", bool b_delay = false)

Parameters

Description

Basics

This function adds a new text object to the manager. The text object must have a unique, spaceless identifier label - if the ID given to the text object is already in use, the text object will not be added to the manager. The text passed in via str_text is the actual text that will appear on the screen. The font ID passed in via str_font_id must be already created and stored in the font manager (actually this only matters for Input and Select text objects, not Normal ones, but it's just better to load all fonts before texts anyways).

Text Positioning

When you pass in the (x,y) location of the text, unless you pass TRUE for the b_center flag, the text's upper-left corner will be displayed at the given coordinates. When using the center flag, clip settings will be taken into affect, meaning the center of the text becomes the center of the clip window.

Text Hiding/Showing/Flashing

Text can be hidden (FALSE) or shown (TRUE) upon creation using the b_show flag. If you want to be able to hide or show text for only a certain amount of time, set the i_delay_ms parameter to the proper number of milliseconds. If you set the b_repeat flag to TRUE, then you can have text flash (blink) at the rate set in i_delay_ms. If you want the text to be shown with its delay timer in effect when added (instead of having to call ShowText()), then use the b_delay flag. For more information on using the delay and repeat with show/hide, see ShowText().

Text Clipping

If you want to restrict text to a certain area of the screen, use i_clip_w and i_clip_h to set up a clipping rectangle at the (x,y) coordinates specified. Text will wordwrap automatically to fit inside the clip window. If the text wraps past the bottom of the clip window, that text will not be displayed on the screen. Currently there is no way to scroll a clip window.

Text Types

Normal Text

These are normal text objects that have no special properties and are just used to display text on the screen. To create a Normal Text object, pass in TTYPE_NORMAL for i_ttype.

Input Text

These are text objects that can be clicked on with a mouse cursor and then edited. To enable this, a hotspot is placed over the input text. Each Input Text hotspot begins with "input_spot_" followed by the ID of the text object associated with that hotspot. This lets you identify when an input hotspot has been pressed and then extract the ID of the Input Text object. This ID is then passed into EnableInput() to enable the text input. Now a blinking cursor appears at the end of the text signaling input readiness. In order to modify the text, you must use DoInput() everytime a key is pressed. To stop editing text, use EnableInput() again coupled with some action (pressing Enter or clicking away from the object, for example). Note that the entire text of an Input Text object can be modified, therefore the prompt should not be an Input Text object. The function GetText() can be used to get the current text inputted. To create an Input Text object, pass in TTYPE_INPUT for i_ttype.

NOTE: When using the CApp class, text input activation, capture, and deactivation is all handled automatically.

Selection Text

These are text objects that can be "selected". A Selection Text object is associated with an image that contains the picture of the selection box, stored in str_select. Like the Input Text object, the Selection Text object creates a hotspot starting with "select_spot_" and followed by the ID of the associated text object. This ID can then be extracted and passed to SelectText() when the hotspot is clicked to create the selection box around the text. SelectText() also disables the selection box. The curently selected text object ID can be obtained using GetSelectedText(). To create a Selection Text object, pass in TTYPE_SELECT for i_ttype.

NOTE: When using the CApp class, text select activation and deactivation is all handled automatically.

Font Specifics

There are four parameters in the function that account for the way text will appear on the screen. The first is i_font_size. This will set the point size of the font that the text is rendered in. The second two are rgb_fore and rgb_back. These two take an RGB_SET that makes up the colors for the text color and background color, respectively. The last parameter is i_font_style. For more on font styles see SetFontStyle().

Use

CTextMngr text;

text.AddText("my_text", "Hello World!", "my_font", 12, 50, 50, RGB_SET(255, 255, 0), RGB_SET(0, 0, 0), true, 5000, false, 
             false, TTF_TYPE_NORMAL, TTYPE_SELECT, 500, 200, "my_select");