NCL Website header
NCL Home > Documentation > HLUs > Classes

TextItem class

The TextItem object draws arbitrary text.

Synopsis

Header file:		ncarg/hlu/TextItem.h
Class name:		textItemClass
Class pointer:		NhltextItemClass
Fortran class function:	NHLFTEXTITEMCLASS
Superclass:		View
Composite classes:	<None>

Class-defined types

Type name:		NhlTFontQuality
Definition:
typedef enum {
	NhlHIGH		= 0,	/* "High"	*/
	NhlMEDIUM	= 1,	/* "Medium"	*/
	NhlLOW		= 2	/* "Low"	*/
} NhlFontQuality;

Type name:		NhlTTextDirection
Definition:
typedef enum {
	NhlDOWN		= 0,	/* "Down"	*/
	NhlACROSS	= 1,	/* "Across"	*/
} NhlTextDirection;

Resources

Local resources

TextItem resources are logically arranged into three groups:

 Orientation  - Resources affecting text location and orientation
 Appearance   - Resources that affect text appearance
 Bounding Box - Resources affecting the text bounding box
|===============================================================|
|			TextItem Resource Set			|
|===============================================================|
| Text Location and Orientation Resources                       |
|---------------------------------------------------------------|
| NAME				TYPE			ACCESS	|
|	CLASS				DEFAULT			|
|===============================================================|
| txPosXF			NhlTFloat		RCSG	|
|	TxPosXF				<Dynamic>		|
|---------------------------------------------------------------|
| txPosYF			NhlTFloat		RCSG	|
|	TxPosYF				<Dynamic>		|
|---------------------------------------------------------------|
| txAngleF			NhlTFloat		RCSG	|
|       TextAngleF                      0.0                     |
|---------------------------------------------------------------|
| txJust                        NhlTJustification       RCSG    |
|       TextJustification              NhlCENTERCENTER		|
|---------------------------------------------------------------|
| txDirection			NhlTTextDirection	RCSG	|
|       TextDirection                   NhlACROSS               |
|===============================================================|
| Text Appearance Resources                                     |
|---------------------------------------------------------------|
| NAME				TYPE			ACCESS	|
|	CLASS				DEFAULT			|
|===============================================================|
| txString			NhlTString		RCSG	|
|	TxString			<dynamic>		|
|---------------------------------------------------------------|
| txFont			NhlTFont		RCSG	|
|       Font                            pwritx			|
|---------------------------------------------------------------|
| txFontQuality			NhlTFontQuality		RCSG	|
|	FontQuality			"high"			|
|---------------------------------------------------------------|
| txFontColor			NhlTColorIndex		RCSG	|
|       FontColor                       NhlFOREGROUND		|
|---------------------------------------------------------------|
| txFontHeightF			NhlTFloat		RCSG	|
|       FontHeightF                     .05                     |
|---------------------------------------------------------------|
| txFontAspectF			NhlTFloat		RCSG	|
|       FontAspectF                     1.3125                  |
|---------------------------------------------------------------|
| txFontThicknessF		NhlTFloat		RCSG	|
|       FontThicknessF                  1.0                     |
|---------------------------------------------------------------|
| txConstantSpacingF		NhlTFloat		RCSG	|
|       TextConstantSpacingF            0.0                     |
|---------------------------------------------------------------|
| txFuncCode			NhlTCharacter		RCSG	|
|       TextFuncCode                    :                       |
|===============================================================|
| Text Bounding Box Resources                                   |
|---------------------------------------------------------------|
| NAME				TYPE			ACCESS	|
|	CLASS				DEFAULT			|
|===============================================================|
| txPerimOn			NhlTBoolean		RCSG	|
|       EdgesOn                         False                   |
|---------------------------------------------------------------|
| txPerimColor			NhlTColorIndex		RCSG	|
|       EdgeColor                       NhlFOREGROUND           |
|---------------------------------------------------------------|
| txPerimThicknessF		NhlTFloat		RCSG	|
|       EdgeThicknessF                  1.0                     |
|---------------------------------------------------------------|
| txPerimDashPattern		NhlTDashIndex		RCSG	|
|       EdgeDashPattern                 0                       |
|---------------------------------------------------------------|
| txPerimDashLengthF		NhlTFloat		RCSG	|
|       EdgeDashSegLenF                 0.15                    |
|---------------------------------------------------------------|
| txPerimSpaceF			NhlTFloat		RCSG	|
|       EdgeBorderWidthF                0.5                     |
|---------------------------------------------------------------|
| txBackgroundFillColor		NhlTColorIndex		RCSG	|
|       FillBackgroundColor             NhlTRANSPARENT          |
+---------------------------------------------------------------+

Composite resources

The TextItem object class has no composite class objects.

Superclass resources

You may set any resources belonging to the superclasses of the TextItem object class, including:


Description

The TextItem, as its name implies, draws text. The text can have any font, any color, any angle, and be any size. You can also draw a rectangular perimeter around the text and optionally provide a solid colored background to the area inside the perimeter box. The TextItem is derived from the View class and therefore inherits all of the functionality of the View class.

The location and size of the text to be drawn can be set using two distinct and separate methods. The two methods can not be mixed because the resources for each method are assigned values based on the placement determined from the other.

The first method is simply using the regular View resources vpXF, vpYF, vpWidthF, and vpHeightF. However, the View resources will be ignored if any of the TextItem resources that effect size or position are set at the same time. These resources are: txPosXF, txPosYF, txAngleF, txJust, txDirection, txFontAspectF, txConstantSpacingF, and txFontHeightF.

When the View object resources vpWidthF, and vpHeightF are set, the value of the txFontHeightF resource automatically scales proportionally. Additionally, if the values of vpWidthF and vpHeightF resource do not preserve the aspect ratio, either the height or width resource are reduced to produce an aspect ratio preserving transformation.

For the second placement method, the TextItem uses the resources txPosXF, and txPosYF in combination with the txJust resource. Using this method, it is very easy to determine exactly how the text will be justified relative to other objects on the output frame.

The two position resources txPosXF and txPosYF specify where the justification point of the text string will be placed. You set the justification point using any of the nine values available to the NhlJustification type resource txJust. The default value of txJust is NhlCENTERCENTER meaning that the TextItem centers the text along both its axes. These axes may be rotated from the NDC coordinate axes if you give txAngleF a non-zero value, or they may be exchanged depending on the value given to txDirection.

There are 32 HLU Library Fonts, numbered in the range 0 to 37. You specify the desired font using the NhlFont type resource txFont. You may set this resource as a string using the name of the font or as an integer using the font index. If you specify the integer index you should note that there are some gaps in the numbering system used for the font indexes.

You can control various attributes of the TextItem string's appearance by setting the resources txFontQuality, txFontColor, txFontHeightF, txFontAspectF, txFontThicknessF, and txConstantSpacingF.

The HLU TextItem allows you to specify Text Function Codes just as you would for the low-level NCAR Graphics package Plotchar. Through the use of function codes, you can control the appearance of the text from within the string txString. You can change fonts, vary the size of characters, set the text direction, and use up to five levels of subscripts and superscripts. You can also embed "carriage returns" within the string for multi-line output. You can modify the character used as a function code sentinel using the NhlTCharacter resource txFuncCode. Keep in mind, however, that for many normal text operations you do not need to learn how to use function codes.

If you set the boolean resource txPerimOn True, the TextItem draws a rectangular box around the text string. The box is aligned with the axes of the text string after taking any rotation as a result of txAngleF into account. You control the line attributes of the perimeter line using the resources txPerimColor, txPerimThicknessF, txPerimDashPattern, and txPerimDashLengthF. You can also set the spacing or margin between the boundary of the characters and the perimeter as a fraction of the current txFontHeightF using the resource txPerimSpaceF. In addition you can provide a solid- colored background to the space within the rectangular perimeter by setting the resource txBackgroundFillColor. The default value of this resource is NhlTRANSPARENT, implying no background fill.


Support functions

The TextItem object does not define any support functions, but inherits all the support functions available to its superclass.

Status


See also