Extended box styles

Metadata values can be used to instruct the PDF builder to apply effects to rectangular areas on the page. The available effects are:

  • Make one or more of the corners rounded.

  • Insert a text title in the top border of the box.

  • Add a “shadow” under the box.

The metadata values are used to define one or more extended box styles. Each style describes the appearance of the rectangular area.

The effects are only applied to PDF output. The page preview and secondary transforms are not affected.

Defining a style

Each box style is identified by a unique key color expressed as an RGB color value. The PDF builder looks for rules and fills using the key colors and uses them to apply the extended styles.

Note that the key color does not need to be related to the colors that appear in the output when the box style is applied.

To define a box style, define a metadata value with the following name:

pdf.ext.boxstyle.R.G.B

where R, G and B are the red. blue and green components of the key color expressed as integers in the range 0 to 255 inclusive.

The metadata value is a comma-separated list of integer values:

BR,BG,BB,THK,RAD,MSK

where:

  • BR,BG,BB is the border color expressed as RGB components in the range 0 to 255 inclusive;

  • THK is the border thickness in tenths of a point (zero means no border);

  • RAD is the corner radius in tenths of a point;

  • MSK is a mask to select the corners to be rounded. Zero means all corners, otherwise a sum of any of the values 1 (top left), 2 (bottom left), 4 (bottom right) and 8 (top right).

Any values omitted have the value zero.

Box fill

By default an extended box is not filled. To apply a fill, define a metadata value with name:

pdf.ext.boxstyle.fill.R.G.B

where the R, G and B values match the key color of the style.

The metadata value is the RGB color of the fill expressed as three comma-separated values in the range 0 to 22 inclusive.

Shadow box

To draw a shadow beneath the box define a metadata value with name:

pdf.ext.boxstyle.shadow.R.G.B

with value:

SX,SY,SR,SG,SB

where:

  • SX is the horizontal offset of the shadow box in tenths of a point;

  • SY is the vertical offset of the shadow box in tenths of a point;

  • SR,SG,SB is the fill color expressed as RGB components in the range 0 to 255 inclusive.

Note that the shadow box is drawn as a filled area with no border, so if the extended box has a border the shadow offsets may need to be increased to get the desired appearance.

Creating an extended box on the page

There are three ways to define an extended box:

  1. Create a fill using the key color. This can be done by defining a mapping box style with a fill color and a frame type of None.

  2. Create two horizontal rules using the key color. The first rule defines the top of the box while the second defines its bottom. For correct operation the two rules should be identical except for their vertical positions.

  3. To insert a title into the top border, use a rule on either side of the title. The two rules must have the same vertical position. A third rule defines the bottom of the box.

Note that the PDF builder applies the extended style to each rectangular area it finds on a page. If a box breaks across a page each area will be styled independently. This means that all sides of a border will be drawn, unlike breakable boxes drawn without extended styles.