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 provided available width and height are 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’, ‘align’, ‘valign’, ‘margin’ and ‘mask_mode’ 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, context: nil) ⇒ Frame

Creates a new Frame object for the given rectangular area.



196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
 
# File 'lib/hexapdf/layout/frame.rb', line 196

def initialize(left, bottom, width, height, shape: nil, context: nil)
  @left = left
  @bottom = bottom
  @width = width
  @height = height
  @shape = shape || create_rectangle(left, bottom, left + width, bottom + height)
  @context = context

  @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 of the current region for placing a box.

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



189
190
191
 
# File 'lib/hexapdf/layout/frame.rb', line 189

def available_height
  @available_height
end

#available_width ⇒ Object (readonly)

The available width of the current region for placing a box.

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



184
185
186
 
# File 'lib/hexapdf/layout/frame.rb', line 184

def available_width
  @available_width
end

#bottom ⇒ Object (readonly)

The y-coordinate of the bottom-left corner.



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

def bottom
  @bottom
end

#context ⇒ Object (readonly)

The context object (a HexaPDF::Type::Page or HexaPDF::Type::Form) for which this frame should be used.



193
194
195
 
# File 'lib/hexapdf/layout/frame.rb', line 193

def context
  @context
end

#height ⇒ Object (readonly)

The height of the frame.



164
165
166
 
# File 'lib/hexapdf/layout/frame.rb', line 164

def height
  @height
end

#left ⇒ Object (readonly)

The x-coordinate of the bottom-left corner.



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

def left
  @left
end

#shape ⇒ Object (readonly)

The shape of the frame, either a Geom2D::Rectangle in the simple case or a Geom2D::PolygonSet consisting of rectilinear polygons in the more complex case.



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

def shape
  @shape
end

#width ⇒ Object (readonly)

The width of the frame.



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

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.



174
175
176
 
# File 'lib/hexapdf/layout/frame.rb', line 174

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.



179
180
181
 
# File 'lib/hexapdf/layout/frame.rb', line 179

def y
  @y
end

Instance Method Details

#document ⇒ Object

Returns the HexaPDF::Document instance (through #context) that is associated with this Frame object or nil if no context object has been set.



215
216
217
 
# File 'lib/hexapdf/layout/frame.rb', line 215

def document
  @context&.document
end

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



357
358
359
360
361
 
# File 'lib/hexapdf/layout/frame.rb', line 357

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 fitting or drawing a box 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.



372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
 
# File 'lib/hexapdf/layout/frame.rb', line 372

def find_next_region
  case @region_selection
  when :max_width
    if @shape.kind_of?(Geom2D::Rectangle)
      @x = @shape.x
      @y = @shape.y + @shape.height
      @available_width = @shape.width
      @available_height = @shape.height
      @region_selection = :trim_shape
    else
      find_max_width_region
      @region_selection = :max_height
    end
  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.

Fitting a box takes the style properties ‘position’, ‘align’, ‘valign’, ‘margin’, and ‘mask_mode’ into account.

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



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
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
 
# File 'lib/hexapdf/layout/frame.rb', line 226

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

  margin = box.style.margin if box.style.margin?

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

  if position.kind_of?(Array)
    x, y = box.style.position

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

    x += left
    y += bottom
  else
    aw = available_width
    ah = available_height

    margin_top = margin_right = margin_left = margin_bottom = 0
    if 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 = 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 :default, :float
      x = case box.style.align
          when :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 = case box.style.valign
          when :top
            @y - margin_top - height
          when :bottom
            @y - available_height + margin_bottom
          when :center
            max_margin = [margin_top, margin_bottom].max
            # If we have enough space left for equal margins, we center perfectly
            if available_height - height >= 2 * max_margin
              @y - height - (available_height - height) / 2.0
            else
              @y - margin_top - height - (ah - height) / 2.0
            end
          end
    when :flow
      x = 0
      y = @y - height
    else
      raise HexaPDF::Error, "Invalid value '#{position}' for style property position"
    end
  end

  mask_mode = if box.style.mask_mode == :default
                case position
                when :default, :flow then :fill_frame_horizontal
                else :box
                end
              else
                box.style.mask_mode
              end
  rectangle =
    case mask_mode
    when :none
      create_rectangle(x, y, x, y)
    when :box
      if margin
        create_rectangle([left, x - (margin&.left || 0)].max,
                         [bottom, y - (margin&.bottom || 0)].max,
                         [left + self.width, x + box.width + (margin&.right || 0)].min,
                         [bottom + self.height, y + box.height + (margin&.top || 0)].min)
      else
        create_rectangle(x, y, x + box.width, y + box.height)
      end
    when :fill_horizontal
      create_rectangle(@x, [bottom, y - (margin&.bottom || 0)].max,
                       @x + available_width,
                       [@y, y + box.height + (margin&.top || 0)].min)
    when :fill_frame_horizontal
      create_rectangle(left, [bottom, y - (margin&.bottom || 0)].max,
                       left + self.width, @y)
    when :fill_vertical
      create_rectangle([@x, x - (margin&.left || 0)].max, @y - available_height,
                       [@x + available_width, x + box.width + (margin&.right || 0)].min, @y)
    when :fill
      create_rectangle(@x, @y - available_height, @x + available_width, @y)
    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) 


420
421
422
 
# File 'lib/hexapdf/layout/frame.rb', line 420

def full?
  available_width == 0
end

#remove_area(polygon) ⇒ Object

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



401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
 
# File 'lib/hexapdf/layout/frame.rb', line 401

def remove_area(polygon)
  return if polygon.kind_of?(Geom2D::Rectangle) && (polygon.width == 0 || polygon.height == 0)

  @shape = if @shape.kind_of?(Geom2D::Rectangle) && polygon.kind_of?(Geom2D::Rectangle) &&
               float_equal(@shape.x, polygon.x) && float_equal(@shape.width, polygon.width) &&
               float_equal(@shape.y + @shape.height, polygon.y + polygon.height)
             if float_equal(@shape.height, polygon.height)
               Geom2D::PolygonSet()
             else
               Geom2D::Rectangle(@shape.x, @shape.y, @shape.width, @shape.height - polygon.height)
             end
           else
             Geom2D::Algorithms::PolygonOperation.run(@shape, polygon, :difference)
           end
  @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.



349
350
351
 
# File 'lib/hexapdf/layout/frame.rb', line 349

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.



436
437
438
 
# File 'lib/hexapdf/layout/frame.rb', line 436

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