Guiliani  Version 2.4 revision 5970 (build 3)
CGUIText Class Reference

Class for handling a text. More...

#include <GUIText.h>

Inheritance diagram for CGUIText:

Classes

class  ExtendedString_t
 Class containing a text, its width and its height. More...
 

Public Types

enum  HorAligned_t { H_LEFT, H_CENTERED, H_RIGHT, H_PROPERTY }
 Possible horizontal alignments. More...
 
enum  TextColorTypeFlags_t { TEXT_COLOR_STANDARD_IS_PROPERTY = 1, TEXT_COLOR_HIGHLIGHTED_IS_PROPERTY = 2, TEXT_COLOR_GRAYED_OUT_IS_PROPERTY = 4, TEXT_COLOR_PRESSED_IS_PROPERTY = 8 }
 Enumeration indicating if a property or a color value is used for each text color.
 
enum  VerAligned_t { V_TOP, V_CENTERED, V_BOTTOM }
 Possible vertical alignments. More...
 

Public Member Functions

 CGUIText (const CGUIObject *const pParentObject, const eC_String &kText, const eC_Value &vXPos=eC_FromInt(0), const eC_Value &vYPos=eC_FromInt(0), const eC_Bool &bSingleLine=true)
 
 CGUIText (const CGUIObject *const pParentObject, const eC_String *const pkText, const eC_Value &vXPos=eC_FromInt(0), const eC_Value &vYPos=eC_FromInt(0), const eC_Bool &bSingleLine=true)
 
 CGUIText (const CGUIObject *const pParentObject, const TextResource_t &eTextID, const eC_Value &vXPos=eC_FromInt(0), const eC_Value &vYPos=eC_FromInt(0), const eC_Bool &bSingleLine=true)
 
 CGUIText (const CGUIText &kTextToBeCopied)
 
virtual ~CGUIText ()
 Destructor.
 
virtual CGUITextClone () const
 
void FitHeightToContainedText ()
 
void GetAdjustment (eC_Value &vXAdjustment, eC_Value &vYAdjustment) const
 
eC_Bool GetAutoSize () const
 
const CGUIObjectGetContainingObject () const
 
FontResource_t GetFont () const
 
eC_Int GetFontSize () const
 
eC_Float GetFontSpacing () const
 
HorAligned_t GetHorAlign () const
 
virtual eC_Value GetLineSpacing () const
 
eC_UInt GetNumberOfLines ()
 
virtual eC_Value GetRelXPos () const
 
virtual eC_Value GetRelYPos () const
 
virtual void GetRequiredOrgTextSpace (eC_Value &vTextWidth, eC_Value &vTextHeight)
 
virtual eC_Value GetRequiredTextHeightForWidth (eC_Value vAvailableWidth=0)
 
virtual void GetRequiredTextSpace (eC_Value &vTextWidth, eC_Value &vTextHeight)
 
const CGUIRectGetSpecificClipRect () const
 
const eC_String * GetText () const
 
void GetTextColor (eC_UInt &uiTextColorStandard, eC_UInt &uiTextColorHighlighted, eC_UInt &uiTextColorGrayedOut, eC_UInt &uiTextColorPressed) const
 
void GetTextColor (GlobalProperty_t &eTextColorStandard, GlobalProperty_t &eTextColorHighlighted, GlobalProperty_t &eTextColorGrayedOut, GlobalProperty_t &eTextColorPressed) const
 
eC_UInt GetTextColorGrayedOut () const
 
eC_UInt GetTextColorHighlighted () const
 
eC_UInt GetTextColorPressed () const
 
eC_UInt GetTextColorStandard () const
 
virtual eC_Value GetTextHeight () const
 
TextResource_t GetTextID () const
 
virtual eC_Value GetTextWidth () const
 
VerAligned_t GetVerAlign () const
 
void InvalidateArea ()
 
eC_Bool IsBidi () const
 
eC_Bool IsTextCut ()
 
eC_Bool IsTextID () const
 
eC_Bool IsTextSingleLine () const
 
CGUITextoperator= (const CGUIText &kSource)
 
virtual void PrintText ()
 
virtual void ReadFromStream ()
 
void SetAdjustment (const eC_Value &vXAdjustment, const eC_Value &vYAdjustment)
 
void SetAligned (const VerAligned_t &eVerAligned=V_TOP, const HorAligned_t &eHorAligned=H_LEFT)
 
void SetAlignedHorizontal (const HorAligned_t &eHorAligned=H_LEFT)
 
void SetAlignedVertical (const VerAligned_t &eVerAligned=V_TOP)
 
void SetAutoSize (const eC_Bool &bAutoSize)
 
void SetContainingObject (const CGUIObject *const pParent)
 
virtual void SetFont (const FontResource_t &eFontID)
 
void SetFontSpacing (const eC_Float &fFontSpacing)
 
virtual void SetLineSpacing (const eC_Value vLineSpacing)
 
void SetRelRect (const CGUIRect &kRect)
 
virtual void SetRelXPos (const eC_Value &vRelXPos)
 
virtual void SetRelYPos (const eC_Value &vRelYPos)
 
void SetSpecificClipRect (const CGUIRect &kRect)
 
void SetTextAlignmentProperty (const GlobalProperty_t &eTextAlignmentProperty)
 
virtual void SetTextColor (const eC_UInt &uiTextColorStandard, const eC_UInt &uiTextColorHighlighted, const eC_UInt &uiTextColorGrayedOut, const eC_UInt &uiTextColorPressed)
 
virtual void SetTextColor (const GlobalProperty_t &eTextColorStandard, const GlobalProperty_t &eTextColorHighlighted, const GlobalProperty_t &eTextColorGrayedOut, const GlobalProperty_t &eTextColorPressed)
 
void SetTextColorGrayedOut (const eC_UInt &uiTextColorGrayedOut)
 
void SetTextColorGrayedOut (const GlobalProperty_t &eTextColorPropertyGrayedOut)
 
void SetTextColorHighlighted (const eC_UInt &uiTextColorHighlighted)
 
void SetTextColorHighlighted (const GlobalProperty_t &eTextColorPropertyHighlighted)
 
void SetTextColorPressed (const eC_UInt &uiTextColorPressed)
 
void SetTextColorPressed (const GlobalProperty_t &eTextColorPropertyPressed)
 
void SetTextColorStandard (const eC_UInt &uiTextColorStandard)
 
void SetTextColorStandard (const GlobalProperty_t &eTextColorPropertyStandard)
 
virtual void SetTextHeight (const eC_Value &vTextHeight)
 
virtual void SetTextID (const TextResource_t &eTextID)
 
virtual void SetTextSingleLine (const eC_Bool &bSingleLine)
 
void SetTextString (const eC_String *pkTextString)
 
virtual void SetTextString (const eC_String &kTextString)
 
virtual void SetTextWidth (const eC_Value &vTextWidth)
 
virtual void WriteToStream (const eC_Bool bWriteTextType=false)
 
- Public Member Functions inherited from CGUIColorPropertyObserver
 CGUIColorPropertyObserver ()
 default-constructor
 
 ~CGUIColorPropertyObserver ()
 destructor
 
eC_UInt AddColorProperty (const eC_Bool &bColorIsProperty, const eC_UInt &uiColorValue, const GlobalProperty_t &eColorProperty)
 
void AddColorProperty (const eC_UInt &uiIndex, const eC_Bool &bColorIsProperty, const eC_UInt &uiColorValue, const GlobalProperty_t &eColorProperty)
 
ColorValue_t GetColorProperty (const eC_UInt &uiIndex) const
 
eC_UInt GetColorValue (const eC_UInt &uiIndex) const
 
virtual void OnColorPropertyChange ()
 
void RemoveColorProperty (const eC_UInt &uiIndex)
 
void SetColorProperty (const eC_UInt &uiIndex, const eC_UInt &uiColorValue)
 
void SetColorProperty (const eC_UInt &uiIndex, const GlobalProperty_t &eColorProperty)
 
void SetColorProperty (const eC_UInt &uiIndex, const ColorValue_t &kColorValue)
 
- Public Member Functions inherited from CGUIObserver
 CGUIObserver ()
 Default constructor.
 
virtual ~CGUIObserver ()
 Default destructor. Notifies all subjects of destruction.
 
const eC_TListDoubleLinked< CGUISubject * > & GetSubjectList () const
 
virtual void OnNotification (const eC_String &kMessage)
 
virtual void OnNotification (const CGUIObject *const pkUpdatedObject)
 
virtual void OnNotification (const CGUIValue &kObservedValue, const CGUIObject *const pkUpdatedObject, const eC_UInt uiX=0, const eC_UInt uiY=0)
 
void SetAutoDelete (const eC_Bool bAutoDelete)
 
- Public Member Functions inherited from CGUIStreamableObject
const eC_String & GetXMLTag () const
 
void SetXMLTag (const eC_String &kXMLTag)
 

Static Public Member Functions

static eC_String GetEllipsisString ()
 
static eC_String GetHyphenString ()
 
static void SetEllipsisString (const eC_String &kEllipsis)
 
static void SetHyphenString (const eC_String &kHyphen)
 

Static Public Attributes

static const eC_Char XMLTAG_TEXT_COLOR_GRAYEDOUT [] = "TextColorGrayedOut"
 xml-tag for grayedout-color
 
static const eC_Char XMLTAG_TEXT_COLOR_HIGHLIGHTED [] = "TextColorHighlighted"
 xml-tag for highlighted-color
 
static const eC_Char XMLTAG_TEXT_COLOR_PRESSED [] = "TextColorPressed"
 xml-tag for pressed-color
 
static const eC_Char XMLTAG_TEXT_COLOR_PROPERTY_FLAGS [] = "ColorPropertyFlags"
 XML tag to be used when writing text colors into a stream. More...
 
static const eC_Char XMLTAG_TEXT_COLOR_STANDARD [] = "TextColorStandard"
 xml-tag for standard-color
 
static const eC_Char XMLTAG_TEXTID [] = "TextID"
 XML tag to be used when writing a text ID into a stream.
 
static const eC_Char XMLTAG_TEXTTYPEID [] = "TextTypeID"
 XML tag to be used when writing a text type ID into a stream.
 
- Static Public Attributes inherited from CGUIStreamableObject
static const eC_Char XMLTAG_CLASSVERSION [] = "ClassVersion"
 

Protected Types

typedef eC_TListDoubleLinked< ExtendedString_tExtendedStringList_t
 The extended string list is a double-linked list of extended strings.
 
typedef eC_TListDoubleLinked< eC_UInt > UIntList
 Double linked List of unsigned integers.
 

Protected Member Functions

virtual void AdaptText ()
 
virtual void CollectHyphenationMarks (eC_String &rkStr, eC_UInt uiOffset)
 
eC_Bool ContainsHyphenationMarks (const eC_String &kStr) const
 
void CreateLocalTextCopy ()
 
virtual void FitString (ExtendedString_t &rkResultStrData, const eC_String &rkStrToAnalyse, eC_String &rkRestStr, eC_UInt &uiOffset)
 
virtual eC_Value GetPrintLineAbsXPos (const eC_Value vWidth)
 
virtual eC_Value GetPrintLineAbsXPos (const eC_UInt uiLine)
 
virtual eC_Value GetPrintLineAbsXPos ()
 
eC_Value GetRequiredTextHeight () const
 
eC_Value GetRequiredTextWidth () const
 
virtual eC_Value GetVerStartAbsYPos ()
 
virtual void OnNotification ()
 
eC_Bool PrepareClipRect ()
 
virtual void PreparePrint ()
 
void ReadFontColors (const eC_UInt uiVersion)
 
void SetRequiredTextHeight (eC_Value vRequiredTextHeight)
 
void SetRequiredTextWidth (eC_Value vRequiredTextWidth)
 
void SetTextCut (const eC_Bool bIsCut)
 
void WriteFontColors ()
 Helper function for WriteStream().
 
- Protected Member Functions inherited from CGUIObserver
virtual void AddSubject (CGUISubject *pSubjectToAdd)
 
virtual void RemoveSubject (CGUISubject *pSubjectToRemove)
 
- Protected Member Functions inherited from CGUIStreamableObject
eC_UInt ReadStreamingHeader (const eC_UInt &uiClassVersion, const eC_UInt &uiClassMinVersion=0) const
 
void WriteStreamingFooter (const eC_Bool &bWriteClassID) const
 
void WriteStreamingHeader (const eC_Bool &bWriteClassID, const eC_Char *const pkClassIDTag, const eC_Int &iClassID, const eC_UInt &uiClassVersion) const
 

Protected Attributes

eC_Bool m_bAdaptText
 
eC_Bool m_bSingleLine
 Indicates whether this text is single- or multi-line.
 
eC_Bool m_bTextIDLocalCopy
 
eC_Bool m_bTextIsBiDi
 Indicates whether the text is a BiDi-text.
 
eC_Bool m_bUseEllipsis
 use ellipsis if text is too long
 
HorAligned_t m_eHorAligned
 Horizontal alignment.
 
GlobalProperty_t m_eTextAlignmentProperty
 Property used for the text color for alignment. By default, this value is DUMMY_PROPERTY, i.e. a fixed alignment is used.
 
VerAligned_t m_eVerAligned
 Vertical alignment.
 
UIntList m_kHyphens
 List of hyphen positions in the original text.
 
ExtendedStringList_t m_kListStringsExtended
 List of strings to be printed, and their cached width and height.
 
const CGUIObjectm_pkParentObject
 The object containing (and printing) this text.
 
eC_String * m_pkText
 
eC_Value m_vLineHeight
 The height of one text line with this text's font.
 
eC_Value m_vLineSpacing
 The line spacing factor.
 
eC_Value m_vRelXPos
 X position of this text's printing area relative to the parent object.
 
eC_Value m_vRelYPos
 Y position of this text's printing area relative to the parent object.
 
eC_Value m_vRequiredOrgTextHeight
 
eC_Value m_vRequiredOrgTextWidth
 
eC_Value m_vTextHeight
 Height of this text's printing area.
 
eC_Value m_vTextWidth
 Width of this text's printing area.
 
eC_Value m_vXAdjustment
 Printing adjustment for m_vRelXPos.
 
eC_Value m_vYAdjustment
 Printing adjustment for m_vRelYPos.
 

Static Protected Attributes

static const ExtendedString_t ms_ckEmptyExtendedString
 An empty Extended String.
 
static const eC_String ms_ckEmptyString
 An empty string.
 
static const eC_String ms_ckSingleSpace
 A single space character for text size calculations.
 

Detailed Description

Class for handling a text.

Objects of this class represent texts but are no CGUIObject instances. They are instead assigned to a "parent" GUI object that has to take care of printing the text in its DoDraw implementation when needed. Controls (CGUIObjects) that want to display text should use CGUIText. For an example of how to print a simple text somewhere in your GUI, have a look at CGUIBaseTextField.

Each text object has basic attributes like font, text color and so on. It also has an area in which the text is aligned. This area is positioned relative to its containing ("parent") GUI object and can be adjusted by calling the methods SetRelXPos(), SetRelYPos(), SetTextWidth() and SetTextHeight(). The horizontal and vertical alignment can be set by calling SetAligned().

Clipping is done at the borders of the assigned containing CGUIObject but no extra clipping is done for the area in which the text is aligned. The area in which the text is aligned does only matter for formatting and positioning the text (line wrapping, cutting with ellipsis, position offset from containing object) but not for clipping. Therefore, if part of CGUIText's area is outside of CGUIObject's area and text is placed into this part then part of the text will be invisible because of clipping CGUIObject. That is, the text graphics belong to the graphics of the assigned containing CGUIObject in the same way as all other graphic of that GUI object.

A text is either a single-line or multi-line text (set either at construction time or later by calling SetTextSingleLine()). A single line text always shows only one line of text, whereas in multi-line mode the text may be wrapped at blank characters to achieve optimum line width usage. To further optimise line width usage, it is possible to enter "soft hyphenation" markers ("\-") in texts. These markers are not printed but enable multi-line texts to break words into pieces and insert hyphens in these places.

To print the character sequence backslash minus ("\-"), another backspace has to be prefixed to escape the special meaning, like this: "\\-".

To force linebreaks, enter ccLinebreak characters into the text.

In both single and multi-line texts, the text is cut off if it is too long to be displayed in its CGUIText area and an ellipsis ("...") is appended at the end. Certainly the ellipsis will be inside CGUIText's area.

Objects of this class can represent two different kinds of text: ID texts and string texts. An ID text is represented by a valid TextResource_t ID that is used to access the text in CGUILocalisationHandler whereas string texts manage an independent string on their own. Each text object internally has a text ID but only ID texts have a valid one; for string texts, the ID is invalid (TEXT_START_TAG). To determine what kind of text an object is, call IsTextID(). A CGUIText object can change its type during its lifetime if SetTextString() or SetTextID() is called.

Example:

// Create a text.
CGUIText* pkText = new CGUIText(this, // attach to "this" object
"Hello World!", // Text to display in this text object
eC_FromInt(0), eC_FromInt(0), // Position at coordinates 0,0 relative to containing object
true); // This text shall be single-line (=no word wrap)
// Sets the font.
pkText->SetFont(FontResource_t(GUI_PROP_DEFAULT_FONT));
// The colors of the text. They are used for different states of the containing object.
pkText->SetTextColor(0xffff0000, 0xffff00ff, 0xff0000ff, 0xff00ffff);
// Print text. This method is normally called in the DoDraw method of the containing object.
pkText->PrintText();

Member Enumeration Documentation

◆ HorAligned_t

Possible horizontal alignments.

Enumerator
H_LEFT 

The text is left-aligned.

H_CENTERED 

The text is horizontally centered.

H_RIGHT 

The text is right-aligned.

H_PROPERTY 

The text is aligned according to property.

◆ VerAligned_t

Possible vertical alignments.

Enumerator
V_TOP 

The text is aligned at the top of its area.

V_CENTERED 

The text is vertically centered in its area.

V_BOTTOM 

The text is aligned at the bottom of its area.

Constructor & Destructor Documentation

◆ CGUIText() [1/4]

CGUIText::CGUIText ( const CGUIObject *const  pParentObject,
const eC_String &  kText,
const eC_Value &  vXPos = eC_FromInt(0),
const eC_Value &  vYPos = eC_FromInt(0),
const eC_Bool &  bSingleLine = true 
)

Constructs a string text. By default, the text width and height are set to the width and height of the parent object minus the relative positions.

Parameters
pParentObjectPointer to object containing the text.
kTextReference of text string.
vXPosX position of text relative to the parent.
vYPosY position of text relative to the parent.
bSingleLinetrue: text is always displayed in a single line, false: lines can be wrapped.

◆ CGUIText() [2/4]

CGUIText::CGUIText ( const CGUIObject *const  pParentObject,
const eC_String *const  pkText,
const eC_Value &  vXPos = eC_FromInt(0),
const eC_Value &  vYPos = eC_FromInt(0),
const eC_Bool &  bSingleLine = true 
)

Constructs a string text. By default, the text width and height are set to the width and height of the parent object minus the relative positions.

Parameters
pParentObjectPointer to object containing the text.
pkTextPointer of text string.
vXPosX position of text relative to the parent.
vYPosY position of text relative to the parent.
bSingleLinetrue: text is always displayed in a single line, false: lines can be wrapped.

◆ CGUIText() [3/4]

CGUIText::CGUIText ( const CGUIObject *const  pParentObject,
const TextResource_t eTextID,
const eC_Value &  vXPos = eC_FromInt(0),
const eC_Value &  vYPos = eC_FromInt(0),
const eC_Bool &  bSingleLine = true 
)

Constructs an ID text. By default, the text width and height are set to the width and height of the parent object minus the relative positions.

Parameters
pParentObjectPointer to object containing the text.
eTextIDID of the internationalised text.
vXPosX position of text relative to the parent.
vYPosY position of text relative to the parent.
bSingleLinetrue: text is always displayed in a single line, false: lines can be wrapped.

◆ CGUIText() [4/4]

CGUIText::CGUIText ( const CGUIText kTextToBeCopied)

Copy constructor.

Parameters
kTextToBeCopiedThe text object to be copied.

Member Function Documentation

◆ AdaptText()

void CGUIText::AdaptText ( )
protectedvirtual

Adapt the text to the given width of the text field. The only adaptation made is replacing some trailing part of the last text line by Ellipsis characters. No font attribute, like font size, is changed. The function also removes HyphenationMarks from a single line text and calculates the required text width and height. For multi line texts this method breaks the original text into a list of strings at positions indicated by the user. It then calls CreateStringList() for further processing. This method only performs calculations if m_bAdaptText is set to true. Therefore, any method that changes attributes related to the text layout (including font settings, area size and so on) should set this flag to true instead of calling this method directly. It is called in as few places as possible.

Reimplemented in CGUIRichText, and CGUIScrollingText.

◆ Clone()

CGUIText * CGUIText::Clone ( ) const
virtual

Clones the instance of the GUIText object.

Returns
Reference to the cloned GUIText object.

Reimplemented in CGUIEditableText, CGUIRichText, and CGUIScrollingText.

◆ CollectHyphenationMarks()

void CGUIText::CollectHyphenationMarks ( eC_String &  rkStr,
eC_UInt  uiOffset 
)
protectedvirtual

Removes hyphenation marks from a string and stores their positions in a list. It goes through the string, removes every hyphenation mark and adds its position (adjusted with the offset) to the list.

Parameters
[in,out]rkStrThe string to be searched for hyphenation marks. When this method returns, all of them are removed.
[in]uiOffsetOffset of rkStr in this text's string.

◆ ContainsHyphenationMarks()

eC_Bool CGUIText::ContainsHyphenationMarks ( const eC_String &  kStr) const
protected

Checks a string for non-escaped hyphenation marks.

Parameters
kStrThe string to be checked for hyphenation marks.
Returns
True if kStr contains at least one hyphenation mark, otherwise False.

◆ CreateLocalTextCopy()

void CGUIText::CreateLocalTextCopy ( )
protected

This creates a copy of a TextID which is stored in the localisation handler, for local modifications. The copy is stored in m:pkText. If a local copy already exists, this will do nothing.

◆ FitHeightToContainedText()

void CGUIText::FitHeightToContainedText ( )

Resizes the GUIText's height so that the contained text will be fully visible and not truncated. The text's width will be left untouched.

◆ FitString()

void CGUIText::FitString ( ExtendedString_t rkResultStrData,
const eC_String &  rkStrToAnalyse,
eC_String &  rkRestStr,
eC_UInt &  uiOffset 
)
protectedvirtual

Fits a string to the area width of this text object. The goal of this method is to cut as few characters as possible from the string while using as much of the area width of this text object as possible.

This method returns not only the result (fitting ExtendedString) but also the string that was cut off to make it available for further processing.

The algorithm starts by searching for a fitting word boundary (blank characters). Starting from the beginning of the found word, it tries adjusting the width character by character. It then applies hyphenation and adjusts the result strings.

Parameters
[out]rkResultStrDataThe result of the analysis is stored here.
[in]rkStrToAnalyseThe string that is to be analysed.
[out]rkRestStrReturns the string that did not fit and was cut off of pkStrToAnalyse.
[in,out]uiOffsetThe absolute offset (position) of pkStrToAnalyse in the original text represented by this object. Required for finding the correct hyphenation points. When this method returns, this value is updated to reflect the offset of pkRestStr for further processing.

◆ GetAdjustment()

void CGUIText::GetAdjustment ( eC_Value &  vXAdjustment,
eC_Value &  vYAdjustment 
) const
inline

Returns adjustment values. These values are only used by PrintText(). The values are added to the current relative x and y positions, but only for printing. A common use case for this feature is a button that displays its text one or two pixels displaced while the button is pressed down.

Parameters
vXAdjustmentThe adjustment in X direction.
vYAdjustmentThe adjustment in Y direction.

◆ GetAutoSize()

eC_Bool CGUIText::GetAutoSize ( ) const
inline

Get autosize of control

Returns
true if active

◆ GetContainingObject()

const CGUIObject* CGUIText::GetContainingObject ( ) const
inline

Get the object which contains the text.

Returns
The object which contains the text.

◆ GetEllipsisString()

static eC_String CGUIText::GetEllipsisString ( )
inlinestatic

Returns the marker which will be append if a text has to be cut-off because of insufficient space.

Returns
String to be append on cut-off texts.

◆ GetFont()

FontResource_t CGUIText::GetFont ( ) const
inline

Retrieves the font.

Returns
Font identifier.

◆ GetFontSize()

eC_Int CGUIText::GetFontSize ( ) const

Retrieves the font size of set font.

Returns
Font size.

◆ GetFontSpacing()

eC_Float CGUIText::GetFontSpacing ( ) const
inline

Retrieves the font spacing (space between two letters).

Returns
Font spacing in subpixels.

◆ GetHorAlign()

HorAligned_t CGUIText::GetHorAlign ( ) const
inline

Retrieves the horizontal alignment.

Returns
Horizontal alignment.

◆ GetHyphenString()

static eC_String CGUIText::GetHyphenString ( )
inlinestatic

Returns the hyphen string which will be used on cutting strings.

Returns
Currently set hyphen string.

◆ GetLineSpacing()

virtual eC_Value CGUIText::GetLineSpacing ( ) const
inlinevirtual

Returns the current line spacing factor.

Returns
Current line spacing factor.

◆ GetNumberOfLines()

eC_UInt CGUIText::GetNumberOfLines ( )
inline

Returns the number of lines in this text.

Returns
Total number of lines in text.

◆ GetPrintLineAbsXPos() [1/3]

eC_Value CGUIText::GetPrintLineAbsXPos ( const eC_Value  vWidth)
protectedvirtual

Get the absolute horizontal position at which the text with the given width should be printed, with regard to the active horizontal alignment.

Parameters
vWidthwidth of the text to be printed.
Returns
The X position where kString should be printed.

◆ GetPrintLineAbsXPos() [2/3]

eC_Value CGUIText::GetPrintLineAbsXPos ( const eC_UInt  uiLine)
protectedvirtual

Get the absolute horizontal position at which a line of a multi-line text should be printed, with regard to the active horizontal alignment. Calls GetPrintLineAbsXPos with the cached width of the given line of text.

Parameters
uiLineIndex of the line of text which is to be printed.
Returns
The X position where kString should be printed.

◆ GetPrintLineAbsXPos() [3/3]

eC_Value CGUIText::GetPrintLineAbsXPos ( )
protectedvirtual

Get the absolute horizontal position at which the internal text should be printed with regard to the active horizontal alignment. Calls GetPrintLineAbsXPos with the cached width of the internal string.

Returns
The X position where kString should be printed.

◆ GetRelXPos()

virtual eC_Value CGUIText::GetRelXPos ( ) const
inlinevirtual

Returns the relative x position to the parent object.

Returns
The x position of this text relative to the parent object.

Reimplemented in CGUIScrollingText.

◆ GetRelYPos()

virtual eC_Value CGUIText::GetRelYPos ( ) const
inlinevirtual

Returns the relative y position to the parent object.

Returns
The y position of this text relative to the parent object.

Reimplemented in CGUIScrollingText.

◆ GetRequiredOrgTextSpace()

void CGUIText::GetRequiredOrgTextSpace ( eC_Value &  vTextWidth,
eC_Value &  vTextHeight 
)
virtual

Get the required space for the text. Calculates the space required for printing the original text string in a single line. No line breaks or hyphenation markers are taken into account.

Parameters
[out]vTextWidthThe required text width.
[out]vTextHeightThe required text height.

Reimplemented in CGUIRichText.

◆ GetRequiredTextHeight()

eC_Value CGUIText::GetRequiredTextHeight ( ) const
inlineprotected

Returns the required text height.

Returns
Required text height

◆ GetRequiredTextHeightForWidth()

eC_Value CGUIText::GetRequiredTextHeightForWidth ( eC_Value  vAvailableWidth = 0)
virtual

Get the required height for the complete, uncut text for a given width. If the text is a multi-line text, the required height for the wrapped text is returned. If the text is single-line, height for the single line is returned.

Parameters
[in]vAvailableWidthThe available width for the text. By default, the current width is used.
Returns
The required height.

◆ GetRequiredTextSpace()

void CGUIText::GetRequiredTextSpace ( eC_Value &  vTextWidth,
eC_Value &  vTextHeight 
)
virtual

Get the required space for the text. If the text is a multi-line text, the required space for the wrapped text is returned. If the text is single-line, the width of the whole text is returned. Note that the returned width will also include potential ellipsis in case the text got truncated.

Parameters
[out]vTextWidthThe required text width.
[out]vTextHeightThe required text height.

◆ GetRequiredTextWidth()

eC_Value CGUIText::GetRequiredTextWidth ( ) const
inlineprotected

Returns the required text width.

Returns
Required text width

◆ GetSpecificClipRect()

const CGUIRect& CGUIText::GetSpecificClipRect ( ) const
inline

Get the currently set specific cliprect.

Returns
The rect (if set), or an invalid rect ((0,0,0,0) if no specific cliprect was set.

◆ GetText()

const eC_String * CGUIText::GetText ( ) const

Retrieves the text. The text is returned as an eC_String* and can be NULL.

Returns
A pointer to the text of this object.

◆ GetTextColor() [1/2]

void CGUIText::GetTextColor ( eC_UInt &  uiTextColorStandard,
eC_UInt &  uiTextColorHighlighted,
eC_UInt &  uiTextColorGrayedOut,
eC_UInt &  uiTextColorPressed 
) const

Retrieves the text color.

Parameters
uiTextColorStandardStandard Text color in ARGB coding (e.g. 0xFFFFFFFF).
uiTextColorHighlightedText color in ARGB coding if the parent object is highlighted.
uiTextColorGrayedOutText color in ARGB coding if the parent object is grayed out.
uiTextColorPressedText color in ARGB coding if the parent object is pressed.

◆ GetTextColor() [2/2]

void CGUIText::GetTextColor ( GlobalProperty_t eTextColorStandard,
GlobalProperty_t eTextColorHighlighted,
GlobalProperty_t eTextColorGrayedOut,
GlobalProperty_t eTextColorPressed 
) const

Retrieves the text color.

Parameters
eTextColorStandardStandard Text color as property (e.g. 0xFFFFFFFF).
eTextColorHighlightedText color as property if the parent object is highlighted.
eTextColorGrayedOutText color as property if the parent object is grayed out.
eTextColorPressedText color as property if the parent object is pressed.

◆ GetTextColorGrayedOut()

eC_UInt CGUIText::GetTextColorGrayedOut ( ) const

Returns the currently used color for grayedout-state

Returns
grayedout-color

◆ GetTextColorHighlighted()

eC_UInt CGUIText::GetTextColorHighlighted ( ) const

Returns the currently used color for highlighted-state

Returns
highlighted-color

◆ GetTextColorPressed()

eC_UInt CGUIText::GetTextColorPressed ( ) const

Returns the currently used color for pressed-state

Returns
pressed-color

◆ GetTextColorStandard()

eC_UInt CGUIText::GetTextColorStandard ( ) const

Returns the currently used color for standard-state

Returns
standard-color

◆ GetTextHeight()

virtual eC_Value CGUIText::GetTextHeight ( ) const
inlinevirtual

Get the height of the text area.

Returns
The height of the text area.

Reimplemented in CGUIScrollingText.

◆ GetTextID()

TextResource_t CGUIText::GetTextID ( ) const
inline

Retrieves the TextID represented by this object.

Returns
The TextID of the text attribute of this object. Attention! For a string text the ID is invalid. To determine the type of a text object, use IsTextID().

◆ GetTextWidth()

virtual eC_Value CGUIText::GetTextWidth ( ) const
inlinevirtual

Get the width of the text area.

Returns
The width of the text area.

Reimplemented in CGUIScrollingText.

◆ GetVerAlign()

VerAligned_t CGUIText::GetVerAlign ( ) const
inline

Retrieves the vertical alignment.

Returns
Vertical alignment.

◆ GetVerStartAbsYPos()

eC_Value CGUIText::GetVerStartAbsYPos ( )
protectedvirtual

Get the absolute vertical position at which the first line of the text begins. Takes the alignment into account.

Returns
The vertical absolute position at which the first line of text should be printed.

◆ InvalidateArea()

void CGUIText::InvalidateArea ( )

Invalidates the area of the text to be printed. Note that InvalidateArea has to be called before and after changing the text of this object! Example:

pMyText->InvalidateArea();
pMyText->SetTextString("Hello Guiliani!");
pMyText->InvalidateArea();

◆ IsBidi()

eC_Bool CGUIText::IsBidi ( ) const

Checks if the currently set text contains any BiDi-characters.

Returns
true if text contains BiDi-chracters

◆ IsTextCut()

eC_Bool CGUIText::IsTextCut ( )
inline

Determine whether the text is cut and an ellipsis (...) is appended.

Returns
True if the string is cut and an ellipsis is appended, otherwise False.

◆ IsTextID()

eC_Bool CGUIText::IsTextID ( ) const

Checks whether this text object is an ID text or a string text.

Returns
True if this text represents an ID, False if it represents a string.

◆ IsTextSingleLine()

eC_Bool CGUIText::IsTextSingleLine ( ) const
inline

Determines whether this text is single- or multi-line.

Returns
True if the text is single-line, False if it is multi-line.

◆ OnNotification()

void CGUIText::OnNotification ( )
protectedvirtual

Observe the localisation handler and the property handler. If the text behind an ID is changed in the localisation handler and this text is an ID text, this function will be called. If a color property which is used by this text is changed, the property handler calls this function.

Reimplemented from CGUIColorPropertyObserver.

Reimplemented in CGUIRichText.

◆ operator=()

CGUIText & CGUIText::operator= ( const CGUIText kSource)

Copies the base attributes from a source object. This text object will have the same containing object as the source. If you want to set another containing object, you should use SetContainingObject() to set it.

Parameters
kSourceThe source object whose attributes are copied.
Returns
CGUIText& Reference to this object.

◆ PrepareClipRect()

eC_Bool CGUIText::PrepareClipRect ( )
protected

Prepare the clipping rectangle for text printing. This will set the clipping rectangle to the intersecting rectangle of the text's specific clipping rectangle with the GUI's currently set clipping rectangle.

Returns
false if the resulting clipping rectangle would be incomprehensive and the text must not be printed, true otherwise.

◆ PreparePrint()

void CGUIText::PreparePrint ( )
protectedvirtual

Prepare to print the text. This function may only be used in PrintText. It prepares the graphics wrapper state with the correct font, color etc.

Reimplemented in CGUIScrollingText.

◆ PrintText()

void CGUIText::PrintText ( )
virtual

Prints the text. This function may only be called from the DoDraw() implementation of the text's containing GUI object as it uses absolute positioning.

Reimplemented in CGUIScrollingText, CGUIRichText, and CGUIEditableText.

◆ ReadFontColors()

void CGUIText::ReadFontColors ( const eC_UInt  uiVersion)
protected

Helper function for ReadFromStream().

Parameters
uiVersion

◆ ReadFromStream()

void CGUIText::ReadFromStream ( )
virtual

Reads attributes from the streaming file. Only for use with GUIFactoryManager.

See also
CGUIObject::ReadFromStream()

Reimplemented from CGUIStreamableObject.

Reimplemented in CGUIRichText, CGUIEditableText, and CGUIScrollingText.

◆ SetAdjustment()

void CGUIText::SetAdjustment ( const eC_Value &  vXAdjustment,
const eC_Value &  vYAdjustment 
)
inline

Set positional adjustment values. These values are only used by PrintText(). The values are added to the current relative x and y positions, but only for printing. A common use case for this feature is a button that displays its text one or two pixels displaced while the button is pressed down.

Parameters
vXAdjustmentThe adjustment in X direction.
vYAdjustmentThe adjustment in Y direction.

◆ SetAligned()

void CGUIText::SetAligned ( const VerAligned_t eVerAligned = V_TOP,
const HorAligned_t eHorAligned = H_LEFT 
)

Sets the text alignment.

Parameters
eVerAlignedVertical alignment
eHorAlignedHorizontal alignment

◆ SetAlignedHorizontal()

void CGUIText::SetAlignedHorizontal ( const HorAligned_t eHorAligned = H_LEFT)

Sets horizontal alignment.

Parameters
eHorAlignedHorizontal alignment

◆ SetAlignedVertical()

void CGUIText::SetAlignedVertical ( const VerAligned_t eVerAligned = V_TOP)

Sets vertical alignment.

Parameters
eVerAlignedVertical alignment

◆ SetAutoSize()

void CGUIText::SetAutoSize ( const eC_Bool &  bAutoSize)
inline

Set autosizing of control.

Parameters
bAutoSizeture if active

◆ SetContainingObject()

void CGUIText::SetContainingObject ( const CGUIObject *const  pParent)
inline

Sets the object which contains the text. This method just changes the internal pointer to the containing object without re-calculating the text layout. If necessary, adjust the text positioning and area size manually.

Parameters
pParentThe object which contains the text.

◆ SetEllipsisString()

static void CGUIText::SetEllipsisString ( const eC_String &  kEllipsis)
inlinestatic

Sets the marker which will be append if a text has to be cut-off because of insufficient space.

Parameters
kEllipsisString to be append on cut-off texts.

◆ SetFont()

void CGUIText::SetFont ( const FontResource_t eFontID)
virtual

Sets the font.

Parameters
eFontIDThe identifier of the font to set.

Reimplemented in CGUIEditableText, and CGUIRichText.

◆ SetFontSpacing()

void CGUIText::SetFontSpacing ( const eC_Float &  fFontSpacing)

Sets the font spacing (space between letters).

Parameters
fFontSpacingFont spacing in subpixels (1.0 subpixels equals 1 pixel).

◆ SetHyphenString()

static void CGUIText::SetHyphenString ( const eC_String &  kHyphen)
inlinestatic

Sets the hyphen string which will be used on cutting strings.

Parameters
kHyphenHyphen string to use.

◆ SetLineSpacing()

void CGUIText::SetLineSpacing ( const eC_Value  vLineSpacing)
virtual

Sets the line spacing factor (default line spacing factor is 1). Valid values are in the range of 0-100.

Parameters
vLineSpacingThe line spacing factor.

◆ SetRelRect()

void CGUIText::SetRelRect ( const CGUIRect kRect)
inline

Sets the relative rectangle for this text

Parameters
kRectRectangle relative to containing object which is available for the text

◆ SetRelXPos()

virtual void CGUIText::SetRelXPos ( const eC_Value &  vRelXPos)
inlinevirtual

Sets relative x position to the parent object. The effect depends on the alignment. If the text is left aligned, this value is used relative to the left border of the parent object, if it is right aligned, relative to the right border of the parent object. If the text is centered, changing this value has no effect. Attention: the text width will not be re-adjusted by this method. If required, please set it by using SetTextWidth().

Parameters
vRelXPosRelative x position.

Reimplemented in CGUIScrollingText.

◆ SetRelYPos()

virtual void CGUIText::SetRelYPos ( const eC_Value &  vRelYPos)
inlinevirtual

Sets relative y position to the parent object. The effect depends on the alignment. If the text is top aligned, this value is used relative to the top border of the parent object, if it is bottom aligned, relative to the bottom border of the parent object. If the text is centered, changing this has no effect. Attention: the text height will not be re-adjusted by this method. If required, please set it by using SetTextHeight().

Parameters
vRelYPosRelative y position.

Reimplemented in CGUIScrollingText.

◆ SetRequiredTextHeight()

void CGUIText::SetRequiredTextHeight ( eC_Value  vRequiredTextHeight)
inlineprotected

Sets the required text height.

Parameters
vRequiredTextHeightRequired text height to set.

◆ SetRequiredTextWidth()

void CGUIText::SetRequiredTextWidth ( eC_Value  vRequiredTextWidth)
inlineprotected

Sets the required text width.

Parameters
vRequiredTextWidthRequired text width to set.

◆ SetSpecificClipRect()

void CGUIText::SetSpecificClipRect ( const CGUIRect kRect)
inline

Set a clip rect that different from the relative text position and text dimension. Setting a rectangle of width or height of zero will disable the specific clip rect and default to clipping against the containing object.

Parameters
kRectThe rect (in coordinates relative to the containing object) that shall be used for clipping the text.

◆ SetTextAlignmentProperty()

void CGUIText::SetTextAlignmentProperty ( const GlobalProperty_t eTextAlignmentProperty)

Set a global alignment property

Parameters
eTextAlignmentPropertyThe id of the property.

◆ SetTextColor() [1/2]

void CGUIText::SetTextColor ( const eC_UInt &  uiTextColorStandard,
const eC_UInt &  uiTextColorHighlighted,
const eC_UInt &  uiTextColorGrayedOut,
const eC_UInt &  uiTextColorPressed 
)
virtual

Sets the color of the text. The colors are used when printing the text. The state of the containing CGUIObject determines which color is used.

Parameters
uiTextColorStandardStandard Text color in ARGB coding (e.g. 0xFFFFFFFF).
uiTextColorHighlightedText color in ARGB coding used if the parent object is highlighted.
uiTextColorGrayedOutText color in ARGB coding used if the parent object is grayed out.
uiTextColorPressedText color in ARGB coding used if the parent object is pressed.

Reimplemented in CGUIRichText.

◆ SetTextColor() [2/2]

void CGUIText::SetTextColor ( const GlobalProperty_t eTextColorStandard,
const GlobalProperty_t eTextColorHighlighted,
const GlobalProperty_t eTextColorGrayedOut,
const GlobalProperty_t eTextColorPressed 
)
virtual

Sets the color of the text. The colors are used when printing the text. The state of the containing CGUIObject determines which color is used.

Parameters
eTextColorStandardStandard Text color as property (e.g. 0xFFFFFFFF).
eTextColorHighlightedText color as property used if the parent object is highlighted.
eTextColorGrayedOutText color as property used if the parent object is grayed out.
eTextColorPressedText color as property used if the parent object is pressed.

◆ SetTextColorGrayedOut() [1/2]

void CGUIText::SetTextColorGrayedOut ( const eC_UInt &  uiTextColorGrayedOut)

Sets the grayed out color of the text. The colors are used when printing the text. The state of the containing CGUIObject determines which color is used.

Parameters
uiTextColorGrayedOutText color in ARGB coding used if the parent object is grayed out.

◆ SetTextColorGrayedOut() [2/2]

void CGUIText::SetTextColorGrayedOut ( const GlobalProperty_t eTextColorPropertyGrayedOut)

Set a global color property as grayed out color.

Parameters
eTextColorPropertyGrayedOutThe id of the property.

◆ SetTextColorHighlighted() [1/2]

void CGUIText::SetTextColorHighlighted ( const eC_UInt &  uiTextColorHighlighted)

Sets the highlighted color of the text. The colors are used when printing the text. The state of the containing CGUIObject determines which color is used.

Parameters
uiTextColorHighlightedText color in ARGB coding used if the parent object is highlighted.

◆ SetTextColorHighlighted() [2/2]

void CGUIText::SetTextColorHighlighted ( const GlobalProperty_t eTextColorPropertyHighlighted)

Set a global color property as highlighted color.

Parameters
eTextColorPropertyHighlightedThe id of the property.

◆ SetTextColorPressed() [1/2]

void CGUIText::SetTextColorPressed ( const eC_UInt &  uiTextColorPressed)

Sets the pressed color of the text. The colors are used when printing the text. The state of the containing CGUIObject determines which color is used.

Parameters
uiTextColorPressedText color in ARGB coding used if the parent object is pressed.

◆ SetTextColorPressed() [2/2]

void CGUIText::SetTextColorPressed ( const GlobalProperty_t eTextColorPropertyPressed)

Set a global color property as pressed color.

Parameters
eTextColorPropertyPressedThe id of the property.

◆ SetTextColorStandard() [1/2]

void CGUIText::SetTextColorStandard ( const eC_UInt &  uiTextColorStandard)

Sets the standard color of the text. The colors are used when printing the text. The state of the containing CGUIObject determines which color is used.

Parameters
uiTextColorStandardStandard Text color in ARGB coding (e.g. 0xFFFFFFFF).

◆ SetTextColorStandard() [2/2]

void CGUIText::SetTextColorStandard ( const GlobalProperty_t eTextColorPropertyStandard)

Set a global color property as standard color.

Parameters
eTextColorPropertyStandardThe id of the property.

◆ SetTextCut()

void CGUIText::SetTextCut ( const eC_Bool  bIsCut)
inlineprotected

Sets the internal flagindicating thwther this text has been truncated.

Parameters
bIsCutTrue means that the string was truncated, False means that it was not truncated

◆ SetTextHeight()

void CGUIText::SetTextHeight ( const eC_Value &  vTextHeight)
virtual

Sets the text height.

Parameters
vTextHeightThe height assigned to the text.

Reimplemented in CGUIScrollingText.

◆ SetTextID()

void CGUIText::SetTextID ( const TextResource_t eTextID)
virtual

Sets the text ID.

Parameters
eTextIDThe ID of the text to assign to this object.

Reimplemented in CGUIRichText.

◆ SetTextSingleLine()

void CGUIText::SetTextSingleLine ( const eC_Bool &  bSingleLine)
virtual

Sets the text line wrapping mode (single or multi-line).

Parameters
bSingleLinetrue: single line; false: multi-line.

◆ SetTextString() [1/2]

void CGUIText::SetTextString ( const eC_String *  pkTextString)

Sets the string text to be represented by this object.

Parameters
pkTextStringThe string to be assigned to this object.

◆ SetTextString() [2/2]

void CGUIText::SetTextString ( const eC_String &  kTextString)
virtual

Sets the string text to be represented by this object.

Parameters
kTextStringThe string to be assigned to this object.

Reimplemented in CGUIEditableText, and CGUIRichText.

◆ SetTextWidth()

void CGUIText::SetTextWidth ( const eC_Value &  vTextWidth)
virtual

Sets the text width.

Parameters
vTextWidthThe width assigned to the text.

Reimplemented in CGUIScrollingText.

◆ WriteToStream()

void CGUIText::WriteToStream ( const eC_Bool  bWriteTextType = false)
virtual

Called by the framework when writing streaming files. When deriving a new text class in an application, re-implement this method.

Parameters
bWriteTextTypeIndicates whether the ID needs to be written. If the framework calls this method, it passes true here. The base class implementation has to be called with false (default). If called with true, the first two tags written must be this text's XML name tag (see GetXMLTag()) and its text type ID. After all attributes are written, the name tag has to be written again as a closing tag (preceded by a slash).

Reimplemented from CGUIStreamableObject.

Reimplemented in CGUIRichText, CGUIEditableText, and CGUIScrollingText.

Member Data Documentation

◆ m_bAdaptText

eC_Bool CGUIText::m_bAdaptText
protected

Flag to keep track of whether AdaptText() needs to perform calculations upon its next call. Every method that changes text attributes that can potentially lead to a change in the text layout should set this flag to true. AdaptText() resets it.

◆ m_bTextIDLocalCopy

eC_Bool CGUIText::m_bTextIDLocalCopy
protected

Set to True if this text is an ID text but m_pkText points to a local copy instead to the string in the localisation handler. This happens if the string contains hyphenation marks.

◆ m_pkText

eC_String* CGUIText::m_pkText
protected

This contains the text string if it is a string literal, or a locally modified copy of a string in the Localisation handler. For instances of CGUIText which are referencing an unmodified TextResource in the localisation handler, this is NULL. A TextID will for instance be stored in a local copy if it is truncated or was word-wrapped.

See also
GetText()

◆ m_vRequiredOrgTextHeight

eC_Value CGUIText::m_vRequiredOrgTextHeight
protected

The required height of this text's original (not wrapped) string as calculated by the most recent call to AdaptText().

◆ m_vRequiredOrgTextWidth

eC_Value CGUIText::m_vRequiredOrgTextWidth
protected

The required width of this text's original (not wrapped) string as calculated by the most recent call to AdaptText().

◆ XMLTAG_TEXT_COLOR_PROPERTY_FLAGS

const eC_Char CGUIText::XMLTAG_TEXT_COLOR_PROPERTY_FLAGS = "ColorPropertyFlags"
static

XML tag to be used when writing text colors into a stream.

xml-tag of color-properties


The documentation for this class was generated from the following files: