1PCHIQU(3NCARG) NCAR GRAPHICS PCHIQU(3NCARG)
2
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 PLCHHQ is an alternate name for the routine PCHIQU.
12
14 CALL PCHIQU (XPOS,YPOS,CHRS,SIZE,ANGD,CNTR)
15
17 #include <ncarg/ncargC.h>
18 void c_pchiqu (float xpos, float ypos, char *chrs,
20 float size, float angd, float cntr)
21
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 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 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 · 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 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 · 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 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 · 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 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 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 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 SIZE = DLOS / REAL(NCIS)
103 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 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 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 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 CNTR (an input expression of type REAL) is the centering option.
147 If the internal parameter ´CE´ is zero (the default), then
148 · 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 · 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 · 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 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 Upon return from PCHIQU, all arguments are unchanged.
179
181 The C-binding argument descriptions are the same as the FORTRAN
182 argument descriptions.
183
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 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 F Switch to using the database specified by the value of
205 ´FN´.
206 F0 Switch to using the PWRITX database.
208 Fn Switch to using fontcap-defined font "n".
210 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 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 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 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 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 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 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 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 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 A Switch to writing "across" the frame, in the direction
255 ANGD. This is the normal mode.
256 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 B Switch to subscript level.
262 Bn For the next "n" characters, use subscript level and then
264 revert to normal level.
265 S Switch to superscript level.
267 Sn For the next "n" characters, use superscript level and then
269 revert to normal level.
270 E Switch to normal level in such a way as to allow for
272 another sub- or superscript on the base character.
273 N Switch to normal level in such a way as not to allow for
275 another sub- or superscript on the base character.
276 Hn Offset by "n" digitization units in the direction ANGD.
278 HnQ Offset by "n" blank widths in the direction ANGD.
280 Vn Offset by "n" digitization units in the direction ANGD+90.
282 VnQ Offset by "n" blank heights in the direction ANGD+90.
284 C Do a "carriage return".
286 Xn or XnQ Zoom character width to "n" percent of normal.
288 Yn Zoom character height to "n" percent of normal.
290 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 Zn Same as "XnYn".
296 ZnQ Same as "XnQYnQ".
298 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
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.
313
315 To use PCHIQU or c_pchiqu, load the NCAR Graphics libraries ncarg,
316 ncarg_gks, and ncarg_c, preferably in that order.
317
319 Online: plotchar, pcdlsc, pcgetc, pcgeti, pcgetr, pcloqu, pcmequ,
320 pcmpxy, pcpnwi, pcrset, pcsetc, pcseti, pcsetr, ncarg_cbind.
321 Hardcopy: NCAR Graphics Fundamentals, UNIX Version
323
325 Copyright (C) 1987-2007
326 University Corporation for Atmospheric Research
327 This documentation is free software; you can redistribute it and/or
329 modify it under the terms of the GNU General Public License as
330 published by the Free Software Foundation; either version 2 of the
331 License, or (at your option) any later version.
332 This software is distributed in the hope that it will be useful, but
334 WITHOUT ANY WARRANTY; without even the implied warranty of
335 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
336 General Public License for more details.
337 You should have received a copy of the GNU General Public License along
339 with this software; if not, write to the Free Software Foundation,
340 Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
341UNIX March 1993 PCHIQU(3NCARG)