123456789_123456789_123456789_123456789_123456789_

Class: Layout::Document

Relationships
Inherits: Object

Overview

This is the interface to a LayOut document. A Document is the 2D drawing that the user is working with, and it serves as the “entry point” for most Ruby API interactions. The .open method gives you a handle to a Document, and from there you can use the document-level methods to start getting information and making changes.

Examples:

# Grab a handle to an existing LayOut document.
doc = Layout::Document.open("C:/path/to/document.layout")

# Grab other handles to commonly used collections inside the model.
layers = doc.layers
pages = doc.pages
entities = doc.shared_entities

# Now that we have our handles, we can start pulling objects and making
# method calls that are useful.
first_entity = entities[0]

number_pages = pages.count

Version:

  • LayOut 2018

Constant Summary

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new ⇒ Document .new(template_path) ⇒ Document

The #initialize method creates a new Document. Passing a path to an existing Document will use that file as a template. The new Document won’t have a path until it is saved for the first time.

Examples:

doc = Layout::Document.new
doc2 = Layout::Document.new("/path/to/template.layout")

Overloads:

  • .new ⇒ Document
  • .new(template_path) ⇒ Document

    Parameters:

    • template_path (String) —

      The path to the Document to use as a template

Raises:

  • (RuntimeError) —

    if there was an error reading the template file

  • (ArgumentError) —

    if the template file could not be found

Version:

  • LayOut 2018

Class Method Details

.open(path) ⇒ Document

The .open method creates a new Document by loading an existing .layout file.

Examples:

filename = File.join(ENV['Home'], 'Desktop', 'template.layout')
doc = Layout::Document.open(filename)

Parameters:

  • path (String) —

    The path to the .layout file on disk.

Returns:

  • (Document) —

    The Document created from the .layout file.

Raises:

  • (ArgumentError) —

    if the file does not exist

Version:

  • LayOut 2018

Instance Attribute Details

#grid_snap_enabled=(enabled) (rw)

The #grid_snap_enabled= method sets whether or not grid snap is enabled in the Document.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
doc.grid_snap_enabled = true

Parameters:

  • enabled (Boolean) —

    true for enabled false for disabled

Version:

  • LayOut 2018

#grid_snap_enabled? ⇒ Boolean (rw)

The #grid_snap_enabled? method returns whether or not grid snap is enabled in the Document.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
enabled = doc.grid_snap_enabled?

Version:

  • LayOut 2018

#object_snap_enabled=(enabled) (rw)

The #object_snap_enabled= method enables or disables inference in the Document.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
doc.object_snap_enabled = false

Parameters:

  • enabled (Boolean) —

    true for enabled false for disabled

Version:

  • LayOut 2018

#object_snap_enabled? ⇒ Boolean (rw)

The #object_snap_enabled? method returns whether or not inference is enabled in the Document.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
enabled = doc.object_snap_enabled?

Version:

  • LayOut 2018

#precision ⇒ Float (rw)

The #precision method returns the precision for the Document.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
precision = doc.precision

Returns:

  • (Float) —

    the number specifying the precision for the Document

Version:

  • LayOut 2018

#precision=(precision) (rw)

Note:

LayOut only allows for a finite set of precision values for each units setting, so it will set the precision to the closest valid setting for the specified units. See the “Units” section of LayOut’s “Document Setup” dialog for a reference of the available precisions for each units setting.

The #precision= method sets the precision for the Document.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
doc.precision = 0.0001

Parameters:

  • precision (Float) —

    The double specifying the precision for the Document

Version:

  • LayOut 2018

#render_mode_override ⇒ Integer (rw)

The #render_mode_override method returns the override setting for output render modes of SketchUpModels in the Document.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
render_mode = doc.render_mode_override

Version:

  • LayOut 2023.1

#render_mode_override=(render_mode) (rw)

The #render_mode_override= method sets the override setting for output render modes of SketchUpModels in the Document. Setting this to NO_OVERRIDE will prevent overriding the individual SketchUpModel render mode setting during export. This override will only affect raster rendered SketchUpModels, if a viewport is set to vector or hybrid, it will retain that render mode as its output render mode.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
doc.render_mode_override = Layout::SketchUpModel::VECTOR_RENDER

Parameters:

  • render_mode (Integer) —

    NO_OVERRIDE, VECTOR_RENDER, or HYBRID_RENDER

Raises:

  • (ArgumentError) —

    if render_mode is not a valid render mode

  • (ArgumentError) —

    if render_mode is RASTER_RENDER

Version:

  • LayOut 2023.1

#units ⇒ Integer (rw)

The #units method returns the units for the Document.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
units = doc.units

Returns:

  • (Integer) —

    The unit format of the Document

Version:

  • LayOut 2018

#units=(units_format) (rw)

The #units= method sets the units for the Document.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
units_format = LAYOUT::DOCUMENT::DECIMAL_MILLIMETERS
doc.units = units_format

Parameters:

  • units_format (Integer) —

    The format of the units in the Document

Raises:

  • (ArgumentError) —

    if units format is not a valid format

Version:

  • LayOut 2018

Instance Method Details

#==(other) ⇒ Boolean

The #== method checks to see if the two Documents are equal. This checks whether the Ruby Objects are pointing to the same internal object.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
document = doc.pages.first.document
doc == document

Parameters:

  • other (Document)

Version:

  • LayOut 2018

#add_entity(entity, layer, page) #add_entity(entity, layer)

The #add_entity method adds an Entity to the Document and places it on the given Layer and Page. If layer is a shared Layer then page may be ommitted. The Entity must not already belong to a Document. If the Entity is a Group, then the Group along with all of its children will be added to the Document.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
rect = Layout::Rectangle.new([[1, 1], [2, 2]])
all_layers = doc.layers
all_pages = doc.pages
doc.add_entity(rect, all_layers.first, all_pages.first)

Overloads:

Raises:

  • (ArgumentError) —

    if no Page is passed in and layer is non-shared

  • (ArgumentError) —

    if page does not belong to the Document

  • (ArgumentError) —

    if layer does not belong to the Document

  • (ArgumentError) —

    if entity already belongs to a Document

Version:

  • LayOut 2018

#auto_text_definitions ⇒ Layout::AutoTextDefinitions

The #auto_text_definitions method returns an array of AutoTextDefinition‘s in the Document.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
defs = doc.auto_text_definitions

Version:

  • LayOut 2018

#export(file_path, options = nil)

The #export method exports the Document to a given file format. It knows which format to export based on the file extension you place on the file name. For example, a filename of “thing.pdf” will export a PDF file, whereas “thing.png” will export a set of PNG images.

For LayOut version 2020.1, valid extensions include .pdf, .jpg, and .png.

Examples:

PDF Export Examples

doc = Layout::Document.open("c:/path/to/document.layout")

# Export pdf file on a PC, with default settings.
status = doc.export("c:/my_export.pdf")

# Export pages one through three at high quality, compressing jpeg images
# at 0.75 compression quality (valid range is 0.0 - 1.0). Note that the
# first page of a {Layout::Document} is index 0.
options = { start_page: 1,
            end_page: 3,
            compress_images: TRUE,
            compress_quality: 0.75 }

status = doc.export("c:/my_export.pdf", options)

# Export pages one and three through five. Note that page_range starts at
# index 1.
# `page_range` support added in LayOut 2024.0.
options = { page_range: "1,3-5",
            compress_images: TRUE,
            compress_quality: 0.75 }

status = doc.export("c:/my_export.pdf", options)

Image Set Export Examples

doc = Layout::Document.open("c:/path/to/document.layout")

# Export png files on macOS, with default settings.
status = doc.export("/Users/<username>/Desktop/pngs/page.png")

# Export pages one through three at 300 dpi as JPGs.
options = { start_page: 1,
            end_page: 3,
            dpi: 300 }
status = doc.export('c:/page.jpg', options)

# Export pages one and three through five. Note that page_range starts at
# index 1.
# `page_range` support added in LayOut 2024.0.
options = { page_range: "1,3-5",
            compress_images: TRUE,
            compress_quality: 0.75 }

status = doc.export("c:/my_export.png", options)

Parameters:

  • file_path (String) —

    The file or image set to create. The directory path must already exist. The path must include the file extension.

  • options (Hash, nil) (defaults to: nil) —

    An optional hash of settings for the export.

Raises:

  • (TypeError) —

    if an options value is the wrong type

  • (RangeError) —

    if an options value is out of range

  • (ArgumentError) —

    if the full file path does not exist

  • (ArgumentError) —

    if the specified file type is missing or not supported

Version:

  • LayOut 2020.1

#grid ⇒ Layout::Grid

The #grid method returns the Grid for a Document.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
grid = doc.grid

Version:

  • LayOut 2018

#layers ⇒ Layout::Layers

The #layers method returns the Layers of the Document.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
layers = doc.layers

Version:

  • LayOut 2018

#page_info ⇒ Layout::PageInfo

The #page_info method returns a reference to the PageInfo settings of the Document.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
page_info = doc.page_info

Version:

  • LayOut 2018

#pages ⇒ Layout::Pages

The #pages method returns the Pages of the Document.

@example:

doc = Layout::Document.open("C:/path/to/document.layout")
doc_pages = doc.pages

Returns:

Version:

  • LayOut 2018

#path ⇒ String

The #path method returns the full path of the Document file. An empty string is returned for a new Document (one which has not been saved and opened).

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
path = doc.path

Version:

  • LayOut 2018

#remove_entity(entity)

The #remove_entity method removes an Entity from the Document. If entity is a Group, then the Group and all of its children will be removed from the Document.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
shared_entities = doc.shared_entities
# Remove the first entity in the document
doc.remove_entity(shared_entities.first)

Parameters:

Raises:

  • (ArgumentError) —

    if entity does not belong to the Document

Version:

  • LayOut 2018

#save #save(path, version = Layout::Document::VERSION_CURRENT)

The #save method saves the Document to a file at the given path. Passing an empty path string will save the Document at its current path.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
# Save the model using the current Layout format
path = File.join(ENV['Home'], 'Desktop', 'mydoc.layout')
status = doc.save(path)
# Save the document to the current file using the current LayOut format
status = doc.save
# Save the document to the current file in LayOut 3 format
status = doc.save(Layout::Document::VERSION_3)
# Save the document in LayOut 2013 format
path = File.join(ENV['Home'], 'Desktop', 'mydoc_v2013.layout')
status = doc.save(path, Layout::Document::VERSION_2013)

Overloads:

  • #save

    path yet

    Raises:

    • (ArgumentError) —

      if the Document hasn’t been saved with a

  • #save(path, version = Layout::Document::VERSION_CURRENT)

    Parameters:

    • path (String) —

      The path to the .layout file on disk.

    • version (Integer) (defaults to: Layout::Document::VERSION_CURRENT) —

      LayOut file format to save.

Raises:

  • (ArgumentError) —

    if version is not a valid version

  • (ArgumentError) —

    if saving failed. This may be due to the LayOut file being open in the LayOut application

Version:

  • LayOut 2018

#shared_entities ⇒ Layout::Entities

The #shared_entities method returns the Entities that exist on shared Layers in the Document.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
entities = doc.shared_entities

Version:

  • LayOut 2018

#time_created ⇒ Time

The #time_created method returns the time when the Document was created.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
created_time = doc.time_created

Returns:

  • (Time) —

    time when the Document was created

Version:

  • LayOut 2018

#time_modified ⇒ Time

The #time_modified method returns the last time the Document was modified.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
mod_time = doc.time_modified

Returns:

  • (Time) —

    time when the Document was last modified

Version:

  • LayOut 2018

#time_published ⇒ Time

The #time_published method returns the time when the Document was published.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
pub_time = doc.time_published

Returns:

  • (Time) —

    time when the Document was published

Version:

  • LayOut 2018