Chapter 3: Basic Text Operations
3.1. Coordinates and measurements
In RML, the page origin is in the bottom left hand corner (0,0). Any point on the page can be specified by a pair of numbers - a pair of X,Y co-ordinates. The X co-ordinate states how far to the right the point is and the Y co-ordinate states how far up it is.
When an RML element has co-ordinates, the co-ordinate origin is the lower left corner.
In the case of elements in a <pageGraphics> tag, the
origin of the lower left corner of the page. For elements within an
<illustration> tag, the origin is the lower left
corner of the bounding box declared by the <illustration>.
These co-ordinates (and any other measurements in an RML document) can
be given in one of four units. Inches use the term 'in',
centimetres use the term 'cm', and millimetres use the
term 'mm'. If no unit is specified, RML will assume
that you are giving a measurement in points - one point is 1/72 of an inch. You
can also explicitly use points with the term 'pt'.
As an example, the following pairs of co-ordinates all refer to the same point. Notice that there is no space between the number and any unit that follows it.
You can mix and match these units within RML, though it generally isn't a good idea to do so. The co-ordinate pair (3.5in, 3.5cm) is valid, and won't confuse the RML parser - but it may well confuse you.3.2. Using Colors
There are three ways to specify colors in RML:
- by red/green/blue value (e.g. "#ff0000" or "(0.0,0.0,1.0)")
- by cyan/magenta/yellow/black value (e.g. "#ff99001f" or "(1.0,0.6,0.0,0.1)")
- by color name using standard HTML names
The RGB or additive color specification follows the way a computer screen adds different levels of the red, green, or blue light to make any color. White is formed by turning all three lights on full (1,1,1).
The CMYK or subtractive method follows the way a printer mixes three pigments (cyan, magenta, and yellow) to form colors. Because mixing chemicals is more difficult than combining light there is a fourth parameter for darkness. A chemical combination of the CMY pigments almost never makes a perfect black - instead producing a muddy brown - so, to get black printers use a direct black ink rather than use the CMY pigments.
The name CMYK comes from the name of the four colors used: Cyan, Magenta, Yellow and "Key" - a term sometimes used by printers to refer to black.
Because CMYK maps more directly to the way printer hardware works it may be the case that colors specified in CMYK will provide better fidelity and better control when printed.
The color names which RML recognizes are mostly drawn from the HTML specification. (For a list of these color names recognized by RML, see Appendix A).
3.3. Using fonts
Font names are given in the following format:
Fontname-style
where fontname is the name of the font (e.g. Courier), and the style is its appearance (eg, Oblique, BoldOblique).
The only fonts supplied with Adobe's Acrobat Reader are the "14 standard fonts". These 14 standard fonts are:
Courier,
Courier-Bold,
Courier-BoldOblique,
Courier-Oblique,
Helvetica,
Helvetica-Bold,
Helvetica-BoldOblique,
Helvetica-Oblique,
Symbol,
Times-Bold,
Times-BoldItalic,
Times-Italic,
Times-Roman,
ZapfDingbats
Custom fonts can also be used in your document. RML supports TrueType and Type 1 fonts. In order
to use them, make sure they are on the appropriate path and then register them in the
<docinit> section at the top of the RML file.
Use the <registerTTFont> and
<registerFont> tags to register them.
To use a common set of fonts together as bold, italic etc., you need to put them
into a common grouping using the <registerFontFamily> tag.
An example of how to use these tags with different font types and styles can be found in the file rml2pdf/test/test_005_fonts.rml
3.4. Basic text operations - setFont and drawString
The simplest way to put text on a page is using the <drawString>
tag. This places the "string" of text on the page at the
co-ordinates you give it. The only attributes you can give it are a
pair of X and Y co-ordinates. After the tag itself comes the string of
text you want put on the page, and then you need the closing
</drawString> tag.
DrawString has a pair of companions.
<drawRightString> and
<drawCentredString> both work in the same way,
but right justify the string and center it, respectively.
This is how they look in practice:
<drawString x="523" y="800">
This is a drawString example
</drawString>
<drawRightString x="523" y="800">
This is a drawRightString example
</drawRightString>
<drawCentredString x="523" y="800">
This is a drawCentredString example
</drawCentredString>
To set the font that you want a piece of text to be, you need to use the
<setFont> tag. This has two arguments which are required - you need to
give it the name of the font, and the size you want it displayed at.
A setFont tag looks like this:
To use all the drawString commands, you need to use a tag called
<pageGraphics>. This tag appears at the start of a RML document,
in the <pageTemplate> section. pageGraphics are the graphics that have
to do with a whole page (rather than just individual illustrations, as
we will see later). pageGraphics can be used to provide a background
to a page, to place captions or other textual information on a page,
or to provide logos or other colorful elements. Whatever you use them for,
they are always anchored to a spot on the page - they do not wrap or flow
with any text you might put into paragraphs.