Setting Character Attributes
Prev | Chapter 3. Advanced Use of PLplot | Next

## Setting Character Attributes

Plplot uses two separate font systems to display characters. The Hershey font system gives access to Hershey fonts that come with PLplot. All of our older devices and most of our modern devices allow use of the Hershey font system. The unicode font system gives access to unicode-aware system fonts. Some of our older devices and most of our modern devices allow use of the unicode font system. The advantages of the unicode font system over the Hershey font system are discussed in the section called “Unicode font system”.

### Hershey font system

There are two Hershey font character sets included with PLplot. These are known as the standard and extended character sets. The standard character set is a subset of the extended set. It contains 177 characters including the ascii characters in a normal style font, the Greek alphabet and several plotter symbols. The extended character set contains almost 1000 characters, including four font styles, and several math, musical and plotter symbols.

The extended character set is loaded into memory automatically when PLplot is initialized. The standard character set is loaded by calling `plfontld`. The extended character set requires about 50 KBytes of memory, versus about 5 KBytes for the standard set. `plfontld` can be used to switch between the extended and standard sets (one set is unloaded before the next is loaded). `plfontld` can be called before `plstar`.

When the extended character set is loaded there are four different font styles to choose from. In this case, the routine `plfont` sets up the default Hershey font for all character strings. It may be overridden for any portion of a string by using an escape sequence within the text, as described in the section called “Escape sequences in text”. For the Hershey font system (but not the unicode font system, see below) this routine has no practical effect when the standard font set is loaded. The default font (1) is simple and fastest to draw; the others are useful for presentation plots on a high-resolution device.

The font codes are interpreted as follows:

- `font = 1`: normal (sans-serif) font

- `font = 2`: roman (serif) font

- `font = 3`: italic font

- `font = 4`: script font

### Unicode font system

The advantages of the unicode fonts over the more traditional PLplot Hershey fonts are the availability of many additional glyphs (including mathematical symbols and glyphs from other than western-European languages); support of complex text layout languages for a substantial subset (see the section called “The svg device driver” and the section called “The psttf, cairo, qt, and wxwidgets device drivers”) of the devices that support the Unicode font system; and much better display of characters on computer screens using anti-aliasing and hinting.

The unicode font system can use font specification methods that were designed for the Hershey fonts to specify the unicode font. For this case `plfont` internally calls `plsfci` using four different FCI values to choose unicode font attributes similar to the 4 kinds of Hershey fonts, and the corresponding Hershey text escape-sequences (see the section called “Escape sequences in text”) designed to override the Hershey font selection are treated similarly. However, for the unicode font system the preferred and much more flexible methods of specifying the unicode font are calling the `plsfci` routine, calling the `plsfont` routine which provides a user-friendly interface to `plsfci`, or using unicode text escape-sequences to override unicode font attributes in the middle of strings (see the section called “FCI”).

#### The ps device driver

The ps and psc devices that are implemented with the ps device driver are only unicode-aware in a technical sense because they use a fixed relationship between the FCI (font characterization integer, see the section called “FCI”) and the actual Type 1 system fonts that are being used which unlike typical TTF system fonts have extremely limited glyphs available. This fixed relationship is specified in the Type1Lookup array in include/plfci.h. This array maps the FCI font-family attributes of sans-serif, serif, monotype, script, and symbol to the standard PostScript font families called Helvetica, Times-Roman, Courier, Times-Roman, and Symbol. (There is no script font family amongst the 35 standard Type 1 postscript fonts so that is why we map the font-family attribute of script to Times-Roman.) Similarly, this array maps the FCI font-style attributes of upright, italic or oblique and the FCI font-weight attributes of medium or bold to the appropriate variety of the Helvetica, Times-Roman, Courier, and Symbol font families that are part of the 35 standard Type 1 PostScript fonts. These fonts are normally available on all platforms (e.g., with the gsfonts package on Linux systems).

#### The gd and wingcc device drivers

For the png, jpeg, and gif devices (implemented with the gd device driver) and the wingcc device (implemented with the wingcc device driver), the deprecated plfreetype approach is used for accessing unicode-aware system fonts. This approach is deprecated because of its two major drawbacks. (1) text layout is only left-to-right so that complex text layout languages (such as those used in our standard example 24) are not correctly rendered. (2) System fonts are only accessed by file name rather than using the fontconfig approach or something similar to select the best system font to render the given unicode glyph. Because of this latter drawback a configurable relationship must be established between the FCI (font characterization integer, see the section called “FCI”) and the TrueType font name that is actually used for rendering a unicode glyph. This can be a considerable inconvenience for the user if they want to specify anything other than a default set of font names.

The TrueType font names corresponding to the 30 possible valid FCIs can be specified using cmake options. The defaults for the 30 cmake variables PL_FREETYPE_FONT[_MODIFIER] (where FONT is one of MONO, SANS, SCRIPT, SERIF or SYMBOL and the optional MODIFIER is one of BOLD, BOLD_ITALIC, BOLD_OBLIQUE, ITALIC or OBLIQUE) are documented in cmake/modules/freetype.cmake. On Windows these defaults use standard Windows font files. On all other platforms default font file names are taken from fonts available from the ttf-freefont font package. We recommend this font package because it has a rather complete set of glyphs for most unicode blocks. (We also recommend the gucharmap application for determining other unicode font possibilities on your system that are available via the FreeType library.)

For all platforms, the 30 possible TrueType font files can be specified at run time using the following environment variables:

- PLPLOT_FREETYPE_SANS_FONT

- PLPLOT_FREETYPE_SERIF_FONT

- PLPLOT_FREETYPE_MONO_FONT

- PLPLOT_FREETYPE_SCRIPT_FONT

- PLPLOT_FREETYPE_SYMBOL_FONT

- PLPLOT_FREETYPE_SANS_ITALIC_FONT

- PLPLOT_FREETYPE_SERIF_ITALIC_FONT

- PLPLOT_FREETYPE_MONO_ITALIC_FONT

- PLPLOT_FREETYPE_SCRIPT_ITALIC_FONT

- PLPLOT_FREETYPE_SYMBOL_ITALIC_FONT

- PLPLOT_FREETYPE_SANS_OBLIQUE_FONT

- PLPLOT_FREETYPE_SERIF_OBLIQUE_FONT

- PLPLOT_FREETYPE_MONO_OBLIQUE_FONT

- PLPLOT_FREETYPE_SCRIPT_OBLIQUE_FONT

- PLPLOT_FREETYPE_SYMBOL_OBLIQUE_FONT

- PLPLOT_FREETYPE_SANS_BOLD_FONT

- PLPLOT_FREETYPE_SERIF_BOLD_FONT

- PLPLOT_FREETYPE_MONO_BOLD_FONT

- PLPLOT_FREETYPE_SCRIPT_BOLD_FONT

- PLPLOT_FREETYPE_SYMBOL_BOLD_FONT

- PLPLOT_FREETYPE_SANS_BOLD_ITALIC_FONT

- PLPLOT_FREETYPE_SERIF_BOLD_ITALIC_FONT

- PLPLOT_FREETYPE_MONO_BOLD_ITALIC_FONT

- PLPLOT_FREETYPE_SCRIPT_BOLD_ITALIC_FONT

- PLPLOT_FREETYPE_SYMBOL_BOLD_ITALIC_FONT

- PLPLOT_FREETYPE_SANS_BOLD_OBLIQUE_FONT

- PLPLOT_FREETYPE_SERIF_BOLD_OBLIQUE_FONT

- PLPLOT_FREETYPE_MONO_BOLD_OBLIQUE_FONT

- PLPLOT_FREETYPE_SCRIPT_BOLD_OBLIQUE_FONT

- PLPLOT_FREETYPE_SYMBOL_BOLD_OBLIQUE_FONT

On Unix/Linux systems if these environment variables are not specified with an absolute path starting with "/", then the absolute path is specified by the cmake variable PL_FREETYPE_FONT_PATH or at run time with the environment variable PLPLOT_FREETYPE_FONT_DIR.

#### The svg device driver

The svg device (which is implemented with the svg device driver) is a device that implements the unicode font method by mapping FCI attributes (see the section called “FCI”) to corresponding combinations of the SVG attributes font-family, font-style, and font-weight. Since these attributes are generic ones, (e.g., FCI font-family "sans-serif", "serif", "monospace", "script", and "symbol" correspond to SVG font-family "sans-serif", "serif", "mono-space", "cursive", and "sans-serif") the SVG viewer applications that render the SVG files produced by the svg device have a large degree of freedom within these generic guidelines for choosing which system font to use to render a given unicode glyph. Note that unlike devices that use the plfreetype approach (see the section called “The gd and wingcc device drivers”) this device requires no user intervention to set up the correct mapping between FCI and font, and complex text layout languages are rendered correctly (assuming the SVG viewer does that).

#### The psttf, cairo, qt, and wxwidgets device drivers

The large number of unicode-aware devices that are implemented by the psttf, cairo, qt, and wxwidgets device drivers implement the unicode font method using PLplot FCI values (see the section called “FCI”) to characterize the generic fonts that are needed by the associated libLASi (psttf), pango/cairo (cairo), Qt (qt), and wxWidgets (wxwidgets) library dependencies of these device drivers. Note that unlike devices that use the plfreetype approach (see the section called “The gd and wingcc device drivers”) these devices require no user intervention to set up the correct mapping between FCI and font, and complex text layout languages are rendered correctly (assuming the associated library dependency of the device driver does that).

### FCI

We specify the properties of unicode fonts with the FCI (font characterization integer). The FCI is a 32-bit unsigned integer whose most significant hexadecimal digit is set (by ORing 0x80000000 with the FCI value) to distinguish it from a unicode (UCS4) integer (whose maximum value is 0x7fffffff). Users obtain the current FCI by calling `plgfci` and store a new FCI to be used at the start of each subsequent string using `plsfci`. The FCI contains three independent hexadecimal values corresponding to font family, font-style, and font weight. These three values can also be obtained and set in a user-friendly way using `plgfont` and `plsfont`. These values are also characterized by "hexdigit" (defined as the actual hexadecimal value used for one of the hexadecimal digits) and "hexpower" (defined as the power of 16 or number of hexadecimal places to the left of the "decimal place" in the FCI where the hexdigit is stored). The interpretation of the hexdigit and hexpower values in the FCI are given in Table 3.3, “FCI interpretation”.

Table 3.3. FCI interpretation

| hexdigit --> | 0 | 1 | 2 | 3 | 4
Font attribute | hexpower |  |  |  |  |
font-family | 0 | sans-serif | serif | monospace | script | symbol
font-style | 1 | upright | italic | oblique |  |
font-weight | 2 | medium | bold |  |  |

Note the maximum value of hexdigit is 7 and the maximum value of hexpower is 6 so there is substantial room for expansion of this scheme. On the other hand, since each font attribute is independent of the rest, what is implemented now gives us a maximum of 30 different font possibilities which is probably more than enough for most plotting purposes.

### Escape sequences in text

The routines which draw text all allow you to include escape sequences in the text to be plotted. These are character sequences that are interpreted as instructions to change fonts, draw superscripts and subscripts, draw non-ASCII (e.g. Greek), and so on. All escape sequences start with a number symbol (`#`) by default. Some language interfaces have the capability of changing this default, but we will assume (`#`) in the remaining documentation of the escape sequences.

The following escape sequences are defined:

- `#u`: move up to the superscript position (ended with `#d`)

- `#d`: move down to subscript position (ended with `#u`)

- `#b`: backspace (to allow overprinting)

- `##`: number symbol

- `#+`: toggle overline mode

- `#-`: toggle underline mode

- `#gx`: Greek letter corresponding to Roman letter `x` (see below)

- `#fn`: switch to normal (sans-serif) font

- `#fr`: switch to Roman (serif) font

- `#fi`: switch to italic font

- `#fs`: switch to script font

- `#(nnn)`: Hershey character nnn (1 to 4 decimal digits)

- `#[nnn]`: unicode character nnn (nnn can be decimal or hexadecimal [e.g., starting with 0x]) (UNICODE ONLY).

- `#<0x8nnnnnnn>`: absolute FCI to be used to change fonts in mid-string. (nnnnnnn must be exactly 7 digits). (UNICODE ONLY).

- `#<0xmn>`: change just one attribute of the FCI in mid-string where m is the hexdigit and n is the hexpower. If more than two digits are given (so long as the eighth digit does not mark this as an absolute FCI, see above) they are ignored. (UNICODE ONLY).

- `#<FCI COMMAND STRING/>`: the FCI COMMAND STRING is currently one of "sans-serif", "serif", "monospace", "script", "symbol", "upright", "italic", "oblique" "medium", or "bold" (without the surrounding quotes). These FCI COMMAND STRINGS change one attribute of the FCI according to their name. (UNICODE ONLY).

Sections of text can have an underline or overline appended. For example, the string S̅(f̲r̲e̲q̲) is obtained by specifying `"#+S#+(#-freq#-)"`.

Greek letters are obtained by `#g` followed by a Roman letter. Table 3.4, “Roman Characters Corresponding to Greek Characters” shows how these letters map into Greek characters.

Table 3.4. Roman Characters Corresponding to Greek Characters

Roman | A | B | G | D | E | Z | Y | H | I | K | L | M
Greek | Α | Β | Γ | Δ | Ε | Ζ | Η | Θ | Ι | Κ | Λ | Μ

Roman | N | C | O | P | R | S | T | U | F | X | Q | W
Greek | Ν | Ξ | Ο | Π | Ρ | Σ | Τ | Υ | Φ | Χ | Ψ | Ω

Roman | a | b | g | d | e | z | y | h | i | k | l | m
Greek | α | β | γ | δ | ε | ζ | η | θ | ι | κ | λ | μ

Roman | n | c | o | p | r | s | t | u | f | x | q | w
Greek | ν | ξ | ο | π | ρ | σ | τ | υ | φ | χ | ψ | ω

The escape sequences `#fn`, `#fr`, `#fi`, `#fs`, and `#(nnn)` are designed for the four Hershey fonts, but an effort has been made to allow some limited forward compatibility so these escape sequences have a reasonable result when unicode fonts are being used. However, for maximum flexibility when using unicode fonts, these 5 Hershey escape sequences should be replaced by using the 4 unicode escape sequences `#<0x8nnnnnnn>`, `#<0xmn>`, `#<FCI COMMAND STRING/>`, and `#[nnn]` as appropriate.

It should be emphasized that the unicode escape sequences above only work properly for modern unicode-aware devices such as the svg and wxwidgets devices or the very large set of cairo and qt devices. And for those devices the alternative of directly specifying the unicode symbols using UTF-8 encoding of PLplot input strings is much more convenient for users than using the above `#[nnn]` type of escape sequence. For example, we use UTF-8 strings rather than escape sequences in our standard example 24 to render the word "Peace" in several different languages.

Table 3.5. The word "peace" expressed in several different languages in example 24 using UTF-8

Hebrew | שלום
French | Paix
Kurdish | Hasîtî
English | Peace
Korean | 평화
Turkish | Barış
Hindi | शांति
German | Friede
Arabic | ﺳﻼم
Mandarin | 和平
Russian | Мир
Spanish | Paz

For unicode-aware devices it is possible as well to specify mathematical glyphs (such as ∂, ∇, ∑, ∫, and ∰) using UTF-8 encoding of PLplot input strings. A typical input method in this case is simply to cut and paste the desired mathematical glyph from, e.g., gucharmap to source code being edited by a unicode-aware editor such as emacs. Such input methods may be conveniently used, for example, to specify the very wide range of mathematical symbols that are typically desired for scientific plots.

### Character size adjustment

The routine `plschr` is used to set up the size of subsequent characters drawn. The actual height of a character is the product of the default character size and a scaling factor. If no call is made to `plschr`, the default character size is set up depending on the number of subpages defined in the call to `plstar` or `plstart`, and the scale is set to 1.0. Under normal circumstances, it is recommended that the user does not alter the default height, but simply use the scale parameter. This can be done by calling `plschr` with `def = 0.0` and `scale` set to the desired multiple of the default height. If the default height is to be changed, `def` is set to the new default height in millimeters, and the new character height is again set to `def` multiplied by `scale`.

The routine `plssym` sets up the size of all subsequent characters drawn by calls to `plpoin` and `plsym`. It operates analogously to `plschr` as described above.

Prev | Up | Next
Setting Color | Home | Three-dimensional Plots