Difference between revisions of "Report API"

From Gramps
Jump to: navigation, search
m
Line 22: Line 22:
  
 
===Page===
 
===Page===
Description of the paper, which every report will be rendered on, is stored by an instance of the [http://www.gramps-project.org/api3/BaseDoc.PaperStyle-class.html PaperStyle class]. This instance is available via the <tt>BaseDoc.paper_style</tt> class attribute. The chosen PaperStyle is given to the document generator at initialization, and is handled by the reporting framework.
+
[[Image:Doc_paper.png|thumbnail]] Description of the paper, which every report will be rendered on, is stored by an instance of the [http://www.gramps-project.org/api3/BaseDoc.PaperStyle-class.html PaperStyle class]. This instance is available via the <tt>BaseDoc.paper_style</tt> class attribute. The chosen PaperStyle is given to the document generator at initialization, and is handled by the reporting framework.
  
 
Text reports do not need to care about paper properties, as the document generator (or the external viewer) paginates the report according to those properties. While, on the other hand, graphical reports do need to take paper properties into account when creating graphical elements.
 
Text reports do not need to care about paper properties, as the document generator (or the external viewer) paginates the report according to those properties. While, on the other hand, graphical reports do need to take paper properties into account when creating graphical elements.
[[Image:gramps-devel.png|left|22px]] ''document generator should hide paper properies for graphical reports too'' <br/>
+
[[Image:gramps-devel.png|left|22px]] ''document generator should hide paper properies for graphical reports too''<br/><br/>
 +
The <tt>PaperStyle</tt> holds information on the size of the paper ([http://www.gramps-project.org/api3/BaseDoc.PaperSize-class.html PaperSize class] instance), the size of the margins, and the orientation of the paper. Use the proper accessor methods to get the values. To get the metrics of the usable area of a page one can also use the [http://www.gramps-project.org/api3/BaseDoc.PaperStyle-class.html#get_usable_width PaperStyle.get_usable_width] and [http://www.gramps-project.org/api3/BaseDoc.PaperStyle-class.html#get_usable_height PaperStyle.get_usable_height] convenience methods.
 +
<br clear="all" />
  
 
==Text document API==
 
==Text document API==
  
 
==Graphical document API==
 
==Graphical document API==

Revision as of 14:30, 24 September 2007

Gnome-important.png

This is still a draft. Please don't link to it yet!

In GRAMPS there are six different types of reports.

  • Text report
  • Graphical report
  • Book report
  • Code generators
  • Web page generator
  • View only report

Only Text reports and Graphical reports use the Report (Document) API, since the latter three directly write their output into file(s) or onto the screen, while Book reports are simply combination of Text reports and Graphical reports.

Common API

At the moment the combination of textual and graphical elements within one document is not supported (for future plans refer to Report API redesign), thus Text and Graphical reports are implemented via separate APIs, though they have a common part. This common part is implemented in the BaseDoc class, which contains among others basic document opening, closing, and stylesheet handling methods. It also stores the physical description of a page (sheet of paper in print).

Note! The BaseDoc.open and the BaseDoc.close methods have to be implemented by the subclassed document generators.

Page

Doc paper.png

Description of the paper, which every report will be rendered on, is stored by an instance of the PaperStyle class. This instance is available via the BaseDoc.paper_style class attribute. The chosen PaperStyle is given to the document generator at initialization, and is handled by the reporting framework.

Text reports do not need to care about paper properties, as the document generator (or the external viewer) paginates the report according to those properties. While, on the other hand, graphical reports do need to take paper properties into account when creating graphical elements.

Gramps-devel.png

document generator should hide paper properies for graphical reports too

The PaperStyle holds information on the size of the paper (PaperSize class instance), the size of the margins, and the orientation of the paper. Use the proper accessor methods to get the values. To get the metrics of the usable area of a page one can also use the PaperStyle.get_usable_width and PaperStyle.get_usable_height convenience methods.

Text document API

Graphical document API