cellname

Usage:

cellname option

where option is one of the following:

[list] children [name]

List all of the children definitions of cell name, or the children of the currently selected cell instance.

[list] childinst [name]

List all of the children instances of cell name, or the children of the currently selected cell instance.

[list] parent [name]

List the parent cell definition of cell name, or the parent of the currently selected cell instance.

[list] exists|self [name]

Returns the name of the cell if the cell exists, or false (0) if the cell 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 cell.

[list] allcells

List all of the cells in the database. Note that expansion is not automatic, so cells that are not expanded are not searched.

[list] topcells

List the name of the top-level cell or cells. Note that the cells are searched in the whole database, so multiple cells may be returned, regardless of what cell is the topmost cell in the layout window. For that, use cellname window (see below).

[list] window

List the name of the topmost cell in the window. If only one window exists, it is implicit. If more than one window exists, the command operates on the window from which the command was called if the ":" macro was used to invoke the command. Otherwise, the window can be specified as the command (q.v. tk_path_name).

create name

Create a new cell definition with name name. This is most often used with scripts, where it is not necessary or desirable to load the cell into the window. Note that this command does not search the layout search path for a cell named name.mag, so it can be used to replace a cell which exists on disk but is not currently loaded.

rename name newname

Change the name of the cell definition name to newname.

delete name

Delete the cell definition with name name. If cell name is a descendent of another cell, the command will be prohibited. If the cell name is currently the topmost cell in the window, the window will be loaded with default cell "(UNNAMED)".

dereference name

Perform a flush of the cell (per the "flush" command), first removing any file path associated with the cell, so that the cell will be reloaded from the first valid location found using the search paths.

flags

Reports flag settings for the cell. Flags which are reported are "available", "modified", and "readonly". Flag "available" is true if the cell has been loaded into the database. Flag "modified" is true if layout changes have been made to the cell. Flag "readonly" is true if the cell has been locked to prevent edits.

timestamp name [value]

Reports or sets the cell timestamp value. Note that timestamps should be handled automatically, so setting the timestamp is discouraged outside of limited functions like creating cell libraries. The timestamp is in the usual integer format and can be printed as a human-readable date using the Tcl clock command, e.g., "clock format [cellname timestamp]".

filepath name [default|pathname]

With no option, this command returns the path to the file for the cell name, or the keyword "default" if the cell is not associated with a specific file path. With option "default", if the cell is associated with a specific file path, that association is removed. With option "pathname", the cell is associated with the given file path. Note that this is meant to be used to resolve issues with database libraries being moved from one location or another. More typically, the "save" command should be used to create a copy of the (possibly modified) cell in a new location. Changing the filepath will not perform any disk reads or writes.

writeable name [true|false]

Option writeable false makes the current cell read-only and therefore prevents any edits from being written to disk. If magic is compiled with file-locking, then any advisory lock on the file is released. Option writeable true makes the current cell read-write. If magic is compiled with file-locking, then magic attempts to grab an advisory lock on the file. If a lock is already held on the file, then the command cannot be executed, and the cell remains read-only. Option writeable with no other arguments returns the state of the cell (roughly equivalent to cellname flags readonly).

Summary:

The cellname command performs various operations on cell definitions. For the first four options listed above, cellname lists cells by their relationship to cell 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:

cellname 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 the same options, but references are to cell instances rather that cell definitions (q.v.).

The command option cellname 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 that is currently selected.

The cellname command replaces a number of commands that briefly appeared in version 7.1, such as parent, child, and top. These commands are now options of the cellname and instance commands.

See Also:

instance
load
path
flush
tk_path_name

Return to command index

Last updated: February 3, 2021 at 3:52pm