HomeExamplesDocsCodeNews
Home  »  Docs  »  API Reference  »  HexaPDF  »  Layout  »  Box

Classes and Modules

class HexaPDF::Layout::Box

Parent Object
Included Modules HexaPDF::Utils

The base class for all layout boxes.

Box Model ↑

HexaPDF uses the following box model:

  • Each box can specify a width and height. Padding and border are inside, the margin outside of this rectangle.

  • The content_width and content_height accessors can be used to get the width and height of the content box without padding and the border.

  • If width or height is set to zero, they are determined automatically during layouting.

Subclasses ↑

Each subclass should only take keyword arguments on initialization so that the boxes can be instantiated from the common convenience method HexaPDF::Document::Layout#box. To use this facility subclasses need to be registered with the configuration option ‘layout.boxes.map’.

The methods supports_position_flow?, empty?, fit_content, split_content, and draw_content need to be customized according to the subclass’s use case (also see the documentation of the methods besides the information below):

supports_position_flow?

If the subclass supports the value :flow of the ‘position’ style property, this method needs to be overridden to return true.

Additionally, if a box object uses flow positioning, fit_result.x should be set to the correct value since Frame#fit can’t determine this and uses Frame#left in the absence of a set value.

empty?

This method should return true if the subclass won’t draw anything when draw is called.

fit_content

This method determines whether the box fits into the available region and should set the status of fit_result appropriately.

It is called from the fit method which should not be overridden in most cases. The default implementations of both methods provide code common to all use-cases and delegates the specifics to the subclass-specific fit_content method.

split_content

This method is called from split which handles the common cases based on the status of the fit_result. It needs to handle the case when only some part of the box fits. The method create_split_box should be used for getting a basic cloned box.

draw_content

This method draws the box specific content and is called from draw which already handles things like drawing the border and background. So draw should usually not be overridden.

This base class also provides various protected helper methods for use in the above methods:

Attributes

fit_result[R]

The FitResult instance holding the result after a call to fit.

height[R]

The height of the box, including padding and/or borders.

properties[R]

Hash with custom properties. The keys should be strings and can be arbitrary.

This can be used to store arbitrary information on boxes for later use. For example, a generic style layer could use one or more custom properties for its work.

The Box class itself uses the following properties:

optional_content

If this property is set, it needs to be an optional content group dictionary, a String defining an (optionally existing) optional content group dictionary, or an optional content membership dictionary.

The whole content of the box, i.e. including padding, border, background…, is wrapped with the appropriate commands so that the optional content group or membership dictionary specifies whether the content is shown or not.

See: HexaPDF::Type::OptionalContentProperties

width[R]

The width of the box, including padding and/or borders.

Public Class Methods

create(width: 0, height: 0, content_box: false, style: nil, **style_properties, &block)

Creates a new Box object, using the provided block as drawing block (see ::new).

If content_box is true, the width and height are taken to mean the content width and height and the style’s padding and border are added to them appropriately.

The style argument defines the Style object (see Style::create for details) for the box. Any additional keyword arguments have to be style properties and are applied to the style object.

new(width: 0, height: 0, style: nil, properties: nil) {|canv, box| block} → box

Creates a new Box object with the given width and height that uses the provided block when it is asked to draw itself on a canvas (see draw).

Since the final location of the box is not known beforehand, the drawing operations inside the block should draw inside the rectangle (0, 0, content_width, content_height) - note that the width and height of the box may not be known beforehand.

Public Instance Methods

content_height()

The height of the content box, i.e. without padding and/or borders.

content_width()

The width of the content box, i.e. without padding and/or borders.

draw(canvas, x, y)

Draws the content of the box onto the canvas at the position (x, y).

When +@draw_block+ is used (the block specified when creating the box), the coordinate system is translated so that the origin is at the bottom left corner of the **content box**.

Subclasses should not rely on the +@draw_block+ but implement the draw_content method. The coordinates passed to it are also modified to represent the bottom-left corner of the content box but the coordinate system is not translated.

empty?()

Returns true if no drawing operations are performed.

fit(available_width, available_height, frame)

Fits the box into the frame and returns the fit_result.

The arguments available_width and available_height are the width and height of the current region of the frame, adjusted for this box. The frame itself is provided as third argument.

If the box uses flow positioning, the width is set to the frame’s width and the height to the remaining height in the frame. Otherwise the given available width and height are used for the width and height if they were initially set to 0. Otherwise the intially specified dimensions are used. The method returns early if the thus configured box already doesn’t fit. Otherwise, the fit_content method is called which allows sub-classes to fit their content.

The following variables are set that may later be used during splitting or drawing:

  • (@fit_x, @fit_y): The lower-left corner of the content box where fitting was done. Can be used to adjust the drawing position in draw_content if necessary.

split()

Tries to split the box into two, the first of which needs to fit into the current region of the frame, and returns the parts as array. The method fit needs to be called before this method to correctly set-up the fit_result.

If the first item in the result array is not nil, it needs to be this box and it means that even when fit fails, a part of the box may still fit. Note that fit should not be called again before draw on the first box since it is already fitted. If not even a part of this box fits into the current region, nil should be returned as the first array element.

Possible return values:

[self, nil]

The box fully fits into the current region.

[nil, self]

The box can’t be split or no part of the box fits into the current region.

[self, new_box]

A part of the box fits and a new box is returned for the rest.

This default implementation provides the basic functionality based on the status of the fit_result that should be sufficient for most subclasses; only split_content needs to be implemented if necessary.

split_box?()

Returns the set truthy value if this is a split box, i.e. the rest of another box after it was split.

supports_position_flow?()

Returns false since a basic box doesn’t support the ‘position’ style property value :flow.

Protected Instance Methods

create_split_box(split_box_value: true)

Creates a new box based on this one and resets the internal data back to their original values.

The variable +@split_box+ is set to split_box_value (defaults to true) to make the new box aware that it is a split box. If needed, subclasses can set the variable to other truthy values to convey more meaning.

This method should be used by subclasses to create their split box.

draw_content(canvas, x, y)

Draws the content of the box at position [x, y] which is the bottom left corner of the content box.

This implementation uses the drawing block provided on initialization, if set, to draw the contents. Subclasses should override it to provide box specific behaviour.

fit_content(_available_width, _available_height, _frame)

Fits the content of the box and returns whether fitting was successful.

This is just a stub implementation that sets the fit_result status to success. Subclasses should override it to provide the box specific behaviour.

See fit for details.

reserved_height()

Returns the height that is reserved by the padding and border style properties.

reserved_height_bottom()

Returns the height that is reserved by the padding and the border style properties on the bottom side of the box.

reserved_height_top()

Returns the height that is reserved by the padding and the border style properties on the top side of the box.

reserved_width()

Returns the width that is reserved by the padding and border style properties.

reserved_width_left()

Returns the width that is reserved by the padding and the border style properties on the left side of the box.

reserved_width_right()

Returns the width that is reserved by the padding and the border style properties on the right side of the box.

split_content()

Splits the content of the box.

This is just a stub implementation, returning [nil, self] since we can’t know how to split the content when it didn’t fit.

Subclasses that support splitting content need to provide an appropriate implementation and use create_split_box to create a cloned box to supply as the second return argument.

update_content_height { block }

Updates the height of the box using the content height returned by the block.

update_content_width { block }

Updates the width of the box using the content width returned by the block.