| 1 |
<?xml version="1.0" encoding="UTF-8"?> |
| 2 |
<!-- |
| 3 |
(C) Copyright 1996-2016 ECMWF. |
| 4 |
|
| 5 |
This software is licensed under the terms of the Apache Licence Version 2.0 |
| 6 |
which can be obtained at http://www.apache.org/licenses/LICENSE-2.0. |
| 7 |
In applying this licence, ECMWF does not waive the privileges and immunities |
| 8 |
granted to it by virtue of its status as an intergovernmental organisation nor |
| 9 |
does it submit to any jurisdiction. |
| 10 |
--> |
| 11 |
|
| 12 |
<chapter id="Text_Plotting" label="12"> |
| 13 |
<title>Text Plotting</title> |
| 14 |
|
| 15 |
<xi:include href="../phrases/chapterinfo_mod.xml" |
| 16 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 17 |
|
| 18 |
<section id="Text_Introduction"> |
| 19 |
<title>Introduction</title> |
| 20 |
|
| 21 |
<para><productname>Magics</productname> text plotting offers to write custom strings in a text box.</para> |
| 22 |
|
| 23 |
<para>Each line of text consists of one character string. This can be made |
| 24 |
up of standard ASCII characters including special instruction strings |
| 25 |
for inline formatting of the text. New to <productname>Magics++</productname> |
| 26 |
is HTML text,<!--cross-ref--> enabling a higher degree of formatting control using |
| 27 |
a familiar syntax. Users may plot any number of lines in a single text block if |
| 28 |
passed as an array, or up to 10 text lines if passed individually. Each block |
| 29 |
of text is plotted with a call to the action routine <function>PTEXT</function>.</para> |
| 30 |
|
| 31 |
|
| 32 |
<!-- |
| 33 |
<para>A line of text consists of one character string, which may be made |
| 34 |
up of standard ASCII characters as well as Magics parameters. Magics text |
| 35 |
parameters exist to enable users to plot integer, real and character |
| 36 |
variables. Instruction strings may also be included in a text line. Users |
| 37 |
may plot up to 10 text lines in a single text block.</para> |
| 38 |
--> |
| 39 |
|
| 40 |
|
| 41 |
<para>The text block is always plotted in a text box, the position and |
| 42 |
dimensions of which may be defined by the user or automatically calculated |
| 43 |
by <productname>Magics</productname>.</para> |
| 44 |
|
| 45 |
<section id="HtmlStyle"> |
| 46 |
<title>Using Html-like styles in texts</title> |
| 47 |
<para> |
| 48 |
In <productname>Magics++</productname> users can use the HTML-like syntax to style text. |
| 49 |
In HTML syntax the user can write |
| 50 |
<programlisting>CALL <function>PSETC</function>("text_user_line_1", ”<font colour='red'> red text </font> <font colour='red'> and now blue</font>”)</programlisting> |
| 51 |
</para> |
| 52 |
|
| 53 |
<important id="pgf90"> <title>Pgf90 - Escaping of special characters</title> |
| 54 |
Some Fortran compilers, such as <productname>Pgf90</productname> require the high commas in the text strings to be escaped. This can be done |
| 55 |
by typing a font definition as <font colour=\'red\'> red text </font>. Note the backslashes used to escape the high comma. This behaviour can be |
| 56 |
deactivated by using the compiler option <function>-Mnobackslash</function> when compiling with Pgf90. </important> |
| 57 |
</section> |
| 58 |
|
| 59 |
<section id="Unicode"> |
| 60 |
<title>Unicode</title> |
| 61 |
<para> |
| 62 |
<productname>Magics++</productname> has support for Unicode if written |
| 63 |
directly as input for parameters or through the HTML syntax. In HTML syntax |
| 64 |
the user can write <code>&auml;</code> to get an <code>ä</code>. |
| 65 |
<programlisting> |
| 66 |
CALL <function>PSETC</function> ('<parameter>TEXT_HTML</parameter>','ON')</programlisting> |
| 67 |
</para> |
| 68 |
</section> |
| 69 |
|
| 70 |
<section id="GribKeys"> |
| 71 |
<title>GRIB keys in titles</title> |
| 72 |
<para> |
| 73 |
<productname>Magics++</productname> allows users to insert information from a GRIB headers through the HTML syntax. |
| 74 |
In HTML syntax the user can write |
| 75 |
<programlisting>CALL <function>PSETC</function>("text_user_line_1", ”<grib_info key=‘name’ /> at <grib_info key=‘level’ />hPa”)</programlisting> |
| 76 |
</para> |
| 77 |
</section> |
| 78 |
|
| 79 |
|
| 80 |
</section> |
| 81 |
|
| 82 |
<section id="Text_Modes"> |
| 83 |
<title>Text Modes</title> |
| 84 |
|
| 85 |
<para>All text plotting in Magics is achieved by calling action routine |
| 86 |
<function>PTEXT</function>, which has no arguments. |
| 87 |
Text parameters exist to control all aspects of text plotting and any text |
| 88 |
parameters required should be set before <function> |
| 89 |
<function>PTEXT</function> </function> is called.</para> |
| 90 |
|
| 91 |
<para>Action routine <function>PTEXT</function> works in two modes, |
| 92 |
'<code>TITLE</code>' and '<code>POSITIONAL</code>', the default being |
| 93 |
'<code>TITLE</code>'.</para> |
| 94 |
|
| 95 |
<para>To change the text mode, users should set the parameter |
| 96 |
<parameter>TEXT_MODE</parameter>, e.g.</para> |
| 97 |
|
| 98 |
<programlisting> |
| 99 |
CALL <function>PSETC</function> ('<parameter>TEXT_MODE</parameter>','POSITIONAL')</programlisting> |
| 100 |
|
| 101 |
<para>In '<code>TITLE</code>' mode, which is the default, the user's text |
| 102 |
will be automatically positioned above the current subpage. The height and |
| 103 |
width of the text box are calculated automatically by Magics.</para> |
| 104 |
|
| 105 |
<!-- |
| 106 |
<?pagebreak?><figure id="figure_basic_text_parameters"> |
| 107 |
<title>Basic Text Parameters</title> |
| 108 |
|
| 109 |
<mediaobject> |
| 110 |
<imageobject> |
| 111 |
<imagedata fileref="diagrams/epsi/text-d01.epsi" /> |
| 112 |
</imageobject> |
| 113 |
</mediaobject> |
| 114 |
</figure><?pagebreak?> |
| 115 |
|
| 116 |
<highlights> |
| 117 |
<important> <title>Magics++</title> |
| 118 |
<para>DIAGRAM 1 HERE</para> |
| 119 |
</important> |
| 120 |
</highlights> |
| 121 |
--> |
| 122 |
|
| 123 |
<para>The height of the text box is approximately the distance from the |
| 124 |
top of the current subpage to the top of the page.</para> |
| 125 |
|
| 126 |
<para>There will be a small gap between the subpage and the text box to |
| 127 |
allow for grid labels and a small gap between the top of the text box and |
| 128 |
the top of the page. The width of the box is the |
| 129 |
<parameter>SUBPAGE_X_LENGTH</parameter>.</para> |
| 130 |
|
| 131 |
<!-- reduction mode to be described here once it has been implemented --> |
| 132 |
|
| 133 |
<para>In '<code>POSITIONAL</code>' mode, the user |
| 134 |
can place text anywhere within the current page. They may define the |
| 135 |
position of the text box as well as the height and width.</para> |
| 136 |
|
| 137 |
|
| 138 |
<important id="Text_No_Automatic_Adjustments"> <title>Magics++</title> |
| 139 |
<productname>Magics++</productname> performs no automatic adjustments on |
| 140 |
the positions or dimensions of text boxes which are partially or completely |
| 141 |
outside of the page. This behaviour differs from previous versions.</important> |
| 142 |
|
| 143 |
<para>The default position of the text box in '<code>POSITIONAL</code>' |
| 144 |
mode is the lower left corner of the current subpage. The Magics |
| 145 |
parameters <parameter>TEXT_BOX_X_POSITION</parameter> and |
| 146 |
<parameter>TEXT_BOX_Y_POSITION</parameter> may be used to set the position |
| 147 |
of the text box, if the default values are not suitable. The positions are |
| 148 |
relative to the <parameter>PAGE_X_POSITION</parameter> and |
| 149 |
<parameter>PAGE_Y_POSITION</parameter> respectively. The default height of the |
| 150 |
box will be 20% of the <parameter>SUBPAGE_Y_LENGTH</parameter> and the default |
| 151 |
width will be 50% of the <parameter>SUBPAGE_X_LENGTH</parameter>.</para> |
| 152 |
|
| 153 |
</section> |
| 154 |
|
| 155 |
|
| 156 |
<section id="Creating_Text"> <!-- ~~~~~~~~~~~~~~ Creating_Text ~~~~~~~~~~~~~~ --> |
| 157 |
<title>Creating Text</title> |
| 158 |
|
| 159 |
<important> <title>Magics++</title> |
| 160 |
<productname>Magics++</productname> allows any number of lines in a text block using |
| 161 |
the new interface in which an array of strings is passed. The old interface |
| 162 |
still exists, allowing up to 10 text lines to be passed individually.</important> |
| 163 |
|
| 164 |
|
| 165 |
<section id="Array_Text_Blocks"> |
| 166 |
<title>Array Text Blocks</title> |
| 167 |
<para> |
| 168 |
Lines of text can be created by passing an array of text strings to <productname>Magics</productname>: |
| 169 |
</para> |
| 170 |
|
| 171 |
<programlisting> |
| 172 |
PARAMETER (NLINES=5) |
| 173 |
CHARACTER*16 LINES |
| 174 |
DIMENSION LINES (NLINES) |
| 175 |
DATA LINES /'This is a', |
| 176 |
x 'text block', |
| 177 |
x 'passed', |
| 178 |
x 'by', |
| 179 |
x 'array'/ |
| 180 |
|
| 181 |
[...] |
| 182 |
|
| 183 |
CALL <function>PSET1C</function> ('<parameter>TEXT_LINES</parameter>', LINES, NLINES) |
| 184 |
</programlisting> |
| 185 |
|
| 186 |
</section> |
| 187 |
|
| 188 |
<section id="Individual_Text_Blocks"> |
| 189 |
<title>Individual Text Blocks</title> |
| 190 |
<para>For convenience, and compatibility with previous versions of <productname>Magics</productname>, |
| 191 |
it is possible to individually set lines 1 to 10 by setting parameters <parameter>TEXT_LINE_1</parameter> |
| 192 |
to <parameter>TEXT_LINE_10</parameter> with <function>PSETC</function>, for example:</para> |
| 193 |
|
| 194 |
<programlisting> |
| 195 |
CALL <function>PSETC</function> ('<parameter>TEXT_LINE_1</parameter>', 'THIS IS A TEXT EXAMPLE')</programlisting> |
| 196 |
|
| 197 |
|
| 198 |
<para>When passing the lines of text individually, the number of text lines to be plotted |
| 199 |
should be indicated to <productname>Magics</productname> |
| 200 |
by setting the parameter <parameter>TEXT_LINE_COUNT</parameter>, |
| 201 |
e.g.</para> |
| 202 |
|
| 203 |
<programlisting> |
| 204 |
CALL <function>PSETI</function> ('<parameter>TEXT_LINE_COUNT</parameter>', 4)</programlisting> |
| 205 |
|
| 206 |
<para>It is possible to start plotting text from any line in the text |
| 207 |
block by setting the parameter <parameter>TEXT_FIRST_LINE</parameter> to |
| 208 |
the number of the line required. Magics will start plotting from this line |
| 209 |
and will plot the subsequent lines in the block if more than one line of |
| 210 |
text is to be plotted. For example, if 3 lines of text are required |
| 211 |
starting at line 5 in the text block, the user should set |
| 212 |
<parameter>TEXT_FIRST_LINE</parameter> to 5 and |
| 213 |
<parameter>TEXT_LINE_COUNT</parameter> to 3.</para> |
| 214 |
|
| 215 |
</section> |
| 216 |
|
| 217 |
|
| 218 |
|
| 219 |
</section> <!-- Creating_Text --> |
| 220 |
|
| 221 |
|
| 222 |
<!-- |
| 223 |
<section id="Text_Special_Characters"> |
| 224 |
<title>Text Special Characters</title> |
| 225 |
|
| 226 |
<para>Magics has facilities which enable users to plot text inside a text |
| 227 |
block with varying attributes such as colour, upper and lower case |
| 228 |
characters and different character sets. This is achieved by use of |
| 229 |
special characters and instruction strings and the following sections |
| 230 |
explain these facilities and the special characters involved.</para> |
| 231 |
|
| 232 |
<para>The following is the order of precedence of special characters used |
| 233 |
in interpolating text instruction strings.</para> |
| 234 |
|
| 235 |
<orderedlist> |
| 236 |
<listitem> |
| 237 |
<para>The quote character (<code>'</code>)</para> |
| 238 |
</listitem> |
| 239 |
|
| 240 |
<listitem> |
| 241 |
<para><parameter>TEXT_ESCAPE_CHARACTER</parameter> |
| 242 |
(<code>#</code>)</para> |
| 243 |
</listitem> |
| 244 |
|
| 245 |
<listitem> |
| 246 |
<para><parameter>TEXT_PARAMETER_ESCAPE_CHARACTER</parameter> |
| 247 |
(<code>@</code>)</para> |
| 248 |
</listitem> |
| 249 |
|
| 250 |
<listitem> |
| 251 |
<para><parameter>TEXT_INSTRUCTION_SHIFT_CHARACTER</parameter> |
| 252 |
(<code>/</code>)</para> |
| 253 |
</listitem> |
| 254 |
</orderedlist> |
| 255 |
|
| 256 |
<para>Detailed explanations of the special characters can be found in the |
| 257 |
following sections.</para> |
| 258 |
</section> |
| 259 |
|
| 260 |
<section id="Text_Manipulation"> |
| 261 |
<title>Text Manipulation</title> |
| 262 |
|
| 263 |
<para>Magics parameter values may be included in a text line using the |
| 264 |
text parameter escape character (<code>@</code>), i.e.</para> |
| 265 |
|
| 266 |
<programlisting> |
| 267 |
CALL PSETC ('TEXT_LINE_3', 'MAP SCALE=@SUBPAGE_MAP_SCALE@')</programlisting> |
| 268 |
|
| 269 |
<para>In this case, the current value in the parameter |
| 270 |
<parameter>SUBPAGE_MAP_SCALE</parameter>, e.g. <code>0.5E8</code>, will be |
| 271 |
plotted in the text line. Facilities also exist to enable users to store |
| 272 |
their own integer, real and character values within Magics parameters. Up |
| 273 |
to 10 parameters exist for each type.</para> |
| 274 |
|
| 275 |
<programlisting> |
| 276 |
TEXT_INTEGER_1, TEXT_INTEGER_2, ......... TEXT_INTEGER_10 |
| 277 |
TEXT_REAL_1, TEXT_REAL_2, ............... TEXT_REAL_10 |
| 278 |
TEXT_CHARACTER_1, TEXT_CHARACTER_2, ..... TEXT_CHARACTER_10</programlisting> |
| 279 |
|
| 280 |
<para>These parameters may be included in a user's text line by using the |
| 281 |
text parameter escape character (@), i.e.</para> |
| 282 |
|
| 283 |
<programlisting> |
| 284 |
CALL PSETC ('TEXT_LINE_1', 'RESOLUTION =@TEXT_REAL_3@') |
| 285 |
CALL PSETC ('TEXT_LINE_2', 'INTERVAL=@TEXT_INTEGER_1@')</programlisting> |
| 286 |
|
| 287 |
<para></para> |
| 288 |
|
| 289 |
<highlights> |
| 290 |
<important> |
| 291 |
<para>DIAGRAM 3 HERE</para> |
| 292 |
</important> |
| 293 |
</highlights> |
| 294 |
|
| 295 |
<para>Users can specify the format for integer and real variables in which |
| 296 |
they wish the values to be plotted by including the required format before |
| 297 |
the Magics parameter.</para> |
| 298 |
|
| 299 |
<programlisting> |
| 300 |
CALL PSETC ('TEXT_LINE_1','RESOLUTION=@(F8.3)TEXT_REAL_3@') |
| 301 |
CALL PSETC ('TEXT_LINE_2','INTERVAL=@(I5)TEXT_INTEGER_1@')</programlisting> |
| 302 |
|
| 303 |
<para>See Chapter XVII- Appendix for full details of Magics formats. In |
| 304 |
the above examples, the user should have stored the correct values before |
| 305 |
calling action routine <function>PTEXT</function>, e.g.</para> |
| 306 |
|
| 307 |
<programlisting> |
| 308 |
CALL PSETR ('TEXT_REAL_3', 1.875) |
| 309 |
CALL PSETI ('TEXT_INTEGER_1', 5)</programlisting> |
| 310 |
|
| 311 |
<para>The following is an example of the Magics calls to set up and plot a |
| 312 |
text block, using the default value for mode, character height and line |
| 313 |
spacing.</para> |
| 314 |
|
| 315 |
<programlisting> |
| 316 |
CALL PSETR ('TEXT_REAL_1', 1.875) |
| 317 |
CALL PSETI ('TEXT_INTEGER_1', 5) |
| 318 |
CALL PSETC ('TEXT_LINE_1', 'RESOLUTION =@(F8.3)TEXT_REAL_1@') |
| 319 |
CALL PSETC ('TEXT_LINE_2', 'CONTOUR INTERVAL = @(I3)TEXT_INTEGER_1@') |
| 320 |
CALL PSETC ('TEXT_LINE_3', 'MAP SCALE = @(F10.1)SUBPAGE_MAP_SCALE@') |
| 321 |
CALL PSETI ('TEXT_LINE_COUNT', 3) |
| 322 |
CALL PTEXT</programlisting> |
| 323 |
|
| 324 |
<para>This sequence of calls would result in a text block of three lines |
| 325 |
being plotted on top of the current subpage. Note the spacing in the text |
| 326 |
plotted due to the format requirements in the above calls.</para> |
| 327 |
|
| 328 |
<programlisting> |
| 329 |
RESOLUTION = 1.875 |
| 330 |
CONTOUR INTERVAL = 5 |
| 331 |
MAP SCALE = 50000000.0</programlisting> |
| 332 |
|
| 333 |
<para>Magics performs any type conversion necessary for plotting. The user |
| 334 |
may change the text parameter escape character, if required, by setting |
| 335 |
the Magics parameter |
| 336 |
<parameter>TEXT_PARAMETER_ESCAPE_CHARACTER</parameter> to the required |
| 337 |
value, e.g.</para> |
| 338 |
|
| 339 |
<programlisting> |
| 340 |
CALL PSETC ('TEXT_PARAMETER_ESCAPE_CHARACTER', '%')</programlisting> |
| 341 |
|
| 342 |
<para>The <parameter>TEXT_ESCAPE_CHARACTER</parameter> (<code>#</code>) |
| 343 |
allows the user to display special symbols and various national |
| 344 |
characters. The encoding tables (see Figure XIV-1 to Figure XIV-3) show |
| 345 |
the complete set of characters available in the three supported fonts, |
| 346 |
Times-Roman, Helvetica and Helvetica-Bold.</para> |
| 347 |
|
| 348 |
<remark>A character can be plotted either by using the character itself or |
| 349 |
by using a corresponding character from one of the encoding tables. To |
| 350 |
substitute a character from the encoding tables, the |
| 351 |
<parameter>TEXT_ESCAPE_CHARACTER</parameter> (<code>#</code>) should be |
| 352 |
typed followed by exactly 3 octal numbers which refer to one of the font |
| 353 |
encoding tables (Figure XIV-1 to Figure XIV-3). The relevant table can be |
| 354 |
chosen by the FN instruction string command (e.g. FN2 selects Encoding |
| 355 |
Table 2 - see the section "Instruction Strings" on page XIV-13). As an |
| 356 |
example, the text ABC is displayed by all these strings: 'ABC' |
| 357 |
'#101#102#103" 'A#102C' As another example, the following text 'L#346ngde |
| 358 |
Grad 20#260 #330st' prints Danish for 'Longitude 20 degrees east' using |
| 359 |
Danish letters and the degree symbol. The result is: Længde Grad 20o Øst |
| 360 |
In the above two examples, the default font, Encoding Table 1 |
| 361 |
(Times-Roman), is used.</remark> |
| 362 |
|
| 363 |
--> |
| 364 |
|
| 365 |
<section id="Text_Plotting_Section"> |
| 366 |
<title>Text Plotting</title> |
| 367 |
|
| 368 |
|
| 369 |
|
| 370 |
<!-- |
| 371 |
<section id="Upper_And_Lower_Case"> |
| 372 |
<title>Upper and Lower Case</title> |
| 373 |
|
| 374 |
<para>Text will be plotted as it is typed. Upper case text will be |
| 375 |
plotted in upper case and lower case text will be plotted in lower case. |
| 376 |
There are no special characters needed to move from upper to lower case |
| 377 |
and vice versa.</para> |
| 378 |
</section> |
| 379 |
</section> |
| 380 |
--> |
| 381 |
|
| 382 |
<section id="Text_Line_Limit"> |
| 383 |
<title>Text Line Limit</title> |
| 384 |
|
| 385 |
<important> <title>Magics++</title> |
| 386 |
With <productname>Magics++</productname>, there is no limit to the length |
| 387 |
of a line of text. This differs from previous versions, where a limit of |
| 388 |
200 characters was imposed.</important> |
| 389 |
|
| 390 |
</section> |
| 391 |
|
| 392 |
<section id="Text_Height"> |
| 393 |
<title>Text Height</title> |
| 394 |
|
| 395 |
<para>The height and width of text may be controlled by the user. The parameter |
| 396 |
<parameter>TEXT_FONT_SIZE</parameter> enables the user to |
| 397 |
plot the text lines in the height required. This parameter, whose default |
| 398 |
value is 0.5cm, may be defined by the user. It is used by <productname>Magics</productname> to |
| 399 |
calculate the heights of text lines and the spacing between text lines. |
| 400 |
<!--If after calculating all heights and spacings, it is found that the text |
| 401 |
block will not fit into the current text box, Magics will temporarily |
| 402 |
adjust the parameter |
| 403 |
<parameter>TEXT_FONT_SIZE</parameter> to a value that |
| 404 |
will enable all the text block to be plotted inside the current text box. |
| 405 |
<parameter>TEXT_FONT_SIZE</parameter> will be restored to |
| 406 |
its original value at the termination of action routine |
| 407 |
<function>PTEXT</function>. All subsequent references to |
| 408 |
<parameter>TEXT_FONT_SIZE</parameter> in this section |
| 409 |
assume that its value is such that all the text block can fit into the |
| 410 |
text box. |
| 411 |
--> |
| 412 |
The height of each text line may be specified as a ratio of the |
| 413 |
<parameter>TEXT_FONT_SIZE</parameter>. |
| 414 |
This information can be passed as an array of floating-point values |
| 415 |
such as:</para> |
| 416 |
|
| 417 |
<programlisting> |
| 418 |
CALL <function>PSET1R</function> ('<parameter>TEXT_LINE_HEIGHT_RATIOS</parameter>', RHEIGHTS, NHEIGHTS) |
| 419 |
</programlisting> |
| 420 |
|
| 421 |
<para>Alternatively, you can use separate parameters for setting the height ratio |
| 422 |
of each text line individually (up to 10 lines): |
| 423 |
<parameter>TEXT_LINE_HEIGHT_RATIO_1, .......... |
| 424 |
TEXT_LINE_HEIGHT_RATIO_10,</parameter>.</para> |
| 425 |
|
| 426 |
<para>For example, if |
| 427 |
<parameter>TEXT_FONT_SIZE</parameter> is set to 0.5cm and |
| 428 |
<parameter>TEXT_LINE_HEIGHT_RATIO_3</parameter> is set to 0.8, then the |
| 429 |
height of the text in line 3 of the text block will be 0.4 cm (0.5 x 0.8). |
| 430 |
The default value for all text line ratios is 1.0, which results in the |
| 431 |
character height of all lines being the same height.</para> |
| 432 |
|
| 433 |
|
| 434 |
<important id="Text_Reference_Height_Changed"> <title>Magics++</title> |
| 435 |
With <productname>Magics++</productname>, parameter |
| 436 |
<parameter>TEXT_REFERENCE_CHARACTER_HEIGHT</parameter> with a default of 2cm |
| 437 |
is replaced by <parameter>TEXT_FONT_SIZE</parameter> with a default of 0.5cm. |
| 438 |
This will give sensible and consistent text sizes by default. The old system |
| 439 |
relied on large text being automatically scaled down to fit its text box; this |
| 440 |
produced text which was as generally large as possible within its box, but |
| 441 |
meant that the text size varied between plots where the text differed, for example |
| 442 |
in plot titles. The new system does not automatically scale text down, but its |
| 443 |
default size is sensible. If a line of text does not fit into its box, you must |
| 444 |
change its size yourself. This lack of automation requires a little more care when |
| 445 |
initially setting up a plot, but will reduce inconsistencies when comparing plots |
| 446 |
produced by the same program. |
| 447 |
Note also the additional parameter <parameter>TEXT_LINE_HEIGHT_RATIOS</parameter> for |
| 448 |
setting all the line ratios in one go.</important> |
| 449 |
|
| 450 |
</section> |
| 451 |
|
| 452 |
|
| 453 |
<!-- Parameter TEXT_LINE_SPACE_RATIO not implemented as of 19/04/2007! |
| 454 |
|
| 455 |
<section id="Text_Line_Spacing"> |
| 456 |
<title>Text Line Spacing</title> |
| 457 |
|
| 458 |
<para></para> |
| 459 |
</section> |
| 460 |
--> |
| 461 |
|
| 462 |
|
| 463 |
|
| 464 |
|
| 465 |
|
| 466 |
|
| 467 |
<section id="Text_Fonts"> |
| 468 |
<title>Text Fonts and Colour</title> |
| 469 |
|
| 470 |
<important> <title>Magics++</title> |
| 471 |
<productname>Magics++</productname> has new parameters to set the text font |
| 472 |
attributes with greater user control. The old parameter, |
| 473 |
<parameter>TEXT_QUALITY</parameter> may still be used, but offers less control |
| 474 |
over the font.</important> |
| 475 |
|
| 476 |
<para>The text font may be set with the parameter <parameter>TEXT_FONT</parameter>. |
| 477 |
Available fonts are: '<code>Courier</code>', '<code>Helvetica</code>', |
| 478 |
'<code>Arial</code>', '<code>Times</code>' and '<code>Symbol</code>'.</para> |
| 479 |
|
| 480 |
<para>The text font style may be set with the parameter <parameter>TEXT_FONT_STYLE</parameter>. |
| 481 |
Available styles are: '<code>Bold</code>', '<code>Italic</code>' |
| 482 |
and '<code>BoldItalic</code>'.</para> |
| 483 |
|
| 484 |
<para>The text colour may be set with the parameter <parameter>TEXT_COLOUR</parameter>. |
| 485 |
Any valid <productname>Magics</productname> colour name or definition is allowed here. |
| 486 |
The default colour is '<code>BLUE</code>'.</para> |
| 487 |
|
| 488 |
<para>The following code illustrates the use of these parameters:</para> |
| 489 |
|
| 490 |
<programlisting> |
| 491 |
CALL <function>PSETC</function> ('<parameter>TEXT_FONT</parameter>', 'ARIAL') |
| 492 |
CALL <function>PSETC</function> ('<parameter>TEXT_FONT_STYLE</parameter>', 'BOLD') |
| 493 |
CALL <function>PSETC</function> ('<parameter>TEXT_COLOUR</parameter>', 'BROWN') |
| 494 |
</programlisting> |
| 495 |
|
| 496 |
<para>These parameters affect all the text in the current and any subsequent text blocks. |
| 497 |
For variations within a block of text, instruction strings or HTML text can be used. |
| 498 |
<!-- cross ref --></para> |
| 499 |
|
| 500 |
</section> |
| 501 |
|
| 502 |
|
| 503 |
<section id="Text_Justification"> |
| 504 |
<title>Text Justification</title> |
| 505 |
|
| 506 |
|
| 507 |
<para>A <productname>Magics</productname> parameter, <parameter>TEXT_JUSTIFICATION</parameter> |
| 508 |
exists to control the positioning of text in all the lines of text in a text block. |
| 509 |
There are three types of justification available:</para> |
| 510 |
|
| 511 |
<itemizedlist> |
| 512 |
|
| 513 |
<listitem> |
| 514 |
<para>LEFT - the text will be left justified. This means that the text will start near |
| 515 |
the left side of the text box, allowing for a small margin between the left side of |
| 516 |
the box and the beginning of the text.</para> |
| 517 |
</listitem> |
| 518 |
|
| 519 |
<listitem> |
| 520 |
<para>CENTRE - the text will be centred between the left and right side of the |
| 521 |
text box. This is the default value for <parameter>TEXT_JUSTIFICATION</parameter>.</para> |
| 522 |
</listitem> |
| 523 |
|
| 524 |
<listitem> |
| 525 |
<para>RIGHT - the text will be right justified. This means that the text will end near |
| 526 |
the right side of the text box, allowing for a small margin between the right side of |
| 527 |
the box and the end of the text.</para> |
| 528 |
</listitem> |
| 529 |
|
| 530 |
<!-- |
| 531 |
<listitem> |
| 532 |
<para>TYPESET - the text will be arranged so that each line will be left and |
| 533 |
right justified. If there is more than one word in the text, the first word |
| 534 |
will start at the left side of the text box and the last word will finish |
| 535 |
at the right side of the box, allowing for small margins between the text |
| 536 |
and the sides of the text box. The line will be padded with blanks. When |
| 537 |
there is only one word of text to be plotted, it will be left justified.</para> |
| 538 |
</listitem> |
| 539 |
--> |
| 540 |
|
| 541 |
</itemizedlist> |
| 542 |
|
| 543 |
|
| 544 |
<important id="Text_Justification_Change"> <title>Magics++</title> |
| 545 |
<productname>Magics++</productname> now supports a justification value of '<code>RIGHT</code>' |
| 546 |
but no longer supports a value of '<code>TYPESET</code>'.</important> |
| 547 |
|
| 548 |
</section> |
| 549 |
|
| 550 |
|
| 551 |
|
| 552 |
<section id="Text_Box_Border"> |
| 553 |
<title>Text Box Border</title> |
| 554 |
|
| 555 |
<para>It is possible to draw a border (or frame) around the text box by setting the |
| 556 |
parameter <parameter>TEXT_BORDER</parameter> to '<code>ON</code>', the default being |
| 557 |
'<code>OFF</code>'.</para> |
| 558 |
|
| 559 |
<para><productname>Magics</productname> uses the text box positioning parameters to draw |
| 560 |
the border, i.e. <parameter>TEXT_BOX_X_POSITION</parameter>, |
| 561 |
<parameter>TEXT_BOX_Y_POSITION</parameter>, <parameter>TEXT_BOX_X_LENGTH</parameter> etc. |
| 562 |
The border will be drawn around the defined text box regardless of the |
| 563 |
number of text lines in the box. The user may control the colour, |
| 564 |
thickness and linestyle of the border by setting the parameters |
| 565 |
<parameter>TEXT_BORDER_COLOUR</parameter>, <parameter>TEXT_BORDER_THICKNESS</parameter> |
| 566 |
and <parameter>TEXT_BORDER_LINE_STYLE</parameter> respectively.</para> |
| 567 |
|
| 568 |
</section> |
| 569 |
|
| 570 |
<section id="Text_Box_Blanking"> |
| 571 |
<title>Text Box Blanking</title> |
| 572 |
|
| 573 |
<para>A text box can be drawn in such a way that either its background is |
| 574 |
transparent (default behaviour) or its background overwrites anything |
| 575 |
currently in that part of the plot. This latter |
| 576 |
behaviour is called 'text box blanking' and is controlled with the |
| 577 |
parameter <parameter>TEXT_BOX_BLANKING</parameter>. This can be set to |
| 578 |
'<code>ON</code>', the default being '<code>OFF</code>'.</para> |
| 579 |
|
| 580 |
<para>To ensure full blanking inside a text box, users should call action |
| 581 |
routine <function>PTEXT</function> after all other action routines. If plotting |
| 582 |
has already taken place in the text box area, before <function>PTEXT</function> |
| 583 |
is called, it will be erased and will not appear in the final plot.</para> |
| 584 |
|
| 585 |
</section> |
| 586 |
|
| 587 |
|
| 588 |
</section> <!-- Text Plotting --> |
| 589 |
|
| 590 |
|
| 591 |
<!-- |
| 592 |
<section id="I"> |
| 593 |
<title>Instruction Strings</title> |
| 594 |
</section> |
| 595 |
--> |
| 596 |
|
| 597 |
<!-- |
| 598 |
<section id="HTML_Text"> |
| 599 |
<title>HTML Text</title> |
| 600 |
</section> |
| 601 |
--> |
| 602 |
|
| 603 |
|
| 604 |
|
| 605 |
|
| 606 |
|
| 607 |
|
| 608 |
<xi:include href="../paramtables/ptext_tables.xml" |
| 609 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 610 |
|
| 611 |
|
| 612 |
<section id = 'Text_magml_all_tables'> |
| 613 |
<title>MagML Templates for Text Plotting</title> |
| 614 |
|
| 615 |
<xi:include href="../paramtables/TextVisitor_text_magml_tables.xml" |
| 616 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 617 |
|
| 618 |
<xi:include href="../paramtables/TextVisitor_text_magml_flat_tables.xml" |
| 619 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 620 |
</section> |
| 621 |
|
| 622 |
<!-- |
| 623 |
|
| 624 |
<section id="Text Program_Examples"> |
| 625 |
<title>Program Examples</title> |
| 626 |
|
| 627 |
<para>These examples show how to do stuff with text</para> |
| 628 |
</section> |
| 629 |
|
| 630 |
<xi:include href="../examples/manual/xml/text_examples.xml" |
| 631 |
xmlns:xi="http://www.w3.org/2001/XInclude" /> |
| 632 |
--> |
| 633 |
</chapter> |