<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!-- edited with XMLSPY v2004 rel. 3 U (http://www.xmlspy.com) by Andy Robinson (ReportLab Europe Ltd.) -->
<!DOCTYPE document SYSTEM "rml_1_0.dtd">
<document filename="test_014_graphics.pdf">
  <docinit>
    <registerTTFont faceName="Vera" fileName="Vera.ttf" />
    <registerTTFont faceName="VeraBold" fileName="VeraBd.ttf" />
    <registerTTFont faceName="VeraItalic" fileName="VeraIt.ttf" />
  </docinit>
  <template pageSize="(595, 842)" leftMargin="72" showBoundary="0">
    <pageTemplate id="main" pageSize="(595,842)">
      <pageGraphics>
        <setFont name="Helvetica-Bold" size="18"/>
		    <drawString x="35" y="783">RML Example 17: Graphics</drawString>
			<image file="logo_no_bar.png" preserveAspectRatio="1" x="488" y="749" width="72" height="72"/>
    		<image file="strapline.png" preserveAspectRatio="1" x="35" y="0" width="525" />
        <setFont name="Vera" size="10"/>
		<saveState/>
		<setFontSize size="20" leading="24"/>
		<restoreState/>
        <drawCenteredString x="297" y="25">Page <pageNumber/>
        </drawCenteredString>
      </pageGraphics>
      <frame id="second" x1="35" y1="45" width="525" height="590"/>
    </pageTemplate>
    
    <pageTemplate id="main2" pageSize="(595,842)">
      <pageGraphics>
        <setFont name="Helvetica-Bold" size="18"/>
		    <drawString x="35" y="783">RML Example 17: Graphics</drawString>
			<image file="logo_no_bar.png" preserveAspectRatio="1" x="488" y="749" width="72" height="72"/>
    		<image file="strapline.png" preserveAspectRatio="1" x="35" y="0" width="525" />
        <setFont name="Vera" size="10"/>
		<saveState/>
		<setFontSize size="20" leading="24"/>
		<restoreState/>
        <drawCenteredString x="297" y="25">Page <pageNumber/>
        </drawCenteredString>
      </pageGraphics>
      <frame id="first" x1="1in" y1="1in" width="6.27in" height="8.69in"/>
    </pageTemplate>
  </template>
  <stylesheet>
    <initialize>
      <alias id="style.normal" value="style.Normal"/>
    </initialize>
    <paraStyle name="h1" fontName="VeraBold" fontSize="12" spaceBefore="12" leading="15"/>
    <paraStyle name="normal" fontName="Vera" fontSize="10" spaceBefore="6" leading="12"/>
    <paraStyle name="code" fontName="Courier" fontSize="8" leading="10" textColor="navy" spaceBefore="12"/>
    <paraStyle name="intro"  fontName="Helvetica" fontSize="12" leading="12" spaceAfter="12"/>
  </stylesheet>
  <story>
  <setNextTemplate name="main2"/>
  <storyPlace x="35" y="660" width="525" height="73" origin="page">
<para style="intro">RML (Report Markup Language) is ReportLab's own language for specifying the appearance of a printed page, which is converted into PDF by the utility rml2pdf.</para>
<hr color="white" thickness="8pt"/>
<para style="intro">These RML samples showcase techniques and features for generating various types of ouput and are distributed within our commercial package as test cases. Each should be self explanatory and stand alone.</para>
<illustration height="3" width="525" align="center">
<fill color= "(0,0.99,0.97,0.0)" />
<rect x="0" y = "-12" width="525" height="3" round="1" fill="1" stroke = "Yes" />
</illustration>
</storyPlace>
    <para style="h1">Diagra Integration</para>
    <para style="normal">Diagra is ReportLab's charting and data graphics product.  It allows charts and
    data graphics to be prepared visually in a Drawing Editor, and used in a variety of contexts including
    within RML, as bitmaps on the web, and for generating batches of EPS files.</para>
    <para style="h1">Referring to a Drawing Module</para>
    <para style="normal">The first stage is to use the drawing editor to create a drawing module. Take note
    of the class name as you generate it.  You can then refer to it directly with a drawing tag.
    The drawing tag takes at least two parameters.  The <font face="Courier" color="navy">module</font>attribute holds the 
    name of the module the drawing is defined
    in.  This is a normal python module reference as used with the import statement, and may contain dots to refer to
    items anywhere on the path e.g. <font face="Courier" color="navy">reportlab.graphics.charts.barcharts</font>.  The
    directory where the RML document lives will always be on the path, so if your graphic is in the
    same directory, you can just use the filename (minus extension).  The second attribute,
    <font face="Courier" color="navy">function</font>, is the name of the constructor to call.  If you used the Drawing
    Editor, insert the class name of the drawing here.  You could also call an arbitrary Python function which returns a Python
    object; often it is convenient to write helper functions to set up your drawings outside of RML.  Finally, there is a third optional argument     baseDir, which contains
    a directory name to look under<i>This must be escaped with double slashes on Windows e.g. C:\\mycharts</i>. 
    We included a chart module <i>scatterplot.py</i> in this test directory containing a class <i>ScatterPlotDrawing</i>, 
    so for our example we will just refer so let's refer to it now:</para>
    <xpre style="code">&lt;drawing module="test_014_scatterplot" function="ScatterPlotDrawing" /&gt;</xpre>
    <drawing module="test_014_scatterplot" function="ScatterPlotDrawing"/>
    <para>It's important to recognize that the Diagra framework is completely general and not necessarily for charts.  We use it to crank out ReportLab logos with variable sizes and colors!  So, let's show one more example, which is about the simplest data graphic we have:  a 'slidebox' which accepts one numeric parameter:</para>
    <xpre style="code">&lt;drawing module="test_014_slidebox" function="SlideBoxDrawing" /&gt;</xpre>
    <drawing module="test_014_slidebox" function="SlideBoxDrawing"/>
    <para style="h1">Making it dynamic</para>
    <para>Static charts are not much use to anyone.  In most cases, you will want to pass in the numeric data at runtime, and perhaps change the title.  The Diagra framework is completely general  - not a charting framework per se - and lets you set any attribute of any object within the chart; so you could set the height of a bar or something similar.  Let's start with an ultra-simple example.  The above SlideBox takes a single numeric parameter.  In general you should use the drawing editor to explore the available parameters.  </para>
    <xpre style="code">
&lt;drawing module="test_014_slidebox" function="SlideBoxDrawing" &gt;
    &lt;param name="SlideBox.trianglePosition"&gt;4&lt;/param&gt;
&lt;/drawing&gt;
  </xpre>
    <drawing module="test_014_slidebox" function="SlideBoxDrawing">
      <param name="SlideBox.trianglePosition">4</param>
    </drawing>
    <nextFrame/>
    <para>The most common use of the param tag will be to set the dynamic data for a chart. For example,
    let's take the preceding one and pass in some data.  The Drawing Editor will reveal that the
    data parameter for scatter plot is a list of sequences of x-y pairs, so we make
    up our data nested this way (you can use square or round brackets, it doesn't matter):</para>
    <xpre style="code">    
    &lt;drawing module="test_014_scatterplot" function="ScatterPlotDrawing"&gt;
      &lt;param name="ScatterPlot.data"&gt;[((0.03, 50), (0.04, 54), (0.05, 43)), 
                                      ((0.03, 27), (0.04, 32), (0.055, 15))]&lt;/param&gt;
      &lt;/drawing>
  </xpre>
    <drawing module="test_014_scatterplot" function="ScatterPlotDrawing">
      <param name="ScatterPlot.data">[((0.03, 50), (0.07, 54), (0.09, 43)), ((0.03, 27), (0.07, 32), (0.08, 15))]</param>
    </drawing>
    <para>The content of each param tag is evaluated literally.  This is more compact and easier
    to generate and parse than generating thousands of series and data-point tags.</para>
    <para>You can also modify other parameters which are nothing to do with numeric data,
    just as you do in the Drawing Editor.  Let's force the x axis to include the zero, so the 
    leftmost points do not dangle in the margin, and change the title below the y axis:
    </para>
	<para>Parameters passed through to charts may now contain the standard
XML escapes for '&amp;','&lt;' and '&gt;'.  However, unicode font handling
for charts and graphics is not yet complete; non-ASCII characters
such as copyright and trademark which are passed in through RML 
may be displayed as multiple bytes of garbage when displayed in a 
Type 1 Font.  We believe that the graphics are the last remaining 
area of our framework that needs unicode-enabling and hope to
complete this in a release next week.
	</para>
	<para>The PDF rendering for the standard numeric escapes eg &amp;#2122; is carried out, but will only work in
		param tags if the relevant objects font understands them. This should be the case for TTF fonts if the document encoding is "utf-8". See
	the example below where you should see <font face="VeraItalic">&lt;&amp;&#x2122;&#174;&#169;&gt;</font> in the x axis label.
	</para>
    <xpre style="code">
      &lt;drawing module="test_014_scatterplot" function="ScatterPlotDrawing"&gt;
        &lt;param name="ScatterPlot.height"&gt;50&lt;/param&gt;
        &lt;param name="ScatterPlot.xValueAxis.labels.fontName"&gt;VeraItalic&lt;/param&gt;
        &lt;param name="ScatterPlot.xLabel"&gt;Implied Volatility (to end Q3 2003)&amp;lt;&amp;amp;&amp;#x2122;&amp;#174;&amp;#169;&amp;gt;&lt;/param&gt;
        &lt;param name="ScatterPlot.xValueAxis.forceZero"&gt;1&lt;/param&gt;
        &lt;param name="ScatterPlot.data"&gt;
          [((0.03, 50), (0.07, 54), (0.09, 43)), ((0.03, 27), (0.07, 32), (0.08, 15))]
        &lt;/param&gt;
      &lt;/drawing&gt;
  </xpre>
    <drawing module="test_014_scatterplot" function="ScatterPlotDrawing">
      <param name="ScatterPlot.height">50</param>
	  <param name="ScatterPlot.xValueAxis.labels.fontName">VeraItalic</param>
	  <param name="ScatterPlot.xLabel">Implied Volatility (to end Q3 2003)&lt;&amp;&#x2122;&#174;&#169;&gt;</param>
      <param name="ScatterPlot.xValueAxis.forceZero">1</param>
      <param name="ScatterPlot.data">[((0.03, 50), (0.07, 54), (0.09, 43)), ((0.03, 27), (0.07, 32), (0.08, 15))]</param>
    </drawing>
    <para style="h1">Alignment and Boundaries</para>
    <para style="normal">It is convenient to be able to align the drawings, and sometimes you want to
    see where they are on the page.  The <b>hAlign</b> attribute takes values of <b>LEFT</b>, <b>RIGHT</b>,
    <b>Center</b> and (for the sake of the Brits who maintain the software) <b>CENTRE</b>.  The default
    is CENTER.  Here is a right aligned drawing with a boundary:</para>
    <xpre style="code">&lt;drawing module="test_014_slidebox" function="SlideBoxDrawing" 
        hAlign="RIGHT" showBoundary="1"/&gt;</xpre>
    <drawing module="test_014_slidebox" function="SlideBoxDrawing" hAlign="RIGHT" showBoundary="1"/>
    <para style="normal">If you want fine-grained control of the border, we suggest to implement
    suitable rectangles within your Drawing.</para>
    <nextFrame/>
    <para style="h1">Adding widgets and dynamic graphic creation</para>
    <para style="normal">There is a <b>widget</b> tag which permitted on-the-fly creation of drawings and adding things
    to groups.</para>
    <para style="normal">What follows is advanced and will probably be easiest understood if you (a) have Python skills,
    or (b) look at one of the source files in the drawin editor.</para>
    <para style="normal">You can add shapes and widgets to drawings at runtime.  In fact, you can even start with
    a bare-bones drawing and build it up from nothing.  In general it is MUCH easier to do this in
    the Drawing Editor and just change the numeric data at runtime.  
    </para>
    <para style="normal">In the example below, we have taken our Scatter Plot and added a title at the top.
    In addition, to make it a bit easier to see where the boundaries are, I have added a thin border
    around the edge of the drawing using a rectangle widget.  The <b>param</b> tag is used to set the
    added widgets.
    </para>
    <xpre style="code">
    &lt;drawing module="test_014_scatterplot" function="ScatterPlotDrawing"&gt;
      &lt;param name="ScatterPlot.height"&gt;50&lt;/param&gt;
      &lt;param name="ScatterPlot.xLabel"&gt;Implied Volatility (to end Q3 2003)&lt;/param&gt;
      &lt;param name="ScatterPlot.xValueAxis.forceZero"&gt;1&lt;/param&gt;
      &lt;param name="ScatterPlot.data"&gt;[((0.03, 50), (0.07, 54), (0.09, 43)), 
                ((0.03, 27), (0.07, 32), (0.08, 15))]&lt;/param&gt;

      &lt;widget module="reportlab.graphics.shapes" function="String" name="title" 
            initargs="87.5,90,'My Plot Title'"/&gt;
      &lt;param name="title.fontName"&gt;Helvetica&lt;/param&gt;

      &lt;widget module="reportlab.graphics.shapes" function="Rect" name="border" 
            initargs="0,0,175,105"/&gt;
      &lt;param name="border.fillColor"&gt;None&lt;/param&gt;
      &lt;param name="border.strokeColor"&gt;reportlab.lib.colors.black&lt;/param&gt;      
    &lt;/drawing>

    </xpre>
    <drawing module="test_014_scatterplot" function="ScatterPlotDrawing">
      <param name="ScatterPlot.height">50</param>
      <param name="ScatterPlot.xLabel">Implied Volatility (to end Q3 2003)</param>
      <param name="ScatterPlot.xValueAxis.forceZero">1</param>
      <param name="ScatterPlot.data">[((0.03, 50), (0.07, 54), (0.09, 43)), ((0.03, 27), (0.07, 32), (0.08, 15))]</param>
      <widget module="reportlab.graphics.shapes" function="String" name="title" initargs="87.5,90,'My Plot Title'"/>
      <param name="title.fontName">Helvetica</param>
      <widget module="reportlab.graphics.shapes" function="Rect" name="border" initargs="0,0,175,105"/>
      <param name="border.fillColor">None</param>
      <param name="border.strokeColor">reportlab.lib.colors.black</param>
    </drawing>
    <para style="normal">This last one illustrates a "feature":  it is possible for drawings to draw out
    of the box, as the data point does on the left.  Obviously, if you ask Diagra to make a bitmap
    file on disk, this is cut off; but in RML documents it leaks out.  You should design your drawings
    to leave adequate space for the longest expected data labels.
    </para>
	<nextFrame/>
    <para style="h1">Drawings in graphics mode</para>
	<graphicsMode borderStrokeColor="red" borderStrokeWidth="1" origin="frame">
	<stroke width="0.5" color="blue"/>
	<drawingGraphic x="10" y="536" anchor="w" module="test_014_graphic" function="Graphic">
		<param name="s.text">anchor='w'</param>
	</drawingGraphic>
	<drawingGraphic x="154" y="536" anchor="c" module="test_014_graphic" function="Graphic">
		<param name="s.text">anchor='c'</param>
	</drawingGraphic>
	<drawingGraphic x="398" y="536" anchor="e" module="test_014_graphic" function="Graphic">
		<param name="s.text">anchor='e'</param>
	</drawingGraphic>
	<drawingGraphic x="10" y="464" anchor="sw" module="test_014_graphic" function="Graphic">
		<param name="s.text">anchor='sw'</param>
	</drawingGraphic>
	<drawingGraphic x="154" y="464" anchor="s" module="test_014_graphic" function="Graphic">
		<param name="s.text">anchor='s'</param>
	</drawingGraphic>
	<drawingGraphic x="398" y="464" anchor="se" module="test_014_graphic" function="Graphic">
		<param name="s.text">anchor='se'</param>
	</drawingGraphic>
	<drawingGraphic x="10" y="392" anchor="nw" module="test_014_graphic" function="Graphic">
		<param name="s.text">anchor='nw'</param>
	</drawingGraphic>
	<drawingGraphic x="154" y="392" anchor="n" module="test_014_graphic" function="Graphic">
		<param name="s.text">anchor='n'</param>
	</drawingGraphic>
	<drawingGraphic x="398" y="392" anchor="ne" module="test_014_graphic" function="Graphic">
		<param name="s.text">anchor='ne'</param>
	</drawingGraphic>
	<stroke color="red"/>
	<lines>10 534 10 538 8 536 12 536</lines>
	<lines>154 534 154 538 152 536 156 536</lines>
	<lines>398 534 398 538 396 536 400 536</lines>
	<lines>10 462 10 466 8 464 12 464</lines>
	<lines>154 462 154 466 152 464 156 464</lines>
	<lines>398 462 398 466 396 464 400 464</lines>
	<lines>10 390 10 394 8 392 12 392</lines>
	<lines>154 390 154 394 152 392 156 392</lines>
	<lines>398 390 398 394 396 392 400 392</lines>
</graphicsMode>

<para>The <b>&lt;drawingGraphic&gt;</b> is the equivalent of the <b>&lt;drawing&gt;</b> tag that can be used in graphics mode. It has extra attributes <b>x</b>, <b>y</b> and <b>anchor</b>.</para>

  </story>
</document>
