Class: Layout::Entity

Inherits:

Object

• Object
• Layout::Entity

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

Direct Known Subclasses

AngularDimension, Ellipse, FormattedText, Group, Image, Label, LinearDimension, Path, Rectangle, ReferenceEntity, SketchUpModel, Table

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(*args) ⇒ Object

  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.

• #locked=(is_locked) ⇒ Object

  The #locked= method sets the Entity as locked or unlocked.

• #locked? ⇒ Boolean

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

• #move_to_group(group) ⇒ Object

  The #move_to_group method moves the Entity into a Group.

• #move_to_layer(*args) ⇒ Object

  The #move_to_layer method moves the Entity to the given Layer.

• #on_shared_layer? ⇒ Boolean

  The #on_shared_layer? method returns whether or not the Entity is on a shared 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) ⇒ Object

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

• #style ⇒ Layout::Style^?

  The #style method returns the Style of the Entity.

• #style=(style) ⇒ Object

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

• #transform!(transformation) ⇒ Object

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

• #transformation ⇒ Geom::Transformation2d^?

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

• #untransformed_bounds ⇒ Geom::Bounds2d

  The #untransformed_bounds method returns the untransformed bounds of the Entity.

• #untransformed_bounds=(bounds) ⇒ Object

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

Instance Method Details

#==(other) ⇒ Boolean

The #== method checks to see if the two Layout::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 (Layout::Entity)

Returns:

• (Boolean)

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 Layout::Entity.

Examples:

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

Returns:

• (Geom::Bounds2d)

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.

  Returns:

  • (Boolean)
• #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.

  Returns:

  • (Boolean)

Version:

• LayOut 2026.0

#document ⇒ Layout::Document^?

The #document method returns the Document that the Layout::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

Returns:

• (Layout::Document, nil)

Version:

• LayOut 2018

#drawing_bounds ⇒ Geom::OrientedBounds2d

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

Examples:

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

Returns:

• (Geom::OrientedBounds2d)

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 Layout::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

Returns:

• (Layout::Group, nil)

Version:

• LayOut 2018

#layer_instance ⇒ Layout::LayerInstance^?

Note:

Groups are never associated with a LayerInstance.

The #layer_instance method returns the LayerInstance that the Layout::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

Returns:

• (Layout::LayerInstance, nil)

Version:

• LayOut 2018

#locked=(is_locked) ⇒ Object

The #locked= method sets the Layout::Entity as locked or unlocked. When locked, the Layout::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

The #locked? method returns whether the Layout::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?

Returns:

• (Boolean)

Version:

• LayOut 2018

#move_to_group(group) ⇒ Object

The #move_to_group method moves the Layout::Entity into a Group. If the Layout::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 Layout::Entity, the old Group will be collapsed and the remaining Layout::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 Layout::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 Layout::Entity is locked

Version:

• LayOut 2018

#move_to_layer(layer) ⇒ Object #move_to_layer(layer, pages) ⇒ Object

The #move_to_layer method moves the Layout::Entity to the given Layer. If the Layer is non-shared and the Layout::Entity is currently on a shared Layer, an array of Pages must be provided to move the Layout::Entity to. In all other cases, passing in an array of Pages is not necessary. The Layout::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) ⇒ Object

  Parameters:

  • layer (Layout::Layer)
• #move_to_layer(layer, pages) ⇒ Object

  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 Layout::Entity is on a locked Layer

• (LockedLayerError) —

  if layer is locked

• (LockedEntityError) —

  if the Layout::Entity is locked

Version:

• LayOut 2018

Known Bugs:

• In LayOut versions prior to LayOut 2024.0 this method would fail to move entities from non-shared layers.

#on_shared_layer? ⇒ Boolean

The #on_shared_layer? method returns whether or not the Layout::Entity is on a shared Layer. This function works for all Layout::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?

Returns:

• (Boolean)

Raises:

• (ArgumentError) —

  if the Layout::Entity is not in a Document

Version:

• LayOut 2018

#page ⇒ Layout::Page^?

The #page method returns the Page that the Layout::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

Returns:

• (Layout::Page, nil)

Version:

• LayOut 2018

#set_attribute(name, key, value) ⇒ Object

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, Layout::Dictionary, nil] value The value for the

  attribute.
  

Version:

• LayOut 2026.0

#style ⇒ Layout::Style^?

The #style method returns the Style of the Layout::Entity. If the Layout::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

Returns:

• (Layout::Style, nil)

Version:

• LayOut 2018

#style=(style) ⇒ Object

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

Parameters:

• style (Layout::Style)

Raises:

• (LockedLayerError) —

  if the Layout::Entity is on a locked Layer

• (LockedEntityError) —

  if the Layout::Entity is locked

Version:

• LayOut 2018

#transform!(transformation) ⇒ Object

The #transform! method transforms the Layout::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 Layout::Entity is on a locked Layer

• (LockedEntityError) —

  if the Layout::Entity is locked

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

Returns:

• (Geom::Transformation2d, nil)

Version:

• LayOut 2018

#untransformed_bounds ⇒ Geom::Bounds2d

The #untransformed_bounds method returns the untransformed bounds of the Layout::Entity. This is the bounds of the Layout::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

Returns:

• (Geom::Bounds2d)

Raises:

• (ArgumentError) —

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

Version:

• LayOut 2018

#untransformed_bounds=(bounds) ⇒ Object

The #untransformed_bounds= method sets the untransformed bounds of the Layout::Entity. This is the bounds of the Layout::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 Layout::Entity does not have an explicit Geom::Transformation2d

• (LockedLayerError) —

  if the Layout::Entity is on a locked Layer

• (LockedEntityError) —

  if the Layout::Entity is locked

• (ArgumentError) —

  if the bounds are of zero size

Version:

• LayOut 2018