SoTextProperty Class Reference

Text property node. More...

#include <Inventor/nodes/SoTextProperty.h>

Inheritance diagram for SoTextProperty:

Public Types
enum	AlignmentH {   LEFT = 0x01 ,   CENTER = 0x03 ,   RIGHT = 0x02 }
	Possible horizontal alignment values. More...
enum	AlignmentV {   TOP = 0x01 ,   HALF = 0x03 ,   BASE = 0x04 ,   BOTTOM = 0x05 }
	Possible vertical alignment values. More...
enum	Orientation {   LEFT_TO_RIGHT = 0x01 ,   RIGHT_TO_LEFT = 0x02 ,   TOP_TO_BOTTOM = 0x03 ,   BOTTOM_TO_TOP = 0x04 }
	Possible text orientation values. More...
enum	Style {   NONE = SoTextStyleElement::NONE ,   UNDERLINE = SoTextStyleElement::UNDERLINE ,   STRIKETHROUGH = SoTextStyleElement::STRIKETHROUGH ,   DOUBLE_STRIKETHROUGH = SoTextStyleElement::DOUBLE_STRIKETHROUGH ,   BACK_FRAME = SoTextStyleElement::BACK_FRAME ,   BACK_FRAME_LINE = SoTextStyleElement::BACK_FRAME_LINE ,   OVERLINE = SoTextStyleElement::OVERLINE }
	TextProperty style values. More...
enum	StyleColor {   UNDERLINE_COLOR ,   STRIKETHROUGH_COLOR ,   DOUBLE_STRIKETHROUGH_COLOR ,   BACK_FRAME_COLOR ,   BACK_FRAME_LINE_COLOR ,   OVERLINE_COLOR ,   NUM_EFFECTS_COLORS }
	Index values for setting colors in the styleColors field. More...

Public Member Functions
virtual SoType	getTypeId () const
	Returns the type identifier for this specific instance.
	SoTextProperty ()
	Text property constructor.
virtual void	setOverride (const SbBool state)
	Set the state of the override field.
virtual SbBool	isOverride () const
	Returns the state of the override field.
Public Member Functions inherited from SoNode
virtual SoNode *	copy (SbBool copyConnections=FALSE) const
	Creates and returns an exact copy of the node.
virtual SbBool	affectsState () const
	Returns TRUE if a node has an effect on the state during traversal.
virtual void	touch ()
	Marks an instance as modified, simulating a change to it.
Public Member Functions inherited from SoFieldContainer
void	setToDefaults ()
	Sets all fields in this object to their default values.
SbBool	hasDefaultValues () const
	Returns TRUE if all of the object's fields have their default values.
SbBool	fieldsAreEqual (const SoFieldContainer *fc) const
	Returns TRUE if this object's fields are exactly equal to fc's fields.
void	copyFieldValues (const SoFieldContainer *fc, SbBool copyConnections=FALSE)
	Copies the contents of fc's fields into this object's fields.
SoNONUNICODE SbBool	set (const char *fieldDataString)
	Sets one or more fields in this object to the values specified in the given string, which should be a string in the Open Inventor file format.
SbBool	set (const SbString &fieldDataString)
	Sets one or more fields in this object to the values specified in the given string, which should be a string in the Open Inventor file format.
void	get (SbString &fieldDataString)
	Returns the values of the fields of this object in the Open Inventor ASCII file format in the given string.
virtual int	getFields (SoFieldList &list) const
	Appends references to all of this object's fields to resultList, and returns the number of fields appended.
virtual int	getAllFields (SoFieldList &list) const
	Returns a list of fields, including the eventIn's and eventOut's.
virtual SoField *	getField (const SbName &fieldName) const
	Returns a the field of this object whose name is fieldName.
virtual SoField *	getEventIn (const SbName &fieldName) const
	Returns a the eventIn with the given name.
virtual SoField *	getEventOut (const SbName &fieldName) const
	Returns the eventOut with the given name.
SbBool	getFieldName (const SoField *field, SbName &fieldName) const
	Returns the name of the given field in the fieldName argument.
SbBool	enableNotify (SbBool flag)
	Notification at this Field Container is enabled (if flag == TRUE) or disabled (if flag == FALSE).
SbBool	isNotifyEnabled () const
	Notification is the process of telling interested objects that this object has changed.
virtual void	setUserData (void *data)
	Sets application data.
void *	getUserData (void) const
	Gets user application data.
Public Member Functions inherited from SoBase
virtual SbName	getName () const
	Returns the name of an instance.
virtual void	setName (const SbName &name)
	Sets the name of an instance.
void	setSynchronizable (const bool b)
	Sets this to be a ScaleViz synchronizable object.
bool	isSynchronizable () const
	Gets the ScaleViz synchronizable state of this object.
Public Member Functions inherited from SoRefCounter
void	ref () const
	Adds a reference to an instance.
void	unref () const
	Removes a reference from an instance.
void	unrefNoDelete () const
	unrefNoDelete() should be called when it is desired to decrement the reference count, but not delete the instance if this brings the reference count to zero.
int	getRefCount () const
	Returns current reference count.
void	lock () const
	lock this instance.
void	unlock () const
	unlock this instance.
Public Member Functions inherited from SoTypedObject
SbBool	isOfType (const SoType &type) const
	Returns TRUE if this object is of the type specified in type or is derived from that type.
template<typename TypedObjectClass >
SbBool	isOfType () const
	Returns TRUE if this object is of the type of class TypedObjectClass or is derived from that class.

Static Public Member Functions
static SoType	getClassTypeId ()
	Returns the type identifier for this class.
Static Public Member Functions inherited from SoNode
static SoType	getClassTypeId ()
	Returns the type identifier for this class.
static SoNode *	getByName (const SbName &name)
	A node's name can be set using SoBase::setName().
static int	getByName (const SbName &name, SoNodeList &list)
	A node's name can be set using SoBase::setName().
Static Public Member Functions inherited from SoFieldContainer
static SoType	getClassTypeId ()
	Returns the type of this class.
Static Public Member Functions inherited from SoBase
static SoType	getClassTypeId ()
	Returns type identifier for this class.
Static Public Member Functions inherited from SoTypedObject
static SoType	getClassTypeId ()
	Returns the type identifier for this class.

Public Attributes
SoSFFloat	aliasingFactor
	Defines the anti-aliasing factor to apply to the textured text rendering.
SoSFEnum	alignmentH
	Indicates horizontal placement and alignment of strings.
SoSFEnum	alignmentV
	Indicates vertical placement and alignment of strings.
SoSFFloat	backFrameLineWidth
	Defines the width of the line when BACK_FRAME_LINE has been enabled for the current style.
SoSFBool	kerning
	Set this field to TRUE to apply kerning on text rendering.
SoSFEnum	orientation
	Specifies the text rendering orientation.
SoSFVec2i32	textureQualityRange
	Defines a quality range of values taken into account during textured text texture computation.
SoSFBitMask	style
	Specifies zero or more styles to be applied to text.
SoMFColorRGBA	styleColors
	Specifies the color to use for each style.
SoSFFloat	margin
	Set a margin (extra space) to apply around the text string for the BACK_FRAME and BACK_FRAME_LINE styles.
SoMFBool	styleColorsUseCurrentMaterial
	This field allows to use the current SoMaterial instead of the value specified by styleColors for each available style (default gray).
SoSFFloat	characterSpacing
	This field specifies the spacing between individual characters.

Detailed Description

Text property node.

This node specifies properties used for text rendering.

The application can specify text alignment and orientation using the alignmentH, alignmentV, and orientation fields.

Note:
Horizontal alignment can also be specified in some text nodes, for example SoText2 and SoText3, using the justification field. The value in the text node's field is used unless that field is explicitly set to INHERIT. To allow SoTextProperty to control horizontal justification, set the text node's justification field to INHERITED.

The application can also request use of font kerning using the kerning field. Kerning consists of modifying the spacing between two successive glyphs according to their outlines. For examples, a "T" and a "y" can be moved closer together as the top of the "y" fits nicely under the upper right bar of the "T". Kerning depends on the specific font being used.

Different text rendering styles such as underline, strikethrough and background rectangle can be specified using the style field. A color can be specified for each style using the styleColors field. The current material does not affect the color of a text rendering style unless the corresponding value in the styleColorsUseCurrentMaterial field is set to true. Text rendering styles apply to the entire string.

Text rendering effects

Notes:

• Underline/overline/strike always has the same position relative to the text string, regardless of the vertical justification setting.
• The underline/overline/strike position is determined by the font and the results should be similar to what you see in other applications using the same font (e.g. MS-Word on Windows). For some fonts the underline will intersect character descenders, for example on the lower case 'g'. For some fonts the overline will intersect the top portion of some characters.
• When using BACK_FRAME and BACK_FRAME_LINE you will usually want to set the margin field to a small value, for example 0.05.
• Color can be specified separately for each style. However underline and overline are often intended to be the same color as the text. It can be convenient to set the styleColorsUseCurrentMaterial field so that the current SoMaterial controls both the text and the lines.
• Note that the color for each style is an RGBA value, allowing transparency to be applied. This is particularly useful for the BACK_FRAME attribute so the text background rectangle can be semi-transparent.
• As backFrameLineWidth is increased, the width of the line expands outward, away from the string (the backframe box stays the same size).
• Be sure to use the values in the StyleColor enum to set colors and inheritance flags, not the values in the Style enum. For example, use UNDERLINE_COLOR, not UNDERLINE. Open Inventor will not report an error, but the desired effect will not occur.

FILE FORMAT/DEFAULT

TextProperty {

aliasingFactor	1.0
alignmentH	LEFT
alignmentV	BASE
backFrameLineWidth	0.0
kerning	FALSE
margin	0.0
orientation	LEFT_TO_RIGHT
textureQualityRange	150 300
style	NONE
styleColors	0.8 0.8 0.8 1
styleColorsUseCurrentMaterial	FALSE

}

ACTION BEHAVIOR

Sets: SoTextAlignmentHElement, SoTextAlignmentVElement, SoTextBackFrameLineWidthElement, SoTextOrientationElement, SoTextKerningElement, SoTextMarginElement

SEE ALSO

SoAnnoText3, SoText3, SoText2, SoAsciiText, SoFont

Definition at line 134 of file SoTextProperty.h.

Member Enumeration Documentation

AlignmentH

enum SoTextProperty::AlignmentH

Possible horizontal alignment values.

Enumerator
LEFT	Left edges of all strings are aligned. (default)
CENTER	Horizontal centers of all strings are aligned.
RIGHT	Right edges of all strings are aligned.

Definition at line 178 of file SoTextProperty.h.

AlignmentV

enum SoTextProperty::AlignmentV

Possible vertical alignment values.

Enumerator
TOP	Top edges of all strings are aligned.
HALF	Vertical centers of all strings are aligned.
BASE	All strings are aligned on their baseline. (default)
BOTTOM	Bottom edges of all strings are aligned.

Definition at line 210 of file SoTextProperty.h.

Orientation

enum SoTextProperty::Orientation

Possible text orientation values.

Enumerator
LEFT_TO_RIGHT	Text string is left to right oriented. (default)
RIGHT_TO_LEFT	Text string is right to left oriented.
TOP_TO_BOTTOM	Text string is top to bottom oriented.
BOTTOM_TO_TOP	Text string is bottom to top oriented.

Definition at line 263 of file SoTextProperty.h.

Style

enum SoTextProperty::Style

TextProperty style values.

Enumerator
NONE	No effects.
UNDERLINE	UNDERLINE.
STRIKETHROUGH	STRIKETHROUGH.
DOUBLE_STRIKETHROUGH	DOUBLE_STRIKETHROUGH.
BACK_FRAME	BACK_FRAME.
BACK_FRAME_LINE	BACK_FRAME_LINE.
OVERLINE	OVERLINE.

Definition at line 305 of file SoTextProperty.h.

StyleColor

enum SoTextProperty::StyleColor

Index values for setting colors in the styleColors field.

Enumerator
UNDERLINE_COLOR	UNDERLINE_COLOR.
STRIKETHROUGH_COLOR	STRIKETHROUGH_COLOR.
DOUBLE_STRIKETHROUGH_COLOR	DOUBLE_STRIKETHROUGH_COLOR.
BACK_FRAME_COLOR	BACK_FRAME_COLOR.
BACK_FRAME_LINE_COLOR	BACK_FRAME_LINE_COLOR.
OVERLINE_COLOR	OVERLINE_COLOR.
NUM_EFFECTS_COLORS	NUM_EFFECTS_COLORS.

Definition at line 337 of file SoTextProperty.h.

Constructor & Destructor Documentation

SoTextProperty()

SoTextProperty::SoTextProperty

(

)

Text property constructor.

Member Function Documentation

getClassTypeId()

static SoType SoTextProperty::getClassTypeId ( )

static

Returns the type identifier for this class.

getTypeId()

virtual SoType SoTextProperty::getTypeId ( ) const

virtual

Returns the type identifier for this specific instance.

Reimplemented from SoNode.

isOverride()

virtual SbBool SoTextProperty::isOverride ( ) const

inlinevirtual

Returns the state of the override field.

Reimplemented from SoNode.

Definition at line 154 of file SoTextProperty.h.

setOverride()

virtual void SoTextProperty::setOverride ( const SbBool  state )

inlinevirtual

Set the state of the override field.

see SoNode::setOverride doc.

Reimplemented from SoNode.

Definition at line 148 of file SoTextProperty.h.

Member Data Documentation

aliasingFactor

SoSFFloat SoTextProperty::aliasingFactor

Defines the anti-aliasing factor to apply to the textured text rendering.

Default is 1.0. Default value can be changed using the environment variable OIV_TEXT_ALIASING_FACTOR.

The anti-aliasing applied transfer functions are:

• if aliasingFactor <= 1.0 => Max( (v + f - 1) / f , 0.0)
• if aliasingFactor > 1.0 => Min( (v * f) , 1.0)

A value of 0 essentially turns off antialiasing. Only pixels that are full opacity will be rendered. Value 1 is the native antialiasing provided by the FreeType library. Values < 1 scale down the opacity of semi-transparent pixels, so lower opacity pixels become completely transparent, effectively making the character glyphs sharper but narrower. Values > 1 scale up the opacity of semi-transparent pixels, effectively making the characters sharper but wider. Values greater than 5 have little additional visual effect.

Definition at line 175 of file SoTextProperty.h.

alignmentH

SoSFEnum SoTextProperty::alignmentH

Indicates horizontal placement and alignment of strings.

Use the AlignmentH enum. Default value is LEFT. With LEFT alignment, the left edge of the first line is at the (transformed) origin, and all left edges are aligned. RIGHT alignment is similar. CENTER alignment places the center of the first string at the (transformed) origin, with the centers of all remaining strings aligned under it. Default value can be changed using the environment variable OIV_TEXT_ALIGNMENTH.

Note: This field is only effective when the justification field of a text node is set to INHERITED. When orientation is vertical, horizontal alignment is only applied on the first line.

Definition at line 207 of file SoTextProperty.h.

alignmentV

SoSFEnum SoTextProperty::alignmentV

Indicates vertical placement and alignment of strings.

Use the AlignmentV enum. Default is BASE. With TOP alignment, the top edge of the first line is at the (transformed) origin, and all top edges are aligned. BOTTOM alignment is similar. HALF alignment places the center of the first string at the (transformed) origin, with the centers of all remaining strings aligned under it. Default value can be changed using the environment variable OIV_TEXT_ALIGNMENTV. When orientation is horizontal, vertical alignment is only applied on the first line.

Definition at line 242 of file SoTextProperty.h.

backFrameLineWidth

SoSFFloat SoTextProperty::backFrameLineWidth

Defines the width of the line when BACK_FRAME_LINE has been enabled for the current style.

The backFrameLineWidth value is pixel size for SoText2 text, and is a 1/40 of the current font size for SoText3 text. Default value is 1.0 Default value can be changed using the environment variable OIV_TEXT_BACKFRAMELINE_WIDTH.

NOTE: field available since Open Inventor 9.2

Definition at line 252 of file SoTextProperty.h.

characterSpacing

SoSFFloat SoTextProperty::characterSpacing

This field specifies the spacing between individual characters.

The value is in font size units for 2D text (SoText2) and 3D text (SoText3). Default is 0.

• 0 means no extra space with respect to the standard spacing defined in the font.
• A positive value is added to the default spacing (it is not relative or proportional).
• Negative values are ignored.

Definition at line 415 of file SoTextProperty.h.

kerning

SoSFBool SoTextProperty::kerning

Set this field to TRUE to apply kerning on text rendering.

For more information about kerning, refer to the FreeType documentation located at http://www.freetype.org/freetype2/documentation.html Default value is FALSE.

Definition at line 260 of file SoTextProperty.h.

margin

SoSFFloat SoTextProperty::margin

Set a margin (extra space) to apply around the text string for the BACK_FRAME and BACK_FRAME_LINE styles.

The margin value is specified as a fraction of the font size. Default value is 0.0. Default value can be changed using the environment variable OIV_TEXT_MARGIN. NOTE: field available since Open Inventor 8.1

Definition at line 393 of file SoTextProperty.h.

orientation

SoSFEnum SoTextProperty::orientation

Specifies the text rendering orientation.

Use the Orientation enum. Default is LEFT_TO_RIGHT. Default value can be changed using the environment variable OIV_TEXT_ORIENTATION.

Definition at line 290 of file SoTextProperty.h.

style

SoSFBitMask SoTextProperty::style

Specifies zero or more styles to be applied to text.

Use the Style enum. Default is NONE.

Note: UNDERLINE, STRIKETHROUGH and DOUBLE_STRIKETHROUGH are not implemented for vertical oriented text ( ie: Orientation set to TOP_TO_BOTTOM or BOTTOM_TO_TOP).

NOTE: field available since Open Inventor 8.1

Definition at line 332 of file SoTextProperty.h.

styleColors

SoMFColorRGBA SoTextProperty::styleColors

Specifies the color to use for each style.

Use the index values defined in the StyleColor enum (NOT the Style enum) to assign the color to the desired style. For example, assign opaque red to the underline color.

SoTextProperty* node = new SoTextProperty();
pNode->styleColors.set1Value( SoTextProperty::UNDERLINE_COLOR, SbColorRGBA(1,0,0,1) );

Default is (0.8,0.8,0.8,1) = the Open Inventor default diffuse color with alpha=1 (opaque).

NOTE: field available since Open Inventor 8.1

Definition at line 383 of file SoTextProperty.h.

styleColorsUseCurrentMaterial

SoMFBool SoTextProperty::styleColorsUseCurrentMaterial

This field allows to use the current SoMaterial instead of the value specified by styleColors for each available style (default gray).

For example, if the entry corresponding to UNDERLINE_COLOR is set to TRUE, underline will be rendered using the color inherited from SoMaterial. This is convenient if (as usual) the underline should be the same color as the text. Use the index values defined in the StyleColor enum (NOT the Style enum) to set the value for the desired style (see example code for styleColors field). NOTE: field available since Open Inventor 9.4

Definition at line 404 of file SoTextProperty.h.

textureQualityRange

SoSFVec2i32 SoTextProperty::textureQualityRange

Defines a quality range of values taken into account during textured text texture computation.

The size of the generated textures depends on this range, expressed in terms of DPI, and depends on the SoComplexity::value. Default is 150 to 300. Default range values can be changed using the environment variables OIV_MIN_TEXTURED_FONT_RES and OIV_MAX_TEXTURED_FONT_RES.

NOTE: field available since Open Inventor 8.1

Definition at line 302 of file SoTextProperty.h.

---

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

• Inventor/nodes/SoTextProperty.h