Flow layout API

Revision as of 16:38, 4 June 2018 by Adminko (talk | contribs)
Jump to: navigation, search


This API provides a new way to generate PDF files programmatically. In opposite to Fixed layout API, designed to be as close as possible to PDF specification, Flow layout API provides you with a number of high-level content building blocks e.g. TextBlock, Grid, Image which can be placed on a page and automatically positioned using so-called layout rules. The layout engine analyzes various properties of these content elements and then logically processes them according to the layout rules generating the resulting PDF document. Properties of these content elements can be assigned directly or defined by styles, thus it becomes possible to easily manage groups of objects with similar properties by changing corresponding style objects.

A process called style matching assigns a style to a particular object(content building block) based on style selector – a rule that defines which elements should be affected by this style. It works similar to HTML+CSS and one familiar with the latter can easily use one's experience and build PDF documents within a minute or even quicker. Actually, styles and content element are so native and easy to work with that we would recommend using it for generating of quickly changing and repetitive content, e.g. invoices, bills, reports, forms etc.

A list of supported features is rather big and we’d recommend checking code samples included along with the download package and showing the full power of Apitron PDF Kit and its Flow layout API in action. To name a few, it supports floating text, automatic pagination of grids and sections, ordered and unordered lists with various types of markers (including nested lists), text justification, dynamic content generation, automatic links and bookmarks creation and much more. It can even be mixed with elements from Fixed layout API.

This API is built around FlowDocument class and it’s possible to save created layout as XML template and load from it. It separates document design from actual processing and can be used to alter document appearance and introduce future changes without(!) recompiling the application.

Creating simple PDF document

Let's see how to create a simple PDF document with “Hello world” message on the first page using Flow layout API.

Consider the following code:

// create output file
using (Stream outputStream = File.Create("hello_world.pdf"))
    // create new document
    FlowDocument document = new FlowDocument()
    // add textual content element
    document.Add(new TextBlock("Hello world using flow layout API"));

    // save to output stream with page size A4
    document.Write(outputStream,new ResourceManager(), new PageBoundary(Boundaries.A4));    

Here you can see the basics of flow layout workflow, we create FlowDocument instance first, then we fill it with some content (simple TextBlock is used in this sample) and at the end we write it as PDF document to the output stream.

For writing we need an output stream, a ResourceManager instance that holds all resource objects used in the document (empty in our case) and PageBoundary object describing page dimensions. All pages in the target document will have the same dimensions unless they’re explicitly adjusted using techniques described in the article change page size and styles on the fly. As you can see, there is no notion of any style object or explicit property usage in this code sample. It was made intentionally to give you a very brief overview and a valid PDF document before moving on to more advanced topics.

And the results of the execution can be seen on the image below:

Create simple PDF file using flow layout API

Box model and layout basics

Flow Layout API uses a slightly modified traditional box model to define its content elements. Vertically infinite canvas limited by page width in horizontal dimension is used to layout them and to form the content of the resulting PDF document. The box model used by the Flow layout API assumes that margin, border and padding are inside the box defined by the element's width and height. See the image below:

Box model used by the Flow layout API

A content element gets rendered within its box and later placed on a page according to the layout rules and corresponding properties. It’s important to note that every element will always have implicit box even if you don’t specify its dimensions. One of the important properties, affecting the layout of the element, is Display. It specifies whether the element should be processed as:

  • Block – creating a line break before and after
  • Inline – added to the current line
  • InlineBlock – a special kind of Block element that doesn’t create line breaks
  • None - shouldn’t be processed at all

The main difference between Block, InlineBlock and Inline elements is that pure inline elements can’t be sized explicitly by setting their dimensions. It will be ignored the same way as HTML processors do. In addition several style properties can be inherited only by Block elements (actually a very few of them) and it will be discussed later in section Available styling properties.

Main type used for specifying various elements' dimensions in Flow layout API is Length. Its constructor accepts values given in points, pixels, centimeters, inches, %'s and a special value Auto that depends on the context where it's used.