PDFlib 8 Windows COM/.NET Tutorial

8.4 Matchboxes
Matchboxes provide access to coordinates calculated by PDFlib as a result of placing
some content on the page. Matchboxes are not defined with a dedicated function, but
with the matchbox option in the function call which places the actual element, for example
fit_textline( ) and fit_image( ). Matchboxes can be used for various purposes:
> Matchboxes can be decorated, e.g. filled with color or surrounded by a frame.
> Matchboxes can be used to automatically create one or more annotations with
create_annotation( ).
> Matchboxes define the height of a text line which will be fit into a box with fit_
textline( ) or the height of a text fragment in a Textflow which will be decorated
(boxheight option).
> Matchboxes define the clipping for an image.
> The coordinates of the matchbox and other properties can be queried with info_
matchbox( ) to perform some other task, e.g. insert an image.
For each element PDFlib will calculate the matchbox as a rectangle corresponding to the
bounding box which describes the position of the element on the page (as specified by
all relevant options). For Textflows and table cells a matchbox may consist of multiple
rectangles because of line or row breaking.
The rectangle(s) of a matchbox will be drawn before drawing the element to be
placed. As a result, the element may obscure the effect of the matchbox border or filling,
but not vice versa. In particular, those parts of the matchbox which overlap the area
covered by an image are hidden by the image. If the image is placed with fitmethod=slice
or fitmethod=clip the matchbox borders outside the image fitbox will be clipped as well.
To avoid this effect the matchbox rectangle can be drawn using the basic drawing functions,
e.g. rect( ), after the fit_image( ) call. The coordinates of the matchbox rectangle can
be retrieved using info_matchbox( ) as far as the matchbox has been provided with a
name in the fit_image( ) call.
In the following sections some examples for using matchboxes are shown. For details
about the functions which support the matchbox option list, see the PDFlib API
Reference.
8.4.1 Decorating a Textline
Let’s start with a discussion of matchboxes in text lines. In fit_textline( ) the matchbox is
the textbox of the supplied text. The width of the textbox is the text width, and the
height is the capheight of the given font size, by default. To illustrate the matchbox size
the following code fragment will fill the matchbox with blue background color (see Figure
8.40a).
String optlist =
"font=" + normalfont + " fontsize=8 position={left top} " +
"matchbox={fillcolor={rgb 0.8 0.8 0.87} boxheight={capheight none}}";
p.fit_textline("Giant Wing Paper Plane", 2, 20, optlist);
You can omit the boxheight option since boxheight={capheight none} is the default setting.
It will look better if we increase the box height so that it also covers the descenders
using the boxheight option (see Figure 8.40b).
242 Chapter 8: Text and Table Formatting (Edition for COM, .NET, and REALbasic)