class HexaPDF::Layout::Frame

Parent
Included Modules

A Frame describes the available space for placing boxes and provides additional methods for calculating the needed information for the actual placement.

Usage

After a Frame object is initialized, the draw method can be used to draw a box onto frame. If drawing is successful, the next box can be drawn. Otherwise, find_next_region should be called to determine the next region for placing the box. If the call returns true, a region was found and draw can be tried again. Once find_next_region returns false the frame has no more space for placing boxes.

Frame Shape and Contour Line

A frame's shape is used to determine the available space for laying out boxes and its contour line is used whenever text should be flown around objects. They are normally the same but can differ if a box with an arbitrary contour line is drawn onto the frame.

Initially, a frame has a rectangular shape. However, once boxes are added and the frame's available area gets reduced, a frame may have a polygon set consisting of arbitrary rectilinear polygons as shape.

In contrast to the frame's shape its contour line may be a completely arbitrary polygon set.

Attributes

available_height[R]

The available height for placing a box.

Also see the note in the x documentation for further information.

available_width[R]

The available width for placing a box.

Also see the note in the x documentation for further information.

bottom[R]

The y-coordinate of the bottom-left corner.

contour_line[R]

The contour line of the frame, a Geom2D::PolygonSet consisting of arbitrary polygons.

height[R]

The height of the frame.

left[R]

The x-coordinate of the bottom-left corner.

shape[R]

The shape of the frame, a Geom2D::PolygonSet consisting of rectilinear polygons.

width[R]

The width of the frame.

x[R]

The x-coordinate where the next box will be placed.

Note: Since the algorithm for draw takes the margin of a box into account, the actual x-coordinate (and y-coordinate, available width and available height) might be different.

y[R]

The y-coordinate where the next box will be placed.

Also see the note in the x documentation for further information.

Public Class Methods

new(left, bottom, width, height, contour_line: nil)

Creates a new Frame object for the given rectangular area.

If the contour line of the frame is not specified, then the rectangular area is used as contour line.

Public Instance Methods

draw(canvas, box)

Draws the given box onto the canvas at the frame's current position. Returns true if drawing was possible, false otherwise.

When positioning the box, the style properties “position”, “position_hint” and “margin” are taken into account. Note that the margin is ignored if a box's side coincides with the frame's original boundary.

After a box is successfully drawn, the frame's shape and contour line are adjusted to remove the occupied area.

find_next_region()

Finds the next region for placing boxes. Returns false if no useful region was found.

This method should be called after drawing a box using draw was not successful. It finds a different region on each invocation. So if a box doesn't fit into the first region, this method should be called again to find another region and to try again.

The first tried region starts at the top-most, left-most vertex of the polygon and uses the maximum width. The next tried region uses the maximum height. If both don't work, part of the frame's shape is removed to try again.

remove_area(polygon)

Removes the given rectilinear polygon from both the frame's shape and the frame's contour line.

width_specification(offset = 0)

Returns a width specification for the frame's contour line that can be used, for example, with TextLayouter.

Since not all text may start at the top of the frame, the offset argument can be used to specify a vertical offset from the top of the frame where layouting should start.

To be compatible with TextLayouter, the top left corner of the bounding box of the frame's contour line is the origin of the coordinate system for the width specification, with positive x-values to the right and positive y-values downwards.

Depending on the complexity of the frame, the result may be any of the allowed width specifications of TextLayouter#fit.