next up previous contents index
Next: Property Management 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. 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 (19.13.12) 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. 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.

(object_handle) BoxH(left, bottom, right, top)
This is similar to the Box function, but will return a handle to the new object. On error, a scalar 0 is returned.

(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.

(object_handle) PolygonH(num, arraypts)
This is similar to the Polygon function, but will return a handle to the new object. On error, a scalar 0 is returned.

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

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

All dimensions are given in microns. The first two arguments provide the center coordinates. The second two arguments are the inner radius in the X and Y directions. If these differ, the inner radus will be elliptical, otherwise it will be circular. If both are zero, the figure will not have an inner surface.

Similarly, the next two arguments specify the outer radius, X and Y directions separately. Both are required to be larger than the inner radius counterpart.

The final two arguments are the start and end angle, given 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 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.

The function returns 1 on success, 0 otherwise.

(object_handle) ArcH(x, y, rad1X, rad1Y, rad2X, rad2Y, ang_start, ang_end)
This is similar to the Arc function, but will return a handle to the new object. On error, a scalar 0 is returned.

(int) Round(x, y, rad)
This a simplification of the Arc function which simply creates a circular disk object at the location specified in the first two arguments. All dimensions are in microns. The third argument specifies the radius.

The function returns 1 on success, 0 otherwise.

(object_handle) RoundH(x, y, rad)
This is similar to the Round function, but will return a handle to the new object. On error, a scalar 0 is returned.

(int) HalfRound(x, y, rad, dir)
This is a simplification of the Arc function which creates a half-circular figure. The first two arguments indicate the center of an equivalent full circle, i.e., it is the midpoint of the flat edge. The dir argument is an integer 0-7 which specifies the orientation, in increments of 45 degrees. With 0, the flat section is horizontal with the curved surface on top. The dir rotates clockwise, so that a value of 2 would produce a figure that looks like the letter D.

The function returns 1 on success, 0 otherwise.

(object_handle) HalfRoundH(x, y, rad, dir)
This is similar to the HalfRound function, but will return a handle to the new object. On error, a scalar 0 is returned.

(int) Sides(numsides)
This sets the number of segments to use in generating round objects, for the current display mode (electrical or physical). The function returns the present value for this parameter. This is similar to the sides side menu button in physical mode. It simply sets the RoundFlashSides variable, or clears the variable if the number of sides given is the default. Similarly, in electrical mode it is similar to the sides entry in the menu from the shape button in the side menu, and sets or clears the ElecRoundFlashSides variable.

(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.

(object_handle) WireH(width, num, arraypts, end_style)
This is similar to the Wire function, but will return a handle to the new object. On error, a scalar 0 is returned.

(int) Label(text, x, y [, width, height, flags)]
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 label reference point.

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 flags argument is a label flags word used in Xic to set various label attributes, as described in C.2. If given, the Justify function and UseTransform function settings will be ignored, and these attributes will be set from the flags. If flags is not given, the functions will set the justification and transformation.

This function always returns 1.

(object_handle) LabelH(text, x, y [, width, height, xform)]
This is similar to the Label function, but will return a handle to the new object. On error, a scalar 0 is returned.

(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
LogoPixelSize
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) Delete()
This function deletes all selected objects from the database.

(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. 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 multiples 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 specified in the Editing Setup panel from the Edit Menu, or corresponding variables.

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.

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 Up: Geometry Editing Functions 2 Previous: Clipping Functions   Contents   Index
Stephen R. Whiteley 2024-09-29