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:

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