Panda3D
Public Member Functions | Static Public Member Functions | Public Attributes | List of all members
TextAssembler Class Reference

This class is not normally used directly by user code, but is used by the TextNode to lay out a block of text and convert it into rows of Geoms according to the TextProperties. More...

Public Member Functions

 __init__ (const TextAssembler copy)
 
 __init__ (TextEncoder encoder)
 
PandaNode assembleText ()
 Actually assembles all of the text into a GeomNode, and returns the node (or possibly a parent of the node, to keep the shadow separate). More...
 
int calcC (int n)
 Computes the column index of the nth character or graphic object in the text and returns it. More...
 
int calcIndex (int r, int c)
 Computes the character index of the character at the rth row and cth column position. More...
 
int calcR (int n)
 Computes the row index of the nth character or graphic object in the text and returns it. More...
 
 clear ()
 Reinitializes the contents of the TextAssembler. More...
 
wchar_t getCharacter (int n)
 Returns the character at the indicated position in the pre-wordwrapped string. More...
 
wchar_t getCharacter (int r, int c)
 Returns the character at the indicated position in the indicated row. More...
 
bool getDynamicMerge ()
 Returns the dynamic_merge flag. More...
 
const TextGraphic getGraphic (int n)
 Returns the graphic object at the indicated position in the pre-wordwrapped string. More...
 
const TextGraphic getGraphic (int r, int c)
 Returns the graphic object at the indicated position in the indicated row. More...
 
const LVector2 getLr ()
 Returns the lower-right corner of the assembled text, in 2-d text coordinates. More...
 
int getMaxRows ()
 If max_rows is greater than zero, no more than max_rows will be accepted. More...
 
bool getMultilineMode ()
 Returns the multline_mode flag. More...
 
int getNumCharacters ()
 Returns the number of characters of text, before wordwrapping. More...
 
int getNumCols (int r)
 Returns the number of characters and/or graphic objects in the nth row. More...
 
int getNumRows ()
 Returns the number of rows of text after it has all been wordwrapped and assembled. More...
 
str getPlainWtext ()
 Returns a wstring that represents the contents of the text, without any embedded properties characters. More...
 
const TextProperties getProperties ()
 Returns the default TextProperties that are applied to the text in the absence of any nested property change sequences. More...
 
const TextProperties getProperties (int n)
 Returns the TextProperties in effect for the object at the indicated position in the pre-wordwrapped string. More...
 
const TextProperties getProperties (int r, int c)
 Returns the TextProperties in effect for the object at the indicated position in the indicated row. More...
 
const LVector2 getUl ()
 Returns the upper-left corner of the assembled text, in 2-d text coordinates. More...
 
GeomEnums::UsageHint getUsageHint ()
 Returns the UsageHint that will be applied to generated geometry. More...
 
float getWidth (int n)
 Returns the width of the character or object at the indicated position in the pre-wordwrapped string. More...
 
float getWidth (int r, int c)
 Returns the width of the character or object at the indicated position in the indicated row. More...
 
str getWordwrappedPlainWtext ()
 Returns a wstring that represents the contents of the text, with newlines inserted according to the wordwrapping. More...
 
str getWordwrappedWtext ()
 Returns a wstring that represents the contents of the text, with newlines inserted according to the wordwrapping. More...
 
str getWtext ()
 Returns a wstring that represents the contents of the text. More...
 
float getXpos (int r, int c)
 Returns the x position of the origin of the character or graphic object at the indicated position in the indicated row. More...
 
float getYpos (int r, int c)
 Returns the y position of the origin of all of the characters or graphic objects in the indicated row. More...
 
TextAssembler operator= (const TextAssembler copy)
 
 setDynamicMerge (bool dynamic_merge)
 Sets the dynamic_merge flag. More...
 
 setMaxRows (int max_rows)
 If max_rows is greater than zero, no more than max_rows will be accepted. More...
 
 setMultilineMode (bool flag)
 Sets the multiline mode flag. More...
 
 setProperties (const TextProperties properties)
 Specifies the default TextProperties that are applied to the text in the absence of any nested property change sequences. More...
 
 setUsageHint (GeomEnums::UsageHint usage_hint)
 Specifies the UsageHint that will be applied to generated geometry. More...
 
bool setWsubstr (str wtext, int start, int count)
 Replaces the 'count' characters from 'start' of the current text with the indicated replacement text. More...
 
bool setWtext (str wtext)
 Accepts a new text string and associated properties structure, and precomputes the wordwrapping layout appropriately. More...
 

Static Public Member Functions

static float calcWidth (const TextGraphic graphic, const TextProperties properties)
 Returns the width of a single TextGraphic image. More...
 
static float calcWidth (wchar_t character, const TextProperties properties)
 Returns the width of a single character, according to its associated font. More...
 
static bool hasCharacter (wchar_t character, const TextProperties properties)
 Returns true if the named character exists in the font or can be synthesized by Panda, false otherwise. More...
 
static bool hasExactCharacter (wchar_t character, const TextProperties properties)
 Returns true if the named character exists in the font exactly as named, false otherwise. More...
 
static bool isWhitespace (wchar_t character, const TextProperties properties)
 Returns true if the indicated character represents whitespace in the font, or false if anything visible will be rendered for it. More...
 

Public Attributes

bool dynamic_merge
 Returns the dynamic_merge flag. More...
 
int max_rows
 If max_rows is greater than zero, no more than max_rows will be accepted. More...
 
bool multiline_mode
 Returns the multline_mode flag. More...
 
const TextProperties properties
 Returns the default TextProperties that are applied to the text in the absence of any nested property change sequences. More...
 
GeomEnums::UsageHint usage_hint
 Returns the UsageHint that will be applied to generated geometry. More...
 

Detailed Description

This class is not normally used directly by user code, but is used by the TextNode to lay out a block of text and convert it into rows of Geoms according to the TextProperties.

However, user code may take advantage of it, if desired, for very low-level text operations.

Member Function Documentation

◆ __init__() [1/2]

__init__ ( const TextAssembler  copy)

◆ __init__() [2/2]

__init__ ( TextEncoder  encoder)

◆ assembleText()

PandaNode assembleText ( )

Actually assembles all of the text into a GeomNode, and returns the node (or possibly a parent of the node, to keep the shadow separate).

Once this has been called, you may query the extents of the text via get_ul(), get_lr().

◆ calcC()

int calcC ( int  n)

Computes the column index of the nth character or graphic object in the text and returns it.

If the nth character is not a normal printable character with a position in the wordwrapped string, returns -1 (for instance, a soft-hyphen character, or a newline character, may not have a corresponding position).

◆ calcIndex()

int calcIndex ( int  r,
int  c 
)

Computes the character index of the character at the rth row and cth column position.

This is the inverse of calc_r_c().

It is legal for c to exceed the index number of the last column by 1, and it is legal for r to exceed the index number of the last row by 1, if c is 0.

◆ calcR()

int calcR ( int  n)

Computes the row index of the nth character or graphic object in the text and returns it.

If the nth character is not a normal printable character with a position in the wordwrapped string, returns -1 (for instance, a soft-hyphen character, or a newline character, may not have a corresponding position).

◆ calcWidth() [1/2]

static float calcWidth ( const TextGraphic  graphic,
const TextProperties  properties 
)
static

Returns the width of a single TextGraphic image.

◆ calcWidth() [2/2]

static float calcWidth ( wchar_t  character,
const TextProperties  properties 
)
static

Returns the width of a single character, according to its associated font.

This also correctly calculates the width of cheesy ligatures and accented characters, which may not exist in the font as such.

This does not take kerning into account, however.

◆ clear()

clear ( )

Reinitializes the contents of the TextAssembler.

◆ getCharacter() [1/2]

wchar_t getCharacter ( int  n)

Returns the character at the indicated position in the pre-wordwrapped string.

If the object at this position is a graphic object instead of a character, returns 0.

◆ getCharacter() [2/2]

wchar_t getCharacter ( int  r,
int  c 
)

Returns the character at the indicated position in the indicated row.

If the object at this position is a graphic object instead of a character, returns 0.

◆ getDynamicMerge()

bool getDynamicMerge ( )

Returns the dynamic_merge flag.

See TextNode::set_flatten_flags().

◆ getGraphic() [1/2]

const TextGraphic getGraphic ( int  n)

Returns the graphic object at the indicated position in the pre-wordwrapped string.

If the object at this position is a character instead of a graphic object, returns NULL.

◆ getGraphic() [2/2]

const TextGraphic getGraphic ( int  r,
int  c 
)

Returns the graphic object at the indicated position in the indicated row.

If the object at this position is a character instead of a graphic object, returns NULL.

◆ getLr()

const LVector2 getLr ( )

Returns the lower-right corner of the assembled text, in 2-d text coordinates.

◆ getMaxRows()

int getMaxRows ( )

If max_rows is greater than zero, no more than max_rows will be accepted.

Text beyond that will be truncated.

◆ getMultilineMode()

bool getMultilineMode ( )

Returns the multline_mode flag.

See TextNode::set_multiline_mode().

◆ getNumCharacters()

int getNumCharacters ( )

Returns the number of characters of text, before wordwrapping.

◆ getNumCols()

int getNumCols ( int  r)

Returns the number of characters and/or graphic objects in the nth row.

◆ getNumRows()

int getNumRows ( )

Returns the number of rows of text after it has all been wordwrapped and assembled.

◆ getPlainWtext()

str getPlainWtext ( )

Returns a wstring that represents the contents of the text, without any embedded properties characters.

If there is an embedded graphic object, a zero value is inserted in that position.

This string has the same length as get_num_characters(), and the characters in this string correspond one-to-one with the characters returned by get_character(n).

◆ getProperties() [1/3]

const TextProperties getProperties ( )

Returns the default TextProperties that are applied to the text in the absence of any nested property change sequences.

◆ getProperties() [2/3]

const TextProperties getProperties ( int  n)

Returns the TextProperties in effect for the object at the indicated position in the pre-wordwrapped string.

◆ getProperties() [3/3]

const TextProperties getProperties ( int  r,
int  c 
)

Returns the TextProperties in effect for the object at the indicated position in the indicated row.

◆ getUl()

const LVector2 getUl ( )

Returns the upper-left corner of the assembled text, in 2-d text coordinates.

◆ getUsageHint()

GeomEnums::UsageHint getUsageHint ( )

Returns the UsageHint that will be applied to generated geometry.

See set_usage_hint().

◆ getWidth() [1/2]

float getWidth ( int  n)

Returns the width of the character or object at the indicated position in the pre-wordwrapped string.

◆ getWidth() [2/2]

float getWidth ( int  r,
int  c 
)

Returns the width of the character or object at the indicated position in the indicated row.

◆ getWordwrappedPlainWtext()

str getWordwrappedPlainWtext ( )

Returns a wstring that represents the contents of the text, with newlines inserted according to the wordwrapping.

The string will contain no embedded properties characters. If there is an embedded graphic object, a zero value is inserted in that position.

This string has the same number of newline characters as get_num_rows(), and the characters in this string correspond one-to-one with the characters returned by get_character(r, c).

◆ getWordwrappedWtext()

str getWordwrappedWtext ( )

Returns a wstring that represents the contents of the text, with newlines inserted according to the wordwrapping.

The string will contain embedded properties characters, which may not exactly match the embedded properties characters of the original string, but it will encode the same way.

Embedded properties characters will be closed before every newline, then reopened (if necessary) on the subsequent character following the newline. This means it will be safe to divide the text up at the newline characters and treat each line as an independent piece.

◆ getWtext()

str getWtext ( )

Returns a wstring that represents the contents of the text.

The string will contain embedded properties characters, which may not exactly match the embedded properties characters of the original string, but it will encode the same way.

◆ getXpos()

float getXpos ( int  r,
int  c 
)

Returns the x position of the origin of the character or graphic object at the indicated position in the indicated row.

It is legal for c to exceed the index number of the last column by 1, and it is legal for r to exceed the index number of the last row by 1, if c is 0.

◆ getYpos()

float getYpos ( int  r,
int  c 
)

Returns the y position of the origin of all of the characters or graphic objects in the indicated row.

It is legal for r to exceed the index number of the last row by 1. The value of c is presently ignored.

◆ hasCharacter()

static bool hasCharacter ( wchar_t  character,
const TextProperties  properties 
)
static

Returns true if the named character exists in the font or can be synthesized by Panda, false otherwise.

(Panda can synthesize some accented characters by combining similar-looking glyphs from the font.)

This returns true for whitespace and Unicode whitespace characters (if they exist in the font), but returns false for characters that would render with the "invalid glyph".

◆ hasExactCharacter()

static bool hasExactCharacter ( wchar_t  character,
const TextProperties  properties 
)
static

Returns true if the named character exists in the font exactly as named, false otherwise.

Note that because Panda can assemble glyphs together automatically using cheesy accent marks, this is not a reliable indicator of whether a suitable glyph can be rendered for the character. For that, use has_character() instead.

This returns true for whitespace and Unicode whitespace characters (if they exist in the font), but returns false for characters that would render with the "invalid glyph". It also returns false for characters that would be synthesized within Panda, but see has_character().

◆ isWhitespace()

static bool isWhitespace ( wchar_t  character,
const TextProperties  properties 
)
static

Returns true if the indicated character represents whitespace in the font, or false if anything visible will be rendered for it.

This returns true for whitespace and Unicode whitespace characters (if they exist in the font), and returns false for any other characters, including characters that do not exist in the font (these would be rendered with the "invalid glyph", which is visible).

Note that this function can be reliably used to identify Unicode whitespace characters only if the font has all of the whitespace characters defined. It will return false for any character not in the font, even if it is an official Unicode whitespace character.

◆ operator=()

TextAssembler operator= ( const TextAssembler  copy)

◆ setDynamicMerge()

setDynamicMerge ( bool  dynamic_merge)

Sets the dynamic_merge flag.

See TextNode::set_flatten_flags().

◆ setMaxRows()

setMaxRows ( int  max_rows)

If max_rows is greater than zero, no more than max_rows will be accepted.

Text beyond that will be truncated.

Setting this will not truncate text immediately. You must follow this up with a call to set_wtext() to truncate the existing text.

◆ setMultilineMode()

setMultilineMode ( bool  flag)

Sets the multiline mode flag.

Set the multiline mode to allow text to wrap. It defaults to true.

◆ setProperties()

setProperties ( const TextProperties  properties)

Specifies the default TextProperties that are applied to the text in the absence of any nested property change sequences.

◆ setUsageHint()

setUsageHint ( GeomEnums::UsageHint  usage_hint)

Specifies the UsageHint that will be applied to generated geometry.

The default is UH_static, which is probably the right setting, but if you know the TextNode's geometry will have a short lifespan, it may be better to set it to UH_stream. See geomEnums.h.

◆ setWsubstr()

bool setWsubstr ( str  wtext,
int  start,
int  count 
)

Replaces the 'count' characters from 'start' of the current text with the indicated replacement text.

If the replacement text does not have count characters, the length of the string will be changed accordingly.

The substring may include nested formatting characters, but they must be self-contained and self-closed. The formatting characters are not literally saved in the internal string; they are parsed at the time of the set_wsubstr() call.

The return value is true if all the text is accepted, or false if some was truncated (see set_max_rows()).

◆ setWtext()

bool setWtext ( str  wtext)

Accepts a new text string and associated properties structure, and precomputes the wordwrapping layout appropriately.

After this call, get_wordwrapped_wtext() and get_num_rows() can be called.

The return value is true if all the text is accepted, or false if some was truncated (see set_max_rows()).

Member Data Documentation

◆ dynamic_merge

bool dynamic_merge

Returns the dynamic_merge flag.

See TextNode::set_flatten_flags().

◆ max_rows

int max_rows

If max_rows is greater than zero, no more than max_rows will be accepted.

Text beyond that will be truncated.

◆ multiline_mode

bool multiline_mode

Returns the multline_mode flag.

See TextNode::set_multiline_mode().

◆ properties

const TextProperties properties

Returns the default TextProperties that are applied to the text in the absence of any nested property change sequences.

Returns the TextProperties in effect for the object at the indicated position in the pre-wordwrapped string.Returns the TextProperties in effect for the object at the indicated position in the indicated row.

◆ usage_hint

Returns the UsageHint that will be applied to generated geometry.

See set_usage_hint().