#

## instance

Operations on cell instances (uses).

### Usage:

> instance option

> > where option is one of the following:
> > [list] children [name]
> >   List all of the children instances of cell use name, or the children of the currently selected cell instance.
> > [list] parent [name]
> >   List the parent cell definition of cell use name, or the parent of the currently selected cell instance.
> > [list] exists|self [name]
> >   Returns the name of the instance if the cell exists, or false (0) if the instance does not exist (is not loaded into the database; the cell may still exist on disk). If name is not present, returns the name of the currently selected instance.
> > [list] allcells
> >   List all of the cell instances in the database. Note that expansion is not automatic, so cells that are not expanded are not searched.
> > orientation [name] [-def]
> >   Returns the orientation of the instance. By default, returns the orientation in the naming convention used by the "getcell" command. If the option "-def" is specified, then the orientation is given in the naming convention used by the DEF format for component placement. if name is given, then return the orientation of the named instance. Otherwise, the orientation of all selected instances is returned as an unordered list.
> > [list] abutment
> >   Returns the coordinates of the instance's abutment box (the bounding box formed by the coordinates saved in the FIXED_BBOX property in the cell), translated into the coordinate system of the parent cell (which must be the edit cell). This should be used, for example, when replacing an instance of a standard cell with another standard cell, to move the cursor box to the abutment box position so that the new cell has the same alignment as the old cell (see also orientation, above).
> > lock|unlock [name]
> >   Locking an instance prevents it from being moved, rotated, flipped, deleted, or copied. This is useful, for example, when part of a layout is declared "final" and changes to that area are prohibited. The cell instance's lock status can be saved to and read from the layout file, so the lock will remain in effect until the instance is unlocked. Cells that are locked have the character "*" prepended to the instance name in the display. With no name given to the command, the lock will be applied to all selected cell instances.

### Summary:

> The instance command performs various operations on cell uses, or instances. For the first four options listed above, instance lists cells by their relationship to cell use name, or to the current selection if no name is given. The optional argument list returns the result as a list. In particular, in the Tcl version of magic, this list is a Tcl result that may be operated on by Tcl procedures.

### Implementation Notes:

> instance is implemented as a built-in function in magic The Tcl version of magic returns Tcl results when the "list" option is present. instance is essentially an alias for the cellname command, and takes many of the same options, but references are to cell instances rather that cell definitions (q.v.). A number of options to cellname are meaningless for instances.

> Warning: Because instance names are arbitrary, looking up an instance name is computationally intensive compared to looking up a cell name. When used inside a loop, such as to search the cell name hierarchy, use command cellname on cell definitions instead of command instance on cell instance names whenever possible.

> The command option instance list exists is nonsensical from the standpoint of the end-user (if the cell is selected, of course it exists). However, it is a very useful function for Tcl scripts to determine the name of the cell instance that is currently selected.

### Bugs:

> Technically, instance rename should be implemented as a replacement for the command identify.

### See Also:

> cellname
> load
> getcell
> tk_path_name

Return to command index

Last updated: January 15, 2021 at 12:47pm