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, it is ready for drawing boxes on it.

The explicit way of drawing a box follows these steps:

  • Call fit with the box to see if the box can fit into the currently selected region of available space. If fitting is successful, the box can be drawn using draw.

    The method fit is also called for absolutely positioned boxes but since these boxes are not subject to the normal constraints, the available space used is the width and height inside the frame to the right and top of the bottom-left corner of the box.

  • If the box didn't fit, call find_next_region to determine the next region for placing the box. If a new region was found, start over with fit. Otherwise the frame has no more space for placing boxes.

  • Alternatively to calling find_next_region it is also possible to call split. This method tries to split the box into two so that the first part fits into the current region. If splitting is successful, the first box can be drawn (Make sure that the second box is handled correctly). Otherwise, start over with find_next_region.

For applications where splitting is not necessary, an easier way is to just use draw and find_next_region together, as draw calls fit if the box was not fit into the current region.

Used Box Properties

The style properties “position”, “position_hint” and “margin” are taken into account when fitting, splitting or drawing a box. Note that the margin is ignored if a box's side coincides with the frame's original boundary.

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.

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 drawing 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.

Public Instance Methods

contour_line()

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

draw(canvas, box)

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

If the given box is not the last fitted box, fit is called before drawing the box.

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.

fit(box)

Fits the given box into the current region of available space.

full?()

Returns true if the frame has no more space left.

remove_area(polygon)

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

split(box)

Tries to split the (fitted) box into two parts, where the first part needs to fit into the available space, and returns both parts.

If the given box is not the last fitted box, fit is called before splitting the box.

See Box#split for further details.

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.