<!-- chapterName "Basic figures - lines and shapes" -->

<!-- sectionName "Rect, circle and ellipse" -->

<para>
As well as allowing you to place text on the page, <font face="Courier">pageGraphics</font>
also allows you to place shapes and graphics on it.
</para>

<para style="nospace">
The basic types of shape that RML allows you to use are:
</para>
<para style="bulletList" bulletText="">
<font face="Courier">rect</font> (rectangle), <font face="Courier">circle</font>,
and <font face="Courier">ellipse</font>.
</para>

<para style="nospace">
A <font face="Courier">rect</font> needs to have a list of attributes passed to it:
</para>
<para style="bulletNospace" bulletText="">
- the co-ordinates for the bottom left hand corner,
</para>
<para style="bulletList" bulletText="">
- its <font face="Courier">width</font> and <font face="Courier">height</font>,
</para>
<para>
It also has optional <font face="Courier">fill</font> and <font face="Courier">stroke</font> attributes,
and a <font face="Courier">round</font> attribute, which tell it if the corners should be rounded off.
</para>

<para style="nospace">
The <font face="Courier">circle</font> needs the following attributes passed to it:
</para>
<para style="bulletNospace" bulletText="">
- the <font face="Courier">x</font> and <font face="Courier">y</font> co-ordinates of the point where its center should be,
</para>
<para style="bulletList" bulletText="">
- its radius
</para>

<para>
If you imagine the <font face="Courier">ellipse</font> inside a rectangle, the <font face="Courier">x</font>
and <font face="Courier">y</font> attributes give the co-ordinates for the bottom left hand corner, and the
<font face="Courier">width</font> and <font face="Courier">height</font> attributes give the co-ordinates
for the top right hand corner of the box.
</para>

<para style="nospace">
All shapes also have two optional attributes:
</para>
<para style="bulletNospace" bulletText="">
- <font face="Courier">fill</font>, which tells the parser if the shape should be filled in or not, and
</para>
<para style="bulletList" bulletText="">
- <font face="Courier">stroke</font> which tells it if the shape should have its outline displayed.
</para>
<para>
Both these attributes take Boolean values as arguments. You can uses
either "1" or "yes" to set them as on, or "0" or "no" to set them as
off.
</para>

<para>
The following example shows various combinations of attributes for each of
the basic shapes. Notice how this example starts with the XML definition -
you can get away with not using it, but it is still better to make sure it
is there.
</para>

<illustration width="228" height="333">
<image file="images/Example_3a.gif" x="0" y="12"/>
</illustration>

<para style="figureCaption">
Figure <seq id="figureNumber"/>: Output from EXAMPLE 3
</para>

<para style="figureCaption">EXAMPLE 3</para>
<codesnippet language="xml" style="code-small"><![CDATA[
{{safeTopInclude('example_3.rml')}}
]]></codesnippet>


<spacer length="15"/>

<!-- sectionName "Fill and stroke" -->

<para>
If you look at the example 3, you will see that as well as having
<font face="Courier">fill</font> and <font face="Courier">stroke</font>
attributes for the shapes, there are separate <font face="Courier">&lt;fill&gt;</font>
and <font face="Courier">&lt;stroke&gt;</font> tags.
</para>
<para>
Inside the tag for a shape (such as <font face="Courier">rect</font>),
<font face="Courier">fill</font> and <font face="Courier">stroke</font>
simply tell rml2pdf whether those qualities should be turned on. Should
there be a <font face="Courier">fill</font>, or not? Should there be a
<font face="Courier">stroke</font>, or not? That is why the
argument is Boolean - "yes" or "no" (though "1" or "0" are also
allowed).
</para>
<para>
The <font face="Courier">fill</font> and <font face="Courier">stroke</font>
tags do a different job. The only argument that these tags are allowed is
a color. If there are no <font face="Courier">fill</font> or
<font face="Courier">stroke</font> tags in a document, both the fill and
the stroke for all shapes default to black. If you have a
<font face="Courier">fill</font> tag before a shape, it allows you
to change the color that that shape is filled with. Similarly, a
<font face="Courier">stroke</font> tag before a shape allows you to set
the color that the outline of that shape will be drawn in. If there is
no <font face="Courier">fill</font> or <font face="Courier">stroke</font>
tag in front of a shape, it will be filled and stroked with the most recently
defined <font face="Courier">fill</font> or <font face="Courier">stroke</font>
- or failing that, the default black.
</para>
<para>
This means that you can use one <font face="Courier">fill</font> tag to refer
to many shapes, while changing the <font face="Courier">stroke</font> for
each of them. Or vice versa.
</para>

<para>
Another brief example of how the <font face="Courier">fill</font> and
<font face="Courier">stroke</font> tags look:
</para>

<codesnippet language="xml" style="code">
<![CDATA[
<fill color="olivedrab"/>
<stroke color="khaki"/>
]]>
</codesnippet>
<spacer length="15"/>

<!-- sectionName "Lines and lineMode" -->

<para>
The other basic drawing element is the line. To draw a simple line,
you use the <font face="Courier">&lt;lines&gt;</font> tag. For each
line you want to draw, you pass <font face="Courier">&lt;lines&gt;</font>
two pairs of X-Y co-ordinates - one pair of co-ordinates for the start
point of the line, the other for the end point.
</para>

<para>
If you want to draw more than one line, you can keep passing
<font face="Courier">&lt;lines&gt;</font> more sets of 4
co-ordinates. <font face="Courier">&lt;lines&gt;</font> then draws those
other separate lines on the page. The lines in a
<font face="Courier">&lt;lines&gt;</font> command are
just lumped together in one <font face="Courier">&lt;lines&gt;</font>
tag for your convenience. (If you want lines that follow on from each
other, look at the "Advanced figures" section later in this manual).
</para>

<condPageBreak height="60"/>
<para>
For example, this draws a simple line:
</para>

<codesnippet language="xml" style="code">
    <![CDATA[
<lines>
    2.5in 10.5in 3.5in 10.5in
</lines>
]]>
</codesnippet>
<spacer length="15"/>

<para>
And this starts with the same line, then draws an extra couple of lines below it:
</para>

<codesnippet language="xml" style="code">
    <![CDATA[
<lines>
    2.5in 10.5in 3.5in 10.5in
    2.5in 10.25in 3.5in 10.25in
    2.5in 10in 3.5in 10in
</lines>

]]>
</codesnippet>
<spacer length="15"/>

<para>
It doesn't matter how you arrange the sets of co-ordinates, but it
helps to keep it human-readable if you keep co-ordinates to do with
the same line on the same line of RML. This second example could have
been written like this (but it would be much harder to follow):
</para>

<codesnippet language="xml" style="code">
<![CDATA[
<lines>
    2.5in 10.5in 3.5in 10.5in 2.5in 10.25in 3.5in 10.25in 2.5in 10in 3.5in 10in
</lines>
]]>
</codesnippet>
<spacer length="15"/>

<para>
One more thing to notice before we move on is that these co-ordinates are separated by spaces.
They are <i>not</i> separated by commas as you might expect.
</para>

<para>
As well as just drawing lines, there are a number of attributes you can modify to
change the appearance of lines. This is done with the
<font face="Courier">&lt;lineMode&gt;</font> tag.
</para>

<para>
The most obvious attribute to <font face="Courier">&lt;lineMode&gt;</font> is
<font face="Courier">width</font>. You can give
<font face="Courier">&lt;lineMode&gt;</font> a number
for the width attribute to change the line width to that number of points.
</para>

<illustration width="405" height="55">
<image file="images/Linewidth.gif" x="0" y="12"/>
</illustration>

<para style="figureCaption">
Figure <seq id="figureNumber"/>: Example of lineMode attribute "width"
</para>


<para>
The <font face="Courier">join</font> attribute to <font face="Courier">&lt;lineMode&gt;</font>
adjusts how what happens when lines meet. They can either come to a point, or the vertex can
be rounded or squared off into a bevelled join. The possible values for join are
<font face="Courier">round</font>, <font face="Courier">mitered</font>, or
<font face="Courier">bevelled</font>.
</para>

<para>
The <font face="Courier">cap</font> attribute to
<font face="Courier">&lt;lineMode&gt;</font> adjusts how the ends of lines
appear. The end of a line can have a square end exactly at the vertex, a square
end that is extended so it is over the vertex, or a half circle - a rounded cap.
These possible values for cap are <font face="Courier">default</font>,
<font face="Courier">square</font> or <font face="Courier">round</font>.
</para>

<illustration width="307" height="100">
<image file="images/Linecap.gif" x="0" y="12"/>
</illustration>

<para style="figureCaption">
Figure <seq id="figureNumber"/>: Example of lineMode attribute "cap"
</para>


<para>
Both the <font face="Courier">join</font> and <font face="Courier">cap</font> attributes
for <font face="Courier">&lt;lineMode&gt;</font> are only really visible if the
line you are applying them to is thick.
</para>

<para>
Another attribute to <font face="Courier">&lt;lineMode&gt;</font> is
<font face="Courier">dash</font>. This allows you to specify if the line
is dotted or dashed. You supply it a series of numbers (separated by commas),
and it takes them as a pattern for how many pixels the line is on for, and then
how many pixels the line is off (i.e. not displayed) for. This can be a simple
pattern such as "1,2" (which gives you a plain dotted line) or "5,5" (which
makes the lines sections equal with the spaces), or as complex as
"1,1,3,3,1,4,4,1" (a complex pattern of dots and dashes).
</para>

<illustration width="316" height="98">
<image file="images/Linedash.gif" x="0" y="12"/>
</illustration>

<para style="figureCaption">
Figure <seq id="figureNumber"/>: Example of lineMode attribute "dash"
</para>


<para>
The following example shows examples of most of the attributes that you can use
with <font face="Courier">&lt;lines&gt;</font> and
<font face="Courier">&lt;lineMode&gt;</font>. Notice how you can use more that one
attribute to <font face="Courier">&lt;lineMode&gt;</font> at the same time.
</para>

<para style="figureCaption">EXAMPLE 4</para>
<codesnippet language="xml" style="code-small"><![CDATA[
{{safeTopInclude('example_4.rml')}}
]]></codesnippet>


<spacer length="15"/>

<illustration width="304" height="339">
<image file="images/Example_4a.gif" x="0" y="12"/>
</illustration>

<para style="figureCaption">
Figure <seq id="figureNumber"/>: Output from EXAMPLE 4
</para>

