10.5 ⁂The flowfram Package and the flowframtk
Application
The LaTeX kernel provides a single-column mode through the use of
\onecolumn (or the onecolumn class option) and
two-column mode through the use of \twocolumn (or the
twocolumn class option). The flowfram package
provides a way to extend this so that you can have an arbitrary
number of columns of arbitrary width and height placed in arbitrary
locations.
The standard LaTeX declarations \onecolumn and \twocolumn
automatically insert a page break before switching modes. One of the
reasons for this page break is to ensure that there isn't a paragraph
spanning different width columns as TeX's output routine doesn't
set the line width until the end of the paragraph which would leave
the tail end of the paragraph with the incorrect width at the start of the
new column. The flowfram package doesn't automatically insert
page breaks in this manner, but this inherent problem caused by the
asynchronous behaviour of TeX's output routine is present if you
have a paragraph spanning different width columns that have been
defined using flowfram, so you need to take care.
These arbitrary columns are termed “flow frames” in the flowfram user manual [98], which is accessed using
(If you just do
you'll get the documented code instead.)
There are two other types of frames: “static frames” and “dynamic frames”. These two types of frames need to have their contents set explicitly. With static frames, the contents are typeset in a box on being set. With dynamic frames, the contents are stored in a macro and retypeset each time the frame is drawn on a page. The frames are drawn onto the page in the following order: static, flow, dynamic. Within each category, the frames are drawn in order of definition. If frames overlap, their contents will overlap. (In other words, the text inside one frame doesn't attempt to avoid collision with the text inside another frame.)
Frames may have a border drawn around them. The default border is
just a rectangle, but other borders may be used. The paragraph shape
is unaffected by the shape of the border but it can be changed
either using TeX's \parshape primitive or one of the commands
provided by the shapepar package [4].
Flow frames can be defined using
Static frames can be defined using
Dynamic frames can be defined using
Each of these commands has a starred version that adds a rectangular border to the frame. The arguments are as follows:
- ⟨page list⟩
- The list of pages on which this frame is
visible. This may be one of the keywords: all,
none, odd or even; or this may be a
comma-separated list of page numbers or page ranges. Page ranges may be
open-ended using
<⟨n⟩ for pages less than page ⟨n⟩ or>⟨n⟩ for pages greater than page ⟨n⟩; or the ranges may be closed using ⟨n⟩-⟨m⟩ for pages between ⟨n⟩ and ⟨m⟩, inclusive. The page numbers referenced in the ⟨page list⟩ by default refer to the decimal value of thepagecounter. (For example, 1 means page 1 or page i or page I.) If thepages=absolutepackage option is used, then the page number refers to the absolute page number. If ⟨page list⟩ is omitted, all is assumed. - ⟨width⟩
- The width of the frame.
- ⟨height⟩
- The height of the frame.
- ⟨x⟩
- The x-coordinate of the bottom left-hand
corner of the frame relative to the typeblock.
- ⟨y⟩
- The y-coordinate of the bottom left-hand
corner of the frame relative to the typeblock.
- ⟨label⟩
- A label that uniquely identifies this frame.
The contents of a static frame can be set using:
where the frame contents are given by ⟨contents⟩. For the
unstarred version, ⟨id⟩ is the frame's index. For the starred
version, ⟨id⟩ is the label. Alternatively, the contents can be
set using the staticcontents environment:
As before there is a starred version where ⟨id⟩ is the frame's label rather than its index.
The contents of a dynamic frame can be set in a similar manner using:
or using the dynamiccontents environment:
Unlike the static frames, you can also append text to a dynamic frame using:
As before, these all have starred versions where ⟨id⟩ is the frame's label.
Example
Static frames are useful for background images, as shown below. This is a simple document that uses the lipsum package [33] to generate dummy text. This is a contrived example that shows what happens when you have overlapping frames and what happens if you have a paragraph spanning flow frames of different widths. The document text is placed in the flow frames in the order of the frame definition, which is why the text starts on the right hand frame, as that was the first flow frame to be defined.
\documentclass[a4paper]{article} \usepackage{lipsum} \usepackage{graphicx} \usepackage{flowfram} \newflowframe {0.6\textwidth}% width {0.3\textheight}% height {0.4\textwidth}% x position {0.7\textheight}% y position \newflowframe{0.6\textwidth}{0.5\textheight}{0pt}{0.5\textheight} \newflowframe*{\textwidth}{0.4\textheight}{0pt}{0pt} \newstaticframe{2in}{2in}{0pt}{0pt} \setstaticcontents{1}{\includegraphics[height=2in]{chicken}} \begin{document} \lipsum[1-4] \end{document}
The rather unpleasant result is shown in Figure 10.6.
The issue caused by TeX's asynchronous output routine being unable to adjust the line width over a frame break can be seen by the shortened lines in the end part of the paragraph at the beginning of the lower frame. (The frame with the border.) The flowfram package notices the problem and issues a warning with a recommendation:
(flowfram) use of
\framebreak advised, or text might not appear
correctly (difference = 137.9979pt, tolerance = 2.0pt)
before the first word of the new frame (between “magna.” and “Nunc” in this example) should only be resorted to on the final version of the document, once all the text has been written.
This example uses the flowfram package to create an advance
information sheet for a book. The geometry package is used to
set the margins. The page numbering is suppressed using the
empty page style and the section numbering is suppressed by
setting the secnumdepth counter to 0. (This just saves me
from remembering to use the starred version of \section.) I've
used the drm package [29] to illustrate a different font from
those I've previously used, and I've used the pifont, which
provides the dinglist environment that was mentioned in
Volume 1. Recall \dimexpr from
§2.1.3 Arithmetic, which is used here to calculate the
position of the static frame.
\documentclass[12pt,a4paper]{article} \usepackage[utf8]{inputenc} \usepackage[T1]{fontenc} \usepackage{drm} \usepackage{pifont} \usepackage[margin=0.5in]{geometry} \usepackage{graphicx} \usepackage{flowfram} \pagestyle{empty} \setcounter{secnumdepth}{0} \newflowframe{0.6\textwidth}{\textheight}{0pt}{0pt} \newdynamicframe{.3\textwidth}{\textheight}{.7\textwidth}{0pt}[sidepane] \newstaticframe{2in}{2in}{\dimexpr(\textwidth-2in)}{0pt}[logo] \setstaticcontents*{logo}{\includegraphics[width=2in]{dummy-logo}} \begin{dynamiccontents*}{sidepane} {\raggedright\bfseries\scshape\Large Oh No! The Chickens Have Escaped \par } \centering \bigskip \includegraphics[width=\linewidth]{chicken} \bigskip \begin{tabular}{@{}ll} Genre: & Children's Illustrated \\ & Fiction\\ RRP: & £5.99\\ Format: & Paperback\\ Pages: & 30\\ Pub Date: & 1st August 2014\\ ISBN: & 978-x-xxxxxx-xx-x \end{tabular} \vfill \includegraphics{barcode-qr} \vfill \end{dynamiccontents*} \begin{document}\raggedright \section{About the Book} A fun illustrated children's story about some escaped chickens. Fred and Mabel are looking after Granny's chickens for the day but, oh no, they've escaped. Will Fred and Mabel find them all before the chickens get into the road or get eaten by the hungry fox? \section{About the Author} Dickie Duck lives somewhere or other and won the best fowl book award in 2014. He likes writing silly stories about ducks and chickens. \section{Keypoints} \begin{dinglist}{118} \item A fun way of teaching children to count. \item Children will enjoy the repetition and rhyme. \item Features chickens doing stupid things. \item Completely fictitious book encourages children's imaginations. \end{dinglist} \section{Marketing} \begin{dinglist}{118} \item Written by award-winning author. \item Illustrated by world famous artist. \item Some other really interesting marketing information. \end{dinglist} \section{Contact} \begin{tabular}{@{}l} Dickie Duck\\ 1 The Street\\ Another Village\\ Some City\\ Imagineshire\\ YZ1 2AB \end{tabular} \end{document}
You can download or view this example document. It uses the sample images chicken.png and dummy-logo.png. It also uses the barcode-qr.pdf file created in Exercise 28.
The resulting document is shown in Figure 10.7.
If you find it a bit awkward to work out the dimensions and locations of the frames, there's a helper GUI application called flowframtk, which provides a graphical means of defining the frames. As with datatooltk and arara, this is a Java application so, if you want to use it, make sure you have an up-to-date version of the Java runtime environment installed on your computer.
To install flowframtk download the installer from flowframtk's home page. This is a .jar file. If your operating system knows how to run a .jar file, you should just be able to double-click on it, otherwise you can run it from the command line using:
(You may need to specify the full path to the .jar file. The version number 0.7 may also need to be changed if a new version has been produced since the time of writing this.)
Once flowframtk has been installed, it can be run either from your operating system's applications menu or from the command line using:
The main window is shown in Figure 10.8.
To illustrate the use of flowframtk, the rest of this section will use flowframtk to create the advance information sheet from Example 54. The result will be slightly different as I'm going to add some extra features such as coloured backgrounds.
For this example, I prefer to work in metric measurements so, to reduce rounding errors, I'm first going to set the storage unit to millimetres and the grid to centimetres. To set the storage unit, go to Settings→Configure Image Settings. This opens the dialog box shown in Figure 10.9. Use the Storage Unit drop-down menu to change the unit to mm. Click on the green tick button to save this change and close the dialog window.
Next go to Settings→Grid→Grid Settings which will open the dialog window shown in Figure 10.10. Select the Rectangular tab (if not already selected) and change the major divisions to 1 cm and the sub-divisions to 2 or 4. Click on the green tick button to save this change and close the dialog window.
Next make sure the paper size is correctly set. I'm using A4 portrait paper, which can be selected through the Settings→Paper submenu. Now the TeX settings for the document need to be specified, so go to Settings→Configure TeX/LaTeX Settings which will open the dialog window shown in Figure 10.11.
Recall from Example 54 that I used the 12pt
class option. I can specify that I want this by changing the
Normal Font Size drop-down menu to 12. I'm going to use the
default article class so I've left the Use default
class radio button selected. If I want to use a different class,
for example scrartcl, then I would have to select the
Use class radio button and type in the class name (without
the extension) in the neighbouring field. Again, click on the green
tick button to save the changes and close the window.
Next I need to specify the packages I want to use. This is done in
the preamble editor, which is opened using the
TeX/LaTeX→Preamble menu item. Note that I
don't include the geometry or flowfram packages since
these will automatically be added when I later use the export function.
Here are the packages (as from the previous example) and I've also
added the code to set the empty page style and switch off the
section numbering, but I've deferred it using \AtBeginDocument:
\usepackage[utf8]{inputenc} \usepackage[T1]{fontenc} \usepackage{drm} \usepackage{pifont} \usepackage{graphicx} \AtBeginDocument{% \pagestyle{empty}% \setcounter{secnumdepth}{0}% }
You can choose whether to show or hide the grid using the Settings→Grid sub-menu. I'm going to hide the grid but keep the rulers visible. Now I need to specify the margins. In Example 54 I had 0.5 in margins, but now I want to have a borderless document, so I'm going to set all the margins to zero. This is done using the TeX/LaTeX→Flow Frames→Set Typeblock menu item, which opens the dialog shown in Figure 10.13. Make sure all the margins are set to 0. (For this example, you don't need the other settings in this dialog window.) Although the margins default to 0, you must still click on the green tick button to save and close the dialog. A grey rectangle should now be displayed on the canvas with the word “typeblock” in the bottom left hand corner of the rectangle. (With zero margins, it may be difficult to see the rectangle.)
Now select the rectangle tool either using the Tools→Rectangle menu item or click on the rectangle button in the left tool bar. To draw a rectangle on the canvas, click where you want one corner and move the mouse to the location where the opposite corner should be and click there. For example, in Figure 10.14, I've created a rectangle with top left corner at (0 mm,0 mm) and bottom right corner at (130 mm,297 mm).
This rectangle will represent the main flow frame in my document, but first I want to add a fill colour and remove the outline. To do this, I need to switch to the select tool (either using the Tools→Select menu item or by clicking on the button in the side bar with an arrow on it). Then I can click anywhere inside the rectangle to select it. When it's selected, a dashed red rectangle will appear around it. Then I can use the Edit→Fill Colour menu item to open the fill colour selector. In Figure 10.15, I have selected the Colour radio button and specified 20% cyan, 20% magenta, 0% yellow and 0% black. The rectangle's black outline can be removed by selecting the Edit→Path→Line Colour menu item, which will open the line colour selector. Click on the Transparent radio button to remove the outline.
This rectangle now needs to be identified as a flow frame. Make sure it's still selected and use the menu item TeX/LaTeX→Flow Frames→Set Frame to open the flow frame selector. Set the Type to Flow and this will enable the flow frame related options. Give the frame a label (for example, “main”) and select the Border As Shown option. The margins can also be set to prevent the document text running against the border. I've chosen 5 mm for each margin, as shown in Figure 10.16. The even page options can be ignored since the result will be a single-paged document. Again click on the green tick to save the changes and close the dialog window. The selected rectangle in the main window should now have a pale grey rectangle inside it that shows the frame's margins (see Figure 10.17).
Now I want to create a static frame in the currently unfilled narrow region on the right hand side of the page. This will just provide a background colour. I will later make some other frames on top of this one that will contain text and images. The process is much the same as for the previous frame. The rectangle tool is selected, a rectangle is drawn with opposing corners at (132 mm,0 mm) and (210 mm,297 mm). The fill colour is set to 0% cyan, 0% magenta, 50% yellow, 0% black, and the outline is set to transparent. However, the frame should now be a static frame, so once the rectangle has been created, select the menu item TeX/LaTeX→Flow Frames→Set Frame and set the Type to Static. This enables a different set of options to earlier, but for this frame the only extra information needed is the label. I've set this to “sidepane”, as shown in Figure 10.18. Again, click on the green tick button to save the changes and close the dialog window.
It's a good idea at this point to save the image in case something goes wrong. There are two native file formats: .jdr (binary) and .ajr (ASCII). The binary version has greater precision but the ASCII version works better with version control systems (see §13.2 Version Control). Since I use version control and I don't need double-precision for my co-ordinates, I'm going to use the ASCII version (.ajr). To save to a new file use the File→Save As menu item and select the appropriate file type (in my case, flowframtk ascii file (*.ajr)), as shown in Figure 10.19.
Now I need an area in which to put the book title (which appears on the top right of Figure 10.7). Again I need to use the rectangle tool to use as a guide for my frame. My rectangle has opposing corners at (136 mm,5 mm) and (206 mm,62 mm). In this case I don't need to change the colours as I'm only using the rectangle as a guide to define a borderless dynamic frame. As before, I need to select this new rectangle and use the TeX/LaTeX→Flow Frames→Set Frame menu item to open the dialog box. Now I set the Type to Dynamic and the label to “title”, but this time the Border option needs to be set to None as shown in Figure 10.20.
At the bottom of this dialog window is an area labelled
Contents with a button labelled Edit next to it. This
allows you to set the contents of a dynamic or static frame, just
as you can do using commands such as \setdynamiccontents,
described earlier. Click on this Edit button to add the frame contents,
which is the LaTeX code from Example 54:
\raggedright\bfseries\scshape\Large Oh No! The Chickens Have Escaped
As shown in Figure 10.21. Click on the green tick button to save these changes and return to the previous dialog window, and click on the green tick button there to save and close that window.
Links to bitmap images can be included in flowframtk images
and they can also be used as frame backgrounds. Note that only the
bitmap location is saved in an .ajr or .jdr file. You
can choose whether this location is an absolute path or a path
relative to the .ajr/.jdr file. To do this,
use the Settings→Configure Image Settings menu
item to open the image settings dialog window (shown earlier in
Figure 10.9). Select the Bitmaps tab and
either check or uncheck the Use relative paths for bitmaps
button. You can also use this panel to select which LaTeX command
to use for inserting images. In Figure 10.22 I have
set this to \includegraphics.
To insert a bitmap, make sure you are in select mode (Tools→Select) and use the menu item Bitmap→Insert Bitmap to open the bitmap selector, shown in Figure 10.23.
Select the required bitmap (I've chosen the sample image
chicken.png) and click on the Open button.
This will insert the bitmap into the image, but this particular
image is far too big so it needs to be scaled. Note that, just like
the transformation options in \includegraphics, this scaling
doesn't modify the actual bitmap file. The newly inserted bitmap
should already be selected. To scale it use the
Transform→Scale menu item to open the scaling
dialog window and set the scale factor, as shown in
Figure 10.24. I've set the scale factor to 0.1.
The bitmap is now the correct size but is in the wrong position, as new bitmaps are always inserted with the top left corner at the origin. With the select tool set, you can use the mouse to drag the bitmap to the desired location, as shown in Figure 10.25.
This bitmap can be set as the background to a static frame in a similar manner to the earlier static frame (labelled “sidepane”). So make sure the bitmap is selected, use the TeX/LaTeX→Flow Frames→Set Frame menu item to open the dialog box, and set the Type to Static, the label to, say, “titleimage” and make sure the Border is set to As Shown. I repeated this process for the sample image dummy-logo.png (with the scale set to 0.2) and labelled this frame “logo”. The image so far, with both bitmaps, is as shown in Figure 10.26.
Now I just need another dynamic frame for the rest of the side panel information. Again this is done by creating a rectangle, selecting it and using the TeX/LaTeX→Flow Frames→ Set Frame menu item to open the frame dialog window. Here I've set the Type to Dynamic, the label to “bookdata” and set Border to None. I've changed the Alignment option to Middle which will vertically balance the frame's contents. The contents can again be set by clicking on the Edit button, which will open the mini-LaTeX editor. The contents are as follows:
\begin{tabular}{@{}ll} Genre: & Children's Illustrated \\ & Fiction\\ RRP: & £5.99\\ Format: & Paperback\\ Pages: & 30\\ Pub Date: & 1st August 2014\\ ISBN: & 978-x-xxxxxx-xx-x \end{tabular} \bigskip \begin{center} \colorbox{white}{\includegraphics{barcode-qr}} \end{center}
(If you prefer, you could convert barcode-qr.pdf to a bitmap and insert it in a similar manner to the other bitmaps.) Click the green tick to save and return to the Set Frame dialog, shown in Figure 10.27.
The final image is as shown in Figure 10.28. Make sure you save it to an .ajr or .jdr before proceeding to the export function. The flowframtk application can only load its own native files. It can't load the files it exports, so if you need to make any modifications you'll need the .jdr/.ajr file.
Now that the image is complete with all the required flowfram data, you can export to a LaTeX class or package file using the File→Export menu item. I'm going to export to a class file, so I've set the file type filter to Class (*.cls) as shown in Figure 10.29.
My examples directory now contains the files: aisheet.ajr, aisheet.cls along with my original image files chicken.png, barcode-qr.pdf and dummy-logo.png. Now I just need to add a LaTeX document that uses this new aisheet class file:
\documentclass{aisheet} \begin{document}\raggedright \section{About the Book} A fun illustrated children's story about some escaped chickens. Fred and Mabel are looking after Granny's chickens for the day but, oh no, they've escaped. Will Fred and Mabel find them all before the chickens get into the road or get eaten by the hungry fox? \section{About the Author} Dickie Duck lives somewhere or other and won the best fowl book award in 2014. He likes writing silly stories about ducks and chickens. \section{Keypoints} \begin{dinglist}{118} \item A fun way of teaching children to count. \item Children will enjoy the repetition and rhyme. \item Features chickens doing stupid things. \item Completely fictitious book encourages children's imaginations. \end{dinglist} \section{Marketing} \begin{dinglist}{118} \item Written by award-winning author. \item Illustrated by world famous artist. \item Some other really interesting marketing information. \end{dinglist} \section{Contact} \begin{tabular}{@{}l} Dickie Duck\\ 1 The Street\\ Another Village\\ Some City\\ Imagineshire\\ YZ1 2AB \end{tabular} \end{document}
The resulting document is shown in Figure 10.30. You can download or view this example document.
This book is also available as A4 PDF or 12.8cm x 9.6cm PDF or paperback (ISBN 978-1-909440-07-4).