class Layout::Document
This is the interface to a LayOut document. A {Layout::Document} is the 2D drawing that the user is working with, and it serves as the “entry point” for most Ruby API interactions. The {Layout::Document.open} method gives you a handle to a {Layout::Document}, and from there you can use the document-level methods to start getting information and making changes.
@example
# 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
Constants
- DECIMAL_CENTIMETERS
Constants
- DECIMAL_FEET
- DECIMAL_INCHES
- DECIMAL_METERS
- DECIMAL_MILLIMETERS
- DECIMAL_POINTS
- FRACTIONAL_INCHES
- VERSION_1
- VERSION_2
- VERSION_2013
- VERSION_2014
- VERSION_2015
- VERSION_2016
- VERSION_2017
- VERSION_2018
- VERSION_2019
- VERSION_2020
- VERSION_2021
- VERSION_3
- VERSION_CURRENT
Public Class Methods
The {#initialize} method creates a new {Layout::Document}. Passing a path to an existing {Layout::Document} will use that file as a template. The new {Layout::Document} won't have a path until it is saved for the first time.
@example
doc = Layout::Document.new doc2 = Layout::Document.new("/path/to/template.layout")
@overload initialize
@return [Layout::Document] an empty {Layout::Document} with one {Layout::Layer} and one {Layout::Page}
@overload initialize(template_path)
@param [String] template_path The path to the {Layout::Document} to use as a template @return [Layout::Document] an unsaved {Layout::Document} based on the template
@raise [RuntimeError] if there was an error reading the template file
@raise [ArgumentError] if the template file could not be found
@version LayOut 2018
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 266 def initialize(*args) end
The {.open} method creates a new {Layout::Document} by loading an existing .layout file.
@example
filename = File.join(ENV['Home'], 'Desktop', 'template.layout') doc = Layout::Document.open(filename)
@param [String] path
The path to the .layout file on disk.
@raise [ArgumentError] if the file does not exist
@return [Layout::Document] The {Layout::Document} created from the .layout
file.
@version LayOut 2018
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 71 def self.open(path) end
Public Instance Methods
The {#==} method checks to see if the two {Layout::Document}s are equal. This checks whether the Ruby Objects are pointing to the same internal object.
@example
doc = Layout::Document.open("C:/path/to/document.layout") document = doc.pages.first.document doc == document
@param [Layout::Document] other
@return [Boolean]
@version LayOut 2018
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 90 def ==(other) end
The {#add_entity} method adds an {Layout::Entity} to the {Layout::Document} and places it on the given {Layout::Layer} and {Layout::Page}. If layer is a shared {Layout::Layer} then page may be ommitted. The {Layout::Entity} must not already belong to a {Layout::Document}. If the {Layout::Entity} is a {Layout::Group}, then the {Layout::Group} along with all of its children will be added to the {Layout::Document}.
@example
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)
@overload add_entity
(entity, layer, page)
@param [Layout::Entity] entity The {Layout::Entity} to be added @param [Layout::Layer] layer The {Layout::Layer} to add the {Layout::Entity} to @param [Layout::Page] page The {Layout::Page} to add the {Layout::Entity} to
@overload add_entity
(entity, layer)
@param [Layout::Entity] entity The {Layout::Entity} to be added @param [Layout::Layer] layer The shared {Layout::Layer} to add the {Layout::Entity} to
@raise [ArgumentError] if no {Layout::Page} is passed in and layer is
non-shared
@raise [ArgumentError] if page does not belong to the {Layout::Document}
@raise [ArgumentError] if layer does not belong to the {Layout::Document}
@raise [ArgumentError] if entity already belongs to a {Layout::Document}
@version LayOut 2018
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 131 def add_entity(*args) end
The {#auto_text_definitions} method returns an array of {Layout::AutoTextDefinition}'s in the {Layout::Document}.
@example
doc = Layout::Document.open("C:/path/to/document.layout") defs = doc.auto_text_definitions
@return [Layout::AutoTextDefinitions]
@version LayOut 2018
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 144 def auto_text_definitions end
The {#export} method exports the {Layout::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.
@example 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, output_resolution: Layout::PageInfo::RESOLUTION_HIGH, compress_images: TRUE, compress_quality: 0.75 } status = doc.export("c:/my_export.pdf", options)
@example 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)
@param [String] file_path
The file or image set to create. The directory path must already exist. The path must include the file extension.
@param [Hash, nil] options
An optional hash of settings for the export.
@raise [TypeError] if an options value is the wrong type
@raise [RangeError] if an options value is out of range
@raise [ArgumentError] if the full file path does not exist
@raise [ArgumentError] if the specified file type is missing or not supported
@version LayOut 2020.1
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 199 def export(file_path, options = nil) end
The {#grid} method returns the {Layout::Grid} for a {Layout::Document}.
@example
doc = Layout::Document.open("C:/path/to/document.layout") grid = doc.grid
@return [Layout::Grid]
@version LayOut 2018
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 211 def grid end
The {#grid_snap_enabled=} method sets whether or not grid snap is enabled in the {Layout::Document}.
@example
doc = Layout::Document.open("C:/path/to/document.layout") doc.grid_snap_enabled = true
@param [Boolean] enabled
+true+ for enabled +false+ for disabled
@version LayOut 2018
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 225 def grid_snap_enabled=(enabled) end
The {#grid_snap_enabled?} method returns whether or not grid snap is enabled in the {Layout::Document}.
@example
doc = Layout::Document.open("C:/path/to/document.layout") enabled = doc.grid_snap_enabled?
@return [Boolean]
@version LayOut 2018
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 238 def grid_snap_enabled? end
The {#layers} method returns the {Layout::Layers} of the {Layout::Document}.
@example
doc = Layout::Document.open("C:/path/to/document.layout") layers = doc.layers
@return [Layout::Layers]
@version LayOut 2018
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 278 def layers end
The {#object_snap_enabled=} method enables or disables inference in the {Layout::Document}.
@example
doc = Layout::Document.open("C:/path/to/document.layout") doc.object_snap_enabled = false
@param [Boolean] enabled
+true+ for enabled +false+ for disabled
@version LayOut 2018
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 292 def object_snap_enabled=(enabled) end
The {#object_snap_enabled?} method returns whether or not inference is enabled in the {Layout::Document}.
@example
doc = Layout::Document.open("C:/path/to/document.layout") enabled = doc.object_snap_enabled?
@return [Boolean]
@version LayOut 2018
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 305 def object_snap_enabled? end
The {#page_info} method returns a reference to the {Layout::PageInfo} settings of the {Layout::Document}.
@example
doc = Layout::Document.open("C:/path/to/document.layout") page_info = doc.page_info
@return [Layout::PageInfo]
@version LayOut 2018
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 318 def page_info end
The {#pages} method returns the {Layout::Pages} of the {Layout::Document}.
@example:
doc = Layout::Document.open("C:/path/to/document.layout") doc_pages = doc.pages
@return [Layout::Pages] The {Layout::Pages} for the {Layout::Document}.
@version LayOut 2018
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 331 def pages end
The {#path} method returns the full path of the {Layout::Document} file. An empty string is returned for a new {Layout::Document} (one which has not been saved and opened).
@example
doc = Layout::Document.open("C:/path/to/document.layout") path = doc.path
@return [String]
@version LayOut 2018
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 345 def path end
The {#precision} method returns the precision for the {Layout::Document}.
@example
doc = Layout::Document.open("C:/path/to/document.layout") precision = doc.precision
@return [Float] the number specifying the precision for the
{Layout::Document}
@version LayOut 2018
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 358 def precision end
The {#precision=} method sets the precision for the {Layout::Document}.
@example
doc = Layout::Document.open("C:/path/to/document.layout") doc.precision = 0.0001
@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.
@param [Float] precision
The double specifying the precision for the {Layout::Document}
@version LayOut 2018
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 377 def precision=(precision) end
The {#remove_entity} method removes an {Layout::Entity} from the {Layout::Document}. If entity is a {Layout::Group}, then the {Layout::Group} and all of its children will be removed from the {Layout::Document}.
@example
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)
@param [Layout::Entity] entity
The {Layout::Entity} to be removed
@raise [ArgumentError] if entity does not belong to the {Layout::Document}
@version LayOut 2018
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 396 def remove_entity(entity) end
The {#save} method saves the {Layout::Document} to a file at the given path. Passing an empty path string will save the {Layout::Document} at its current path.
@example
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)
@overload save
@raise [ArgumentError] if the {Layout::Document} hasn't been saved with a path yet
@overload save(path, version = Layout::Document::VERSION_CURRENT
)
@param [String] path The path to the .layout file on disk. @param [Integer] version LayOut file format to save.
@raise [ArgumentError] if version is not a valid version
@raise [ArgumentError] if saving failed. This may be due to the LayOut file
being open in the LayOut application
@version LayOut 2018
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 432 def save(*args) end
The {#time_created} method returns the time when the {Layout::Document} was created.
@example
doc = Layout::Document.open("C:/path/to/document.layout") created_time = doc.time_created
@return [Time] time when the {Layout::Document} was created
@version LayOut 2018
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 458 def time_created end
The {#time_modified} method returns the last time the {Layout::Document} was modified.
@example
doc = Layout::Document.open("C:/path/to/document.layout") mod_time = doc.time_modified
@return [Time] time when the {Layout::Document} was last modified
@version LayOut 2018
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 471 def time_modified end
The {#time_published} method returns the time when the {Layout::Document} was published.
@example
doc = Layout::Document.open("C:/path/to/document.layout") pub_time = doc.time_published
@return [Time] time when the {Layout::Document} was published
@version LayOut 2018
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 484 def time_published end
The {#units} method returns the units for the {Layout::Document}.
@example
doc = Layout::Document.open("C:/path/to/document.layout") units = doc.units
@return [Integer] The unit format of the {Layout::Document}
@version LayOut 2018
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 496 def units end
The {#units=} method sets the units for the {Layout::Document}.
@example
doc = Layout::Document.open("C:/path/to/document.layout") units_format = LAYOUT::DOCUMENT::DECIMAL_MILLIMETERS doc.units = units_format
@param [Integer] units_format
The format of the units in the {Layout::Document}
@raise [ArgumentError] if units format is not a valid format
@version LayOut 2018
# File lib/sketchup-api-stubs/stubs/Layout/Document.rb, line 512 def units=(units_format) end