KLayout 0.29.8 (2024-11-26 926dac96c) [master]

API reference - Class CellView

Notation used in Ruby API documentation

Module: lay

Description: A class describing what is shown inside a layout view

The cell view points to a specific cell within a certain layout and a hierarchical context. For that, first of all a layout pointer is provided. The cell itself is addressed by an cell_index or a cell object reference. The layout pointer can be nil, indicating that the cell view is invalid.

The cell is not only identified by its index or object but also by the path leading to that cell. This path indicates how to find the cell in the hierarchical context of its parent cells.

The path is in fact composed of two parts: first in an unspecific fashion, just describing which parent cells are used. The target of this path is called the "context cell". It is accessible by the ctx_cell_index or ctx_cell methods. In the viewer, the unspecific part of the path is the location of the cell in the cell tree.

Additionally the path's second part may further identify a specific instance of a certain subcell in the context cell. This is done through a set of InstElement objects. The target of this specific path is the actual cell addressed by the cellview. This target cell is accessible by the cell_index or cell methods. In the viewer, the target cell is shown in the context of the context cell. The hierarchy levels are counted from the context cell, which is on level 0. If the context path is empty, the context cell is identical with the target cell.

Starting with version 0.25, the cellview can be modified directly. This will have an immediate effect on the display. For example, the following code will select a different cell:

cv = RBA::CellView::active
cv.cell_name = "TOP2"

See The Application API for more details about the cellview objects.

Public constructors

new CellView ptrnewCreates a new object of this class

Public methods

[const]bool==(const CellView other)Equality: indicates whether the cellviews refer to the same one
[const]CellView ptr_const_castReturns a non-const reference to self.
void_createEnsures the C++ object is created
void_destroyExplicitly 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_manageMarks the object as managed by the script side.
void_unmanageMarks the object as no longer owned by the script side.
voidascendAscends upwards in the hierarchy.
voidassign(const CellView other)Assigns another object to self
[const]Cell ptrcellGets the reference to the target cell currently addressed
voidcell=(Cell ptr cell)Sets the cell by reference to a Cell object
[const]unsigned intcell_indexGets the target cell's index
voidcell_index=(unsigned int cell_index)Sets the path to the given cell
[const]stringcell_nameGets the name of the target cell currently addressed
voidcell_name=(string cell_name)Sets the cell by name
voidcloseCloses this cell view
[const]DCplxTranscontext_dtransGets the accumulated transformation of the context path in micron unit space
[const]InstElement[]context_pathGets the cell's context path
voidcontext_path=(InstElement[] path)Sets the context path explicitly
[const]ICplxTranscontext_transGets the accumulated transformation of the context path
[const]Cell ptrctx_cellGets the reference to the context cell currently addressed
[const]unsigned intctx_cell_indexGets the context cell's index
voiddescend(InstElement[] path)Descends further into the hierarchy.
[const]new CellView ptrdupCreates a copy of self
[const]stringfilenameGets filename associated with the layout behind the cellview
voidhide_cell(const Cell ptr cell)Hides the given cell
[const]intindexGets the index of this cellview in the layout view
boolis_cell_hidden?(const Cell ptr cell)Returns true, if the given cell is hidden
[const]boolis_dirty?Gets a flag indicating whether the layout needs saving
[const]boolis_valid?Returns true, if the cellview is valid
[const]Layout ptrlayoutGets the reference to the layout object addressed by this view
[const]stringnameGets the unique name associated with the layout behind the cellview
voidname=(string name)sets the unique name associated with the layout behind the cellview
[signal]voidon_technology_changedAn event indicating that the technology has changed
[const]unsigned int[]pathGets the cell's unspecific part of the path leading to the context cell
voidpath=(unsigned int[] path)Sets the unspecific part of the path explicitly
voidreset_cellResets the cell
voidset_cell(unsigned int cell_index)Sets the path to the given cell
voidset_cell_name(string cell_name)Sets the cell by name
voidset_context_path(InstElement[] path)Sets the context path explicitly
voidset_path(unsigned int[] path)Sets the unspecific part of the path explicitly
voidshow_all_cellsMakes all cells shown (cancel effects of hide_cell) for the specified cell view
voidshow_cell(const Cell ptr cell)Shows the given cell (cancels the effect of hide_cell)
[const]stringtechnologyReturns the technology name for the layout behind the given cell view
[const]voidtechnology=(string tech_name)Sets the technology for the layout behind the given cell view
LayoutView ptrviewGets the view the cellview resides in

Public static methods and constants

CellViewactiveGets the active CellView

Deprecated methods (protected, public, static, non-static and constructors)

voidcreateUse of this method is deprecated. Use _create instead
voiddestroyUse of this method is deprecated. Use _destroy instead
[const]booldestroyed?Use of this method is deprecated. Use _destroyed? instead
[const]boolis_const_object?Use of this method is deprecated. Use _is_const_object? instead

Detailed description

==

Signature: [const] bool == (const CellView other)

Description: Equality: indicates whether the cellviews refer to the same one

In version 0.25, the definition of the equality operator has been changed to reflect identity of the cellview. Before that version, identity of the cell shown was implied.

_const_cast

Signature: [const] CellView 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.

active

Signature: [static] CellView active

Description: Gets the active CellView

The active CellView is the one that is selected in the current layout view. This method is equivalent to

RBA::LayoutView::current.active_cellview
If no CellView is active, this method returns nil.

This method has been introduced in version 0.23.

ascend

Signature: void ascend

Description: Ascends upwards in the hierarchy.

Removes one element from the specific path of the cellview with the given index. Returns the element removed. This method has been added in version 0.25.

assign

Signature: void assign (const CellView other)

Description: Assigns another object to self

cell

Signature: [const] Cell ptr cell

Description: Gets the reference to the target cell currently addressed

Python specific notes:
The object exposes a readable attribute 'cell'. This is the getter.

cell=

Signature: void cell= (Cell ptr cell)

Description: Sets the cell by reference to a Cell object

Setting the cell reference to nil invalidates the cellview. This method will construct any path to this cell, not a particular one. It will clear the context path and update the context and target cell.

Python specific notes:
The object exposes a writable attribute 'cell'. This is the setter.

cell_index

Signature: [const] unsigned int cell_index

Description: Gets the target cell's index

Python specific notes:
The object exposes a readable attribute 'cell_index'. This is the getter.

cell_index=

Signature: void cell_index= (unsigned int cell_index)

Description: Sets the path to the given cell

This method will construct any path to this cell, not a particular one. It will clear the context path and update the context and target cell. Note that the cell is specified by its index.

Python specific notes:
The object exposes a writable attribute 'cell_index'. This is the setter.

cell_name

Signature: [const] string cell_name

Description: Gets the name of the target cell currently addressed

Python specific notes:
The object exposes a readable attribute 'cell_name'. This is the getter.

cell_name=

Signature: void cell_name= (string cell_name)

Description: Sets the cell by name

If the name is not a valid one, the cellview will become invalid. This method will construct any path to this cell, not a particular one. It will clear the context path and update the context and target cell.

Python specific notes:
The object exposes a writable attribute 'cell_name'. This is the setter.

close

Signature: void close

Description: Closes this cell view

This method will close the cellview - remove it from the layout view. After this method was called, the cellview will become invalid (see is_valid?).

This method was introduced in version 0.25.

context_dtrans

Signature: [const] DCplxTrans context_dtrans

Description: Gets the accumulated transformation of the context path in micron unit space

This is the transformation applied to the target cell before it is shown in the context cell Technically this is the product of all transformations over the context path. See context_trans for a version delivering an integer-unit space transformation.

This method has been introduced in version 0.27.3.

context_path

Signature: [const] InstElement[] context_path

Description: Gets the cell's context path

The context path leads from the context cell to the target cell in a specific fashion, i.e. describing each instance in detail, not just by cell indexes. If the context and target cell are identical, the context path is empty.

Python specific notes:
The object exposes a readable attribute 'context_path'. This is the getter.

context_path=

Signature: void context_path= (InstElement[] path)

Description: Sets the context path explicitly

This method assumes that the unspecific part of the path is established already and that the context path starts from the context cell.

Python specific notes:
The object exposes a writable attribute 'context_path'. This is the setter.

context_trans

Signature: [const] ICplxTrans context_trans

Description: Gets the accumulated transformation of the context path

This is the transformation applied to the target cell before it is shown in the context cell Technically this is the product of all transformations over the context path. See context_dtrans for a version delivering a micron-unit space transformation.

This method has been introduced in version 0.27.3.

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.

ctx_cell

Signature: [const] Cell ptr ctx_cell

Description: Gets the reference to the context cell currently addressed

ctx_cell_index

Signature: [const] unsigned int ctx_cell_index

Description: Gets the context cell's index

descend

Signature: void descend (InstElement[] path)

Description: Descends further into the hierarchy.

Adds the given path (given as an array of InstElement objects) to the specific path of the cellview with the given index. In effect, the cell addressed by the terminal of the new path components can be shown in the context of the upper cells, if the minimum hierarchy level is set to a negative value. The path is assumed to originate from the current cell and contain specific instances sorted from top to bottom. This method has been added in version 0.25.

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.

dup

Signature: [const] new CellView ptr dup

Description: Creates a copy of self

Python specific notes:
This method also implements '__copy__' and '__deepcopy__'.

filename

Signature: [const] string filename

Description: Gets filename associated with the layout behind the cellview

hide_cell

Signature: void hide_cell (const Cell ptr cell)

Description: Hides the given cell

This method has been added in version 0.25.

index

Signature: [const] int index

Description: Gets the index of this cellview in the layout view

The index will be negative if the cellview is not a valid one. This method has been added in version 0.25.

is_cell_hidden?

Signature: bool is_cell_hidden? (const Cell ptr cell)

Description: Returns true, if the given cell is hidden

This method has been added in version 0.25.

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_dirty?

Signature: [const] bool is_dirty?

Description: Gets a flag indicating whether the layout needs saving

A layout is 'dirty' if it is modified and needs saving. This method returns true in this case.

This method has been introduced in version 0.24.10.

is_valid?

Signature: [const] bool is_valid?

Description: Returns true, if the cellview is valid

A cellview may become invalid if the corresponding tab is closed for example.

layout

Signature: [const] Layout ptr layout

Description: Gets the reference to the layout object addressed by this view

name

Signature: [const] string name

Description: Gets the unique name associated with the layout behind the cellview

Python specific notes:
The object exposes a readable attribute 'name'. This is the getter.

name=

Signature: void name= (string name)

Description: sets the unique name associated with the layout behind the cellview

this method has been introduced in version 0.25.

Python specific notes:
The object exposes a writable attribute 'name'. This is the setter.

new

Signature: [static] new CellView ptr new

Description: Creates a new object of this class

Python specific notes:
This method is the default initializer of the object.

on_technology_changed

Signature: [signal] void on_technology_changed

Description: An event indicating that the technology has changed

This event is triggered when the CellView is attached to a different technology.

This event has been introduced in version 0.27.

Python specific notes:
The object exposes a readable attribute 'on_technology_changed'. This is the getter.
The object exposes a writable attribute 'on_technology_changed'. This is the setter.

path

Signature: [const] unsigned int[] path

Description: Gets the cell's unspecific part of the path leading to the context cell

Python specific notes:
The object exposes a readable attribute 'path'. This is the getter.

path=

Signature: void path= (unsigned int[] path)

Description: Sets the unspecific part of the path explicitly

Setting the unspecific part of the path will clear the context path component and update the context and target cell.

Python specific notes:
The object exposes a writable attribute 'path'. This is the setter.

reset_cell

Signature: void reset_cell

Description: Resets the cell

The cellview will become invalid. The layout object will still be attached to the cellview, but no cell will be selected.

set_cell

Signature: void set_cell (unsigned int cell_index)

Description: Sets the path to the given cell

This method will construct any path to this cell, not a particular one. It will clear the context path and update the context and target cell. Note that the cell is specified by its index.

Python specific notes:
The object exposes a writable attribute 'cell_index'. This is the setter.

set_cell_name

Signature: void set_cell_name (string cell_name)

Description: Sets the cell by name

If the name is not a valid one, the cellview will become invalid. This method will construct any path to this cell, not a particular one. It will clear the context path and update the context and target cell.

Python specific notes:
The object exposes a writable attribute 'cell_name'. This is the setter.

set_context_path

Signature: void set_context_path (InstElement[] path)

Description: Sets the context path explicitly

This method assumes that the unspecific part of the path is established already and that the context path starts from the context cell.

Python specific notes:
The object exposes a writable attribute 'context_path'. This is the setter.

set_path

Signature: void set_path (unsigned int[] path)

Description: Sets the unspecific part of the path explicitly

Setting the unspecific part of the path will clear the context path component and update the context and target cell.

Python specific notes:
The object exposes a writable attribute 'path'. This is the setter.

show_all_cells

Signature: void show_all_cells

Description: Makes all cells shown (cancel effects of hide_cell) for the specified cell view

This method has been added in version 0.25.

show_cell

Signature: void show_cell (const Cell ptr cell)

Description: Shows the given cell (cancels the effect of hide_cell)

This method has been added in version 0.25.

technology

Signature: [const] string technology

Description: Returns the technology name for the layout behind the given cell view

This method has been added in version 0.23.

Python specific notes:
The object exposes a readable attribute 'technology'. This is the getter.

technology=

Signature: [const] void technology= (string tech_name)

Description: Sets the technology for the layout behind the given cell view

According to the specification of the technology, new layer properties may be loaded or the net tracer may be reconfigured. If the layout is shown in multiple views, the technology is updated for all views. This method has been added in version 0.22.

Python specific notes:
The object exposes a writable attribute 'technology'. This is the setter.

view

Signature: LayoutView ptr view

Description: Gets the view the cellview resides in

This reference will be nil if the cellview is not a valid one. This method has been added in version 0.25.