# 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 `&auml;` 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