1PCHIQU(3NCARG)                   NCAR GRAPHICS                  PCHIQU(3NCARG)
2
3
4

NAME

6       PCHIQU - Draws high quality characters. By default, it uses the same
7       database as the old NCAR Graphics routine PWRITX, but it can also use
8       characters from any of the fontcap-defined databases, it has an
9       improved interface, and it has many more capabilities than PWRITX.
10
11       PLCHHQ is an alternate name for the routine PCHIQU.
12

SYNOPSIS

14       CALL PCHIQU (XPOS,YPOS,CHRS,SIZE,ANGD,CNTR)
15

C-BINDING SYNOPSIS

17       #include <ncarg/ncargC.h>
18
19       void c_pchiqu (float xpos, float ypos, char *chrs,
20       float size, float angd, float cntr)
21

DESCRIPTION

23       XPOS,YPOS   (input expressions of type REAL) specify positioning
24                   coordinates for the characters to be drawn. If the internal
25                   parameter ´MA´ has the value 0, these are given in the
26                   current user coordinate system; otherwise, they are given
27                   in an arbitrary X/Y coordinate system, as implied by the
28                   value of ´MA´ and the nature of the routine CPMPXY. (For
29                   example, if ´MA´ has the value 1 and the default version of
30                   CPMPXY is being used, then XPOS is a longitude, in degrees,
31                   and YPOS is a latitude, in degrees.)  The argument CNTR
32                   (described below) specifies how the characters are to be
33                   positioned relative to the point (XPOS,YPOS).
34
35       CHRS        (an input constant or variable of type CHARACTER) specifies
36                   the characters to be drawn.  The number of characters in
37                   CHRS is taken to be LEN(CHRS); to use characters "m"
38                   through "n" from a character variable CHRV, use the
39                   FORTRAN-77 substring notation "CHRV(m:n)". CHRS may contain
40                   characters to be drawn and "function codes", which are used
41                   for various purposes.  The possible function codes are
42                   completely described in the programmer document for
43                   Plotchar and are summarized in a later section of this man
44                   page.
45
46       SIZE        (an input expression of type REAL) specifies the desired
47                   character size. If the internal parameter ´MA´ is zero,
48                   then the following comments apply:
49
50                   ·      If SIZE is less than or equal to zero, its absolute
51                          value specifies the size as a multiple of the
52                          digitized size. On a 1024x1024 grid, principal-size
53                          capitals are about ´PW´ units wide by ´PH´ units
54                          high and the vertical spacing between lines is ´PV´
55                          units (by default, ´PW´, ´PH´, and ´PV´ are 16, 21,
56                          and 32). Indexical-size capitals are ´IW´ units wide
57                          by ´IH´ units high and the vertical spacing between
58                          lines is ´IV´ units (by default, ´IW´, ´IH´, and
59                          ´IV´ are 12, 13, and 20). Cartographic-size capitals
60                          are ´CW´ units wide by ´CH´ units high and the
61                          vertical spacing between lines is ´CV´ units (by
62                          default, ´CW´, ´CH´, and ´CV´ are 8, 9, and 14).
63
64                          Example: Using CHRS = ´ABC´ and SIZE = -2. will
65                          write three characters, each of which is about
66                          32/1024 of the plotter frame in width.
67
68                   ·      If SIZE is greater than zero, but less than one, it
69                          specifies the desired approximate width of a
70                          principal-size capital as a fraction of the distance
71                          across the plotter frame. This is the recommended
72                          scheme.
73
74                          Example: Using CHRS = ´ABC´ and SIZE = .05 will
75                          write three characters, each of which is about 5
76                          hundredths of the plotter frame in width.
77
78                   ·      If SIZE is greater than or equal to one, it
79                          specifies the desired approximate width of a
80                          principal-size capital in plotter coordinates, as
81                          defined by default or by a user call to the SPPS
82                          routine SETI. Note that use of the routine SETI is
83                          now discouraged.
84
85                          Example: Using CHRS = ´ABC´ and SIZE = 13. (assuming
86                          there have been no calls to the SPPS routine SETI)
87                          will write three characters, each of which is about
88                          13/1024 of the plotter frame in width.
89
90                   If ´MA´ is nonzero, then SIZE is the desired approximate
91                   width of a principal-size capital as a value in the X/Y
92                   coordinate system in which XPOS and YPOS are given.
93
94                   In most of the databases used by PCHIQU, the character
95                   width varies from character to character. Most principal-
96                   size capitals will be a little wider than the value
97                   specified by SIZE (and a few will be narrower). Thus, a
98                   little experimenting may be necessary to get just the size
99                   one wants. A rule of thumb that works pretty well when
100                   using all capitals is as follows:
101
102                        SIZE = DLOS / REAL(NCIS)
103
104                   where "DLOS" is the desired length of the string, in the
105                   fractional system, and "NCIS" is the number of characters
106                   in the string.
107
108                   Note: As of version 3.2 of NCAR Graphics, the size of all
109                   characters written by PCHIQU has been reduced by a
110                   multiplicative factor (the internal parameter ´SA´) whose
111                   default value is .88888888... The object of this is to make
112                   the size of characters written by PCHIQU consistent with
113                   the size of characters written by PCMEQU and PCLOQU. If the
114                   value of ´SA´ is not changed, then the height of principal-
115                   size capitals written by PCHIQU and PCMEQU will be 7/6
116                   times the value specified by SIZE. Thus, if the desired
117                   character height (CHRH) is known, use "SIZE = 6.*CHRH/7." .
118
119                   The values of the internal parameters ´PW´, ´PH´, ´PV´,
120                   ´IW´, ´IH´, ´IV´, ´CW´, ´CH´, and ´CV´ (as well as two
121                   others, ´PS´ and ´IS´) may be changed by user calls to
122                   CPSETR. This can be used to change the effective size and
123                   shape of digitized characters in the PWRITX database (the
124                   effect is the same as if the characters had been digitized
125                   differently at the outset). If, for example, one were to
126                   double the value of ´PH´, it would make the principal
127                   characters twice as tall as they are by default. (In this
128                   case, one would probably also want to double the value of
129                   ´PV´, so as to make the vertical spacing between lines
130                   consistent with the character height.) Note that, if one
131                   changes the value of ´PW´, ´IW´, or ´CW´, the meaning of a
132                   negative value of the argument SIZE may thereby be changed.
133
134       ANGD        (an input expression of type REAL) is the angle, in degrees
135                   counterclockwise from the positive X axis, at which the
136                   character string is to be written. If the internal
137                   parameter ´TE´ is nonzero (by default, it is zero) and if
138                   ANGD is exactly 360., then no characters are drawn by
139                   PCHIQU; it just computes the distances, in the fractional
140                   coordinate system, from the point (XPOS,YPOS) to the left
141                   edge, the right edge, the bottom edge, and the top edge of
142                   a box enclosing the string. These are stored as the values
143                   of the parameters ´DL´, ´DR´, ´DB´, and ´DT´ and may be
144                   retrieved by calls to PCGETR.
145
146       CNTR        (an input expression of type REAL) is the centering option.
147                   If the internal parameter ´CE´ is zero (the default), then
148
149                   ·      CNTR = -1. means that (XPOS,YPOS) is the center of
150                          the left edge of the first character (if that
151                          character is to be written "across" the frame) or
152                          the center of the top edge of the first character
153                          (if that character is to be written "down" the
154                          frame).
155
156                   ·      CNTR = 1. means that (XPOS,YPOS) is the center of
157                          the right edge of the last character (if the writing
158                          direction at the end of the character string is
159                          "across" the frame) or the center of the bottom edge
160                          of the last character (if the writing direction at
161                          the end of the character string is "down" the
162                          frame).
163
164                   ·      CNTR = s, where "s" is any real number, means that
165                          (XPOS,YPOS) is a point obtained by linear
166                          interpolation along the line joining the two points
167                          mentioned above (the first point being associated
168                          with the value -1. and the second with the value
169                          +1.). The value "0." gives the midpoint of the line.
170
171                   If ´CE´ is nonzero, then the value of CNTR is ignored.
172                   Text-extent quantities are computed and used to exactly
173                   center the output on the point (XPOS,YPOS). This is useful,
174                   among other things, for labeling each of a number of points
175                   with a single character; however, it works as desired only
176                   when ´QU´ is zero.
177
178                   Upon return from PCHIQU, all arguments are unchanged.
179

C-BINDING DESCRIPTION

181       The C-binding argument descriptions are the same as the FORTRAN
182       argument descriptions.
183

FUNCTION CODES

185       The function codes that may be used for various purposes in the input
186       character string CHRS are described completely in the programmer
187       document for Plotchar.  The material that follows will principally be
188       of use as a memory aid to someone who is already familiar with the use
189       of function codes.
190
191       As the characters of CHRS are scanned from left to right, the scanner
192       is always in one of two states: either it is looking for characters to
193       be drawn or it is looking for characters to be interpreted as function
194       codes.  Each occurrence of the function-code signal character (defined
195       by the internal parameter ´FC´ - a colon by default) flips the state of
196       the scanner.  Thus, in the character string ´ABC:L:DEF´, "A", "B", and
197       "C" will be treated as characters to be drawn, "L" will be treated as a
198       function code, and "D", "E", and "F" will be treated as characters to
199       be drawn.  (In this particular example, since the function code "L"
200       requests lower case, what would be drawn is "ABCdef".)  Occasionally,
201       function codes may need to be separated by commas or blanks; this is
202       necessary only when there would otherwise be a syntactical problem.
203
204       F           Switch to using the database specified by the value of
205                   ´FN´.
206
207       F0          Switch to using the PWRITX database.
208
209       Fn          Switch to using fontcap-defined font "n".
210
211       R           Switch to the "Roman" part of the PWRITX database.  If
212                   characters are currently being used from a fontcap-defined
213                   font, this function code will have no effect.
214
215       G           Switch to the "Greek" part of the PWRITX database.  If
216                   characters are currently being used from a fontcap-defined
217                   font, this function code will have no effect.
218
219       P           Use characters of principal size from the PWRITX database.
220                   If characters are currently being used from a fontcap-
221                   defined font, there will be an appropriate shift in size.
222
223       I           Use characters of indexical size from the PWRITX database.
224                   If characters are currently being used from a fontcap-
225                   defined font, there will be an appropriate shift in size.
226
227       K           Use characters of cartographic size from the PWRITX
228                   database.  If characters are currently being used from a
229                   fontcap-defined font, there will be an appropriate shift in
230                   size.
231
232       U           Switch to using upper case letters from the PWRITX
233                   database.  If characters are currently being used from a
234                   fontcap-defined font, this function code will have no
235                   effect.
236
237       Un          For the next "n" characters, switch to using upper case
238                   letters from the PWRITX database and then switch to lower
239                   case.  If characters are currently being used from a
240                   fontcap-defined font, this function code will have no
241                   effect.
242
243       L           Switch to using lower case letters from the PWRITX
244                   database.  If characters are currently being used from a
245                   fontcap-defined font, this function code will force the use
246                   of lower case letters from it.
247
248       Ln          For the next "n" characters, switch to using lower case
249                   letters from the PWRITX database and then switch to upper
250                   case.  If characters are currently being used from a
251                   fontcap-defined font, this function code will force the use
252                   of lower case letters from it.
253
254       A           Switch to writing "across" the frame, in the direction
255                   ANGD.  This is the normal mode.
256
257       D           Switch to writing "down" the frame, in the direction
258                   ANGD-90.  This causes each character to be written beneath
259                   the previous one.
260
261       B           Switch to subscript level.
262
263       Bn          For the next "n" characters, use subscript level and then
264                   revert to normal level.
265
266       S           Switch to superscript level.
267
268       Sn          For the next "n" characters, use superscript level and then
269                   revert to normal level.
270
271       E           Switch to normal level in such a way as to allow for
272                   another sub- or superscript on the base character.
273
274       N           Switch to normal level in such a way as not to allow for
275                   another sub- or superscript on the base character.
276
277       Hn          Offset by "n" digitization units in the direction ANGD.
278
279       HnQ         Offset by "n" blank widths in the direction ANGD.
280
281       Vn          Offset by "n" digitization units in the direction ANGD+90.
282
283       VnQ         Offset by "n" blank heights in the direction ANGD+90.
284
285       C           Do a "carriage return".
286
287       Xn or XnQ   Zoom character width to "n" percent of normal.
288
289       Yn          Zoom character height to "n" percent of normal.
290
291       YnQ         Zoom character height to "n" percent of normal and
292                   introduce a shift in the direction ANGD+90 sufficient to
293                   keep the bases of characters properly aligned.
294
295       Zn          Same as "XnYn".
296
297       ZnQ         Same as "XnQYnQ".
298
299       nnnn        An octal number may be used as a function code to select a
300                   particular character from the PWRITX database.  The octal
301                   number for a given character is the sum of a font index (0
302                   for Roman or 600 for Greek), a size index (0 for Principal,
303                   200 for Indexical, or 400 for Cartographic), a case index
304                   (0 for Upper or 100 for Lower), and the octal equivalent of
305                   a character index (1-32 for A through Z, 33-44 for 0
306                   through 9, or 45-57 for the individual characters, +, -, *,
307                   /, (, ), $, =, blank, comma, or period).
308

EXAMPLES

310       Use the ncargex command to see the following relevant examples: cmpit,
311       cmpita, cmptit, cpexcc, elblba, cbex01, coex01, coex02, coex03, cpex10,
312       epltch, sfex02, srex01, tpltch, fcoord1, fcoord2.
313

ACCESS

315       To use PCHIQU or c_pchiqu, load the NCAR Graphics libraries ncarg,
316       ncarg_gks, and ncarg_c, preferably in that order.
317

SEE ALSO

319       Online: plotchar, pcdlsc, pcgetc, pcgeti, pcgetr, pcloqu, pcmequ,
320       pcmpxy, pcpnwi, pcrset, pcsetc, pcseti, pcsetr, ncarg_cbind.
321
322       Hardcopy: NCAR Graphics Contouring and Mapping Tutorial; NCAR Graphics
323       Fundamentals, UNIX Version
324
326       Copyright (C) 1987-2009
327       University Corporation for Atmospheric Research
328       The use of this Software is governed by a License Agreement.
329
330
331
332UNIX                              March 1993                    PCHIQU(3NCARG)
Impressum