Class: HexaPDF::Layout::Frame

Inherits:
Object
  • Object
show all
Includes:
Geom2D::Utils
Defined in:
lib/hexapdf/layout/frame.rb

Overview

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

A frame's shape is used to determine the available space for laying out boxes.

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.

It is also possible to provide a different initial shape on initialization.

Defined Under Namespace

Classes: FitResult

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(left, bottom, width, height, shape: nil) ⇒ Frame

Creates a new Frame object for the given rectangular area.



185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
 
# File 'lib/hexapdf/layout/frame.rb', line 185

def initialize(left, bottom, width, height, shape: nil)
  @left = left
  @bottom = bottom
  @width = width
  @height = height
  @shape = shape || Geom2D::PolygonSet.new(
    [create_rectangle(left, bottom, left + width, bottom + height)]
  )
  @x = left
  @y = bottom + height
  @available_width = width
  @available_height = height

  find_max_width_region if shape
  @region_selection = :max_height
end

Instance Attribute Details

#available_height ⇒ Object (readonly)

The available height for placing a box.

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



182
183
184
 
# File 'lib/hexapdf/layout/frame.rb', line 182

def available_height
  @available_height
end

#available_width ⇒ Object (readonly)

The available width for placing a box.

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



177
178
179
 
# File 'lib/hexapdf/layout/frame.rb', line 177

def available_width
  @available_width
end

#bottom ⇒ Object (readonly)

The y-coordinate of the bottom-left corner.



152
153
154
 
# File 'lib/hexapdf/layout/frame.rb', line 152

def bottom
  @bottom
end

#height ⇒ Object (readonly)

The height of the frame.



158
159
160
 
# File 'lib/hexapdf/layout/frame.rb', line 158

def height
  @height
end

#left ⇒ Object (readonly)

The x-coordinate of the bottom-left corner.



149
150
151
 
# File 'lib/hexapdf/layout/frame.rb', line 149

def left
  @left
end

#shape ⇒ Object (readonly)

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



161
162
163
 
# File 'lib/hexapdf/layout/frame.rb', line 161

def shape
  @shape
end

#width ⇒ Object (readonly)

The width of the frame.



155
156
157
 
# File 'lib/hexapdf/layout/frame.rb', line 155

def width
  @width
end

#x ⇒ Object (readonly)

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.



167
168
169
 
# File 'lib/hexapdf/layout/frame.rb', line 167

def x
  @x
end

#y ⇒ Object (readonly)

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

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



172
173
174
 
# File 'lib/hexapdf/layout/frame.rb', line 172

def y
  @y
end

Instance Method Details

#draw(canvas, fit_result) ⇒ Object

Draws the box of the given FitResult onto the canvas at the fitted position.

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



304
305
306
307
308
 
# File 'lib/hexapdf/layout/frame.rb', line 304

def draw(canvas, fit_result)
  return if fit_result.box.height == 0 || fit_result.box.width == 0
  fit_result.draw(canvas)
  remove_area(fit_result.mask)
end

#find_next_region ⇒ Object

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.



319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
 
# File 'lib/hexapdf/layout/frame.rb', line 319

def find_next_region
  case @region_selection
  when :max_width
    find_max_width_region
    @region_selection = :max_height
  when :max_height
    x, y, aw, ah = @x, @y, @available_width, @available_height
    find_max_height_region
    if @x == x && @y == y && @available_width == aw && @available_height == ah
      trim_shape
    else
      @region_selection = :trim_shape
    end
  else
    trim_shape
  end

  available_width != 0
end

#fit(box) ⇒ Object

Fits the given box into the current region of available space and returns a FitResult object.

Use the FitResult#success? method to determine whether fitting was successful.



206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
 
# File 'lib/hexapdf/layout/frame.rb', line 206

def fit(box)
  fit_result = FitResult.new(box)
  return fit_result if full?

  position = if box.style.position != :flow || box.supports_position_flow?
               box.style.position
             else
               :default
             end

  if position == :absolute
    x, y = box.style.position_hint

    aw = width - x
    ah = height - y
    box.fit(aw, ah, self)
    fit_result.success!

    x += left
    y += bottom
    rectangle = if box.style.margin?
                  margin = box.style.margin
                  create_rectangle(x - margin.left, y - margin.bottom,
                                   x + box.width + margin.right, y + box.height + margin.top)
                else
                  create_rectangle(x, y, x + box.width, y + box.height)
                end
  else
    aw = available_width
    ah = available_height

    margin_top = margin_right = margin_left = 0
    if box.style.margin?
      margin = box.style.margin
      aw -= margin_right = margin.right unless float_equal(@x + aw, @left + @width)
      aw -= margin_left = margin.left unless float_equal(@x, @left)
      ah -= margin.bottom unless float_equal(@y - ah, @bottom)
      ah -= margin_top = margin.top unless float_equal(@y, @bottom + @height)
    end

    fit_result.success! if box.fit(aw, ah, self)

    width = box.width
    height = box.height

    case position
    when :flow
      x = 0
      y = @y - height
      rectangle = create_rectangle(left, [bottom, y - (margin&.bottom || 0)].max,
                                   left + self.width, @y)
    else
      x = case box.style.position_hint
          when nil, :left
            @x + margin_left
          when :right
            @x + margin_left + aw - width
          when :center
            max_margin = [margin_left, margin_right].max
            # If we have enough space left for equal margins, we center perfectly
            if available_width - width >= 2 * max_margin
              @x + (available_width - width) / 2.0
            else
              @x + margin_left + (aw - width) / 2.0
            end
          end
      y = @y - height - margin_top
      rectangle = if position == :float
                    create_rectangle([left, x - (margin&.left || 0)].max,
                                     [bottom, y - (margin&.bottom || 0)].max,
                                     [left + self.width, x + width + (margin&.right || 0)].min,
                                     @y)
                  else
                    create_rectangle(left, [bottom, y - (margin&.bottom || 0)].max,
                                     left + self.width, @y)
                  end
    end
  end

  fit_result.available_width = aw
  fit_result.available_height = ah
  fit_result.x = x
  fit_result.y = y
  fit_result.mask = rectangle
  fit_result
end

#full? ⇒ Boolean

Returns true if the frame has no more space left.

Returns:

  • (Boolean) 


347
348
349
 
# File 'lib/hexapdf/layout/frame.rb', line 347

def full?
  available_width == 0
end

#remove_area(polygon) ⇒ Object

Removes the given rectilinear polygon from the frame's shape.



340
341
342
343
344
 
# File 'lib/hexapdf/layout/frame.rb', line 340

def remove_area(polygon)
  @shape = Geom2D::Algorithms::PolygonOperation.run(@shape, polygon, :difference)
  @region_selection = :max_width
  find_next_region
end

#split(fit_result) ⇒ Object

Tries to split the box of the given FitResult into two parts and returns both parts.

See Box#split for further details.



296
297
298
 
# File 'lib/hexapdf/layout/frame.rb', line 296

def split(fit_result)
  fit_result.box.split(fit_result.available_width, fit_result.available_height, self)
end

#width_specification(offset = 0) ⇒ Object

Returns a width specification for the frame's shape 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 shape 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.



363
364
365
 
# File 'lib/hexapdf/layout/frame.rb', line 363

def width_specification(offset = 0)
  WidthFromPolygon.new(shape, offset)
end