next up previous contents index
Next: Property Management by Handles Up: Geometry Editing Functions 2 Previous: Clipping Functions   Contents   Index

Other Object Management Functions

(int) ChangeLayer()
This function will change the layer of all selected geometry to the current layer. This is similar to the functionality of the Chg Layer button in the Modify Menu.

(int) Bloat(dimen, mode)
Each selected object is bloated by the given dimension, similar to the !bloat command. In layer-specific mode, only selected objects on the current layer are affected, otherwise all selected objects are affected. The returned value is 0 on success, or 1 if there was a runtime error. This function will return 1 if not called in physical mode.

The second argument is an integer that specifies the algorithm to use for bloating. Giving zero specifies the default algorithm. See the description of the !bloat command (16.12.13) for documentation of the algorithms available.

(int) Manhattanize(dimen, mode)
Each selected non-Manhattan polygon or wire is converted to a Manhattan polygon or box approximation, similar to the !manh command. In layer-specific mode, only selected objects on the current layer are affected, otherwise all selected non-Manhattan objects are affected. The first argument is a size in microns representing the smallest dimension of the boxes created to approximate the non-Manhattan parts. The second argument is a boolean value that specifies which of two algorithms to use. These algorithms are described with the !manh command.

The returned value is 0 on success, or 1 if there was a runtime error. This function will return 1 if not called in physical mode. The function will fail if the dimen argument is smaller than 0.01.

(int) Join()
The selected objects that touch or overlap are merged together into polygons, similar to the !join command. The returned value is 0 on success, 1 if there is a runtime error. This function will return 1 if not called in physical mode.

(int) Decompose(vert)
The selected polygons and wires are decomposed into elemental non-overlapping trapezoids (polygons) similar to the !split command. If the integer argument is nonzero, the decomposition favors a vertical orientation, otherwise the splitting favors horizontal. The returned value is 0 if called in physical mode, 1 if not called in physical mode (an error).

(int) Box(left, bottom, right, top)
The four arguments are real values specifying the coordinates of a rectangle in microns. Calling this function will generate a box on the current layer with the given coordinates. This provides functionality similar to the box menu button.

If the UseTransform function has been called to enable use of the current transform, the current transform will be applied to given coordinates before the box is created. The translation supplied to UseTransform is added to the coordinates before the current transform is applied.

The Box function will actually create a polygon if the current transform is being used and the rotation angle is 45 degrees or one of the other non-Manhattan angles.

(int) Polygon(num, arraypts)
This function creates a polygon on the current layer. The second argument is an array of values, taken as x-y pairs. The first pair of values must be the same as the last, i.e., the path must be closed. The first argument is the number of pairs of coordinates in the array. This provides functionality similar to the polyg menu button.

If the UseTransform function has been called to enable use of the current transform, the current transform will be applied to the given coordinates before the polygon is created. The translation supplied to UseTransform is added to the coordinates before the current transform is applied.

The Polygon function will actually create a box if the rotated figure can be so represented. The Polygon function will never create boxes unless use of the current transform is enabled.

(int) Arc(x, y, rad1X, rad1Y, rad2X, rad2Y, ang_start, ang_end)
This produces a circular or elliptical figure, providing functionality similar to the round, donut, and arc buttons in the side menu.

x, y center coordinates
rad1X, rad1Y x and y inner or outer radii
rad2X, rad2Y x and y outer or inner radii
ang_start starting angle in degrees
ang_end ending angle in degrees

If ang_start and ang_end are equal, a donut (ring figure) is produced. If the outer and inner radii are equal, a solid figure (flash) is produced. Angles are defined from the positive x-axis, in a counter-clockwise sense. The arc is generated in a clockwise direction.

If the UseTransform function has been called to enable use of the current transform, the current transform will be applied to the arc coordinates before the arc is created. The translation supplied to UseTransform is added to the coordinates before the current transform is applied.

(int) Sides(numsides)
This sets the number of segments to use in generating round objects. The function returns the present value for this parameter. The value is reset if the argument is in the range 8 through 150. This is similar to the sides menu button in the side menu.

(int) Wire(width, num, arraypts, end_style)
This function creates a wire on the current layer. The first argument is the width of the wire in microns. The third argument is the name of an array of coordinates, taken as x-y pairs. The second argument is the number of coordinate pairs in the array. The fourth argument is 0, 1, or 2 to set the end style to flush, rounded, or extended, respectively. This provides the functionality of the wire menu button.

If the UseTransform function has been called to enable use of the current transform, the current transform will be applied to the given coordinates before the wire is created. The translation supplied to UseTransform is added to the coordinates before the current transform is applied. The variable NoWireWidthMag will suppress changes to the wire width due to the magnification component of the current transform when set.

(int) Label(text, x, y [, width, height, xform)]
This function creates a label on the current layer. The function takes a variable number of arguments, but the first three must be present. The first argument is of string type and contains the label text. The next two arguments specify the x and y coordinates of the reference point, which is dependent on the current justification, as set with the Justify function or the optional xform argument. The default is the lower-left corner of the bounding box.

The remaining arguments are optional. The width and height specify the size of the bounding box into which the text will be rendered, in microns. if both are zero or negative or not given, a default size will be used. If only one is given a value greater than zero, the other will be computed using a default aspect ratio. If both are greater than zero, the text will be squeezed or stretched to conform.

The xform argument is an integer whose bits set transformation and justification attributes, and if given the Justify function and UseTransform function settings will be ignored, and these attributes will be set from xform. If xform is not given, the functions will set the justification and transformation. The bits in xform have the following significance:

Bits Effect
0-1 00-no rotation, 01-90, 10-180, 11-270
2 mirror y after rotation
3 mirror x after rotation and mirror y
4 shift rotation to 45, 135, 225, 315
5-6 horiz justification 00,11 left, 01 center, 10 right
7-8 vert justification 00,11 bottom, 01 center, 10 top

This function always returns 1.

(int) Logo(string, x, y [, width, height])
This creates and places physical text, i.e., text that is constructed with database polygons that will appear in the mask layout. The function takes a variable number of arguments, but the first three must be present. The first argument is of string type and contains the label text. The next two arguments specify the x and y coordinates of the reference point, which is dependent on the current justification, as set with the Justify function. The default is the lower-left corner of the bounding box. The text will be transformed according to the current transform.

The remaining arguments are optional. The width and height specify the approximate size of the rendered text. Unlike the Label function, the text aspect ratio is fixed. The first of height or width which is positive will be used to set the ``pixel'' size used to render the text, by dividing this value by the character cell height or width of the default font. Thus, the rendered text size will only be accurate for this font, and will scale with the number of pixels used in the ``pretty'' fonts. One must experiment with a chosen font to obtain accurate sizing. If neither parameter is given and positive, a default size will be used.

This provides the functionality of the logo menu button, and is sensitive to the following variables.

LogoEndStyle
LogoPathWidth
LogoAltFont
LogoPrettyFont
LogoToFile

This function always returns 1.

(int) Justify(hj, vj)
This sets the justification for text created with the logo and label commands and corresponding script functions. The arguments can have the following values:

hj/vj horizontal vertical
0 left bottom
1 center center
2 right top

Values out of range will preserve the present justification setting. The function always returns 1.

(int) Place(cellname, x, y [, refpt, array, smash])
This function places an instance of the named cell at x, y. The first argument is of string type and contains the name of the cell to place. It must be available as a native cell from a library or the search path, or already exist in memory. The second two arguments define the location.

Note: The PlaceParams function available in releases 3.0.11 and earlier no longer exists. These parameters are now supplied to the Place function directly, through the added optional arguments.

The remaining arguments are optional, meaning that they need not be given, but all arguments to the left must be given.

The refpt argument is an integer code that specifies the reference point which will correspond to x, y after placement. The values can be

0 the cell origin (the default)
1 the lower left corner
2 the upper left corner
3 the upper right corner
4 the lower right corner
The corners are those of the untransformed array or cell.

In electrical mode, if the cell has terminals, this code is ignored, and the location of the first terminal is the reference point. If the cell has no terminals, the corner reference points are snapped to the nearest grid location. This is to avoid producing off-grid terminal locations.

The array argument, if given, can be 0 or the name of an array containing four numbers. These are the arraying parameters, and apply in physical mode only. The default is to create a single instance, otherwise the array parameters are:

array[0] NX, integer number in the X direction.
array[1] NY, integer number in the Y direction.
array[2] DX, the real value spacing between cells in the X direction, in microns.
array[3] DY, the real value spacing between cells in the Y direction, in microns.
The NX and NY values should be 1 or larger, there is no restriction on DX,DY.

If the boolean value smash is given and nonzero (TRUE), the cell will be flattened into the parent, rather than placed as an instance. The flatten-level is 1, so subcells of the cell (if any) become subcells of the parent.

The cell will be transformed before placement according to the current transform.

On success, the function returns 1, 0 otherwise.

(int) PlaceTemplateArgs(cell, args)
This sets the default template parameters used when instantiating the template cell named in cell. The second argument is a string giving the comma-separated name=value pairs that will be applied, when the cell is instantiated with the Place function or otherwise. Note that in graphical mode, the given string will be the default string when the user is prompted to enter the parameters. This function should be used when placing template cells in batch or server mode, and applies only to subsequent Place calls. Additional calls to Place will use these parameters for cell, until changed with another call to this function. In graphical mode, if the user modifies the string, the modified string will be used in subsequent placements.

This function actually manages an internal table of cellname/argument list associations. If 0 is given for both arguments, the table will be cleared. If the second argument is 0, the entry for the first argument, if any, will be removed from the table. The table is cleared when the script terminates.

The return value is always 1.

(int) Replace(cellname, add_xform)
This will replace all selected subcells with cellname. The same transformation applied to the previous instance is applied to the replacing instance. In addition, if add_xform is nonzero, the current transform will be added. The function returns 1 if successful, 0 if the new cell could not be opened.

(int) Delete()
This function deletes all selected objects from the database.

(int) DeleteEmpties(recurse)
This function will delete empty cells found in the hierarchy under the current cell. This operation can not be undone. The argument is an integer flag; if zero, one pass is done, and all empty cells are deleted. If the argument is nonzero, additional passes are done to delete cells that are newly empty due to their subcells being deleted on the previous pass. The top-level cells is never deleted. The return value is the number of cells deleted.

(int) Erase(left, bottom, right, top)
This function erases the rectangular area defined by the arguments. Polygons, wires, and boxes are appropriately clipped. The erase function has no effect on subcells or labels. This provides an erase capability similar to the erase menu button.

(int) EraseUnder()
This function will erase geometry from unselected objects that intersect with objects that are selected. If in layer-specific mode, only the current layer will be erased, otherwise all layers will be erased. This is equivalent to the Erase Under command in Xic. This function always returns 1.

(int) Yank(left, bottom, right, top)
This function puts the geometry in the specified rectangle in yank buffer 0. It can be placed with the Put function, or the put command. This provides a yank capability similar to the erase button in the side menu.

(int) Put(x, y, bufnum)
This puts the contents of the indicated yank buffer in the current layout, with the lower left at x, y. The bufnum is the yank buffer index, which can be 0-4. Buffer 0 is the most recent yank or erase, buffer 1 is the next most recent, etc. This provides functionality similar to the put button in the side menu.

(int) Xor(left, bottom, right, top)
This function exclusive-or's the rectangular area defined by the arguments with boxes, polygons, and wires on the current layer. Existing objects become clear areas. This provides functionality similar to the xor button in the side menu.

(int) Copy(fromx, fromy, tox, toy, repcnt)
Copies of selected objects are created and placed such that the point specified by the first two arguments is moved to the location specified by the second two arguments.

The repcnt is an integer replication count in the range 1-100000, which will be silently taken as one if out of range. If not one, multiple copies are made, at mutiples of the translation factors given.

This provides functionality similar to the Copy button in the Modify Menu. The return value is 1 if there were no errors and something was copied, 0 otherwise.

(int) CopyToLayer(fromx, fromy, tox, toy, oldlayer, newlayer, repcnt)
This is similar to the Copy function, but allows layer change. If newlayer is 0, null, or empty, oldlayer is ignored and the function behaves identically to Copy. Otherwise the newlayer string must be a layer name. If oldlayer is 0, null, or empty, all copied objects are placed on newlayer. Otherwise, oldlayer must be a layer name, in which case only objects on oldlayer will be placed on newlayer, other objects will remain on the same layer. Subcell objects are copied as in Copy, i.e., the layer arguments are ignored.

(int) Move(fromx, fromy, tox, toy)
This function moves the selected objects such that the reference point specified in the first two arguments is moved to the point specified by the second two arguments. This provides functionality similar to the Move button in the Modify Menu. The return value is 1 if there were no errors and something was moved, 0 otherwise.

(int) MoveToLayer(fromx, fromy, tox, toy, oldlayer, newlayer)
This is similar to the Move function, but allows layer change. If newlayer is 0, null, or empty, oldlayer is ignored and the function behaves identically to Move. Otherwise the newlayer string must be a layer name. If oldlayer is 0, null, or empty, all moved objects are placed on newlayer. Otherwise, oldlayer must be a layer name, in which case only objects on oldlayer will be placed on newlayer, other objects will remain on the same layer. Subcell objects are moved as in Move, i.e., the layer arguments are ignored.

(int) Rotate(x, y, ang, remove)
The selected objects are rotated counter-clockwise by ang (in degrees) about he point specified in the first two arguments. This provides functionality similar to the spin button in the side menu.

If the boolean argument remove is true (nonzero), the original objects will be deleted. Otherwise, the original objects are retained, and will become deselected.

The return value is 1 if there were no errors and something was rotated, 0 otherwise.

Note: in releases prior to 3.0.5, the remove argument was absent and effectively 0 in the current function implementation.

(int) RotateToLayer(x, y, ang, oldlayer, newlayer, remove)
This is similar to the Rotate function, but allows layer change. If newlayer is 0, null, or empty, oldlayer is ignored and the function behaves identically to Rotate. Otherwise the newlayer string must be a layer name. If oldlayer is 0, null, or empty, all rotated objects are placed on newlayer. Otherwise, oldlayer must be a layer name, in which case only objects on oldlayer will be placed on newlayer, other objects will remain on the same layer. Subcell objects are rotated as in Rotate, i.e., the layer arguments are ignored.

If the boolean argument remove is true (nonzero), the original objects will be deleted. Otherwise, the original objects are retained, and will become deselected.

The return value is 1 if there were no errors and something was rotated, 0 otherwise.

Note: in releases prior to 3.0.5, the remove argument was absent and effectively 0 in the current function implementation.

(int) Split(x, y, flag, orient)
This will sever selected objects along a vertical or horizontal line through x, y if flag is nonzero. If orient is 0, the break line is vertical, otherwise it is horizontal. If flag is zero, the function will return 1 if an object would be split, 0 otherwise, though no objects are actually split. This provides functionality similar to the break button in the side menu.

(int) Flatten(depth, use_merge, fast_mode)
The selected subcells are flattened into the current cell, recursively to the given depth, similar to the effect of the Flatten button in the Edit Menu.

The depth argument may be an integer representing the depth into the hierarchy to flatten: 0 for top-level subcells only, 1 to include second-level subcells, etc. This argument can also be a string starting with `a' to signify flattening all levels. A negative depth also signifies flattening all levels.

The use_merge argument is a boolean which if nonzero indicates that new objects will be merged with existing objects when added to the current cell. This is the same merging as controlled by the Merge Boxes, Polys and Merge, Clip Boxes Only buttons in the Edit Menu.

If the boolean argument fast_mode is nonzero, ``fast'' mode is used, meaning that there will be no undo list generation and no object merging. This is not undoable so should be used with care.

The function returns 1 on success, 0 otherwise, with an error message probably available from GetError.

(int) CreateCell(cellname, [orig_x, orig_y])
This will create a new cell from the contents of the selection queue, with the given name, which can not already be in use. The new cell is created in memory only, with the modified flag set so as to generate a reminder to the user to save the cell to disk when exiting Xic. This provides functionality similar to the Create Cell button in the Edit Menu.

If the optional coordinate pair orig_x and orig_y are given (in microns), then this point will be the new cell origin in physical mode only. Otherwise, the lower-left corner of the bounding box of the objects will be the new cell origin. In electrical mode, the cell origin is selected to keep contacts on-grid, and the origin arguments are ignored.

By default, this function will fail if a cell of the same name already exists in the current symbol table. However, if the CrCellOverwrite variable is set, existing cells will be overwritten with the new data, and the function will succeed.

Layer(string, mode, depth, recurse, noclear, use_merge, fast_mode)
This is very similar to the !layer command, and operations from the Evaluate Layer Expression panel brought up with the Layer Expression button in the Edit Menu. The string is of the form
``new_layer_name [=] layer_expression''.

The mode argument is an integer which sets the split/join mode, similar to the keywords in the !layer command, and the buttons in the Evaluate Layer Expression panel. Only the two least-significant bits of the integer value are used.

0 default
1 horizontal split
2 vertical split
3 join

The depth is the search depth, which can be an integer which sets the maximum depth to search (0 means search the current cell only, 1 means search the current cell plus the subcells, etc., and a negative integer sets the depth to search the entire hierarchy). This argument can also be a string starting with `a' such as ``a'' or ``all'' which specifies to search the entire hierarchy.

The recurse argument is a boolean value which corresponds to the ``-r'' option of the !layer command, or the Recursively create in subcells check box in the Evaluate Layer Expression panel. If nonzero, evaluation will be performed in subcells to depth, using only that cell's geometry. When zero, geometry is created in the current cell only, using geometry found in subcells to depth.

If the boolean argument noclear is true, the target layer will not be cleared before expression evaluation. This corresponds to the ``-c'' option of the !layer command, and the Don't clear layer before evaluation button in the Evaluate Layer Expression panel.

The boolean argument use_merge corresponds to the ``-m'' option in the !layer command, and the Use object merging while processing check box in the Evaluate Layer Expression panel. When nonzero, new objects will be merged with existing objects when added to a cell.

The fast_mode argument is a boolean value that corresponds to the ``-f'' option in the !layer command, and the Fast mode check box in the Evaluate Layer Expression panel. When nonzero, undo list processing and merging are skipped for speed and to reduce memory use. However, the result is not undoable so this flag should be used with care.

There is no return value; the function either succeeds or will terminate the script on error.


next up previous contents index
Next: Property Management by Handles Up: Geometry Editing Functions 2 Previous: Clipping Functions   Contents   Index
Stephen R. Whiteley 2012-04-01