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