Chapter 3: Basic Text Operations
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 pageGraphic, the
origin of the lower left corner of the page. For elements within an
<illustration>, 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.
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
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).
Font names are given in the following format:
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:
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
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 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
<drawRightString x="523" y="800">
This is a drawRightString example
<drawCentredString x="523" y="800">
This is a drawCentredString example
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:
<setFont name="Helvetica-Bold" size="17"/>
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.