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:

In addition, objects of this class inherit:

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.

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.

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).

Note
For more detailed information on alpha channel support for IDL Object Graphics, see Controlling Object Transparency (Object Programming).

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.

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.

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.

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.

DEPTH_TEST_DISABLE

An integer value that determines whether depth testing is disabled.

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.

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.

Less means closer to the viewer.

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

DEPTH_WRITE_DISABLE

An integer value that determines whether depth writing is disabled.

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.

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.

Possible uses for the DRAW_CURSOR property include:

Example

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

Note
For information on how text elements are indexed, see Character Indices in Text Strings.

ENABLE_FORMATTING

A Boolean value that determines whether the text object should honor embedded Hershey-style formatting codes within the strings. (Formatting codes are described in Fonts.) The default is not to honor the formatting codes.

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).

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

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.

HIDE

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

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).

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.

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.

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.

PARENT

An object reference to the object that contains this object.

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:

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.

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:

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.

Note
See Character Indices in Text Strings for examples.

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.

See Character Indices in Text Strings for more information.

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.

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.

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.

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.

XCOORD_CONV

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

NormalizedX = s₀ + s₁ * DataX

Recommended values are:

[(-X_min)/(X_max-X_min), 1/(X_max-X_min)]

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

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.

YCOORD_CONV

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

NormalizedY = s₀ + s₁ * DataY

Recommended values are:

[(-Y_min)/(Y_max-Y_min), 1/(Y_max-Y_min)]

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

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.

ZCOORD_CONV

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

NormalizedZ = s₀ + s₁ * DataZ

Recommended values are:

[(-Z_min)/(Z_max-Z_min), 1/(Z_max-Z_min)]

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

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.