Notation used in Ruby API documentation
Module: lay
Description: A class describing a selected shape or instance
A shape or instance is addressed by a path which describes all instances leading to the specified object. These instances are described through InstElement objects, which specify the instance and, in case of array instances, the specific array member. For shapes, additionally the layer and the shape itself is specified. The ObjectInstPath objects encapsulates both forms, which can be distinguished with the is_cell_inst? predicate.
An instantiation path leads from a top cell down to the container cell which either holds the shape or the instance. The top cell can be obtained through the top attribute, the container cell through the source attribute. Both are cell indexes which can be converted to Cell objects through the Layout#cell. In case of objects located in the top cell, top and source refer to the same cell. The first element of the instantiation path is the instance located within the top cell leading to the first child cell. The second element leads to the next child cell and so forth. path_nth can be used to obtain a specific element of the path.
The cv_index attribute specifies the cellview the selection applies to. Use LayoutView#cellview to obtain the CellView object from the index.
The shape or instance the selection refers to can be obtained with shape and inst respectively. Use is_cell_inst? to decide whether the selection refers to an instance or not.
The ObjectInstPath class plays a role when retrieving and modifying the selection of shapes and instances through LayoutView#object_selection, LayoutView#object_selection=, LayoutView#select_object and LayoutView#unselect_object. ObjectInstPath objects can be modified to reflect a new selection, but the new selection becomes active only after it is installed in the view. The following sample demonstrates that. It implements a function to convert all shapes to polygons:
mw = RBA::Application::instance::main_window
view = mw.current_view
begin
view.transaction("Convert selected shapes to polygons")
sel = view.object_selection
sel.each do |s|
if !s.is_cell_inst? && !s.shape.is_text?
ly = view.cellview(s.cv_index).layout
# convert to polygon
s.shape.polygon = s.shape.polygon
end
end
view.object_selection = sel
ensure
view.commit
end
Note, that without resetting the selection in the above example, the application might raise errors because after modifying the selected objects, the current selection will no longer be valid. Establishing a new valid selection in the way shown above will help avoiding this issue.
| new ObjectInstPath ptr | new | (const RecursiveShapeIterator si, int cv_index) | Creates a new path object from a RecursiveShapeIterator |
| [const] | bool | != | (const ObjectInstPath b) | Inequality of two ObjectInstPath objects |
| [const] | bool | < | (const ObjectInstPath b) | Provides an order criterion for two ObjectInstPath objects |
| [const] | bool | == | (const ObjectInstPath b) | Equality of two ObjectInstPath objects |
| [const] | ObjectInstPath ptr | _const_cast | Returns a non-const reference to self. | |
| void | _create | Ensures the C++ object is created | ||
| void | _destroy | Explicitly destroys the object | ||
| [const] | bool | _destroyed? | Returns a value indicating whether the object was already destroyed | |
| [const] | bool | _is_const_object? | Returns a value indicating whether the reference is a const reference | |
| void | _manage | Marks the object as managed by the script side. | ||
| void | _unmanage | Marks the object as no longer owned by the script side. | ||
| void | append_path | (const InstElement element) | Appends an element to the instantiation path | |
| void | assign | (const ObjectInstPath other) | Assigns another object to self | |
| [const] | unsigned int | cell_index | Gets the cell index of the cell that the selection applies to. | |
| void | clear_path | Clears the instantiation path | ||
| [const] | unsigned int | cv_index | Gets the cellview index that describes which cell view the shape or instance is located in | |
| void | cv_index= | (unsigned int index) | Sets the cellview index that describes which cell view the shape or instance is located in | |
| [const] | DCplxTrans | dtrans | Gets the transformation applicable for the shape in micron space. | |
| [const] | new ObjectInstPath ptr | dup | Creates a copy of self | |
| [const,iter] | InstElement | each_inst | Yields the instantiation path | |
| [const] | Instance | inst | Deliver the instance represented by this selection | |
| [const] | bool | is_cell_inst? | True, if this selection represents a cell instance | |
| [const] | bool | is_valid? | (LayoutView ptr view) | Gets a value indicating whether the instance path refers to a valid object in the context of the given view |
| [const] | variant | layer | Gets the layer index that describes which layer the selected shape is on | |
| void | layer= | (unsigned int layer_index) | Sets to the layer index that describes which layer the selected shape is on | |
| [const] | Layout ptr | layout | Gets the Layout object the selected object lives in. | |
| [const] | InstElement[] | path | Gets the instantiation path | |
| void | path= | (InstElement[] p) | Sets the instantiation path | |
| [const] | unsigned int | path_length | Returns the length of the path (number of elements delivered by each_inst) | |
| [const] | InstElement | path_nth | (unsigned int n) | Returns the nth element of the path (similar to each_inst but with direct access through the index) |
| [const] | unsigned long | seq | Gets the sequence number | |
| void | seq= | (unsigned long n) | Sets the sequence number | |
| [const] | variant | shape | Gets the selected shape | |
| void | shape= | (const Shape shape) | Sets the shape object that describes the selected shape geometrically | |
| [const] | unsigned int | source | Returns to the cell index of the cell that the selected element resides inside. | |
| [const] | DCplxTrans | source_dtrans | Gets the transformation applicable for an instance and shape in micron space. | |
| [const] | ICplxTrans | source_trans | Gets the transformation applicable for an instance and shape. | |
| [const] | unsigned int | top | Gets the cell index of the top cell the selection applies to | |
| void | top= | (unsigned int cell_index) | Sets the cell index of the top cell the selection applies to | |
| [const] | ICplxTrans | trans | Gets the transformation applicable for the shape. |
| void | create | Use of this method is deprecated. Use _create instead | ||
| void | destroy | Use of this method is deprecated. Use _destroy instead | ||
| [const] | bool | destroyed? | Use of this method is deprecated. Use _destroyed? instead | |
| [const] | bool | is_const_object? | Use of this method is deprecated. Use _is_const_object? instead |
!= | Signature: [const] bool != (const ObjectInstPath b) Description: Inequality of two ObjectInstPath objects See the comments on the == operator. This method has been introduced with version 0.24. | ||
< | Signature: [const] bool < (const ObjectInstPath b) Description: Provides an order criterion for two ObjectInstPath objects Note: this operator is just provided to establish any order, not a particular one. This method has been introduced with version 0.24. | ||
== | Signature: [const] bool == (const ObjectInstPath b) Description: Equality of two ObjectInstPath objects Note: this operator returns true if both instance paths refer to the same object, not just identical ones. This method has been introduced with version 0.24. | ||
_const_cast | Signature: [const] ObjectInstPath ptr _const_cast Description: Returns a non-const reference to self. Basically, this method allows turning a const object reference to a non-const one. This method is provided as last resort to remove the constness from an object. Usually there is a good reason for a const object reference, so using this method may have undesired side effects. This method has been introduced in version 0.29.6. | ||
_create | Signature: void _create Description: Ensures the C++ object is created Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created. | ||
_destroy | Signature: void _destroy Description: Explicitly destroys the object Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing. | ||
_destroyed? | Signature: [const] bool _destroyed? Description: Returns a value indicating whether the object was already destroyed This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself. | ||
_is_const_object? | Signature: [const] bool _is_const_object? Description: Returns a value indicating whether the reference is a const reference This method returns true, if self is a const reference. In that case, only const methods may be called on self. | ||
_manage | Signature: void _manage Description: Marks the object as managed by the script side. After calling this method on an object, the script side will be responsible for the management of the object. This method may be called if an object is returned from a C++ function and the object is known not to be owned by any C++ instance. If necessary, the script side may delete the object if the script's reference is no longer required. Usually it's not required to call this method. It has been introduced in version 0.24. | ||
_unmanage | Signature: void _unmanage Description: Marks the object as no longer owned by the script side. Calling this method will make this object no longer owned by the script's memory management. Instead, the object must be managed in some other way. Usually this method may be called if it is known that some C++ object holds and manages this object. Technically speaking, this method will turn the script's reference into a weak reference. After the script engine decides to delete the reference, the object itself will still exist. If the object is not managed otherwise, memory leaks will occur. Usually it's not required to call this method. It has been introduced in version 0.24. | ||
append_path | Signature: void append_path (const InstElement element) Description: Appends an element to the instantiation path This method allows building of an instantiation path pointing to the selected object. For an instance selection, the last component added is the instance which is selected. For a shape selection, the path points to the cell containing the selected shape. This method was introduced in version 0.24. | ||
assign | Signature: void assign (const ObjectInstPath other) Description: Assigns another object to self | ||
cell_index | Signature: [const] unsigned int cell_index Description: Gets the cell index of the cell that the selection applies to. This method returns the cell index that describes which cell the selected shape is located in or the cell whose instance is selected if is_cell_inst? is true. This property is set implicitly by setting the top cell and adding elements to the instantiation path. To obtain the index of the container cell, use source. | ||
clear_path | Signature: void clear_path Description: Clears the instantiation path This method was introduced in version 0.24. | ||
create | Signature: void create Description: Ensures the C++ object is created Use of this method is deprecated. Use _create instead Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created. | ||
cv_index | Signature: [const] unsigned int cv_index Description: Gets the cellview index that describes which cell view the shape or instance is located in Python specific notes: | ||
cv_index= | Signature: void cv_index= (unsigned int index) Description: Sets the cellview index that describes which cell view the shape or instance is located in This method has been introduced in version 0.24. Python specific notes: | ||
destroy | Signature: void destroy Description: Explicitly destroys the object Use of this method is deprecated. Use _destroy instead Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing. | ||
destroyed? | Signature: [const] bool destroyed? Description: Returns a value indicating whether the object was already destroyed Use of this method is deprecated. Use _destroyed? instead This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself. | ||
dtrans | Signature: [const] DCplxTrans dtrans Description: Gets the transformation applicable for the shape in micron space. This method returns the same transformation than trans, but applicable to objects in micrometer units: # renders the micrometer-unit polygon in top cell coordinates: dpolygon_in_top = sel.dtrans * sel.shape.dpolygon This method is not applicable to instance selections. A more generic attribute is source_dtrans. The method has been introduced in version 0.25. | ||
dup | Signature: [const] new ObjectInstPath ptr dup Description: Creates a copy of self Python specific notes: | ||
each_inst | Signature: [const,iter] InstElement each_inst Description: Yields the instantiation path The instantiation path describes by an sequence of InstElement objects the path by which the cell containing the selected shape is found from the cell view's current cell. If this object represents an instance, the path will contain the selected instance as the last element. The elements are delivered top down. | ||
inst | Signature: [const] Instance inst Description: Deliver the instance represented by this selection This method delivers valid results only if is_cell_inst? is true. It returns the instance reference (an Instance object) that this selection represents. This property is set implicitly by adding instance elements to the instantiation path. This method has been added in version 0.16. | ||
is_cell_inst? | Signature: [const] bool is_cell_inst? Description: True, if this selection represents a cell instance If this attribute is true, the shape reference and layer are not valid. | ||
is_const_object? | Signature: [const] bool is_const_object? Description: Returns a value indicating whether the reference is a const reference Use of this method is deprecated. Use _is_const_object? instead This method returns true, if self is a const reference. In that case, only const methods may be called on self. | ||
is_valid? | Signature: [const] bool is_valid? (LayoutView ptr view) Description: Gets a value indicating whether the instance path refers to a valid object in the context of the given view This predicate has been introduced in version 0.27.12. | ||
layer | Signature: [const] variant layer Description: Gets the layer index that describes which layer the selected shape is on Starting with version 0.27, this method returns nil for this property if is_cell_inst? is false - i.e. the selection does not represent a shape. Python specific notes: | ||
layer= | Signature: void layer= (unsigned int layer_index) Description: Sets to the layer index that describes which layer the selected shape is on Setting the layer property to a valid layer index makes the path a shape selection path. Setting the layer property to a negative layer index makes the selection an instance selection. This method has been introduced in version 0.24. Python specific notes: | ||
layout | Signature: [const] Layout ptr layout Description: Gets the Layout object the selected object lives in. This method returns the Layout object that the selected object lives in. This method may return nil, if the selection does not point to a valid object. This method has been introduced in version 0.25. | ||
new | Signature: [static] new ObjectInstPath ptr new (const RecursiveShapeIterator si, int cv_index) Description: Creates a new path object from a RecursiveShapeIterator Use this constructor to quickly turn a recursive shape iterator delivery into a shape selection. Python specific notes: | ||
path | Signature: [const] InstElement[] path Description: Gets the instantiation path The path is a sequence of InstElement objects leading to the target object. This method was introduced in version 0.26. Python specific notes: | ||
path= | Signature: void path= (InstElement[] p) Description: Sets the instantiation path This method was introduced in version 0.26. Python specific notes: | ||
path_length | Signature: [const] unsigned int path_length Description: Returns the length of the path (number of elements delivered by each_inst) This method has been added in version 0.16. | ||
path_nth | Signature: [const] InstElement path_nth (unsigned int n) Description: Returns the nth element of the path (similar to each_inst but with direct access through the index)
This method has been added in version 0.16. | ||
seq | Signature: [const] unsigned long seq Description: Gets the sequence number The sequence number describes when the item was selected. A sequence number of 0 indicates that the item was selected in the first selection action (without 'Shift' pressed). Python specific notes: | ||
seq= | Signature: void seq= (unsigned long n) Description: Sets the sequence number See seq for a description of this property. This method was introduced in version 0.24. Python specific notes: | ||
shape | Signature: [const] variant shape Description: Gets the selected shape The shape object may be modified. This does not have an immediate effect on the selection. Instead, the selection must be set in the view using LayoutView#object_selection= or LayoutView#select_object. This method delivers valid results only for object selections that represent shapes. Starting with version 0.27, this method returns nil for this property if is_cell_inst? is false. Python specific notes: | ||
shape= | Signature: void shape= (const Shape shape) Description: Sets the shape object that describes the selected shape geometrically When using this setter, the layer index must be set to a valid layout layer (see layer=). Setting both properties makes the selection a shape selection. This method has been introduced in version 0.24. Python specific notes: | ||
source | Signature: [const] unsigned int source Description: Returns to the cell index of the cell that the selected element resides inside. If this reference represents a cell instance, this method delivers the index of the cell in which the cell instance resides. Otherwise, this method returns the same value than cell_index. This property is set implicitly by setting the top cell and adding elements to the instantiation path. This method has been added in version 0.16. | ||
source_dtrans | Signature: [const] DCplxTrans source_dtrans Description: Gets the transformation applicable for an instance and shape in micron space. This method returns the same transformation than source_trans, but applicable to objects in micrometer units: # renders the cell instance as seen from top level: dcell_inst_in_top = sel.source_dtrans * sel.inst.dcell_inst The method has been introduced in version 0.25. | ||
source_trans | Signature: [const] ICplxTrans source_trans Description: Gets the transformation applicable for an instance and shape. If this object represents a shape, this transformation describes how the selected shape is transformed into the current cell of the cell view. If this object represents an instance, this transformation describes how the selected instance is transformed into the current cell of the cell view. This method is similar to trans, except that the resulting transformation does not include the instance transformation if the object represents an instance. This property is set implicitly by setting the top cell and adding elements to the instantiation path. This method has been added in version 0.16. | ||
top | Signature: [const] unsigned int top Description: Gets the cell index of the top cell the selection applies to The top cell is identical to the current cell provided by the cell view. It is the cell from which is instantiation path originates and the container cell if no instantiation path is set. This method has been introduced in version 0.24. Python specific notes: | ||
top= | Signature: void top= (unsigned int cell_index) Description: Sets the cell index of the top cell the selection applies to See top_cell for a description of this property. This method has been introduced in version 0.24. Python specific notes: | ||
trans | Signature: [const] ICplxTrans trans Description: Gets the transformation applicable for the shape. If this object represents a shape, this transformation describes how the selected shape is transformed into the current cell of the cell view. Basically, this transformation is the accumulated transformation over the instantiation path. If the ObjectInstPath represents a cell instance, this includes the transformation of the selected instance as well. This property is set implicitly by setting the top cell and adding elements to the instantiation path. This method is not applicable for instance selections. A more generic attribute is source_trans. |