Text Objects

Text objects contain string values that are drawn to the destination object at a location you specify. You have control over the font used (via an IDLgrFont object), the angle of the text baseline, and the vertical direction of the text.

Creating Text Objects

To create a text object, specify a string or an array of strings to the IDLgrText::Init method when calling OBJ_NEW. 

mytext = OBJ_NEW('IDLgrText', 'A Text String')

or 

mytextarr = OBJ_NEW('IDLgrText', $ 
   ['First String', 'Second String', 'Third String'])

See "IDLgrText" (IDL Reference Guide) for details on creating text objects.

Using Text Objects

Creating text annotations in their simplest form—two-dimensional text displayed at a given location—involves only specifying the text, and the location. For example, to display the words Text String in a window in the default font, the following statements suffice: 

mywindow = OBJ_NEW('IDLgrWindow', DIMENSIONS=[400,400]) 
myview = OBJ_NEW('IDLgrView', VIEWPLANE_RECT=[0,0,10,10]) 
mymodel = OBJ_NEW('IDLgrModel') 
mytext = OBJ_NEW('IDLgrText', 'Text String', LOCATION=[4,4], $ 
   COLOR=[50,100,150]) 
myview->Add, mymodel 
mymodel->Add, mytext 
mywindow->Draw, myview

The text is drawn at the specified location, with the baseline parallel to the x-axis.

Location and Alignment

Specifying a location via the LOCATION property picks a point in space where the text object will be placed. By default, text objects are aligned with their lower left edge located at the point specified by the LOCATION property.

You can change the horizontal position of the text object with respect to the point specified by LOCATION by changing the ALIGNMENT property to a floating-point value between 0.0 and 1.0. The default value (0.0) aligns and left-justifies text at the location specified. Setting ALIGNMENT to 1.0 right-justifies the text; setting it to 0.5 centers the text above the point specified. The vertical position with respect to location can also be set using the VERTICAL_ALIGNMENT property. The default value (0.0) bottom-justifies the text at the given location. A vertical alignment of 1.0 top-justifies the text.

3D Text and Text "On the Glass"

Text objects, like all graphics atoms, are located and oriented in three-dimensional space. (We often ignore the third dimension when making simple plots and graphs—in these cases we simply use the default z value of zero.) With text objects, however, there is an option to project text on the glass.

Projecting text on the glass ensures that it is displayed as if it were in flat, two-dimensional space no matter what its true orientation in three-dimensional space may be. In cases where text objects may be rotated at arbitrary angles, projecting on the glass ensures that the text will be readable.

To project text on the glass, set the ONGLASS property of the text object to a value other than zero.

Figure 9-1: 3D Text and Text "On the Glass"

objaxes3.gif

Baseline

The text baseline can be altered from its default orientation (parallel to the x-axis) by setting the text object's BASELINE property to a two- or three-element array. The new baseline will be oriented parallel to a line drawn between the origin and the coordinates specified. For example, the following statement makes the text baseline parallel to a line drawn between the points [0, 0] and [1, 2]: 

mytext->SetProperty, BASELINE=[1,2]

Figure 9-2: Baseline

objaxes4.gif

The following statement makes the baseline parallel to a line drawn between the origin and a point located at [2, 1, 3]: 

mytext->SetProperty, BASELINE=[2,1,3]

Notice that the orientation of the baseline is only an orientation; changing value of the BASELINE property does not change the location of the text object.

Upward Direction

In addition to the baseline orientation, you can control the upward direction of the text object. (The upward direction is the direction defined by a vector pointing from the origin to the point specified.) The upward direction defines the plane on which text is drawn; by specifying a baseline and an upward direction, you define the plane.

Note
The upward direction does not specify a slant angle. That is, even if you specify a direction that is not perpendicular to the baseline for the upward direction, the text will still be perpendicular to the baseline. All that matters is the plane defined by the baseline and upward direction.

For example, in the default situation, the baseline is oriented parallel to the x-axis, and the upward direction is parallel to the y-axis, pointing in the positive y direction.

Warning
If the baseline and upward direction are coincident—that is, if they do not define a plane on which to draw the text—IDL generates an error message.

Fonts

The type style and size of the characters displayed in a text object are controlled by the FONT property. Set the FONT property equal to the object reference of an IDLgrFont object to use that font's properties for the text object. If no font object is specified, IDL uses the default font (12 point Helvetica regular).

Font objects are discussed in Font Objects.

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. Also see Object Graphics Embedded Formatting Examples.

Example Code
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.