IDLgrText

A text object represents one or more text strings that share common rendering attributes. An IDLgrText object is an atomic graphic object; it is one of the basic drawable elements of the IDL Object Graphics system, and it is not a container for other objects.

Tip: The IDLgrTextEdit object class is a helper class that extends the IDLgrText object class, adding methods to delete text, insert text, and position the cursor. If you plan to implement any of these actions, consider using IDLgrTextEdit objects in preference to IDLgrText objects. See IDLgrTextEdit for details.

Superclasses

IDLitComponent

Creation

See IDLgrText::Init.

Properties

Objects of this class have the following properties. See IDLgrText Properties for details on individual 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 the properties of all superclasses of this class.

Methods

This class has the following methods:

• IDLgrText::Cleanup
• IDLgrText::GetCTM
• IDLgrText::GetIndexAtCoord
• IDLgrText::GetIndexRelativeTo
• IDLgrText::GetProperty
• IDLgrText::Init
• IDLgrText::SetProperty

In addition, this class inherits the methods of its superclasses (if any).

Examples

A Text Example

The rot_text.pro example creates a simple text string, rotates it around the y and z axes using the BASELINE and UPDIR properties, and displays several different fonts.

The procedure rot_text.pro is included in the examples/doc/objects subdirectory of the IDL distribution. Run the example procedure by entering rot_text at the IDL command prompt or view the file in an IDL editor window by entering .EDIT rot_text.pro.

Version History

5.0	Introduced
5.6	Added CLIP_PLANES property
6.4	Added SHADER property
7.0.6	Added GetIndexAtCoord and GetIndexRelativeTo methods. Added SELECTION_START, SELECTION_LENGTH, DRAW_CURSOR properties.

Character Indices in Text Strings

The IDLgrText property SELECTION_START uses the character index to position the cursor or the edge of a selection in the string defined by the text object. The character index is a zero-based identifier of the position just to the left of the character identified. For example, in the following string of characters:

String of characters

the character index 7 specifies the position between the first space character and the letter “o” in the word “of.”

In many cases, the location within a visible string of characters that corresponds to a particular character index value is obvious. However, when the text string specified to the IDLgrText object contains embedded formatting commands to change the size, position, or font face, the character indices no longer correspond directly to the locations of the characters displayed on the screen.

The following example shows regular text as well as superscript and subscript.

To create this example in an IDLgrText object, you would set the STRINGS property to the following value, which includes embedded formatting commands to create the superscript and subscript characters:

Text!USuper!DSub

 

Note: You must also set the ENABLE_FORMATTING property of the IDLgrText object for embedded formatting codes to be honored.

The embedded formatting commands themselves are not displayed. In this example, any text following (!U) displays as supertext, while text following (!D) displays as subtext . See these characters in the grayed-out areas in the next example. This example shows the character index used when specifying a value via the SELECTION_START property.

The index specifies a location within the string. Placing the insertion cursor at an index number means that the cursor displays just before the character. In the following example, you would use index number 16 to place the insertion cursor after the last character.

Some indices do not make sense to use and are ignored. For example, index number 12 would place the cursor in between two format control characters.

Note: For more information on formatting text annotations, see Embedded Formatting Commands.

Examples

The following examples illustrate the IDLgrText properties SELECTION_START and SELECTION_LENGTH. The text selection between the bars equates to the following property values (if defined from left to right):

SELECTION_START=1

SELECTION_LENGTH=7

Because the direction of these properties can start from left to right or right to left, the same selection can also be defined from right to left as:

SELECTION_START=8

SELECTION_LENGTH=-7

A selection start between two characters like the one shown below is defined as:

SELECTION_START=10

SELECTION_LENGTH=0