Text Plotting
Introduction
Magics text plotting offers to write custom strings in a text box.
Each line of text consists of one character string. This can be made
up of standard ASCII characters including special instruction strings
for inline formatting of the text. New to Magics++
is HTML text, enabling a higher degree of formatting control using
a familiar syntax. Users may plot any number of lines in a single text block if
passed as an array, or up to 10 text lines if passed individually. Each block
of text is plotted with a call to the action routine PTEXT.
The text block is always plotted in a text box, the position and
dimensions of which may be defined by the user or automatically calculated
by Magics.
Using Html-like styles in texts
In Magics++ users can use the HTML-like syntax to style text.
In HTML syntax the user can write
CALL PSETC("text_user_line_1", ”<font colour='red'> red text </font> <font colour='red'> and now blue</font>”)
Pgf90 - Escaping of special characters
Some Fortran compilers, such as Pgf90 require the high commas in the text strings to be escaped. This can be done
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
deactivated by using the compiler option -Mnobackslash when compiling with Pgf90.
Unicode
Magics++ has support for Unicode if written
directly as input for parameters or through the HTML syntax. In HTML syntax
the user can write ä to get an ä.
CALL PSETC ('TEXT_HTML','ON')
GRIB keys in titles
Magics++ allows users to insert information from a GRIB headers through the HTML syntax.
In HTML syntax the user can write
CALL PSETC("text_user_line_1", ”<grib_info key=‘name’ /> at <grib_info key=‘level’ />hPa”)
Text Modes
All text plotting in Magics is achieved by calling action routine
PTEXT, which has no arguments.
Text parameters exist to control all aspects of text plotting and any text
parameters required should be set before
PTEXT is called.
Action routine PTEXT works in two modes,
'TITLE' and 'POSITIONAL', the default being
'TITLE'.
To change the text mode, users should set the parameter
TEXT_MODE, e.g.
CALL PSETC ('TEXT_MODE','POSITIONAL')
In 'TITLE' mode, which is the default, the user's text
will be automatically positioned above the current subpage. The height and
width of the text box are calculated automatically by Magics.
The height of the text box is approximately the distance from the
top of the current subpage to the top of the page.
There will be a small gap between the subpage and the text box to
allow for grid labels and a small gap between the top of the text box and
the top of the page. The width of the box is the
SUBPAGE_X_LENGTH.
In 'POSITIONAL' mode, the user
can place text anywhere within the current page. They may define the
position of the text box as well as the height and width.
Magics++
Magics++ performs no automatic adjustments on
the positions or dimensions of text boxes which are partially or completely
outside of the page. This behaviour differs from previous versions.
The default position of the text box in 'POSITIONAL'
mode is the lower left corner of the current subpage. The Magics
parameters TEXT_BOX_X_POSITION and
TEXT_BOX_Y_POSITION may be used to set the position
of the text box, if the default values are not suitable. The positions are
relative to the PAGE_X_POSITION and
PAGE_Y_POSITION respectively. The default height of the
box will be 20% of the SUBPAGE_Y_LENGTH and the default
width will be 50% of the SUBPAGE_X_LENGTH.
Creating Text
Magics++
Magics++ allows any number of lines in a text block using
the new interface in which an array of strings is passed. The old interface
still exists, allowing up to 10 text lines to be passed individually.
Array Text Blocks
Lines of text can be created by passing an array of text strings to Magics:
PARAMETER (NLINES=5)
CHARACTER*16 LINES
DIMENSION LINES (NLINES)
DATA LINES /'This is a',
x 'text block',
x 'passed',
x 'by',
x 'array'/
[...]
CALL PSET1C ('TEXT_LINES', LINES, NLINES)
Individual Text Blocks
For convenience, and compatibility with previous versions of Magics,
it is possible to individually set lines 1 to 10 by setting parameters TEXT_LINE_1
to TEXT_LINE_10 with PSETC, for example:
CALL PSETC ('TEXT_LINE_1', 'THIS IS A TEXT EXAMPLE')
When passing the lines of text individually, the number of text lines to be plotted
should be indicated to Magics
by setting the parameter TEXT_LINE_COUNT,
e.g.
CALL PSETI ('TEXT_LINE_COUNT', 4)
It is possible to start plotting text from any line in the text
block by setting the parameter TEXT_FIRST_LINE to
the number of the line required. Magics will start plotting from this line
and will plot the subsequent lines in the block if more than one line of
text is to be plotted. For example, if 3 lines of text are required
starting at line 5 in the text block, the user should set
TEXT_FIRST_LINE to 5 and
TEXT_LINE_COUNT to 3.
Text Plotting
Text Line Limit
Magics++
With Magics++, there is no limit to the length
of a line of text. This differs from previous versions, where a limit of
200 characters was imposed.
Text Height
The height and width of text may be controlled by the user. The parameter
TEXT_FONT_SIZE enables the user to
plot the text lines in the height required. This parameter, whose default
value is 0.5cm, may be defined by the user. It is used by Magics to
calculate the heights of text lines and the spacing between text lines.
The height of each text line may be specified as a ratio of the
TEXT_FONT_SIZE.
This information can be passed as an array of floating-point values
such as:
CALL PSET1R ('TEXT_LINE_HEIGHT_RATIOS', RHEIGHTS, NHEIGHTS)
Alternatively, you can use separate parameters for setting the height ratio
of each text line individually (up to 10 lines):
TEXT_LINE_HEIGHT_RATIO_1, ..........
TEXT_LINE_HEIGHT_RATIO_10,.
For example, if
TEXT_FONT_SIZE is set to 0.5cm and
TEXT_LINE_HEIGHT_RATIO_3 is set to 0.8, then the
height of the text in line 3 of the text block will be 0.4 cm (0.5 x 0.8).
The default value for all text line ratios is 1.0, which results in the
character height of all lines being the same height.
Magics++
With Magics++, parameter
TEXT_REFERENCE_CHARACTER_HEIGHT with a default of 2cm
is replaced by TEXT_FONT_SIZE with a default of 0.5cm.
This will give sensible and consistent text sizes by default. The old system
relied on large text being automatically scaled down to fit its text box; this
produced text which was as generally large as possible within its box, but
meant that the text size varied between plots where the text differed, for example
in plot titles. The new system does not automatically scale text down, but its
default size is sensible. If a line of text does not fit into its box, you must
change its size yourself. This lack of automation requires a little more care when
initially setting up a plot, but will reduce inconsistencies when comparing plots
produced by the same program.
Note also the additional parameter TEXT_LINE_HEIGHT_RATIOS for
setting all the line ratios in one go.
Text Fonts and Colour
Magics++
Magics++ has new parameters to set the text font
attributes with greater user control. The old parameter,
TEXT_QUALITY may still be used, but offers less control
over the font.
The text font may be set with the parameter TEXT_FONT.
Available fonts are: 'Courier', 'Helvetica',
'Arial', 'Times' and 'Symbol'.
The text font style may be set with the parameter TEXT_FONT_STYLE.
Available styles are: 'Bold', 'Italic'
and 'BoldItalic'.
The text colour may be set with the parameter TEXT_COLOUR.
Any valid Magics colour name or definition is allowed here.
The default colour is 'BLUE'.
The following code illustrates the use of these parameters:
CALL PSETC ('TEXT_FONT', 'ARIAL')
CALL PSETC ('TEXT_FONT_STYLE', 'BOLD')
CALL PSETC ('TEXT_COLOUR', 'BROWN')
These parameters affect all the text in the current and any subsequent text blocks.
For variations within a block of text, instruction strings or HTML text can be used.
Text Justification
A Magics parameter, TEXT_JUSTIFICATION
exists to control the positioning of text in all the lines of text in a text block.
There are three types of justification available:
LEFT - the text will be left justified. This means that the text will start near
the left side of the text box, allowing for a small margin between the left side of
the box and the beginning of the text.
CENTRE - the text will be centred between the left and right side of the
text box. This is the default value for TEXT_JUSTIFICATION.
RIGHT - the text will be right justified. This means that the text will end near
the right side of the text box, allowing for a small margin between the right side of
the box and the end of the text.
Magics++
Magics++ now supports a justification value of 'RIGHT'
but no longer supports a value of 'TYPESET'.
Text Box Border
It is possible to draw a border (or frame) around the text box by setting the
parameter TEXT_BORDER to 'ON', the default being
'OFF'.
Magics uses the text box positioning parameters to draw
the border, i.e. TEXT_BOX_X_POSITION,
TEXT_BOX_Y_POSITION, TEXT_BOX_X_LENGTH etc.
The border will be drawn around the defined text box regardless of the
number of text lines in the box. The user may control the colour,
thickness and linestyle of the border by setting the parameters
TEXT_BORDER_COLOUR, TEXT_BORDER_THICKNESS
and TEXT_BORDER_LINE_STYLE respectively.
Text Box Blanking
A text box can be drawn in such a way that either its background is
transparent (default behaviour) or its background overwrites anything
currently in that part of the plot. This latter
behaviour is called 'text box blanking' and is controlled with the
parameter TEXT_BOX_BLANKING. This can be set to
'ON', the default being 'OFF'.
To ensure full blanking inside a text box, users should call action
routine PTEXT after all other action routines. If plotting
has already taken place in the text box area, before PTEXT
is called, it will be erased and will not appear in the final plot.
MagML Templates for Text Plotting