Package ca.spatial.reportwriter

Class MapLayoutReport

java.lang.Object
ca.spatial.reportwriter.Report
ca.spatial.reportwriter.MapLayoutReport
All Implemented Interfaces:
Selectable<Report>, Comparable<Report>
public class MapLayoutReport extends Report
A MapLayout report prepares multi-page reports consisting of maps, charts, tables and other features. Although initially intended for medium quality automated map production, the MapLayoutReport is a flexible tool for many kinds of complex reports. Layouts are composed of a series of elements, such as charts, maps, legends, scale bars, north arrows, text boxes, etc.

NOTE: THIS CLASS IS IN ALPHA STATUS AND THE API IS SUBJECT TO CHANGE. USE AT YOUR OWN RISK. This version is being provided as a technology preview. Features may be added or removed as this technology is improved.

LayoutReports may be rendered as PNG images or PDF files. When producing a layout in PNG format only the first page defined in the report will be rendered. The PDF format provides a number of useful navigation features such as a table of contents, selectable layers, bookmarks, and in the case of map layers, embedded and selectable attribute data.

MapLayoutReports are composed of a hierarchical tree of graphics and container objects. The main branches of the tree are pages. Pages act as containers to hold report objects such as text boxes and map layers. Some elements (e.g. MapLayoutReport.Group, MapLayoutReport.Grid) are containers themselves, and can be used to group elements together.

The process to create a Layout Report is to first create the base MapLayoutReport object. Within this object add pages, and within the pages add the desired graphics elements. Use the grouping elements to assist with alignment, spacing and formatting. Once all of the elements have been added the ReportWriter will produce the report upon request.

Pages are added to reports using the page() or page(double, double) command. The first form adds a page using the default size specified when the report was created. The second form uses an explicit page size.

Once a page is created, use the methods provided by the MapLayoutReport.Page object to add graphics and formatting elements. Here is an example of a simple LayoutReport: 


// Create the layout object specifying inches as the layout units
r = new MapLayoutReport("sample.pdf", "Sample Layout Report", 
                            MapLayoutReport.INCH, 23.39, 33.11, "")

    // Add a page with specified neatline, margin and insets
   .page().neatline(1).margin(0.5).inset(0.5)

     // Add a group so that the set may be selectively displayed or hidden
     .addGroup("Base Features")

       // Add the map layer and legend.  The layerList is the same
       // as for the MapReport
       .addMap(0, 0, 21.39, 31.11, "Sample Features", layerList2, 0).inset(0.1).p()
       .addLegend(1, 8.3, 5, -1, "Sample Features Legend", -1).background(Color.white).inset(0.4).p().p()
   
     // Add a group to hold the ornamentation
     .addGroup("Map Surrounds")
       .addScalebar(1, 16, 5, 2, "Scale bar", 0).title("Kilometers").showRatio(true).background(Color.white).inset(0.5).p()
       .addText(1, 4.6, 8, 4, "Title", "Title goes here").vertical(MapLayoutReport.TOP).background(Color.white).inset(0.2).p()
       .addNorthArrow(5, 16, 2, 2, "North Arrow", 0).background(Color.white).inset(0.5).p()
       .addText(0, 30.3, 6, 1.1, "Credits", "<html><center><i>I made this map</i></center></html>")
         .background(Color.white).horizontal(MapLayoutReport.LEFT).inset(0.2)
   
   // Return the report object
   .r();

// Add the layout report to the report writer
reportWriter.addReport(r);

Fluid style

The above example shows the LayoutReport being created using a 'fluid' programming style. This style creates the report and adds the graphics elements all in a single statment. Each of the methods returns an object, and the next method is chained on to that object.

Some methods will create and return a new object, such as the page() method. Many of the formatting methods simply return a reference to the same object as they are operating on (such as the background() method). As well there are methods (e.g MapLayoutReport.MapElement.p(), MapLayoutReport.MapElement.r()) that traverse back up the hierarchy of Group and Page container objects. In the above example most objects are terminated with a p() method which returns to the parent object. Sometimes there will be two p() methods calls in a row, in order to ascend out of both the object and the group that the object is in. The basis for the fluid style is that every method operates on the object provided by the previous methods, and returns an object reference used by the next method.

The traditional programming style uses more intermediate variables and statements are separated by semicolons. Here below is an example of the non-fluid style for the same report as above. The result is the same, but the syntax is more verbose and explicit. The choice of which style to use is largely a matter of taste and the two styles may be mixed. The traditional style may be required in scripts that perform looping or conditional flow control. 


// Create the layout object specifying inches as the layout units
r = new MapLayoutReport("sample.pdf", "Sample Layout Report", 
                            MapLayoutReport.INCH, 23.39, 33.11, "");

// Add a page with specified neatline, margin and insets
p1 = r.page();
p1.neatline(1).margin(0.5).inset(0.5);

// Add a group so that the set may be selectively displayed or hidden
g1 = p1.addGroup("Base Features");

// Add the map layer and legend.  The layerList is the same
// as for the MapReport
g1.addMap(0, 0, 21.39, 31.11, "Sample Features", layerList2, 0).inset(0.1);
g1.addLegend(1, 8.3, 5, -1, "Sample Features Legend", -1).background(Color.white).inset(0.4);
   
// Add a group to hold the ornamentation
g2 = p1.addGroup("Map Surrounds");
g2.addScalebar(1, 16, 5, 2, "Scale bar", 0).title("Kilometers").showRatio(true).background(Color.white).inset(0.5);
g2.addText(1, 4.6, 8, 4, "Title", "Title goes here").vertical(MapLayoutReport.TOP).background(Color.white).inset(0.2);
g2.addNorthArrow(5, 16, 2, 2, "North Arrow", 0).background(Color.white).inset(0.5);
g2.addText(0, 30.3, 6, 1.1, "Credits", "<html><center><i>I made this map</i></center></html>")
         .background(Color.white).horizontal(MapLayoutReport.LEFT).inset(0.2);
   
// Add the layout report to the report writer
reportWriter.addReport(r);

Object hierarchy

All of the elements that can be placed within a layout descend from the MapLayoutReport.MapElement object. The MapElement class contains the following methods for navigation up the object hierachy:
Navigation elements
MethodPurpose
pReturn a reference to the parent container object. Using this reference you may add more elements to the same container.
topReturn a reference to the topmost container that holds all of the pages in the document. From this object you may add more pages to the document.
rReturn a reference to the report object. Ultimately this reference must be added to a ReportWriter in order to be useful.

In addition to navigation methods, map elements also have formatting methods to set appearance and control other PDF features. The following methods are available to all map elements. All of these methods return a reference to the object being operated on, and may be chained together.

Appearance and PDF control elements
MethodPurpose
marginSet a margin around the element. The background and neatline will be drawn within the margin.
backgroundSet the background colour of the element.
neatlineDraw a neatline around the element.
insetSet a margin within the neatline. The element content will render within the inset.
visibleSpecify that the element should initially be set to invisible. The visibility status may be changed interactively in the PDF table of contents.
hiddenSpecify that the element should not have an entry in the PDF table of contents. The element will be displayed in the layout, but will not appear in the TOC.
bookmarkSpecify that the element should be bookmarked in the PDF bookmark list.
zoomSpecify a zoom factor for the element. This will influence the size of fonts and line thicknesses for some objects.

Additional methods are available to query the status of each map element. See the MapLayoutReport.MapElement documentation for details.

MapLayoutReport.Page elements inherit from the MapLayoutReport.Group element. Groups (and Pages) may contain graphic elements as well as other group containers. The following methods may be used to add elements to a group. Most of these methods require a position to place the graphic object, in the form of a starting x/y location of the top left corner (relative to the container insets), and a width and height (all specified in page units). Many also require a label that uniquely identifies the object.

Graphic elements
MethodPurpose
addTextAdd a text box
addReportChartAdd a chart from an already defined report
addReportTableAdd a table from an already defined report
addNorthArrowAdd a north arrow ornamentation
addLegendAdd a legend box based on a map layer list
addMapAdd a map based on a map layer list
addScalebarAdd a scalebar
addCircleAdd a circle
addEllipseAdd an ellipse
addRectangleAdd a rectangle
addRoundedRectangleAdd a rounded rectangle
addLineAdd a line
addGroupAdd a group container
addGridAdd a grid container

Check the MapLayoutReport.Group element for a description of these methods and their parameters.

Page units

Page sizes and graphic element positional information (upper left starting positions and sizes) are specified using a measurement system that is selected when the report is created. The following measurement systems may be used:
Measuring systems
NameSystem
MapLayoutReport.INCHImperial inches
MapLayoutReport.CMCentimetres
MapLayoutReport.FEETImperial feet
MapLayoutReport.METREMETRE

Substitution values

Several special values are available to be used in text boxes. These values will be substituted in to the text when the following symbols are encountered:
Substitution values
SymbolValue
{%_title%}The report title
{%_date%}The current date when the report is rendered
{%_datetime%}The current date and time when the report is rendered
{%_filename%}The filename for the report
{%_metadata%}Scenario metadata
{%_description%}The description provided in the ScenarioSet.

In addition to these symbols, any additional query values used when the report is created are also available. For example the scenario name is available using the "{%scenario%}" symbol.

Here is an example of using the {%_title%} variable to display the report title within the layout: 

g2.addText(1, 4.6, 8, 4, "Title", "<html><center><h2>{%_title%}</h2>Reports details</center></html>")
    .vertical(MapLayoutReport.TOP).background(Color.white).inset(0.2);

Working with groups and grids

You must specify the position of the upper left corner when you add any map element to a page or group (note that a page is a specialized group). The position is specified in the appropriate page units, and is relative to the upper left corner of the insets of the containing group.

When you position a group within a page or another group, all of the element position references become relative to that group. If you move the group to a different position, then all of the element positions will remain in the same relative position to the new location of the group.

MapLayoutReport.Grid elements are a special type of group that partition the space in the group in to panes. The number of rows and columns in the grid is specified in the method call, as are the propotional sizes of the rows and columns. Once the grid is created then panes (or rectangular selections of panes) may be selected using the MapLayoutReport.Grid.pane(int, int) methods. These object return a group object that is positioned over the selected panes of the grid.

  • Field Details

    • PIXEL

      public static final int PIXEL
      Constant representing units of measure in pixels
      See Also:
      Constant Field Values

    • INCH

      public static final int INCH
      Constant representing units of measure in inches
      See Also:
      Constant Field Values

    • FEET

      public static final int FEET
      Constant representing units of measure in feet
      See Also:
      Constant Field Values

    • MILE

      public static final int MILE
      Constant representing units of measure in miles
      See Also:
      Constant Field Values

    • CM

      public static final int CM
      Constant representing units of measure in centimetres
      See Also:
      Constant Field Values

    • METRE

      public static final int METRE
      Constant representing units of measure in metres
      See Also:
      Constant Field Values

    • KM

      public static final int KM
      Constant representing units of measure in kilometres
      See Also:
      Constant Field Values

    • LEFT

      public static final int LEFT
      Constant representing a left alignment
      See Also:
      Constant Field Values

    • CENTER

      public static final int CENTER
      Constant representing a center alignment
      See Also:
      Constant Field Values

    • TOP

      public static final int TOP
      Constant representing a top alignment
      See Also:
      Constant Field Values

    • BOTTOM

      public static final int BOTTOM
      Constant representing a bottom alignment
      See Also:
      Constant Field Values

    • TYPES

      public String[] TYPES
      An array containing the sub-types produced by this report. The MapLayoutReport may produce a PDF file, in which case the type fields will be null. Otherwise it may produce a PNG image file, in which the types will be "html" and "png".

  • Constructor Details

    • MapLayoutReport

      public MapLayoutReport​(String filename, String title, int pageunits, double width, double height, String htmlText)
      Create the base MapLayoutReport object. This object is a container for pages, and the pages contain the objects to be drawn.

      Parameters:
      filename - the file name in the report writer
      title - the report title
      pageunits - the units to use to reference locations on the page. May be PIXEL, INCH, FEET, MILE, CM, METRE or KM.
      width - the default page width for new pages
      height - the default page height for new pages
      htmlText - optional html data the is included if the output is formatted as png.

  • Method Details

    • getFullFilename

      public String getFullFilename()
      Return the file name of this report

    • setHtmlText

      public void setHtmlText​(String htmlText)
      Set the HTML text that will accompany PNG format reports
      Parameters:
      htmlText - the text to display on the PNG report

    • getHtmlText

      public String getHtmlText()
      Get the HTML text used to accompany PNG format reports

    • getWidth

      public double getWidth()
      Get the default page width

    • getHeight

      public double getHeight()
      Get the default page width

    • getPageUnits

      public int getPageUnits()
      Get the page units used in this report, as an integer constant

    • getPageUnitsString

      public static String getPageUnitsString​(int pageunits)
      Get the page units string for an integer constant
      Parameters:
      pageunits - an integer code for a page unit system

    • getMapElement

      public MapLayoutReport.TopGroup getMapElement()
      Get the baseline map element group. This is the group that map elaments can be added to.

    • page

      public MapLayoutReport.Page page()
      Start a new page in the top level group, using the default page size

    • page

      public MapLayoutReport.Page page​(double width, double height)
      Start a new page in the top level group, using the specified page size
      Parameters:
      width - the default page width
      height - the default page height

    • getMapper

      public MapLayoutReport.Mapper getMapper​(int index)
      Return a reference to a previously defined map. If the index number if ge 0, then return the map defined in the sequential order starting at 0. If the index value is lt 0, then return the return the map defined in reverse sequential order. For example, if index = 0 then return the first map. If index is -1 then return the most recently defined map.
      Parameters:
      index - the index of the mapper to return

    • doReport

      public ca.spatial.reportwriter.Report.DataCache doReport​(String name, PrintStream out, Map<String,​Object> param, ca.spatial.reportwriter.Report.DataCache cache)
      Description copied from class: Report
      The method used by the report writer to format the requested report. This method is implemented in every custom report. Application programs generally do not need to call this method, but instead use the report writer methods to obtain reports.
      Specified by:
      doReport in class Report
      Parameters:
      name - The full name of the report to be printed, including the extension of the sub-report (if any).
      out - The output stream to print output on to.
      param - A HashMap containing parameters that modify the report (for example the scenario name).

    • getTypes

      public String[] getTypes()
      Description copied from class: Report
      An accessor function to retrieve the list of report types supported by this report. See the documentation for the TYPES variable for the list of sub-types.
      Specified by:
      getTypes in class Report