Text Output

Discussed here is the text output primitive GTX and the functions that are used to set text attributes and retrieve current attribute settings.

Text Output Primitive

The text output primitive causes a specified text string to be drawn. A number of attribute setting routines are available for selecting the size, font, precision, and orientation of the text.

-----------------------------------------------------
          Argument | Type        |  Mode  | Dimension
-----------------------------------------------------
CALL GTX  (X,      | Real        |  Input |
           Y,      | Real        |  Input |
           STRING) | Character   |  Input |
-----------------------------------------------------

X: The X coordinate for the position point for the text string. X is a world coordinate value. See GSTXAL for how a text string is positioned with respect to its position point.
Y: The Y coordinate for the position point for the text string. Y is a world coordinate value. See GSTXAL for how a text string is positioned with respect to its position point.
STRING: The string of characters to be drawn.
Defaults:: none
Errors:: 5, 101

-------------------------------------------------------------------------
C Synopsis

#include <ncarg/gks.h>

void gtext(
           const Gpoint  *text_pos,    /*  text position     */
           const char    *char_string  /*  character string  */
);
------------------------------------------------------------------------

Setting Text Output Attributes

The appearance of text on a workstation is controlled by a number of attributes including:

Text path (see GSTXP and GQTXP)
Text alignment (see GSTXAL and GQTXAL)
Text font and precision (see GSTXFP and GQTXFP)
Text color index (see GSTXCI and GQTXCI)
Character height (see GSCHH and GQCHH)
Character spacing (see GSCHSP and GQCHSP)
Character up vector (see GSCHUP and GQCHUP)
Character expansion factor (see GSCHXP and GQCHXP)

Each character is surrounded by an imaginary box called the character body. The ratio of height to width in a character body is part of the font definition. Most fonts allow the width of the character body to vary from character to character. For example, a capital M will be wider than a lowercase l. Figure 8 shows the character body of a capital B. The character body is delimited by the lines labeled left, right, bottom, and top. The character itself is delimited in the vertical by a base and a cap. The distance between the base and the cap is the character height. The character body usually will contain some white space to the left and right of the character in order to provide pleasing character separations when character bodies are concatenated to produce an output text string.

Figure 8 - Character body

A box that consists of the concatenated character bodies of a series of horizontal or vertical characters defines a text extent rectangle. Text path and alignment attributes relate to the text extent rectangle.

Figure 9 - Text Extent Rectangle

Set Text Path

--------------------------------------------------
            Argument | Type    |  Mode | Dimension
--------------------------------------------------
CALL GSTXP  (TXP)    | Integer | Input |
--------------------------------------------------

TXP: Gives the direction in which a character string is to be drawn. Options are:

0 - draw character n+l to the right of character n

1 - draw character n+1 to the left of character n

2 - draw character n+1 above character n

3 - draw character n+1 below character n

The above, below, left, and right directions are relative to the character up vector (see routine GSCHUP). The text path direction "right" is perpendicular to the up vector direction. To draw a text string at a 45 degree angle, an appropriate character up vector would be (-1.,1.), and the text path would be right.

Normal text writing (horizontal direction moving toward the right) defaults are a character up vector of (0.,1.) and text path of right.

Default:: The default text path is to the right.
Errors:: 8, 2000

----------------------------------------------------------------------
C Synopsis

#include <ncarg/gks.h>

void gset_text_path(
                    Gtext_path  text_path  /*  text path  */
);
----------------------------------------------------------------------

Figure 10 - text paths and colors

Set Text Alignment

---------------------------------------------------
             Argument | Type    |  Mode | Dimension
---------------------------------------------------
CALL GSTXAL  (TXALH,  | Integer | Input |
              TXALV)  | Integer | Input |
---------------------------------------------------

TXALH: Determines the horizontal alignment of the text to be drawn. Options are:

0 - normal

1 - left

2 - center

3 - right

TXALV: Determines the vertical alignment of the text to be drawn. Options are:

0 - normal

1 - top

2 - cap

3 - half

4 - base

5 - bottom

Text alignment is used to indicate a position on the text extent rectangle that will be identified with the positioning point specified in a call to GTX. The angle of rotation at which the text is written is determined by the character up vector (see GSCHUP).

Table 1. Normal Text Alignments Relative to Text Path

------------------------------------------------
Text Path |  Normal Horizontal | Normal Vertical
------------------------------------------------
RIGHT     | LEFT               | BASE
LEFT      | RIGHT              | BASE
UP        | CENTER             | BASE
DOWN      | CENTER             | TOP
------------------------------------------------

Defaults:: The default horizontal alignment is 0; the default vertical alignment is 0.
Errors:: 8, 2000

--------------------------------------------------------------------------
C Synopsis

#include <ncarg/gks.h>

void gset_text_align(
                  const Gtext_align  *text_align  /*  text alignment  */
);
--------------------------------------------------------------------------

Figure 11 - text alignments

Figure 11, starting from the top and going down, shows the three horizontal positions of left, center, and right combined with a vertical alignment of "half". The next five lines in Figure 11, going down, show the vertical alignments of top, cap, half, base, and bottom for a horizontal alignment of center. Normal text alignment for each text path option is given in Table 1.

Set Text Font and Precision

---------------------------------------------------
             Argument | Type    |  Mode | Dimension
---------------------------------------------------
CALL GSTXFP  (FONT,   | Integer | Input |
              PREC)   | Integer | Input |
---------------------------------------------------

FONT: Specifies the text font to be used in subsequent calls to the GTX output primitive. Options are:

: The Hershey fonts are not standardized by GKS but are locally implemented in NCAR GKS. The Hershey font description files were originally written by A.V. Hershey in the late 1960s and are now made available from the National Institute of Standards and Technology (NIST). All of the Hershey fonts are stroked fonts, that is, the characters are defined by a sequence of line draws. GKS requires that locally implemented fonts be assigned negative font numbers.
When plotting to a PostScript workstation all GKS fonts are mapped onto an equivalent PostScript font if possible.

PREC: Gives an indication as to how faithfully text should be represented when it is plotted with GTX using the font specified by FONT. Options are:

0 - string precision (good)

1 - character precision (better)

2 - stroke precision (best)

Defaults:: FONT=1 and PREC=2 (All text output from NCAR GKS is at stroke precision.)
Errors:: 8, 75, 2000

As of release 3.2 of NCAR Graphics, eleven filled fonts were made available via the Plotchar package. PostScript source documentation for Plotchar is available. These fonts are not yet available via GSTXFP.

---------------------------------------------------------------------------
C Synopsis

#include <ncarg/gks.h>

void gset_text_font_prec(
        const Gtext_font_prec  *text_font_prec  /*  text font and prec  */
);
---------------------------------------------------------------------------

Figure 12 - same string, different font

Set Character Height

------------------------------------------------
            Argument | Type | Mode  |  Dimension
------------------------------------------------
CALL GSCHH  (CHH)    | Real | Input |
------------------------------------------------

CHH: Gives the height in world coordinates at which a character is drawn using the GTX output primitive. CHH must be > 0.
Default:: The default character height is 0.01
Errors:: 8, 78

----------------------------------------------------------------------
C Synopsis

#include <ncarg/gks.h>

void gset_char_ht(
                  Gdouble  char_ht  /*  character height  */
);
----------------------------------------------------------------------

See Figure 14 for an example of character heights and up vectors.

Set Character Spacing

-------------------------------------------------
             Argument | Type | Mode  |  Dimension
-------------------------------------------------
CALL GSCHSP  (CHSP)   | Real | Input |
-------------------------------------------------

CHSP: Specifies how much additional white space should be inserted between characters drawn using the GTX output primitive. CHSP is specified as a fraction of the character height.
A character spacing of zero concatenates character bodies contiguously. A positive value leaves space between the successive characters. A negative value causes successive characters to overlap.

Default:: The default character spacing is 0.0
Errors:: 8

-----------------------------------------------------------------------
C Synopsis

#include <ncarg/gks.h>

void gset_char_space(
                     Gdouble  char_space  /*  character spacing  */
);
-----------------------------------------------------------------------

Figure 13 - Character spacings and expansion factors

Set Character Up Vector

-------------------------------------------------
             Argument | Type | Mode  |  Dimension
-------------------------------------------------
CALL GSCHUP  (CHUX,   | Real | Input |
              CHUY)   | Real | Input |
-------------------------------------------------

CHUX: Gives the X (horizontal) world coordinate of a vector tip.
CHUY: Gives the Y (vertical) world coordinate of a vector tip. The vector tail is at (0,0). (CHUX, CHUY) cannot be (0,0).
The coordinate (CHUX, CHUY), relative to (0,0), establishes a vector direction which will be perpendicular to the horizontal centerline of the character string to be drawn. Thus, (CHUX, CHUY) equals (0., 1.) implies normal character positioning in which the character centerline is horizontal and the top of the character is up.

Defaults:: The default character up vector is (0.,1.)
Errors:: 8, 79

--------------------------------------------------------------------------
C Synopsis

#include <ncarg/gks.h>

void gset_char_up_vec(
                   const Gvec  *char_up_vec  /*  character up vector  */
);
--------------------------------------------------------------------------

Figure 14 - Character heights and up vectors

Set Character Expansion Factor

-------------------------------------------------
             Argument | Type | Mode  |  Dimension
-------------------------------------------------
CALL GSCHXP  (CHXP)   | Real | Input |
-------------------------------------------------

CHXP: Specifies a deviation of the width to height ratio for characters drawn using the GTX output primitive. CHXP of 10.0 would request a character that is 10 times as wide as normal. CHXP of 0.1 would request characters that are 1/10th as wide as normal. The character height remains unchanged. CHXP must be greater than 0.
Default:: The default character expansion factor is 1.0 .
Errors:: 8, 77

--------------------------------------------------------------------------
C Synopsis

#include <ncarg/gks.h>

void gset_char_expan(
                  Gdouble  char_expan  /*  character expansion factor  */
);
--------------------------------------------------------------------------

See Figure 13 for examples of character spacings and expansion factors.

Text Inquiry Functions

Get the Text Path

---------------------------------------------------
            Argument | Type    | Mode   | Dimension
---------------------------------------------------
CALL GQTXP  (ERRIND, | Integer | Output |
             TXP)    | Integer | Output |
---------------------------------------------------

ERRIND: Error flag. Gives an integer error number from the errors list in Appendix D, or a 0 if no error occurred.
TXP: Gives the text path as set by GSTXP.
Errors:: 8

--------------------------------------------------------------------------
C Synopsis

#include <ncarg/gks.h>

void ginq_text_path(
                    Gint        *err_ind,   /*  error indicator    */
                    Gtext_path  *text_path  /*  current text path  */
);
--------------------------------------------------------------------------

Get the Text Alignment

----------------------------------------------------
             Argument | Type    | Mode   | Dimension
----------------------------------------------------
CALL GQTXAL  (ERRIND, | Integer | Output |
              TXALH,  | Integer | Output |
              TXALV)  | Integer | Output |
----------------------------------------------------

ERRIND: Error flag. Gives an integer error number from the errors list in Appendix D, or a 0 if no error occurred.
TXALH: Gives the horizontal text alignment as set by GSTXAL.
TXALV: Gives the vertical text alignment as set by GSTXAL.
Errors:: 8

--------------------------------------------------------------------------
C Synopsis

#include <ncarg/gks.h>

void ginq_text_align(
                     Gint         *err_ind,    /*  error indicator  */
                     Gtext_align  *text_align  /*  text alignment   */
);
--------------------------------------------------------------------------

Get the Text Font and Precision

----------------------------------------------------
             Argument | Type    | Mode   | Dimension
----------------------------------------------------
CALL GQTXFP  (ERRIND, | Integer | Output |
              FONT,   | Integer | Output |
              PREC)   | Integer | Output |
----------------------------------------------------

ERRIND: Error flag. Gives an integer error number from the errors list in Appendix D, or a 0 if no error occurred.
FONT: Gives the type of font as set by GSTXFP.
PREC: Gives the text precision as set by GSTXFP.
Errors:: 8

--------------------------------------------------------------------------
C Synopsis

#include <ncarg/gks.h>

void ginq_text_font_prec(
                   Gint             *err_ind,   /*  error indicator     */
                   Gtext_font_prec  *font_prec  /*  font and precision  */
);
--------------------------------------------------------------------------

Get the Character Height

---------------------------------------------------
            Argument | Type    | Mode   | Dimension
---------------------------------------------------
CALL GQCHH  (ERRIND, | Integer | Output |
             CHH)    | Real    | Output |
---------------------------------------------------

ERRIND: Error flag. Gives an integer error number from the errors list in Appendix D, or a 0 if no error occurred.
CHH: Gives the character height as set by GSCHH.
Errors:: 8

---------------------------------------------------------------------
C Synopsis

#include <ncarg/gks.h>

void ginq_char_ht(
                  Gint     *err_ind,  /*  error indicator   */
                  Gdouble  *char_ht   /*  character height  */
);
---------------------------------------------------------------------

Get the Character Spacing

----------------------------------------------------
             Argument | Type    | Mode   | Dimension
----------------------------------------------------
CALL GQCHSP  (ERRIND, | Integer | Output |
              CHSP)   | Real    | Output |
----------------------------------------------------

ERRIND

------------------------------------------------------------------------
C Synopsis

#include <ncarg/gks.h>

void ginq_char_space(
                     Gint     *err_ind,    /*  error indicator    */
                     Gdouble  *char_space  /*  character spacing  */
);
------------------------------------------------------------------------

Get the Character Up Vector

----------------------------------------------------
             Argument | Type    | Mode   | Dimension
----------------------------------------------------
CALL GQCHUP  (ERRIND, | Integer | Output |
              CHUX,   | Real    | Output |
              CHUY)   | Real    | Output |
----------------------------------------------------

ERRIND: Error flag. Gives an integer error number from the errors list in Appendix D, or a 0 if no error occurred.
CHUX: Gives the X (horizontal) world coordinate of a vector tip.
CHUY: Gives the Y (vertical) world coordinate of a vector tip. The vector tail is at (0,0).
Errors:: 8

------------------------------------------------------------------------
C Synopsis

#include <ncarg/gks.h>

void ginq_char_up_vec(
                      Gint  *err_ind,     /*  error indicator      */
                      Gvec  *char_up_vec  /*  character up vector  */
);
------------------------------------------------------------------------

Get the Character Expansion Factor

----------------------------------------------------
             Argument | Type    | Mode   | Dimension
----------------------------------------------------
CALL GQCHXP  (ERRIND, | Integer | Output |
              CHXP)   | Real    | Output |
----------------------------------------------------

ERRIND: Error flag. Gives an integer error number from the errors list in Appendix D, or a 0 if no error occurred.
CHXP: Gives the width-to-height ratio of a character as set by GSCHXP.
Errors:: 8

-----------------------------------------------------------------------
C Synopsis

#include <ncarg/gks.h>

void ginq_char_expan(
                     Gint     *err_ind,    /*  error indicator   */
                     Gdouble  *char_expan  /*  expansion factor  */
);
-----------------------------------------------------------------------

Links: GKS Index, GKS Home