API reference - Class ObjectInstPathNotation used in Ruby API documentation 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. Public constructors
Public methods
Deprecated methods (protected, public, static, non-static and constructors)
Detailed description[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. [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. [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. void _createDescription: 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. void _destroyDescription: 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. [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. [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. void _manageDescription: 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. void _unmanageDescription: 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. 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. void assign(const ObjectInstPath other)Description: Assigns another object to self [const] unsigned int cell_indexDescription: 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. void clear_pathDescription: Clears the instantiation path This method was introduced in version 0.24. void createDescription: Ensures the C++ object is created Use of this method is deprecated. Use _create instead [const] unsigned int cv_indexDescription: Gets the cellview index that describes which cell view the shape or instance is located in Python specific notes:The object exposes a readable attribute 'cv_index'. This is the getter. 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:The object exposes a writable attribute 'cv_index'. This is the setter. void destroyDescription: Explicitly destroys the object Use of this method is deprecated. Use _destroy instead [const] bool destroyed?Description: Returns a value indicating whether the object was already destroyed Use of this method is deprecated. Use _destroyed? instead [const] new ObjectInstPath ptr dupDescription: Creates a copy of self [const,iter] InstElement each_instDescription: 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. [const] Instance instDescription: 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. [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. [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 [const] unsigned int layerDescription: Gets the layer index that describes which layer the selected shape is on This method delivers valid results only for object selections that represent shapes, i.e for which is_cell_inst? is false. Python specific notes:The object exposes a readable attribute 'layer'. This is the getter. 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:The object exposes a writable attribute 'layer'. This is the setter. [static] new ObjectInstPath ptr newDescription: Creates a new object of this class Python specific notes:This method is the default initializer of the object [const] unsigned int path_lengthDescription: Returns the length of the path (number of elements delivered by each_inst) This method has been added in version 0.16. [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. [const] unsigned long seqDescription: 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:The object exposes a readable attribute 'seq'. This is the getter. 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:The object exposes a writable attribute 'seq'. This is the setter. Shape shapeDescription: Gets the shape object that describes the selected shape geometrically This method delivers valid results only for object selections that represent shapes, i.e for which is_cell_inst? is false. 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. Python specific notes:The object exposes a readable attribute 'shape'. This is the getter. 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:The object exposes a writable attribute 'shape'. This is the setter. [const] unsigned int sourceDescription: 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. [const] CplxTrans source_transDescription: 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. [const] unsigned int topDescription: 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 not instantiation path is set. This method has been introduced in version 0.24. Python specific notes:The object exposes a readable attribute 'top'. This is the getter. 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:The object exposes a writable attribute 'top'. This is the setter. [const] CplxTrans transDescription: 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. |