Routines (alphabetical) > Object Classes > Graphics Object Classes > IDLgrText Properties

# IDLgrText Properties

IDLgrText objects have the following properties in addition to properties inherited from any superclasses. Properties with the word “Yes” in the “Get” column of the property table can be retrieved via IDLgrText::GetProperty. Properties with the word “Yes” in the “Init” column of the property table can be set via IDLgrText::Init. Properties with the word “Yes” in the “Set” column in the property table can be set via IDLgrText::SetProperty.

Note: For a discussion of the property description tables shown below, see About Object Property Descriptions.

Objects of this class have the following properties:

ALIGNMENT | ALL
ALPHA_CHANNEL | BASELINE
CHAR_DIMENSIONS | CLIP_PLANES
COLOR | DEPTH_TEST_DISABLE
DEPTH_TEST_FUNCTION | DEPTH_WRITE_DISABLE
DRAW_CURSOR | ENABLE_FORMATTING
FILL_BACKGROUND | FILL_COLOR
FONT | HIDE
KERNING | LOCATIONS
ONGLASS | PALETTE
PARENT | RECOMPUTE_DIMENSIONS
REGISTER_PROPERTIES | RENDER_METHOD
SELECTION_LENGTH | SELECTION_START
SHADER | STRINGS
UPDIR | VERTICAL_ALIGNMENT
XCOORD_CONV | XRANGE
YCOORD_CONV | YRANGE
ZCOORD_CONV | ZRANGE

In addition, objects of this class inherit:

- IDLitComponent

### ALIGNMENT

A floating-point value between 0.0 and 1.0 to indicate the requested horizontal alignment of the text baseline. An alignment of 0.0 (the default) left-justifies the text at the given position; an alignment of 1.0 right-justifies the text, and an alignment of 0.5 centers the text over the given position.

Property Type | FLOAT
Name String | Horizontal alignment
Get: Yes | Set: Yes | Init: Yes | Registered: Yes

### ALL

An anonymous structure containing the values of all of the properties associated with the state of this object. State information about the object includes things like color, range, tick direction, etc., but not image, vertex, or connectivity data, or user values.

Note: The fields of this structure may change in subsequent releases of IDL.

Property Type | Structure
Name String | not displayed
Get: Yes | Set: No | Init: No | Registered: No

### ALPHA_CHANNEL

A floating-point value that determines the opacity of the text with respect to the background. Set this property to a value in the range [0.0, 1.0] (1.0 is the default) to draw the text foreground and background with the specified blending factor. A value of 1.0 draws the text opaquely without blending the text with objects already drawn on the destination. Edges of the glyphs are always blended. A value of 0.0 draws no text at all. A value in the middle of the range draws the text semi-transparently, which provides a way of creating labels that are visible while allowing features blocked by the labels to still be seen. This property is used only when the RENDER_METHOD in effect is 0 (Texture).

Property Type | Float-point value
Name String | Transparency
Get: Yes | Set: Yes | Init: Yes | Registered: Yes

### BASELINE

A two- or three-element floating-point vector describing the direction in which the baseline is to be oriented. Use this property in conjunction with the UPDIR property to specify the plane on which the text lies. The default BASELINE is [1.0,0,0] (i.e., parallel to the x-axis).

This property is registered as a user-defined property, but it is hidden by default.

Property Type | USERDEF
Name String | Baseline direction
Get: Yes | Set: Yes | Init: Yes | Registered: Yes

### CHAR_DIMENSIONS

A two-element floating-point vector [width, height] indicating the dimensions (measured in data units) of a bounding box for each character, to be used when scaling text projected in three dimensions. If either width or height is zero, the text will be scaled such that if it were positioned halfway between the near and far clipping planes, it will appear at the point size associated with this text object’s font. The default value is [0, 0]. IDL converts, maintains, and returns this data as double-precision floating-point.

Note: If you set the CHAR_DIMENSIONS property to [0,0] (using the SetProperty method), indicating that IDL should calculate the text size, the value (returned by the GetProperty method) will not be updated to reflect the calculated size until you call either the Draw method or the GetTextDimensions method.

For example, if the VIEWPLANE_RECT of the view the text object is being rendered in is set equal to [0,0,10,10] (that is, it spans ten data units in each of the X and Y directions), setting the CHAR_DIMENSIONS property equal to [2, 3] will scale the text such that each character fills 20% of the X range and 30% of the Y range.

This property has no effect if the ONGLASS property is set equal to one.

Property Type | Floating-point vector
Name String | not displayed
Get: Yes | Set: Yes | Init: Yes | Registered: No

### CLIP_PLANES

A 4-by-N floating-point array that specifies the coefficients of the clipping planes to be applied to this object. The four coefficients for each clipping plane are of the form [A, B, C, D], where Ax + By + Cz + D = 0. Portions of this object that fall in the half space Ax + By + Cz + D > 0 will be clipped. By default, the value of this property is a scalar (-1) indicating that no clipping planes are to be applied.

Note: The clipping planes specified via this property are applied in addition to the near and far clipping planes associated with the IDLgrView in which this object appears.

Note: Clipping planes are applied in the data space of this object (prior to the application of any x, y, or z coordinate conversion).

Note: To determine the maximum number of clipping planes supported by the device, use the MAX_NUM_CLIP_PLANES property of the GetDeviceInfo method for the IDLgrBuffer, IDLgrClipboard, IDLgrWindow, and IDLgrVRML objects.

Property Type | Floating-point array
Name String | not displayed
Get: Yes | Set: Yes | Init: Yes | Registered: No

### COLOR

The color to be used as the foreground color for the text. The color may be specified as a color lookup table index or as a three-element vector [red, green, blue]. The default is [0, 0, 0].

In a property sheet, this property appears as a color property.

Property Type | COLOR
Name String | Color
Get: Yes | Set: Yes | Init: Yes | Registered: Yes

### DEPTH_TEST_DISABLE

An integer value that determines whether depth testing is disabled.

- Set this property to 0 (the default) to inherit the value set by the parent model or view. The parent view always enables depth testing. A model may also enable or disable depth testing.
- Set this property to 1 to explicitly disable depth buffer testing while drawing this object.
- Set this property to 2 to explicitly enable depth testing for this object.

Disabling depth testing allows an object to draw itself “on top” of other objects already on the screen, even if the object is located behind them.

Note: Disabling depth testing also disables depth buffer writing. When disabling depth testing, the DEPTH_TEST_FUNCTION and DEPTH_WRITE_DISABLE properties are effectively ignored.

This property is registered as an enumerated list, but it is hidden by default.

Property Type | ENUMLIST
Name String | not displayed
Get: Yes | Set: Yes | Init: Yes | Registered: No

### DEPTH_TEST_FUNCTION

An integer value that determines the depth test function. Set this property to 0 (the default) to inherit the value set by the parent model or view. The parent view always sets a depth test function of LESS. A model may also set a depth test function value. The graphics device compares the object’s depth at a particular pixel location with the depth stored in the depth buffer at that same pixel location. If the comparison test passes, the object’s pixel is drawn at that location on the screen and the depth buffer is updated (if depth writing is enabled).

Set this property to any of the following values to use the desired function while rendering this object.

- 0 = INHERIT - use value from parent model or view.
- 1 = NEVER - never passes.
- 2 = LESS - passes if the object’s depth is less than the depth buffer’s value.
- 3 = EQUAL - passes if the object’s depth is equal to the depth buffer’s value.
- 4 = LESS OR EQUAL - passes if the object’s depth is less than or equal to the depth buffer’s value.
- 5 = GREATER - passes if the object’s depth is greater than or equal to the depth buffer’s value.
- 6 = NOT EQUAL - passes if the object’s depth is not equal to the depth buffer’s value.
- 7 = GREATER OR EQUAL - passes if the object’s depth is greater than or equal to the depth buffer’s value.
- 8 = ALWAYS - always passes

Less means closer to the viewer.

This property is registered as an enumerated list, but it is hidden by default.

Property Type | ENUMLIST
Name String | not displayed
Get: Yes | Set: Yes | Init: Yes | Registered: No

### DEPTH_WRITE_DISABLE

An integer value that determines whether depth writing is disabled.

- Set this property to 0 (the default) to inherit the value set by the parent model or view. The parent view always enables depth writing. A model may also enable or disable depth writing.
- Set this property to 1 to explicitly disable depth buffer writing while rendering this object.
- Set this property to 2 to explicitly enable depth writing for this object.

Disabling depth writing allows an object to be overdrawn by other objects, even if the object is located in front of them.

Note: If depth testing (see DEPTH_TEST_DISABLE property) is disabled, depth writing is also automatically disabled.

This property is registered as an enumerated list, but it is hidden by default.

Property Type | ENUMLIST
Name String | not displayed
Get: Yes | Set: Yes | Init: Yes | Registered: No

### DRAW_CURSOR

A boolean value that indicates whether the insertion cursor is drawn when no text is selected. This has no effect on the display of selected text. It only determines whether the cursor is displayed. The default is 0.

Property Type | Boolean
Name String | not displayed
Get: Yes | Set: Yes | Init: No | Registered: No

Possible uses for the DRAW_CURSOR property include:

- Hiding the cursor when a text box is not being edited
- Toggling the insertion cursor to blink as in some text editors

### Example

In the following text example, the cursor is shown between two letters. `SELECTION_START=3` and `DRAW_CURSOR=1`.

### ENABLE_FORMATTING

A Boolean value that determines whether the text object should honor embedded Hershey-style formatting codes within the strings. The default is not to honor the formatting codes.

Property Type | Boolean
Name String | not displayed
Get: Yes | Set: Yes | Init: Yes | Registered: No

### FILL_BACKGROUND

Set this property to zero (the default) to render the text with a transparent bitmap background, allowing graphics behind the text to show through between the glyphs. Set this property to non-zero to draw the text bitmap background with the color specified by the FILL_COLOR property. This property can only be used when RENDER_METHOD is set to 0 (Texture).

Property Type | Boolean
Name String | Fill background
Get: Yes | Set: Yes | Init: Yes | Registered: Yes

### FILL_COLOR

An integer vector that determines whether to use a text background color other than the view color. Set this property to -1 (the default) to specify that the text background should be drawn using the view color. Set this property to a three-element vector [red, green, blue] or color index value to specify that the text bitmap background should be drawn using the specified color. This property is used only when the FILL_BACKGROUND property has a non-zero value and the RENDER_METHOD in effect is 0 (Texture).

In a property sheet, this property appears as a color property

Property Type | COLOR
Name String | Fill background
Get: Yes | Set: Yes | Init: Yes | Registered: Yes

### FONT

An object reference to an instance of an IDLgrFont object class to describe the font to use to draw this string. The default is 12 point Helvetica. See IDLgrFont for details.

Note: If the default font is in use, retrieving the value of the FONT property (using the GetProperty method) will return a null object.

Note: Objects specified via this property are not automatically cleaned up when the IDLgrText object is destroyed.

Property Type | Object reference
Name String | not displayed
Get: Yes | Set: Yes | Init: Yes | Registered: No

### HIDE

A Boolean value or an enumerated list item indicating whether this object should be drawn:

Value | Property Sheet Value | Description
0 | True | Draw graphic (the default)
1 | False | Do not draw graphic

Property Type | ENUMLIST
Name String | Show
Get: Yes | Set: Yes | Init: Yes | Registered: Yes

### KERNING

A Boolean value that determines whether to enable kerning while rendering characters. Kerning reduces the amount of space between glyphs if the shape of each glyph allows it, according to the font information stored in the font’s file (e.g., AV). Set this property to a non-zero value (the default is zero) to enable kerning. Enabling kerning may not necessarily result in rendering glyphs more closely together because some fonts do not contain the required kerning information. This property is used only when the RENDER_METHOD in effect is 0 (Texture).

Property Type | Boolean
Name String | Kerning
Get: Yes | Set: Yes | Init: Yes | Registered: Yes

### LOCATIONS

A floating-point array of one or more two- or three-element vectors specifying the coordinates (measured in data units) used to position the string(s). The default location for each string is [0,0,0]. Each vector is of the form [x, y] or [x, y, z]; if z is not provided, it is assumed to be zero. Each location corresponds to a string in the String argument; the number of locations should be equal the number of strings. IDL converts, maintains, and returns this data as double-precision floating-point.

This property is registered as a user-defined property, but it is hidden by default.

Property Type | USERDEF
Name String | Text locations
Get: Yes | Set: Yes | Init: Yes | Registered: Yes

### ONGLASS

A Boolean value that indicates whether the text should be displayed “on the glass”. Text that is drawn “on the glass” always faces the viewer, regardless of the 3-D orientation of the objects “underneath” the glass. The default is projected 3-D text.

Property Type | Boolean
Name String | On glass
Get: Yes | Set: Yes | Init: Yes | Registered: Yes

### PALETTE

An object reference to a palette object (an instance of the IDLgrPalette object class) that defines the color palette of this object. This property is only used if the destination device is using the RGB color model. If so, and a color value for the object is specified as a color index value, the palette set by this property is used to translate the color to RGB space. If the PALETTE property on this object is not set, the destination object PALETTE property is used (which defaults to a grayscale ramp).

Note: Objects specified via this property are not automatically cleaned up when the IDLgrText object is destroyed.

This property is registered as a user-defined property, but it is hidden by default.

Property Type | USERDEF
Name String | Color palette
Get: Yes | Set: Yes | Init: Yes | Registered: Yes

### PARENT

An object reference to the object that contains this object.

Property Type | Object reference
Name String | not displayed
Get: Yes | Set: No | Init: No | Registered: No

### RECOMPUTE_DIMENSIONS

An integer value that indicates when this text object’s character dimensions (refer to the CHAR_DIMENSIONS property) are to be recomputed automatically:

0 | The physical size of the text is affected by model and view transforms. The size of the text in terms of data units is obtained from CHAR_DIMENSIONS. Since the character dimensions are specified in data units, the text will maintain the data space size specified by CHAR_DIMENSIONS as the transforms change. In other words, the physical text size changes along with other primitives. If the value of this property is [0, 0], the text font’s point size is used to compute the physical size of the text in terms of data units using the transforms in effect for the first draw. This setting is the default value for this property.
1 | The physical size of the text is only affected by model transforms. The CHAR_DIMENSIONS property is ignored. The size of the text is computed from the font’s point size the first time it is drawn, and IDL does not try to keep the size of the text constant with respect to changes in the model transforms.
2 | The physical size of the text is held constant, even as the model and view change. The CHAR_DIMENSIONS property is ignored and the text is always drawn with a physical size equal to the text font’s point size. IDL adjusts its internal text transforms to maintain the physical size of the text.

Property Type | ENUMLIST
Name String | not displayed
Get: Yes | Set: Yes | Init: Yes | Registered: No

### REGISTER_PROPERTIES

A Boolean value that determines whether to register properties available for this object. If this property is set, all properties marked in this properties section as “Registered: Yes” will be registered for display in a property sheet. This property is useful mainly when creating iTools. By default, no properties are registered.

Property Type | Boolean
Name String | not displayed
Get: No | Set: No | Init: Yes | Registered: No

### RENDER_METHOD

A Boolean value or enumerated list item that determines how the text object will be rendered. Set this property to one of the following values:

Value | Property Sheet Value | Description
0 | Texture | IDL renders the text by placing a bitmap representation of a glyph into a texture map and then rendering a polygon with the texture map. The FILL_BACKGROUND, ALPHA_CHANNEL, and FILL_COLOR properties control the drawing of the background portions of the texture map and how the entire texture map is blended into the scene. Leaving these three properties set to their default values produces a result that closely approximates the TRIANGLES rendering method. One important difference is that the glyph bitmaps are generated by the FreeType font rendering library, producing glyphs that are more accurately rendered and anti-aliased than those drawn with the TRIANGLES method. The TEXTURE method cannot be used on indexed color destinations. The text is rendered with the TRIANGLES method if the destination color model is indexed.
1 | Triangles | IDL renders the text by tessellating the glyph outline into a set of small triangles that are then drawn to produce the solid glyph. IDL also draws a blended line around the edge of the glyph to approximate anti-aliasing. This setting forces IDL to use the process it used as the default before IDL 6.0.

Property Type | ENUMLIST
Name String | Render method
Get: Yes | Set: Yes | Init: Yes | Registered: Yes

### SELECTION_LENGTH

An integer value that specifies the length of the selection, starting from the cursor. Zero indicates no text is selected; the insertion cursor is just placed at SELECTION_START. The selection length may be positive or negative. A positive number means that the selection begins on the left and moves to the right. A negative number means that the selection begins on the right and moves to the left. The default behavior is zero; no selection.

Property Type | Integer
Name String | not displayed
Get: Yes | Set: Yes | Init: No | Registered: No

### SELECTION_START

An integer value that specifies the character index at which text selection starts, which is the same as the position of the insertion cursor. This index is the space immediately before the character with the given index in the string. The default value is zero; the beginning.

Property Type | Integer
Name String | not displayed
Get: Yes | Set: Yes | Init: No | Registered: No

### STRINGS

The string (or vector of strings) associated with the text object.

Specifying this property is the same as specifying the optional String argument to the IDLgrText::Init method.

If the number of strings matches the number of locations (as specified by the LOCATIONS property), the existing locations are used.

Note: If the number of strings does not match the number of locations, the number of locations is modified to match the number of strings, and the location value for each string is reset to [0,0,0].

This property is registered as a user-defined property, but it is hidden by default.

Property Type | USERDEF
Name String | Text strings
Get: Yes | Set: Yes | Init: Yes | Registered: Yes

### SHADER

An object reference to an IDLgrShader object (or an object containing IDLgrShader as a superclass). When there is suitable graphics card hardware support, the text is rendered using the GLSL shader program (executed on the graphics card) instead of using fixed OpenGL properties when initially drawn. (If a suitable graphics card is not present, IDL ignores the shader object when the scene is drawn.) A single IDLgrShader object may be associated with additional text objects or other graphic objects that have the SHADER property.

Property Type | Object reference
Name String | not displayed
Get: Yes | Set: Yes | Init: Yes | Registered: No

### UPDIR

A two- (or three-) element floating-point vector describing the vertical direction for the string. The upward direction is the direction defined by a vector pointing from the origin to the point specified. Use this property in conjunction with the BASELINE property to specify the plane on which the text lies; the direction specified by UPDIR should be orthogonal to the direction specified by BASELINE. The default UPDIR is [0.0, 1.0, 0.0] (i.e., parallel to the Y axis).

This property is registered as a user-defined property, but it is hidden by default.

Property Type | USERDEF
Name String | Up direction
Get: Yes | Set: Yes | Init: Yes | Registered: Yes

### VERTICAL_ALIGNMENT

A floating-point value between 0.0 and 1.0 to indicate the requested vertical alignment of the text. An alignment of 0.0 (the default) bottom-justifies the text at the given location; an alignment of 1.0 top-justifies the text at the given location.

Property Type | FLOAT
Name String | Vertical alignment
Get: Yes | Set: Yes | Init: Yes | Registered: Yes

### XCOORD_CONV

A floating-point vector, [s0, s1], of scaling factors used to convert X coordinates from data units to normalized units. The formula for the conversion is as follows:

NormalizedX = s0 + s1 * DataX

Recommended values are:

[(-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)]

The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double-precision floating-point.

Property Type | Floating-point vector
Name String | not displayed
Get: Yes | Set: Yes | Init: Yes | Registered: No

### XRANGE

A two-element floating-point vector of the form [xmin, xmax] that specifies the range of x data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating-point.

Property Type | Floating-point vector
Name String | not displayed
Get: Yes | Set: No | Init: No | Registered: No

### YCOORD_CONV

A floating-point vector, [s0, s1], of scaling factors used to convert Y coordinates from data units to normalized units. The formula for the conversion is as follows:

NormalizedY = s0 + s1 * DataY

Recommended values are:

[(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)]

The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double-precision floating-point.

Property Type | Floating-point vector
Name String | not displayed
Get: Yes | Set: Yes | Init: Yes | Registered: No

### YRANGE

A two-element floating-point vector of the form [ymin, ymax] that specifies the range of y data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating-point.

Property Type | Floating-point vector
Name String | not displayed
Get: Yes | Set: No | Init: No | Registered: No

### ZCOORD_CONV

A floating-point vector, [s0, s1], of scaling factors used to convert Z coordinates from data units to normalized units. The formula for the conversion is as follows:

NormalizedZ = s0 + s1 * DataZ

Recommended values are:

[(-Zmin)/(Zmax-Zmin), 1/(Zmax-Zmin)]

The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double-precision floating-point.

Property Type | Floating-point vector
Name String | not displayed
Get: Yes | Set: Yes | Init: Yes | Registered: No

### ZRANGE

A two-element floating-point vector of the form [zmin, zmax] that specifies the range of z data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating-point.

Note: Until the text is drawn to the destination object, the [XYZ]RANGE properties will only report the locations of the text. Use the GetTextDimensions method of the destination object to get the data dimensions of the text prior to a draw operation.

Property Type | Floating-point vector
Name String | not displayed
Get: Yes | Set: No | Init: No | Registered: No