SoTextProperty

java.lang.Object
- com.openinventor.inventor.Inventor
- - com.openinventor.inventor.misc.SoBase
  - - com.openinventor.inventor.fields.SoFieldContainer
    - - com.openinventor.inventor.nodes.SoNode
      - com.openinventor.inventor.nodes.SoTextProperty

All Implemented Interfaces:: SafeDisposable

public class SoTextProperty
extends SoNode

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.
Performance.
Accumulation mode (enableTextAccumulation) significantly improves performance for scene graphs containing many SoText3 nodes. There are some drawbacks and limitations.

File format/default:

TextProperty {

aliasingFactor	1.0
alignmentH	LEFT
alignmentV	BASE
backFrameLineWidth	0.0
enableTextAccumulation	false
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

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`SoTextProperty.AlignmentHs` Possible horizontal alignment values.
`static class`	`SoTextProperty.AlignmentVs` Possible vertical alignment values.
`static class`	`SoTextProperty.Orientations` Possible text orientation values.
`static class`	`SoTextProperty.StyleColorType` Index values for setting colors in the `styleColors` field.
`static class`	`SoTextProperty.Styles` TextProperty style values.

Nested classes/interfaces inherited from class com.openinventor.inventor.Inventor
Inventor.ConstructorCommand

Field Summary

Fields
Modifier and Type	Field and Description
`SoSFFloat`	`aliasingFactor` Defines the anti-aliasing factor to apply to the textured text rendering.
`SoSFEnum<SoTextProperty.AlignmentHs>`	`alignmentH` Indicates horizontal placement and alignment of strings.
`SoSFEnum<SoTextProperty.AlignmentVs>`	`alignmentV` Indicates vertical placement and alignment of strings.
`static int`	`BACK_FRAME` Deprecated. Use `SoTextProperty.Styles.BACK_FRAME` instead.
`static int`	`BACK_FRAME_COLOR` Deprecated. Use `SoTextProperty.StyleColorType.BACK_FRAME_COLOR` instead.
`static int`	`BACK_FRAME_LINE` Deprecated. Use `SoTextProperty.Styles.BACK_FRAME_LINE` instead.
`static int`	`BACK_FRAME_LINE_COLOR` Deprecated. Use `SoTextProperty.StyleColorType.BACK_FRAME_LINE_COLOR` instead.
`SoSFFloat`	`backFrameLineWidth` Defines the width of the line when BACK_FRAME_LINE has been enabled for the current style.
`static int`	`BASE` Deprecated. Use `SoTextProperty.AlignmentVs.BASE` instead.
`static int`	`BOTTOM` Deprecated. Use `SoTextProperty.AlignmentVs.BOTTOM` instead.
`static int`	`BOTTOM_TO_TOP` Deprecated. Use `SoTextProperty.Orientations.BOTTOM_TO_TOP` instead.
`static int`	`CENTER` Deprecated. Use `SoTextProperty.AlignmentHs.CENTER` instead.
`SoSFFloat`	`characterSpacing` This field specifies the spacing between individual characters.
`static int`	`DOUBLE_STRIKETHROUGH` Deprecated. Use `SoTextProperty.Styles.DOUBLE_STRIKETHROUGH` instead.
`static int`	`DOUBLE_STRIKETHROUGH_COLOR` Deprecated. Use `SoTextProperty.StyleColorType.DOUBLE_STRIKETHROUGH_COLOR` instead.
`SoSFBool`	`enableTextAccumulation` Enables the accumulation rendering mode for `SoText3` nodes.
`static int`	`HALF` Deprecated. Use `SoTextProperty.AlignmentVs.HALF` instead.
`SoSFBool`	`kerning` Set this field to true to apply kerning on text rendering.
`static int`	`LEFT` Deprecated. Use `SoTextProperty.AlignmentHs.LEFT` instead.
`static int`	`LEFT_TO_RIGHT` Deprecated. Use `SoTextProperty.Orientations.LEFT_TO_RIGHT` instead.
`SoSFFloat`	`margin` Set a margin (extra space) to apply around the text string for the BACK_FRAME and BACK_FRAME_LINE styles.
`static int`	`NONE` Deprecated. Use `SoTextProperty.Styles.NONE` instead.
`static int`	`NUM_EFFECTS_COLORS` Deprecated. Use `SoTextProperty.StyleColorType.NUM_EFFECTS_COLORS` instead.
`SoSFEnum<SoTextProperty.Orientations>`	`orientation` Specifies the text rendering orientation.
`static int`	`OVERLINE` Deprecated. Use `SoTextProperty.Styles.OVERLINE` instead.
`static int`	`OVERLINE_COLOR` Deprecated. Use `SoTextProperty.StyleColorType.OVERLINE_COLOR` instead.
`static int`	`RIGHT` Deprecated. Use `SoTextProperty.AlignmentHs.RIGHT` instead.
`static int`	`RIGHT_TO_LEFT` Deprecated. Use `SoTextProperty.Orientations.RIGHT_TO_LEFT` instead.
`static int`	`STRIKETHROUGH` Deprecated. Use `SoTextProperty.Styles.STRIKETHROUGH` instead.
`static int`	`STRIKETHROUGH_COLOR` Deprecated. Use `SoTextProperty.StyleColorType.STRIKETHROUGH_COLOR` instead.
`SoSFBitMask<SoTextProperty.Styles>`	`style` Specifies zero or more styles to be applied to text.
`SoMFColorRGBA`	`styleColors` Specifies the color to use for each style.
`SoMFBool`	`styleColorsUseCurrentMaterial` This field allows to use the current `SoMaterial` instead of the value specified by `styleColors` for each available style (default gray).
`SoSFVec2i32`	`textureQualityRange` Defines a quality range of values taken into account during textured text texture computation.
`static int`	`TOP` Deprecated. Use `SoTextProperty.AlignmentVs.TOP` instead.
`static int`	`TOP_TO_BOTTOM` Deprecated. Use `SoTextProperty.Orientations.TOP_TO_BOTTOM` instead.
`static int`	`UNDERLINE` Deprecated. Use `SoTextProperty.Styles.UNDERLINE` instead.
`static int`	`UNDERLINE_COLOR` Deprecated. Use `SoTextProperty.StyleColorType.UNDERLINE_COLOR` instead.

Fields inherited from class com.openinventor.inventor.Inventor
VERBOSE_LEVEL, ZeroHandle

Constructor Summary

Constructors
Constructor and Description

SoTextProperty()
Text property constructor.

Constructors
Constructor and Description
`SoTextProperty()` Text property constructor.

Method Summary
- Methods inherited from class com.openinventor.inventor.nodes.SoNode
  affectsState, callback, copy, copy, distribute, doAction, getAlternateRep, getBoundingBox, getByName, getMatrix, getPrimitiveCount, getRenderUnitID, GLRender, GLRenderBelowPath, GLRenderInPath, GLRenderOffPath, grabEventsCleanup, grabEventsSetup, handleEvent, isBoundingBoxIgnoring, isOverride, pick, rayPick, search, setOverride, touch, write
- Methods inherited from class com.openinventor.inventor.fields.SoFieldContainer
  copyFieldValues, copyFieldValues, enableNotify, fieldsAreEqual, get, getAllFields, getEventIn, getEventOut, getField, getFieldName, hasDefaultValues, isNotifyEnabled, set, setToDefaults
- Methods inherited from class com.openinventor.inventor.misc.SoBase
  dispose, getEXTERNPROTO, getName, getPROTO, isDisposable, isSynchronizable, setName, setSynchronizable
- Methods inherited from class com.openinventor.inventor.Inventor
  getAddress, getNativeResourceHandle, startInternalThreads, stopInternalThreads
- Methods inherited from class java.lang.Object
  equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - LEFT
```
@Deprecated
public static final int LEFT
```
    Deprecated. Use SoTextProperty.AlignmentHs.LEFT instead.
  - CENTER
```
@Deprecated
public static final int CENTER
```
    Deprecated. Use SoTextProperty.AlignmentHs.CENTER instead.
  - RIGHT
```
@Deprecated
public static final int RIGHT
```
    Deprecated. Use SoTextProperty.AlignmentHs.RIGHT instead.
  - TOP
```
@Deprecated
public static final int TOP
```
    Deprecated. Use SoTextProperty.AlignmentVs.TOP instead.
  - HALF
```
@Deprecated
public static final int HALF
```
    Deprecated. Use SoTextProperty.AlignmentVs.HALF instead.
  - BASE
```
@Deprecated
public static final int BASE
```
    Deprecated. Use SoTextProperty.AlignmentVs.BASE instead.
  - BOTTOM
```
@Deprecated
public static final int BOTTOM
```
    Deprecated. Use SoTextProperty.AlignmentVs.BOTTOM instead.
  - LEFT_TO_RIGHT
```
@Deprecated
public static final int LEFT_TO_RIGHT
```
    Deprecated. Use SoTextProperty.Orientations.LEFT_TO_RIGHT instead.
  - RIGHT_TO_LEFT
```
@Deprecated
public static final int RIGHT_TO_LEFT
```
    Deprecated. Use SoTextProperty.Orientations.RIGHT_TO_LEFT instead.
  - TOP_TO_BOTTOM
```
@Deprecated
public static final int TOP_TO_BOTTOM
```
    Deprecated. Use SoTextProperty.Orientations.TOP_TO_BOTTOM instead.
  - BOTTOM_TO_TOP
```
@Deprecated
public static final int BOTTOM_TO_TOP
```
    Deprecated. Use SoTextProperty.Orientations.BOTTOM_TO_TOP instead.
  - NONE
```
@Deprecated
public static final int NONE
```
    Deprecated. Use SoTextProperty.Styles.NONE instead.
  - UNDERLINE
```
@Deprecated
public static final int UNDERLINE
```
    Deprecated. Use SoTextProperty.Styles.UNDERLINE instead.
  - STRIKETHROUGH
```
@Deprecated
public static final int STRIKETHROUGH
```
    Deprecated. Use SoTextProperty.Styles.STRIKETHROUGH instead.
  - DOUBLE_STRIKETHROUGH
```
@Deprecated
public static final int DOUBLE_STRIKETHROUGH
```
    Deprecated. Use SoTextProperty.Styles.DOUBLE_STRIKETHROUGH instead.
  - BACK_FRAME
```
@Deprecated
public static final int BACK_FRAME
```
    Deprecated. Use SoTextProperty.Styles.BACK_FRAME instead.
  - BACK_FRAME_LINE
```
@Deprecated
public static final int BACK_FRAME_LINE
```
    Deprecated. Use SoTextProperty.Styles.BACK_FRAME_LINE instead.
  - OVERLINE
```
@Deprecated
public static final int OVERLINE
```
    Deprecated. Use SoTextProperty.Styles.OVERLINE instead.
  - UNDERLINE_COLOR
```
@Deprecated
public static final int UNDERLINE_COLOR
```
    Deprecated. Use SoTextProperty.StyleColorType.UNDERLINE_COLOR instead.
  - STRIKETHROUGH_COLOR
```
@Deprecated
public static final int STRIKETHROUGH_COLOR
```
    Deprecated. Use SoTextProperty.StyleColorType.STRIKETHROUGH_COLOR instead.
  - DOUBLE_STRIKETHROUGH_COLOR
```
@Deprecated
public static final int DOUBLE_STRIKETHROUGH_COLOR
```
    Deprecated. Use SoTextProperty.StyleColorType.DOUBLE_STRIKETHROUGH_COLOR instead.
  - BACK_FRAME_COLOR
```
@Deprecated
public static final int BACK_FRAME_COLOR
```
    Deprecated. Use SoTextProperty.StyleColorType.BACK_FRAME_COLOR instead.
  - BACK_FRAME_LINE_COLOR
```
@Deprecated
public static final int BACK_FRAME_LINE_COLOR
```
    Deprecated. Use SoTextProperty.StyleColorType.BACK_FRAME_LINE_COLOR instead.
  - OVERLINE_COLOR
```
@Deprecated
public static final int OVERLINE_COLOR
```
    Deprecated. Use SoTextProperty.StyleColorType.OVERLINE_COLOR instead.
  - NUM_EFFECTS_COLORS
```
@Deprecated
public static final int NUM_EFFECTS_COLORS
```
    Deprecated. Use SoTextProperty.StyleColorType.NUM_EFFECTS_COLORS instead.
  - aliasingFactor
```
public final SoSFFloat 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.
  - alignmentH
```
public final SoSFEnum<SoTextProperty.AlignmentHs> 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.
  - alignmentV
```
public final SoSFEnum<SoTextProperty.AlignmentVs> 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.
  - backFrameLineWidth
```
public final SoSFFloat 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.
    
    Since:
    
    Open Inventor 9.2
  - kerning
```
public final SoSFBool 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.
  - orientation
```
public final SoSFEnum<SoTextProperty.Orientations> 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.
  - textureQualityRange
```
public final SoSFVec2i32 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.
    
    Since:
    
    Open Inventor 8.1
  - style
```
public final SoSFBitMask<SoTextProperty.Styles> 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).
    
    Since:
    
    Open Inventor 8.1
  - styleColors
```
public final SoMFColorRGBA 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.
```
 // Note the set1Value method expects an "int" as its first parameter
 SoTextProperty node = new SoTextProperty();
 node.styleColors.set1Value( SoTextProperty.StyleColorType.UNDERLINE_COLOR.getValue(), new SbColorRGBA(1, 0, 0, 1) );
```
    Default is (0.8,0.8,0.8,1) = the Open Inventor default diffuse color with alpha=1 (opaque).
    Since:
    
    Open Inventor 8.1
  - margin
```
public final SoSFFloat 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.
    
    Since:
    
    Open Inventor 8.1
  - styleColorsUseCurrentMaterial
```
public final SoMFBool 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).
    
    Since:
    
    Open Inventor 9.4
  - characterSpacing
```
public final SoSFFloat 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.
  - enableTextAccumulation
```
public final SoSFBool enableTextAccumulation
```
    Enables the accumulation rendering mode for SoText3 nodes. Default is false. Accumulation mode significantly improves performance for scene graphs containing many SoText3 nodes. There are some drawbacks and limitations:
    - In Polygon mode, the accumulation takes time so the first rendering will be longer, and has a memory overhead.
    - Since the feature is based on an accumulation process, if you plan to often update the scene graph it will not fit your needs.
    - SoDepthOffset is not supported.
    - Transparency is not well supported for now.
    Default value can be changed using the environment variable OIV_TEXT_ACCUMULATION.
    Since:
    
    Open Inventor 9.8
- Constructor Detail
  - SoTextProperty
```
public SoTextProperty()
```
    Text property constructor.

Class SoTextProperty

Nested Class Summary

Nested classes/interfaces inherited from class com.openinventor.inventor.Inventor

Field Summary

Fields inherited from class com.openinventor.inventor.Inventor

Constructor Summary

Method Summary

Methods inherited from class com.openinventor.inventor.nodes.SoNode

Methods inherited from class com.openinventor.inventor.fields.SoFieldContainer

Methods inherited from class com.openinventor.inventor.misc.SoBase

Methods inherited from class com.openinventor.inventor.Inventor

Methods inherited from class java.lang.Object

Field Detail

LEFT

CENTER

RIGHT

TOP

HALF

BASE

BOTTOM

LEFT_TO_RIGHT

RIGHT_TO_LEFT

TOP_TO_BOTTOM

BOTTOM_TO_TOP

NONE

UNDERLINE

STRIKETHROUGH

DOUBLE_STRIKETHROUGH

BACK_FRAME

BACK_FRAME_LINE

OVERLINE

UNDERLINE_COLOR

STRIKETHROUGH_COLOR

DOUBLE_STRIKETHROUGH_COLOR

BACK_FRAME_COLOR

BACK_FRAME_LINE_COLOR

OVERLINE_COLOR

NUM_EFFECTS_COLORS

aliasingFactor

alignmentH

alignmentV

backFrameLineWidth

kerning

orientation

textureQualityRange

style

styleColors

margin

styleColorsUseCurrentMaterial

characterSpacing

enableTextAccumulation

Constructor Detail

SoTextProperty