A text based actor that can display text. More...

#include <CzActorText.h>

Inheritance diagram for CzActorText:

Public Member Functions
void	setText (const char *text)
	Sets the text that will be displayed by this actor.
const char *	getText () const
	Returns the text associates with this actor.
void	setRect (const CzIRect &rect)
	Sets a rectangular area that the text will be drawn inside of.
CzIRect	getRect () const
	Gets a rectangular area that the text will be drawn inside of.
void	setFlags (eCzFontFlags flags)
	Sets text flags.
void	setFont (CzFont *font)
	Sets a font.
CzFont *	getFont ()
	Gets a font.
void	setAlignH (eCzAlignH align)
	Sets horizontal alignment of the text.
void	setAlignV (eCzAlignV align)
	Sets vertical alignment of the text.
void	setMarginIsPadding (bool enable)
bool	setProperty (unsigned int property_name, const CzXomlProperty &data, bool delta)
	Sets the named property of the ActorText.
bool	setProperty (unsigned int property_name, const CzString &data, bool delta)
	Sets the named property of the actor.
bool	getProperty (unsigned int property_name, CzXomlProperty &prop)
	Gets the named property of the actor.
void	setAutoHeight (bool enable)
bool	isAutoHeight () const
bool	isFontLoaded () const
	CzActorText ()
virtual	~CzActorText ()
virtual bool	Init (CzFont *font, const CzIRect &rect, const CzString &text, int flags)
	Initialise the text based actor from a font and text.
virtual bool	UpdateVisual ()
	Updates the actors visual.
virtual void	NotifyOrientationChange (CzScene::eOrientation old_orientation, CzScene::eOrientation new_orientation)
	Handles the orientation change event.
int	LoadFromXoml (IzXomlResource parent, bool load_children, CzXmlNode node)
	Creates an instance of this class from XML.
bool	UpdateFromAnimation (CzAnimInstance *animation)
	Updates actor property from supplied animation.
Static Public Member Functions
static void	InitClass ()
	Initialises the class.
static void	ReleaseClass ()
static bool	_setText (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getText (IzXomlResource *target)
static bool	_setFont (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getFont (IzXomlResource *target)
static bool	_setRect (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getRect (IzXomlResource *target)
static bool	_setAlignH (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setAlignV (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setWrap (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static bool	_setSkew (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getSkew (IzXomlResource *target)
static bool	_setBeforeChildren (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getBeforeChildren (IzXomlResource *target)
static bool	_setFilter (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getFilter (IzXomlResource *target)
static bool	_setAutoHeight (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getAutoHeight (IzXomlResource *target)
static bool	_setAlphaMode (IzXomlResource *target, const CzXomlProperty &prop, bool add)
static CzXomlProperty	_getAlphaMode (IzXomlResource *target)
static CzXomlProperty	_getTextSize (IzXomlResource *target)
Protected Member Functions
bool	UpdateBinding (unsigned int property_name, CzXomlVariable *var)
	Updates an actor property from the supplied XOML variable.
void	recalculateHeight ()
	Recalculates the height of the text and sets a new size.
Protected Attributes
bool	AutoHeight
	When true the contained text will decide the height of the text display rect.
bool	MarginIsPadding
	if true then the margin parameter will be used as padding instead
CzIRect	OriginallRect
bool	FontLoaded
Static Protected Attributes
static CzXomlClassDef *	ActorTextClassDef = NULL

Detailed Description

A text based actor that can display text.

Text actors can be created directly but are usually used in conjunction with some other actor. For example user interface controls usually host a text actor on an image actor that represents the background to the user interface control. Lets take a look at text actor properties:

Font (font) - Name of font to use to draw the text
Rect (x, y, width, height) - The area that the text should be drawn inside of. If not provided then the area will be calculated based on the screen size or the parent actor
Text (string) - String to display
AlignH (centre, left, right) - Horizontal alignment, default is centre
AlignV (middle, top, bottom) - Vertical alignment, default is middle
Wrap (boolean) - If true then text is wrapped onto next line if too long to fit on one line, if not then text will overhand its container
Skew (top, bottom, left, right) - Four parameter skewing, which allows the actor to be skewed in four different directions
BeforeChildren (boolean) - When set to true this actor will be rendered before its children, otherwise it will be rendered afterwards (default is true)
Filter (boolean) - When set to true this actor will rendered using filtering (default is true)
AlphaMode (alpha_mode) - Sets the mode to use when mixing transparency (alpha) from the actor. AlphaMode can be one of none, half, add, sub and blend (default mode is blend)
AutoHeight (boolean) - When set to true the height of the text actor will be recalculated to make it large enough to fit its text content. For example, if you set the original Rect to only hold a single line but the text takes 3 lines then the actor will be resized to fit all 3 lines of text (default is false).
Anchor (topleft or centre) - Sets the draw anchor (topleft causes the actor to be displayed relative to its top-left cornr whilst centre will use the actors centre)

Notes:

A font must be specified
Because a text actor inherits from a basic actor, it inherits all of the basic actors properties as well as those properties shown above.

Now lets take a quick look at a text actor definition in XOML:

XOML Example

<ActorText Font="serif" Text="Hello World" Position="10, 20" />

Constructor & Destructor Documentation

CzActorText::CzActorText ( ) [inline]

virtual CzActorText::~CzActorText ( ) [inline, virtual]

Member Function Documentation

CzXomlProperty CzActorText::_getAlphaMode ( IzXomlResource * target ) [static]

CzXomlProperty CzActorText::_getAutoHeight ( IzXomlResource * target ) [static]

CzXomlProperty CzActorText::_getBeforeChildren ( IzXomlResource * target ) [static]

CzXomlProperty CzActorText::_getFilter ( IzXomlResource * target ) [static]

CzXomlProperty CzActorText::_getFont ( IzXomlResource * target ) [static]

CzXomlProperty CzActorText::_getRect ( IzXomlResource * target ) [static]

CzXomlProperty CzActorText::_getSkew ( IzXomlResource * target ) [static]

CzXomlProperty CzActorText::_getText ( IzXomlResource * target ) [static]

CzXomlProperty CzActorText::_getTextSize ( IzXomlResource * target ) [static]

bool CzActorText::_setAlignH	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzActorText::_setAlignV	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzActorText::_setAlphaMode	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzActorText::_setAutoHeight	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzActorText::_setBeforeChildren	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzActorText::_setFilter	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzActorText::_setFont	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzActorText::_setRect	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzActorText::_setSkew	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzActorText::_setText	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

bool CzActorText::_setWrap	(	IzXomlResource *	target,
		const CzXomlProperty &	prop,
		bool	add
	)		`[static]`

CzFont * CzActorText::getFont ( )

Gets a font.

Gets the font that is used to render the text.

Returns:: null if it fails, else the font.

bool CzActorText::getProperty	(	unsigned int	property_name,
		CzXomlProperty &	prop
	)		`[virtual]`

Gets the named property of the actor.

Returns the named property of the actor. The properties value is returned in a CzXomlProperty which is a structure that contains a union of all possible property types. Note that as CzActorText is derived from CzActor, all CzActor properties will also be checked against.

Parameters:

	property_name	Name of the property.
[out]	prop	The property data that.

Returns:: true if it succeeds, false if property does not exist.

Reimplemented from CzActor.

CzIRect CzActorText::getRect ( ) const

Gets a rectangular area that the text will be drawn inside of.

Returns:: The rectangular area.

const char * CzActorText::getText ( ) const

Returns the text associates with this actor.

Returns:: null if no text, else the text.

bool CzActorText::Init	(	CzFont *	font,
		const CzIRect &	rect,
		const CzString &	text,
		int	flags
	)		`[virtual]`

Initialise the text based actor from a font and text.

Initialises the text actor from a font, a rect, text and flags. The size of the actor will be chosen from the with and height of th supplied rectangle. If negative width and height values are supplied then these values will be taken as percntage based sizes. Note that this method will create a CzTextSprite visual and add it to the scenes sprite manager.

Parameters:

[in,out]	font	If non-null, the font.
[in,out]	rect	The rectangular area.
[in,out]	text	The text.
	flags	The flags.

Returns:: true if it succeeds, false if it fails.

void CzActorText::InitClass ( ) [static]

Initialises the class.

Sets up the classes avaiiable properties. Used by the XOML system to find, set amd get class properties.

Reimplemented from CzActor.

bool CzActorText::isAutoHeight ( ) const [inline]

bool CzActorText::isFontLoaded ( ) const [inline]

int CzActorText::LoadFromXoml	(	IzXomlResource *	parent,
		bool	load_children,
		CzXmlNode *	node
	)		`[virtual]`

Creates an instance of this class from XML.

LoadFromXoml is the main method used by all classes that can be instantiated from XOML mark-up. This method creates an instance of this class from the supplied XML node structure specified by node. if parent is not NULL then the created instance will utilise the supplied parent to determine where it should live within the app. For example, if the parent is a scene then the actor will be placed in that scene. if the parent is another actor then this actor will be placed into the scene of the supplied actor and linked as a child to the parent actor. If load_chlldren is true then any child nodes contained within the actor will also be loaded. Note that as CzActorText is derived from CzActor, CzActor::LoadFromXoml() will also be called to load CzActor specific properties.

Parameters:

[in]	parent	If non-null, the parent.
	load_children	true to load child nodes.
[in]	node	If non-null, the XOML markup node that defines this object

Returns:: negative value for error. if 0 then processing of further XOML will stop.

Reimplemented from CzActor.

void CzActorText::NotifyOrientationChange	(	CzScene::eOrientation	old_orientation,
		CzScene::eOrientation	new_orientation
	)		`[virtual]`

Handles the orientation change event.

When a screen orientation or size change occurs all actors will receive this event emabling them to modify themselves to take advantage of the new screen orientation / size. the default implementation for CzActorText updates margin and visual sizes if they are precentage based. It also calls CzActor::NotifyOrientationChange() to update the position.

Parameters:

old_orientation	The old orientation.
new_orientation	The new orientation.

Reimplemented from CzActor.

void CzActorText::recalculateHeight ( ) [protected]

Recalculates the height of the text and sets a new size.

void CzActorText::ReleaseClass ( ) [static]

Reimplemented from CzActor.

void CzActorText::setAlignH ( eCzAlignH align )

Sets horizontal alignment of the text.

Sets how text will be horizontally aligned. Alignment options include:

AlignH_Left
AlignH_Centre
AlignH_Right

Parameters:

align The horizontal alignment.

void CzActorText::setAlignV ( eCzAlignV align )

Sets vertical alignment of the text.

Sets how text will be vertically aligned. Alignment options include:

AlignV_Top
AlignV_Middle
AlignV_Bottom

Parameters:

align The vertical alignment.

void CzActorText::setAutoHeight ( bool enable ) [inline]

void CzActorText::setFlags ( eCzFontFlags flags )

Sets text flags.

Sets flags that modify how the text is rendered.

Parameters:

flags The flags.

void CzActorText::setFont ( CzFont * font )

Sets a font.

Sets the font that is used to render the text.

Parameters:

[in,out] font If non-null, the font.

void CzActorText::setMarginIsPadding ( bool enable ) [inline]

bool CzActorText::setProperty	(	unsigned int	property_name,
		const CzXomlProperty &	data,
		bool	delta
	)		`[virtual]`

Sets the named property of the ActorText.

Sets the named property of this ActorText. The properties value supplied will be converted. If delta is set to true then the existing value of the property will be added to instead of replaced.

Parameters:

	property_name	Name of the property as a string hash (faster searching).
[in]	data	The property data.
	delta	true if property should be added to instead of replaced.

Returns:: true if it succeeds, false if property does not exist.

Reimplemented from CzActor.

bool CzActorText::setProperty	(	unsigned int	property_name,
		const CzString &	data,
		bool	delta
	)		`[virtual]`

Sets the named property of the actor.

Sets the named property of this actor. The properties value (data) is supplied as a string and will be converted. If delta is set to true then the existing value of the property will be added to instead of replaced.

Parameters:

	property_name	Name of the property as a string hash (faster searching).
[in]	data	The property data.
	delta	true if property should be added to instead of replaced.

Returns:: true if it succeeds, false if property does not exist.

Reimplemented from CzActor.

void CzActorText::setRect ( const CzIRect & rect )

Sets a rectangular area that the text will be drawn inside of.

Sets a rectangular area that the text will be drawn inside of, taking into account any text margins. If this actor has docking set then it will be re-docked taking into account its new size.

Parameters:

rect	The rectangular area.

void CzActorText::setText ( const char * text )

Sets the text that will be displayed by this actor.

Parameters:

text	The text to display.

bool CzActorText::UpdateBinding	(	unsigned int	property_name,
		CzXomlVariable *	var
	)		`[protected, virtual]`

Updates an actor property from the supplied XOML variable.

Updates a single property from the value of the bound XOML variable. Note that as CzActorText is derived from CzActor, all CzActor properties will also be checked against.

Parameters:

	property_name	Name of the property.
[in,out]	var	If non-null, the variable.

Returns:: true if it succeeds, false if property does not exist.

Reimplemented from CzActor.

bool CzActorText::UpdateFromAnimation ( CzAnimInstance * animation ) [virtual]

Updates actor property from supplied animation.

Updates the actors property that is specified by the supplied animation. When a timeline animation targets the property of an actor this method will be called by the animation to move the animations frame data into its target property. Note that as CzActorText is derived from CzActor, all CzActor properties will also be checked against.

Parameters:

[in] animation If non-null, the animation.