Clarion uses Windows metafiles to generate reports since the very first version of Clarion for Windows. A metafile is a sequence of records containing a list of GDI functions and parameters. Metafiles are created in memory and can be written to disk files. The RTL also uses metafiles to handle direct drawing operations like ARC() or PIE() in both WINDOWs and REPORTs. A metafile is a simple way to store drawing operations but there are several issues:

1. Windows metafiles do not support all GDI functions used for drawing. For example, images with semi-transparent parts cannot be stored in Windows metafiles.
2. Reports are sequences of bands and bands consist of controls and can be nested. Multiple drawing operations can be required to draw individual controls. For example, multiple lines and multiple strings must be drawn for LIST controls. Reports are best represented as a tree structure, and metafiles with their linear organization are not an easy/adequate way to represent them.
3. The RTL must carefully track images, pens and fonts used in metafiles to avoid leaking of resources.

Problem (1) can be solved by use of Enhanced metafiles (EMF) instead of Windows metafiles (WMF). But other problems exist for both types of metafiles. The RTL must enumerate metafile records every time some delayed action needs to be executed, for example when processing widow/orphan settings to find end of page. The RTL inserts additional records into metafiles to mark logically related records and assist in enumeration and parsing both during report generation and during conversion metafiles to text/PDF/XML/HTML format.

The new RTL won’t use metafiles for direct drawing operations or during report generation. Instead it will produce a dynamic tree structure matching the Report with a sequence of drawing operations. Every tree node is a class instance derived from the MetaNode class:
MetaNode       CLASS,TYPE
Next             &MetaNode
Bounds           LIKE(RECT)
Flags            ULONG
Custom1          LONG
Custom2          LONG
Draw             PROCEDURE (LONG context),VIRTUAL
END

ContainerNode  CLASS(MetaNode),TYPE
Nested           &MetaNode
END

PageNode       CLASS(ContainerNode),TYPE
Print            PROCEDURE (HDC, ULONG skipmask)
END

IndirectNode   CLASS(MetaNode),TYPE
Actual           &ContainerNode
END

There are 3 categories of nodes:

1. Nodes with information to execute a direct draw operation or to draw a control. A Nodes’ classes have fields for all values required to perform both drawing and post-processing: fonts, colors, pen style and width, value of the EXTEND attribute, etc.
2. Container nodes used for referencing a list of nested nodes.
3. Indirect nodes referencing some Container node.

The container node class for a report page has a function to start drawing or printing. The call to this function initiates iteration of the page sub-tree and calls the Draw method for every node. This approach provides a very easy method to get a page in any required form:

• If the HDC parameter is a handle to a screen device context (DC), the page contents are drawn on screen.
• If the HDC parameter is a handle to a printer DC, the page contents are sent to the corresponding printer.
• If the HDC parameter is a handle to an Enhanced metafile DC, an .EMF file with the page’s image is generated.
• If the HDC parameter is a handle to a Windows metafile DC, a .WMF file with the page’s image is generated.

The skipmask parameter of PageNode.Print function is used to filter which nodes to print/draw. If the value of the expression

BAND (node.Flags, skipmask)

is not 0, the node (and all nested nodes for container) are not drawn.  Filtering nodes can be used in multiple ways, for example to exclude some pages from printing, or to show the document form at preview time but not print it without needing to re-generate the report. The program can set its own flags in high WORD of the node’s Flags field (low WORD is reserved for Clarion internal use). The program also can use node’s Custom1 and Custom2 fields to store any useful data associated with that node.

Position of nodes corresponding to bands (FORM, HEADER, FOOTER, DETAIL, BREAK) is calculated relative to the page origin. Position of controls is calculated relative to the origin of the band they belong to. This allows us to have “references to containers” implemented by indirect nodes. Upon drawing/printing an indirect node the RTL uses its position, flags, custom data and a list of nested nodes of the container it points to. Indirect nodes are used internally to handle the FORM band, which is shared by all report pages. But a program can use them in other ways, for example to merge several short reports to print them on the same page, or to print a number of copies of specific pages.

Benefits

The new internal organization for Reports retains complete backward compatibility with the current and prior versions of the RTL because WMF files can be easily generated for every page.  But it opens the door to numerous potential enhancements:

1. Faster report generation by eliminating the need for repeated re-scanning of metafiles to merge them or to find the point of a page break.
2. Easier conversion of reports to formats other than WMF and EMF by elimination of the need to parse the WMF file to reconstruct the structure of the report in another format.
3. Easier after-generation modification of reports, for example placing the correct total number of pages to “Page n of N” text.
4. The possibility to have report pages with multi-layered contents and then selecting the desired layers at preview time.