class HexaPDF:: Composer
Parent | Object |
---|
The composer class can be used to create PDF documents from scratch. It uses HexaPDF::Layout::Frame
and HexaPDF::Layout::Box
objects underneath and binds them together to provide a convenient interface for working with them.
Usage¶ ↑
First, a new Composer
objects needs to be created, either using ::new
or the utility method ::create
.
On creation a HexaPDF::Document
object is created as well the first page and an accompanying HexaPDF::Layout::Frame
object. The frame is used by the various methods for general document layout tasks, like positioning of text, images, and so on. By default, it covers the whole page except the margin area. How the frame gets created can be customized by overriding the create_frame method.
Once the Composer
object is created, its methods can be used to draw text, images, … on the page. Behind the scenes HexaPDF::Layout::Box
(and subclass) objects are created and drawn on the page via the frame.
If the frame of a page is full and a box doesn't fit anymore, a new page is automatically created. The box is either split into two boxes where one fits on the first page and the other on the new page, or it is drawn completely on the new page. A new page can also be created by calling the new_page
method.
The x
and y
methods provide the point where the next box would be drawn if it fits the available space. This information can be used, for example, for custom drawing operations through canvas
which provides direct access to the HexaPDF::Content::Canvas
object of the current page.
When using canvas
and modifying the graphics state, care has to be taken to avoid problems with later box drawing operations since the graphics state cannot completely be reset (e.g. transformations of the canvas cannot always be undone). So it is best to save the graphics state before and restore it afterwards.
Example¶ ↑
HexaPDF::Composer.create('output.pdf', margin: 36) do |pdf| pdf.base_style.font_size(20).align(:center) pdf.text("Hello World", valign: :center) end
Attributes
The Content::Canvas
of the current page. Can be used to perform arbitrary drawing operations.
The PDF document that is created.
The HexaPDF::Layout::Frame
for automatic box placement.
The current page (a HexaPDF::Type::Page
object).
Public Class Methods
Creates a new PDF document and writes it to output
. The options
are passed to ::new
.
Example:
HexaPDF::Composer.create('output.pdf', margin: 36) do |pdf| ... end
Creates a new Composer
object and optionally yields it to the given block.
- skip_page_creation
-
If this argument is
true
(the default), the argumentspage_size
,page_orientation
andmargin
are used to create a page style with the name :default and an initial page is created as well.Otherwise, i.e. when this argument is
false
, no initial page or default page style is created. This has to be done manually using thepage_style
andnew_page
methods. - page_size
-
Can be any valid predefined page size (see Type::Page::PAPER_SIZE) or an array [llx, lly, urx, ury] specifying a custom page size.
- page_orientation
-
Specifies the orientation of the page, either
:portrait
or:landscape
. Only used ifpage_size
is one of the predefined page sizes. - margin
-
The margin to use. See
HexaPDF::Layout::Style::Quad#set
for possible values.
Example:
composer = HexaPDF::Composer.new # uses the default values HexaPDF::Composer.new(page_size: :Letter, margin: 72) do |composer| #... end HexaPDF::Composer.new(skip_page_creation: true) do |composer| page_template = lambda {|canvas, style| style.create_frame(canvas.context, 36) } page_style(:default, template: page_template) new_page # ... end
Public Instance Methods
Draws the named box at the current position.
It uses HexaPDF::Document::Layout#box
behind the scenes to create the named box. See that method for details on the arguments.
Examples:
composer.box(:image, image: composer.document.images.add(machu_picchu))
Draws text like text
but allows parts of the text to be formatted differently.
It uses HexaPDF::Document::Layout#formatted_text_box
behind the scenes to create the HexaPDF::Layout::TextBox
that does the actual work. See that method for details on the arguments.
Examples:
composer.formatted_text(["Some string"]) composer.formatted_text(["Some ", {text: "string", fill_color: 128}]) composer.formatted_text(["Some ", {link: "https://example.com", fill_color: 'blue', text: "Example"}]) composer.formatted_text(["Some ", {text: "string", style: {font_size: 20}}])
See: text
, HexaPDF::Layout::TextBox
, HexaPDF::Layout::TextFragment
Draws the given image at the current position.
It uses HexaPDF::Document::Layout#image_box
behind the scenes to create the HexaPDF::Layout::ImageBox
that does the actual work. See that method for details on the arguments.
Examples:
composer.image(machu_picchu, border: {width: 3}) composer.image(machu_picchu, height: 30)
Draws any custom box that can be created using HexaPDF::Document::Layout
.
Examples:
composer.lorem_ipsum composer.column {|column| column.lorem_ipsum }
Creates a new page, making it the current one.
The page style to use for the new page can be set via the style
argument. If not provided, the currently set page style is used.
The used page style determines the page style that should be used for the following new pages. If this information is not provided, the used page style is used again.
Examples:
composer.page_style(:cover, page_size: :A4).next_style = :content composer.page_style(:content, page_size: :A4) composer.new_page(:cover) # uses the :cover style, set next style to :content composer.new_page # uses the :content style, next style again :content
Creates and/or returns the page style name
.
If no attributes are given, the page style name
is returned. In case it does not exist, nil
is returned.
If one or more page style attributes are given, a new HexaPDF::Layout::PageStyle
object with those attribute values is created, stored under name
and returned. If a block is provided, it is used to define the page template.
Example:
composer.page_style(:default) composer.page_style(:cover, page_size: :A4) do |canvas, style| page_box = canvas.context.box canvas.fill_color("fd0") do canvas.rectangle(0, 0, page_box.width, page_box.height). fill end style.frame = style.create_frame(canvas.context, 36) end
Creates or updates the HexaPDF::Layout::Style
object called name
with the given property values and returns it.
See HexaPDF::Document::Layout#style
for details; this method is just a thin wrapper around that method.
Example:
composer.style(:base, font_size: 12, leading: 1.2) composer.style(:header, font: 'Helvetica', fill_color: "008") composer.style(:header1, base: :header, font_size: 30)
Draws the given text at the current position into the current frame.
The text will be positioned at the current position if possible. Otherwise the next best position is used. If the text doesn't fit onto the current page or only partially, new pages are created automatically.
This method is of the two main methods for creating text boxes, the other being formatted_text
. It uses HexaPDF::Document::Layout#text_box
behind the scenes to create the HexaPDF::Layout::TextBox
that does the actual work.
See HexaPDF::Document::Layout#text_box
for details on the arguments.
Examples:
composer.text("Test " * 15) composer.text("Now " * 7, width: 100) composer.text("Another test", font_size: 15, fill_color: "green") composer.text("Different box style", fill_color: 'white', box_style: { underlays: [->(c, b) { c.rectangle(0, 0, b.content_width, b.content_height).fill }] })
Writes the PDF document to the given output.
See Document#write
for details.
The x-position of the cursor inside the current frame.
The y-position of the cursor inside the current frame.