Class: HexaPDF::Layout::ContainerBox

Inherits:

Box

• Object
• Box
• HexaPDF::Layout::ContainerBox

Defined in:

lib/hexapdf/layout/container_box.rb

Overview

This is a simple container box for laying out a number of boxes together. It is registered under the :container name.

The box does not support the value :flow for the style property position, so the child boxes are laid out in the current region only.

If #splitable is false (the default) and if any box doesn’t fit, the whole container doesn’t fit.

By default the child boxes are laid out from top to bottom. By appropriately setting the style properties ‘mask_mode’, ‘align’ and ‘valign’, it is possible to lay out the children bottom to top, left to right, or right to left:

• The standard top-to-bottom layout:

  #>pdf-composer100
  composer.container do |container|
    container.box(height: 20, style: {background_color: "hp-blue-dark"})
    container.box(height: 20, style: {background_color: "hp-blue"})
    container.box(height: 20, style: {background_color: "hp-blue-light"})
  end
  

• The bottom-to-top layout (using valign = :bottom to fill up from the bottom and mask_mode = :fill_horizontal to only remove the area to the left and right of the box):

  #>pdf-composer100
  composer.container do |container|
    container.box(height: 20, style: {background_color: "hp-blue-dark",
                                      mask_mode: :fill_horizontal, valign: :bottom})
    container.box(height: 20, style: {background_color: "hp-blue",
                                      mask_mode: :fill_horizontal, valign: :bottom})
    container.box(height: 20, style: {background_color: "hp-blue-light",
                                      mask_mode: :fill_horizontal, valign: :bottom})
  end
  

• The left-to-right layout (using mask_mode = :fill_vertical to fill the area to the top and bottom of the box):

  #>pdf-composer100
  composer.container do |container|
    container.box(width: 20, style: {background_color: "hp-blue-dark",
                                     mask_mode: :fill_vertical})
    container.box(width: 20, style: {background_color: "hp-blue",
                                     mask_mode: :fill_vertical})
    container.box(width: 20, style: {background_color: "hp-blue-light",
                                     mask_mode: :fill_vertical})
  end
  

• The right-to-left layout (using align = :right to fill up from the right and mask_mode = :fill_vertical to fill the area to the top and bottom of the box):

  #>pdf-composer100
  composer.container do |container|
    container.box(width: 20, style: {background_color: "hp-blue-dark",
                                     mask_mode: :fill_vertical, align: :right})
    container.box(width: 20, style: {background_color: "hp-blue",
                                     mask_mode: :fill_vertical, align: :right})
    container.box(width: 20, style: {background_color: "hp-blue-light",
                                     mask_mode: :fill_vertical, align: :right})
  end
  

Constant Summary

Constants included from Utils

Utils::EPSILON

Instance Attribute Summary

• #children ⇒ Object readonly

  The child boxes of this ContainerBox.

• #splitable ⇒ Object readonly

  Specifies whether the container box allows splitting its content.

Attributes inherited from Box

#fit_result, #height, #properties, #style, #width

Instance Method Summary

• #empty? ⇒ Boolean

  Returns true if no box was fitted into the container.

• #initialize(children: [], splitable: false, **kwargs) ⇒ ContainerBox constructor

  Creates a new container box, optionally accepting an array of child boxes.

Methods inherited from Box

#content_height, #content_width, create, #draw, #fit, #split, #split_box?, #supports_position_flow?

Constructor Details

#initialize(children: [], splitable: false, **kwargs) ⇒ ContainerBox

Creates a new container box, optionally accepting an array of child boxes.

Example:

#>pdf-composer100
composer.text("A paragraph here")
composer.container(height: 40, style: {border: {width: 1}, padding: 5,
                                       align: :center}) do |container|
  container.text("Some", mask_mode: :fill_vertical)
  container.text("text", mask_mode: :fill_vertical, valign: :center)
  container.text("here", mask_mode: :fill_vertical, valign: :bottom)
end
composer.text("Another paragraph")

# File 'lib/hexapdf/layout/container_box.rb', line 145

def initialize(children: [], splitable: false, **kwargs)
  super(**kwargs)
  @children = children
  @splitable = splitable
end

Instance Attribute Details

#children ⇒ Object (readonly)

The child boxes of this ContainerBox. They need to be finalized before #fit is called.

# File 'lib/hexapdf/layout/container_box.rb', line 106

def children
  @children
end

#splitable ⇒ Object (readonly)

Specifies whether the container box allows splitting its content.

If splitting is not allowed (the default), all child boxes must fit together into one region.

Examples:

# Fails with an error because the content of the container box is too big
composer.column do |col|
  col.container do |container|
    container.lorem_ipsum
  end
end

---

#>pdf-composer
composer.column do |col|
  col.container(splitable: true) do |container|
    container.lorem_ipsum
  end
end

# File 'lib/hexapdf/layout/container_box.rb', line 130

def splitable
  @splitable
end

Instance Method Details

#empty? ⇒ Boolean

Returns true if no box was fitted into the container.

Returns:

• (Boolean)

# File 'lib/hexapdf/layout/container_box.rb', line 152

def empty?
  super && (!@box_fitter || @box_fitter.fit_results.empty?)
end