hoa_video::TextBox Class Reference

Class for representing an invisible box for rendering text to. Although the video engine has an easy-to-use DrawText() function, for any non-trivial text display, the TextBox class must be used. This class provides a few things which aren't handled by DrawText(), namely word wrapping, and "gradual display", such as drawing one character at a time or fading each line of text in individually. More...

#include <textbox.h>

Inheritance diagram for hoa_video::TextBox:

[legend]Collaboration diagram for hoa_video::TextBox:

[legend]List of all members.


Public Member Functions
void	ClearText ()
	Removes all text from the text box.
void	Draw ()
	Renders the textbox to the screen back buffer. Note that the rendering is not affected by any draw flags or coordinate system settings,. This function will use whatever has been set for it using the Set*() calls.
void	ForceFinish ()
	If text is in the middle of gradual rendering, this forces it to complete. This is useful if a player gets impatient while text is scrolling to the screen.
void	GetDimensions (float &w, float &h)
	Obtains the width and height of the text box.
TEXT_DISPLAY_MODE	GetDisplayMode () const
	Return the current text display mode that is set for this textbox.
float	GetDisplaySpeed () const
	Return the current text display speed, in characters per second.
std::string	GetFont () const
	Gets the font label for this textbox.
void	GetText (std::vector< hoa_utils::ustring > &text) const
	Returns the text currently being displayed by the textbox.
void	GetTextAlignment (int32 &xalign, int32 &yalign)
	Retrieve the current x and y alignments for the text.
bool	IsEmpty () const
	Returns true if this text box contains no text empty.
bool	IsFinished () const
	Returns true if this textbox is finished with its gradual display of text.
bool	IsInitialized (std::string &errors)
	Checks all class members to see if all members have been set to valid values.
void	SetDimensions (float w, float h)
	Sets the width and height of the text box. Returns false and prints an error message.
void	SetDisplayMode (const TEXT_DISPLAY_MODE &mode)
	Sets the current text display mode (e.g. fading lines of text, etc.).
void	SetDisplaySpeed (float display_speed)
	Sets the text display speed (in characters per second).
void	SetDisplayText (const std::string &text)
	A non-unicode version of SetDisplayText().
void	SetDisplayText (const hoa_utils::ustring &text)
	Sets the text for this box to the string passed in.
void	SetFont (const std::string &font_name)
	Sets the font to use for this textbox.
void	SetTextAlignment (int32 xalign, int32 yalign)
	Set the x and y alignments for the text.
void	SetTextColor (Color &color)
	Sets the display text color of this text box.
	TextBox (float x, float y, float width, float height, const TEXT_DISPLAY_MODE &mode=VIDEO_TEXT_INSTANT)
	TextBox ()
void	Update (uint32 frame_time)
	Updates the amount of text that has been rendered.
	~TextBox ()
Private Member Functions
void	_AddLine (const hoa_utils::ustring &line)
	Adds a new line of text to the _text vector.
int32	_CalculateTextHeight ()
	Returns the height of the text when it's rendered with the current font.
void	_DrawTextLines (float text_x, float text_y, ScreenRect scissor_rect)
	Draws the textbox text, taking the display mode into account.
bool	_IsBreakableChar (uint16 character)
	Returns true if the given unicode character can be interrupted for a word wrap.
void	_ReformatText ()
	Reformats text for size/font.
Private Attributes
uint32	_current_time
	The number of milliseconds that have passed since SetDisplayText() was called.
float	_display_speed
	The display speed of the text, in characters per second.
uint32	_end_time
	The number of milliseconds remaining until the gradual text display will be complete.
bool	_finished
	True if the text being drawn by SetDisplayText() is done (in the case of gradual rendering).
std::string	_font
	The font name to use for this textbox.
FontProperties *	_font_properties
	A pointer to the structure containing properties of the current font such as its height, etc.
float	_height
TEXT_DISPLAY_MODE	_mode
	The display mode for the text (one character at a time, fading in, instant, etc.).
uint32	_num_chars
	Hold the number of characters in the entire text.
std::vector< hoa_utils::ustring >	_text
	An array of wide strings, one for each line of text.
Color	_text_color
	A set text color to display.
hoa_utils::ustring	_text_save
	The unedited text for reformatting.
int32	_text_xalign
	Alignment flags for the textbox.
int32	_text_yalign
float	_width
	The dimensions of the text box, in pixels.

Detailed Description

****************************************************************************

Note:: The alignment flags affect the textbox as a whole, but not the actual text drawn in the textbox.
This class is based on UNICODE text. If you try to use it for regular strings, it will automatically convert it and store it internally as wide strings.

Definition at line 71 of file textbox.h.

Constructor & Destructor Documentation

hoa_video::TextBox::TextBox ( )

Definition at line 24 of file textbox.cpp.

References hoa_video::private_video::GUIElement::_initialized.

hoa_video::TextBox::TextBox	(	float	x,
		float	y,
		float	width,
		float	height,
		const TEXT_DISPLAY_MODE &	mode = `VIDEO_TEXT_INSTANT`
	)

Definition at line 39 of file textbox.cpp.

References hoa_video::private_video::GUIElement::_initialized, and hoa_video::private_video::GUIElement::SetPosition().

Here is the call graph for this function:

hoa_video::TextBox::~TextBox ( )

Definition at line 56 of file textbox.cpp.

Member Function Documentation

void hoa_video::TextBox::_AddLine ( const hoa_utils::ustring & line ) [private]

Adds a new line of text to the _text vector.

Parameters:

line

The unicode text string to add as a new line If the line is too long to fit in the width of the textbox, it will automatically be split into multiple lines through word wrapping.

Definition at line 371 of file textbox.cpp.

References _IsBreakableChar(), _num_chars, _text, _width, hoa_video::GameVideo::CalculateTextWidth(), hoa_utils::ustring::empty(), hoa_utils::ustring::length(), hoa_utils::ustring::size(), hoa_utils::ustring::substr(), and hoa_video::VideoManager.

Referenced by _ReformatText().

Here is the call graph for this function:

int32 hoa_video::TextBox::_CalculateTextHeight ( ) [private]

Returns the height of the text when it's rendered with the current font.

Returns:: The height of text rendered in current font

Note:: This is a low-level function so it doesn't check if the current font is valid or not

Definition at line 362 of file textbox.cpp.

References _font_properties, _text, hoa_video::FontProperties::height, and hoa_video::FontProperties::line_skip.

Referenced by _ReformatText(), and Draw().

void hoa_video::TextBox::_DrawTextLines	(	float	text_x,
		float	text_y,
		ScreenRect	scissor_rect
	)			`[private]`

Draws the textbox text, taking the display mode into account.

Parameters:

	text_x	The x value to use, depending on the alignment.
	text_y	The y value to use, depending on the alignment.
	scissor_rect	The scissor rectangle used for this textbox.

Definition at line 446 of file textbox.cpp.

Referenced by Draw().

Here is the call graph for this function:

bool hoa_video::TextBox::_IsBreakableChar ( uint16 character ) [private]

Returns true if the given unicode character can be interrupted for a word wrap.

Parameters:

character

The character you wish to check.

Returns:: True if character can be wrapped, false if it can not. For example in English, you can do a word wrap wherever there is a space (code 0x20). Other languages might have space characters corresponding to other unicode values.

Definition at line 437 of file textbox.cpp.

Referenced by _AddLine().

void hoa_video::TextBox::_ReformatText ( ) [private]

Reformats text for size/font.

Definition at line 286 of file textbox.cpp.

References _AddLine(), _CalculateTextHeight(), _font_properties, _height, _num_chars, _text, _text_save, hoa_utils::ustring::find(), hoa_video::private_video::NEWLINE_CHARACTER, hoa_utils::ustring::npos, hoa_utils::ustring::substr(), and hoa_video::VIDEO_DEBUG.

Referenced by SetDimensions(), and SetDisplayText().

Here is the call graph for this function:

void hoa_video::TextBox::ClearText ( )

Removes all text from the text box.

Definition at line 62 of file textbox.cpp.

References _finished, _num_chars, and _text.

Referenced by hoa_shop::private_shop::ObjectInfoWindow::SetObject().

void hoa_video::TextBox::Draw ( ) [virtual]

Renders the textbox to the screen back buffer. Note that the rendering is not affected by any draw flags or coordinate system settings,. This function will use whatever has been set for it using the Set*() calls.

Implements hoa_video::private_video::GUIElement.

Definition at line 79 of file textbox.cpp.

References _CalculateTextHeight(), hoa_video::GameVideo::_coord_sys, _DrawTextLines(), _font, _height, hoa_video::private_video::GUIElement::_initialization_errors, hoa_video::private_video::GUIElement::_initialized, hoa_video::GameVideo::_PopContext(), hoa_video::GameVideo::_PushContext(), _text, _text_color, _text_xalign, _width, hoa_video::private_video::GUIElement::_xalign, hoa_video::private_video::GUIElement::_yalign, hoa_video::private_video::GUIControl::CalculateAlignedRect(), hoa_video::GameVideo::GetTextColor(), hoa_video::CoordSys::GetVerticalDirection(), hoa_video::GameVideo::Move(), hoa_video::GameVideo::SetDrawFlags(), hoa_video::GameVideo::SetFont(), hoa_video::GameVideo::SetTextColor(), hoa_video::VIDEO_BLEND, hoa_video::VIDEO_DEBUG, hoa_video::VIDEO_X_CENTER, hoa_video::VIDEO_X_LEFT, hoa_video::VIDEO_Y_CENTER, hoa_video::VIDEO_Y_TOP, and hoa_video::VideoManager.

Referenced by hoa_shop::private_shop::ObjectInfoWindow::Draw(), hoa_shop::private_shop::ShopActionWindow::Draw(), hoa_menu::private_menu::SkillsWindow::Draw(), hoa_menu::private_menu::InventoryWindow::Draw(), and hoa_map::private_map::DialogueManager::Draw().

Here is the call graph for this function:

void hoa_video::TextBox::ForceFinish ( ) [inline]

If text is in the middle of gradual rendering, this forces it to complete. This is useful if a player gets impatient while text is scrolling to the screen.

Definition at line 97 of file textbox.h.

References _finished, and _text.

Referenced by hoa_map::private_map::DialogueManager::Update().

void hoa_video::TextBox::GetDimensions	(	float &	w,
		float &	h
	)			`[inline]`

Obtains the width and height of the text box.

Parameters:

	w	A reference to the variable in which to store the width.
	h	A reference to the variable in which to store the height. If the dimensions are invalid because SetDimensions has not yet been called, neither w nor h will be modified.

Definition at line 156 of file textbox.h.

References _height, and _width.

TEXT_DISPLAY_MODE hoa_video::TextBox::GetDisplayMode ( ) const [inline]

Return the current text display mode that is set for this textbox.

Definition at line 173 of file textbox.h.

References _mode.

float hoa_video::TextBox::GetDisplaySpeed ( ) const [inline]

Return the current text display speed, in characters per second.

Definition at line 177 of file textbox.h.

References _display_speed.

std::string hoa_video::TextBox::GetFont ( ) const [inline]

Gets the font label for this textbox.

Returns:: The string containing the font label.

Definition at line 169 of file textbox.h.

References _font.

void hoa_video::TextBox::GetText ( std::vector< hoa_utils::ustring > & text ) const [inline]

Returns the text currently being displayed by the textbox.

Definition at line 181 of file textbox.h.

References _text.

void hoa_video::TextBox::GetTextAlignment	(	int32 &	xalign,
		int32 &	yalign
	)			`[inline]`

Retrieve the current x and y alignments for the text.

Parameters:

	xalign	The member to hold the x alignment (e.g. VIDEO_X_LEFT).
	yalign	The member to hold the y alignment (e.g. VIDEO_Y_TOP).

Definition at line 163 of file textbox.h.

References _text_xalign, and _text_yalign.

bool hoa_video::TextBox::IsEmpty ( ) const [inline]

Returns true if this text box contains no text empty.

Definition at line 192 of file textbox.h.

References _text.

bool hoa_video::TextBox::IsFinished ( ) const [inline]

Returns true if this textbox is finished with its gradual display of text.

Note:: If you create a textbox but don't draw any text on it, the finished property will be false. Only after the text is drawn to it will this method return true.

Definition at line 188 of file textbox.h.

References _finished.

Referenced by hoa_map::private_map::DialogueManager::Update().

bool hoa_video::TextBox::IsInitialized ( std::string & errors ) [virtual]

Checks all class members to see if all members have been set to valid values.

Parameters:

errors

A reference to a string to be filled if any errors are found.

Returns:: True if object is initialized, or false if it is not. This is used to make sure that the text box's settings are valid before doing any drawing or update operations. If it detects any problems, it generates a string of errors and returns it by reference so they can be displayed.

Implements hoa_video::private_video::GUIElement.

void hoa_video::TextBox::SetDimensions	(	float	w,
		float	h
	)

Sets the width and height of the text box. Returns false and prints an error message.

Parameters:

	w	The width to set for the text box (for a 1024x768 coordinate system).
	h	The height to set for the text box (for a 1024x768 coordinate system). If the width or height are negative, or if they are larger than 1024 or 768 respectively, then the function will print an error message and will not change the properties of the textbox.

Definition at line 175 of file textbox.cpp.

References _height, _ReformatText(), _width, and hoa_video::VIDEO_DEBUG.

Referenced by hoa_map::private_map::DialogueManager::DialogueManager(), hoa_menu::private_menu::InventoryWindow::InventoryWindow(), hoa_shop::private_shop::ObjectInfoWindow::ObjectInfoWindow(), hoa_shop::private_shop::ShopActionWindow::ShopActionWindow(), and hoa_menu::private_menu::SkillsWindow::SkillsWindow().

Here is the call graph for this function:

void hoa_video::TextBox::SetDisplayMode ( const TEXT_DISPLAY_MODE & mode )

Sets the current text display mode (e.g. fading lines of text, etc.).

Parameters:

mode

The display mode to use for the text.

Definition at line 218 of file textbox.cpp.

References _mode, and hoa_video::VIDEO_TEXT_TOTAL.

void hoa_video::TextBox::SetDisplaySpeed ( float display_speed )

Sets the text display speed (in characters per second).

Parameters:

display_speed

The display speed, in terms ofcharacters per second. If the current display mode is one line at a time, then the display speed is based on VIDEO_CHARS_PER_LINE characters per line, so for example, a display speed of 10 would mean 3 seconds per line if VIDEO_CHARS_PER_LINE is 30.

Note:: This has no effect for textboxes using the VIDEO_TEXT_INSTANT display mode.

Definition at line 229 of file textbox.cpp.

References _display_speed, and hoa_video::VIDEO_DEBUG.

void hoa_video::TextBox::SetDisplayText ( const std::string & text )

A non-unicode version of SetDisplayText().

Parameters:

text

The text to be set in the box (a standard non-unicode string). See the unicode version of SetDisplayText for more details.

void hoa_video::TextBox::SetDisplayText ( const hoa_utils::ustring & text )

Sets the text for this box to the string passed in.

Parameters:

text

The text to display for the textbox

Note:: If you use a gradual text display mode like VIDEO_TEXT_CHAR, then the text will be displayed gradually and when it's done displaying, IsFinished() will return true.
This function checks the text passed in if it's too big for the textbox and inserts new lines where appropriate. If the text is so big that it can't fit even with word wrapping, an error is printed to the console if debugging is enabled.

Definition at line 241 of file textbox.cpp.

References _current_time, _display_speed, _end_time, _finished, hoa_video::private_video::GUIElement::_initialization_errors, hoa_video::private_video::GUIElement::_initialized, _mode, _num_chars, _ReformatText(), _text, _text_save, hoa_video::private_video::CHARS_PER_LINE, hoa_video::VIDEO_DEBUG, hoa_video::VIDEO_TEXT_CHAR, hoa_video::VIDEO_TEXT_FADECHAR, hoa_video::VIDEO_TEXT_FADELINE, hoa_video::VIDEO_TEXT_INSTANT, and hoa_video::VIDEO_TEXT_REVEAL.