Class: Layout::Entity

Relationships
Extension / Inclusion / Inheritance Descendants
Subclasses: AngularDimension, Ellipse, FormattedText, Group, Image, Label, LinearDimension, Path, Rectangle, ReferenceEntity, SketchUpModel, Table
Inherits:	Object

Overview

An entity is an object shown on a page of a LayOut document.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
# Get the shared entities in the document. If there are no shared layers,
# the resulting array will be empty.
entities = doc.shared_entities

# Count how many of the shared entites are rectangles.
rectangle_count = entities.grep(Layout::Rectangle).size

Version:

LayOut 2018

Instance Attribute Summary

#locked=(is_locked) rw

The #locked= method sets the Entity as locked or unlocked.
#locked? ⇒ Boolean rw

The #locked? method returns whether the Entity is locked or unlocked.
#on_shared_layer? ⇒ Boolean readonly

The #on_shared_layer? method returns whether or not the Entity is on a shared Layer.
#style ⇒ Layout::Style^? rw

The #style method returns the Style of the Entity.
#style=(style) rw

The #style= method sets the Style of the Entity.
#untransformed_bounds ⇒ Geom::Bounds2d rw

The #untransformed_bounds method returns the untransformed bounds of the Entity.
#untransformed_bounds=(bounds) rw

The #untransformed_bounds= method sets the untransformed bounds of the Entity.

Instance Method Summary

#==(other) ⇒ Boolean

The #== method checks to see if the two Entitys are equal.
#attribute_dictionary(name) ⇒ Layout::Dictionary^?

The #attribute_dictionary method returns a copy of the entity’s attribute dictionary with the given name.
#bounds ⇒ Geom::Bounds2d

The #bounds method returns the 2D rectangular bounds of the Entity.
#delete_attribute(dictionary_name) ⇒ Boolean

The #delete_attribute method is used to delete an attribute from an entity.
#document ⇒ Layout::Document^?

The #document method returns the Document that the Entity belongs to, or nil if it is not in a Document.
#drawing_bounds ⇒ Geom::OrientedBounds2d

The #drawing_bounds method returns the 2D rectangular drawing bounds of the Entity.
#get_attribute(name, key, default_value = nil) ⇒ String, ...

The #get_attribute method is used to retrieve the value of an attribute in the entity’s attribute dictionary.
#group ⇒ Layout::Group^?

The #group method returns the Group the Entity belongs to, or nil if it is not in a Group.
#layer_instance ⇒ Layout::LayerInstance^?

The #layer_instance method returns the LayerInstance that the Entity is on, or nil if it is not associated with a LayerInstance.
#move_to_group(group)

The #move_to_group method moves the Entity into a Group.
#move_to_layer(layer)

The #move_to_layer method moves the Entity to the given Layer.
#page ⇒ Layout::Page^?

The #page method returns the Page that the Entity belongs to, or nil if it is on a shared Layer or not in a Document.
#set_attribute(name, key, value)

The #set_attribute method adds an attribute to the entity’s attribute dictionary.
#transform!(transformation)

The #transform! method transforms the Entity with a given ::Geom::Transformation2d.
#transformation ⇒ Geom::Transformation2d^?

The #transformation method returns the explicit ::Geom::Transformation2d.

Instance Attribute Details

#locked=(is_locked) (rw)

The #locked= method sets the Entity as locked or unlocked. When locked, the Entity cannot be modified directly.

Examples:

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

Parameters:

is_locked (Boolean)

Version:

LayOut 2018

#locked? ⇒ `Boolean` (rw)

The #locked? method returns whether the Entity is locked or unlocked.

Examples:

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

Version:

LayOut 2018

#on_shared_layer? ⇒ `Boolean` (readonly)

The #on_shared_layer? method returns whether or not the Entity is on a shared Layer. This function works for all Entity types, including Group. Groups do not belong to a specific Layer, but their children are all on either a shared or non-shared Layer.

Examples:

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

Raises:

(ArgumentError) —

if the Entity is not in a Document

Version:

LayOut 2018

#style ⇒ Layout::Style^? (rw)

The #style method returns the Style of the Entity. If the Entity is a Group, nil will be returned, as they do not have a Style.

Examples:

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

Version:

LayOut 2018

#style=(style) (rw)

The #style= method sets the Style of the Entity.

Parameters:

style (Layout::Style)

Raises:

(LockedLayerError) —

if the Entity is on a locked Layer
(LockedEntityError) —

if the Entity is locked

Version:

LayOut 2018

#untransformed_bounds ⇒ Geom::Bounds2d (rw)

The #untransformed_bounds method returns the untransformed bounds of the Entity. This is the bounds of the Entity before its explicit ::Geom::Transformation2d is applied.

Examples:

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

Raises:

(ArgumentError) —

if the Entity does not have an explicit ::Geom::Transformation2d

Version:

LayOut 2018

#untransformed_bounds=(bounds) (rw)

The #untransformed_bounds= method sets the untransformed bounds of the Entity. This is the bounds of the Entity before its explicit ::Geom::Transformation2d is applied.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
entities = doc.pages.first.entities
point1 = Geom::Point2d.new(1, 1)
point2 = Geom::Point2d.new(2, 2)
bounds = Geom::Bounds2d(point1, point2)
entities.first.untransformed_bounds = bounds

Parameters:

bounds (Geom::Bounds2d)

Raises:

(ArgumentError) —

if the Entity does not have an explicit ::Geom::Transformation2d
(LockedLayerError) —

if the Entity is on a locked Layer
(LockedEntityError) —

if the Entity is locked
(ArgumentError) —

if the bounds are of zero size

Version:

LayOut 2018

Instance Method Details

#==(other) ⇒ `Boolean`

The #== method checks to see if the two Entitys 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")
page_entities = doc.pages.first.entities
layer_entities = doc.layers.first.layer_instance(page).entities
page_entities.first == layer_entities.first

Parameters:

other (Entity)

Version:

LayOut 2018

#attribute_dictionary(name) ⇒ Layout::Dictionary^?

The #attribute_dictionary method returns a copy of the entity’s attribute dictionary with the given name.

no attribute dictionary

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
entity = doc.pages.first.entities.first
entity.set_attribute("jane_doe_doc_maker", "made_by_doc_maker", true)
attributes = entity.attribute_dictionary("jane_doe_doc_maker")
# Adding to this Layout::Dictionary does not apply to the entity's attribute dictionary, use
#Layout::Entity#set_attribute.
attributes.merge!(doc_id: 42)

Parameters:

name (String)

Returns:

(Layout::Dictionary, nil) —

A copy of the entity’s attribute dictionary, or nil if there is

Version:

LayOut 2026.0

#bounds ⇒ Geom::Bounds2d

The #bounds method returns the 2D rectangular bounds of the Entity.

Examples:

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

Version:

LayOut 2018

#delete_attribute(dictionary_name) ⇒ `Boolean` #delete_attribute(dictionary_name, key) ⇒ `Boolean`

The #delete_attribute method is used to delete an attribute from an entity.

Overloads:

#delete_attribute(dictionary_name) ⇒ Boolean

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
entity = doc.pages.first.entities.first
entity.set_attribute("jane_doe_doc_maker", "made_by_doc_maker", true)
entity.delete_attribute("jane_doe_doc_maker")

Parameters:

dictionary_name (String) —

The name of an attribute dictionary.

#delete_attribute(dictionary_name, key) ⇒ Boolean

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
entity = doc.pages.first.entities.first
entity.set_attribute("jane_doe_doc_maker", "made_by_doc_maker", true)
entity.delete_attribute("jane_doe_doc_maker", "made_by_doc_maker")

Parameters:

dictionary_name (String) —

The name of an attribute dictionary.
key (String) —

An attribute key.

Version:

LayOut 2026.0

#document ⇒ Layout::Document^?

The #document method returns the Document that the Entity belongs to, or nil if it is not in a Document.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
entities = doc.shared_entities
# entity_doc should be the same document as doc
entity_doc = entities.first.document

Version:

LayOut 2018

#drawing_bounds ⇒ Geom::OrientedBounds2d

The #drawing_bounds method returns the 2D rectangular drawing bounds of the Entity.

Examples:

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

Version:

LayOut 2018

#get_attribute(name, key, default_value = nil) ⇒ String, ...

The #get_attribute method is used to retrieve the value of an attribute in the entity’s attribute dictionary.

If the third parameter, default_value, is not passed and there is no attribute that matches the given name, it returns nil.

If default_value is provided and there is no matching attribute it returns the given value. It does not create an attribute with that name though.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
entity = doc.pages.first.entities.first
# Read an attribute value from the entity. In this case this will return the
# default value provided: 42.
entity.get_attribute("jane_doe_doc_maker", "doc_id", 42)

Parameters:

name (String) —

The name of an attribute dictionary.
key (String) —

An attribute key.
default_value (String, Boolean, Integer, Float, Hash, Layout::Dictionary, nil) (defaults to: nil) —

A default value to return if no attribute is found.

Returns:

(String, Boolean, Integer, Float, Layout::Dictionary, nil) —

the retrieved value.

Version:

LayOut 2026.0

#group ⇒ Layout::Group^?

The #group method returns the Group the Entity belongs to, or nil if it is not in a Group.

Examples:

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

Version:

LayOut 2018

#layer_instance ⇒ Layout::LayerInstance^?

Note:

Groups are never associated with a LayerInstance.

The #layer_instance method returns the LayerInstance that the Entity is on, or nil if it is not associated with a LayerInstance.

Examples:

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

Version:

LayOut 2018

#move_to_group(group)

The #move_to_group method moves the Entity into a Group. If the Entity is already in a Group, it will be removed from that Group prior to being added to the new one. If this action results in the old Group containing only one Entity, the old Group will be collapsed and the remaining Entity will be moved to the old Group‘s parent.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
# We consider that there are two rectangle objects in the entities.
entities = doc.layers.first.layer_instance(doc.pages.first).entities
# We move the first rectangle to a new group.
group = Layout::Group.new([entities.first])
# We move the second rectangle to the same group.
entities[1].first.move_to_group(new_group)

Parameters:

group (Layout::Group)

Raises:

(LockedLayerError) —

if the Entity is on a locked Layer
(ArgumentError) —

if entity and group are not in the same Document
(ArgumentError) —

if entity and group are not on the same Page
(ArgumentError) —

if of entity and group one is shared and one is not
(LockedEntityError) —

if the Entity is locked

Version:

LayOut 2018

#move_to_layer(layer) #move_to_layer(layer, pages)

The #move_to_layer method moves the Entity to the given Layer. If the Layer is non-shared and the Entity is currently on a shared Layer, an array of Pages must be provided to move the Entity to. In all other cases, passing in an array of Pages is not necessary. The Entity must belong to the same Document as the the Layer and the Pages.

Examples:

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

Overloads:

#move_to_layer(layer)
Parameters:
- layer (Layout::Layer)
#move_to_layer(layer, pages)
Parameters:
- layer (Layout::Layer)
- pages (Array<Layout::Page>)

Raises:

(ArgumentError) —

if layer is shared and a valid array of non-duplicate Pages is not passed in
(ArgumentError) —

if entity, layer, and pages are not all in the same Document
(LockedLayerError) —

if the Entity is on a locked Layer
(LockedLayerError) —

if layer is locked
(LockedEntityError) —

if the Entity is locked

Version:

LayOut 2018

#page ⇒ Layout::Page^?

The #page method returns the Page that the Entity belongs to, or nil if it is on a shared Layer or not in a Document.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
# page will be nil
page = doc.shared_entities.first.page
# page will be the first page of the document
page = doc.pages.first.nonshared_entities.first.page

Version:

LayOut 2018

#set_attribute(name, key, value)

The #set_attribute method adds an attribute to the entity’s attribute dictionary.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
entity = doc.pages.first.entities.first
entity.set_attribute("jane_doe_doc_maker", "doc_id", 42)

Parameters:

name (String) —
The name of an attribute dictionary. @param [String] key An attribute key. @param [String, Boolean, Integer, Float, Hash, Dictionary, nil] value The value for the
```
attribute.
```

Version:

LayOut 2026.0

#transform!(transformation)

Note:

Since LayOut 2026.1, passing a non-invertible transformation raises an ArgumentError.

The #transform! method transforms the Entity with a given ::Geom::Transformation2d.

Examples:

doc = Layout::Document.open("C:/path/to/document.layout")
entities = doc.pages.first.entities
transform = Geom::Transformation2d.new([1.0, 0.0, 0.0, 1.0, 1.0, 1.0])
entity = entities.first.transform!(transform)

Parameters:

transformation (Geom::Transformation2d)

Raises:

(LockedLayerError) —

if the Entity is on a locked Layer
(LockedEntityError) —

if the Entity is locked
(ArgumentError) —

if the transformation matrix is not invertible

Version:

LayOut 2018

#transformation ⇒ Geom::Transformation2d^?

The #transformation method returns the explicit ::Geom::Transformation2d.

Examples:

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

Version:

LayOut 2018

Class: Layout::Entity

Overview

Instance Attribute Summary

Instance Method Summary

Instance Attribute Details

#locked=(is_locked) (rw)

#locked? ⇒ Boolean (rw)

#on_shared_layer? ⇒ Boolean (readonly)

#style ⇒ Layout::Style? (rw)

#style=(style) (rw)

#untransformed_bounds ⇒ Geom::Bounds2d (rw)

#untransformed_bounds=(bounds) (rw)

Instance Method Details

#==(other) ⇒ Boolean

#attribute_dictionary(name) ⇒ Layout::Dictionary?

#bounds ⇒ Geom::Bounds2d

#delete_attribute(dictionary_name) ⇒ Boolean #delete_attribute(dictionary_name, key) ⇒ Boolean

#document ⇒ Layout::Document?

#drawing_bounds ⇒ Geom::OrientedBounds2d

#get_attribute(name, key, default_value = nil) ⇒ String, ...

#group ⇒ Layout::Group?

#layer_instance ⇒ Layout::LayerInstance?

#move_to_group(group)

#move_to_layer(layer) #move_to_layer(layer, pages)

#page ⇒ Layout::Page?

#set_attribute(name, key, value)

#transform!(transformation)

#transformation ⇒ Geom::Transformation2d?

#locked? ⇒ `Boolean` (rw)

#on_shared_layer? ⇒ `Boolean` (readonly)

#style ⇒ Layout::Style^? (rw)

#==(other) ⇒ `Boolean`

#attribute_dictionary(name) ⇒ Layout::Dictionary^?

#delete_attribute(dictionary_name) ⇒ `Boolean` #delete_attribute(dictionary_name, key) ⇒ `Boolean`

#document ⇒ Layout::Document^?

#group ⇒ Layout::Group^?

#layer_instance ⇒ Layout::LayerInstance^?

#page ⇒ Layout::Page^?

#transformation ⇒ Geom::Transformation2d^?