Printout Format

Version: 0.10.0    Date: 10-oct-2021

Contents

• Introduction
• Types of element attributes
  • Booleans · Colors · Dimensions · Timestamps
• Printout elements
  • printout · data · font · page · box
  • text · line · rectangle · image · barcode
  • outline · xref

Introduction

PythonReports Printout files are "built" reports, ready to be rendered with a frontend driver. Printouts are stored in XML files with extension .PRP.

This document describes printout structures.

The overall structure of printouts is very simple: printout contains one or more page elements, and each page contains text, line, rectangle, image, barcode, outline, and xref elements, each having its final dimensions and placement.

printout element also contains font definitions and may contain named data elements providing bitmaps for repeated images.

Printouts are produced by the report builder from a report template.

Types of element attributes

This section explains special attribute types used in element descriptions.

Booleans

Values true, yes, and 1 stand for boolean True, values false, no, and 0 stand for boolean False. Recommended form is true and false.

Colors

Color values may be specified in one of the following forms:

• 6-digit hexadecimal number prefixed by a hash mark (HTML format),

• color name from the following dictionary (case insensitive),

• three integer values: red, green, blue (0..255),

• three float values: red, green, blue (0..1),

• single integer value, where

  • the red component is in bits 16-23,
  • the green component is in bits 8-15,
  • the blue component is in bits 0-7.

Recommended form is the first one.

Standard color names:

Name	Value
BLACK	#000000
SILVER	#C0C0C0
GRAY	#808080
WHITE	#FFFFFF
MAROON	#800000
RED	#FF0000
PURPLE	#800080
FUCHSIA	#FF00FF
GREEN	#008000
LIME	#00FF00
OLIVE	#808000
YELLOW	#FFFF00
NAVY	#000080
BLUE	#0000FF
TEAL	#008080
AQUA	#00FFFF
CYAN	#00FFFF
DARKGRAY	#404040
LIGHTGRAY	#C0C0C0
MAGENTA	#FF00FF
ORANGE	#FFC800
PINK	#FFAFAF

Dimensions

All report dimensions (page and field sizes, margins, etc.) are expressed as integer or floating point numbers with optional suffix:

• mm — millimeters,
• cm — centimeters,
• in — inches,
• pt — points (1/72 inch).

If suffix is omitted, dimension is in points.

It is recommended to always use integral points for all dimensions to avoid rounding errors.

The origin of the coordinate system (0,0) is always in the left upper corner of a container (page or section).

Timestamps

Dates and times are recorded in ISO format, e.g. 2006-06-14T14:20:47.

Printout elements

This chapter contains informal descriptions of the printout elements.

In element attribute tables, the second column (Req) shows whether the attribute is required: M for mandatory attributes, O for optional ones.

All elements and attributes not mentioned here are ignored by PythonReports. Element contents (text) are ignored except for data elements.

printout

The root element of the printout tree. Contains elements of types font, data, and page.

Attributes:

Name	Req	Type	Description
name	O	string	Report name. (1)
description	O	string	Description of the report. (1)
version	O	string	Report version. (1)
author	O	string	Author name. (1)
basedir	O	string	Base directory for image file paths. Default: directory containing printout file.
built	O	timestamp	Date and time of report build.

Notes:

1. Copied from report template.

data

Contains arbitrary data for use in image elements.

This is the only element in PythonReports printouts that has significant body text; for all other elements body text is ignored.

Attributes:

Name	Req	Type	Description
name	(1)	string	Data reference needed to use the data in elements other than immediate parent element.
compress	O	string	zlib or bz2.
encoding	O	string	base64, uu or qp.

Notes:

1. Ignored when immediate parent element is image; required otherwise.

font

Font definition for use in text blocks.

Attributes:

Name	Req	Type	Description
name	M	string	Local name of font definition. Used as font reference in text blocks.
typeface	M	string	Typeface name.
size	M	integer	Font size in points.
bold	O	boolean	True for bold fonts.
italic	O	boolean	True for italic fonts.
underline	O	boolean	True for underlined text.

page

Single output page. Child elements are outline, text, line, rectangle, image, and barcode.

Attributes:

Name	Req	Type	Description
width	M	dimension	Page width (including margins).
height	M	dimension	Page height (including margins).
leftmargin	M	dimension	Left page margin.
rightmargin	M	dimension	Right page margin.
topmargin	M	dimension	Top page margin.
bottommargin	M	dimension	Bottom page margin.

box

Required child for all elements placed in pages, i.e. text, line, rectangle, image, and barcode.

Attributes:

Name	Req	Type	Description
x	M	dimension	Horizontal position of the left side.
y	M	dimension	Vertical position of the element top.
width	M	dimension	Element width.
height	M	dimension	Element height.

text

A textual block. The text to print is contained in child data element.

Attributes:

Name	Req	Type	Description
font	M	string	Name of the font definition.
align	O	string	Text alignment: left, center, right, or justified. Default: left.
color	M	color	Text color.

line

Draw a line.

Attributes:

Name	Req	Type	Description
pen	M	dimension or string	Line style: width of the line or one of dot, dash, dashdot.
color	M	color	Line color.
backslant	O	boolean	When both box dimensions are non-zero, draw the line from upper left corner to lower right one — \ instead of /.

rectangle

Draw a rectangle.

Attributes:

Name	Req	Type	Description
pen	M	dimension or string	Outline style: width of the line or one of dot, dash, dashdot. Use 0 to disable outline.
pencolor	M	color	Outline color.
color	O	color	Fill color. If omitted, the rectangle is transparent.
radius	O	dimension	Corner radius for rounded rectangles. Default: 0

image

Place bitmap image. The bitmap may be loaded from a file or from a data element (either put in the image element or referred by the data attribute).

Attributes:

Name	Req	Type	Description
type	M	string	Image type, e.g. jpeg or png.
file	O	string	Image file path. If specified, the data is ignored unless the file cannot be loaded.
data	O	string	Name of a data section defined as a child of the printout element.
scale	O	boolean	If False (default), the image is cut to box dimensions. If True, the bitmap is scaled to the box.

barcode

Draw a bar code image.

Attributes:

Name	Req	Type	Description
type	M	string	Code128, Code39, 2of5i, Aztec, QR-L, QR-M, QR-Q, or QR-H.
value	M	string	The text encoded with the bar code.
stripes	M	list of integers	Precomputed bar code: comma-delimited sequence of alternating mark and blank widths, starting from blank for leading quiet zone. With two-dimensional bar codes, one comma-delimited list represents one scan line of the code, and lists for several lines are separated with spaces.
module	O	number	X dimension, in mils (1/1000 inch). Default: 10.0.
vertical	O	boolean	If True, the image is rotated 90 degrees clockwise. Ignored for 2D codes (Aztec and QR).

outline

A bookmark in the document navigation pane.

Some printout rendering front-ends may support navigation inside document contents. (For example, PDF documents have an outline pane.) The outline element defines an entry in such navigation tree.

Attributes:

Name	Req	Type	Description
name	M	string	An identifier for the bookmark. Must be unique within the document.
title	M	string	Caption text for the outline tree.
level	O	integer	An outline nesting level. The outermost level (default) is 1. Nested levels have bigger numbers. The level number must be increased by one when a nested level is created: going from 1 to 3 without 2 is an error.
closed	O	boolean	True to display the outline closed at this entry (i.e. hide all nested levels).
x	O	dimension	Horizontal position (Default: 0).
y	O	dimension	Vertical position (Default: 0).

xref

A hyperlink to an external resource or an outline entry.

xref elements contain one box element, and a sequence of text, line, rectangle, image, and barcode elements.

Attributes:

Name	Req	Type	Description
type	M	string	url or outline.
target	M	string	An external resource URL for type url, or a name of an outline entry for type outline.
caption	O	string	Optional text to assign to the link. The text is not shown in PDF, but may be used by other front-ends.