The TextItem object draws arbitrary text.
Header file: ncarg/hlu/TextItem.h Class name: textItemClass Class pointer: NhltextItemClass Fortran class function: NHLFTEXTITEMCLASS Superclass: View Composite classes: <None>
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;
TextItem resources are logically arranged into three groups: Orientation - Resources affecting text location and orientation Appearance - Resources that affect tick mark 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 | +---------------------------------------------------------------+
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 proportionially. 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.
NG4.1 Home, Index, Examples, Glossary, Feedback, Ref Contents, Ref WhereAmI?