class HexaPDF:: Layout:: Box
Parent | Object |
---|---|
Included Modules |
Geom2D::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
andcontent_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 fit
, split
or split_content, and draw
or draw_content need to be customized according to the subclass's use case.
fit
-
This method should return
true
if fitting was successful. Additionally, the @fit_successful instance variable needs to be set to the fit result as it is used insplit
. split
-
This method splits the content so that the available space is used as good as possible. The default implementation should be fine for most use-cases, so only split_content needs to be implemented. The method create_split_box should be used for getting a basic cloned box.
draw
-
This method draws the content and the default implementation already handles things like drawing the border and background. Therefore it's best to implement draw_content which should just draw the content.
Attributes
The height of the box, including padding and/or borders.
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 style to be applied.
Only the following properties are used:
The width of the box, including padding and/or borders.
Public Class Methods
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.
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
The height of the content box, i.e. without padding and/or borders.
The width of the content box, i.e. without padding and/or borders.
Draws the content of the box onto the canvas at the position (x, y).
The coordinate system is translated so that the origin is at the bottom left corner of the **content box** during the drawing operations when +@draw_block+ is used.
The block specified when creating the box is invoked with the canvas and the box as arguments. Subclasses can specify an on-demand drawing method by setting the +@draw_block+ instance variable to nil
or a valid block. This is useful to avoid unnecessary set-up operations when the block does nothing.
Returns true
if no drawing operations are performed.
Fits the box into the Frame
and returns true
if fitting was successful.
The default implementation uses the whole available space for width and height if they were initially set to 0. Otherwise the specified dimensions are used.
Tries to split the box into two, the first of which needs to fit into the available space, and returns the parts as array.
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 before draw
on the first box since it is already fitted. If not even a part of this box fits into the available space, nil
should be returned as the first array element.
Possible return values:
- [self]
-
The box fully fits into the available space.
- [nil, self]
-
The box can't be split or no part of the box fits into the available space.
- [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 fit
result that should be sufficient for most subclasses; only split_content needs to be implemented if necessary.
Returns true
if this is a split box, i.e. the rest of another box after it was split.
Returns false
since a basic box doesn't support the 'position' style property value :flow.