XCircuit Tcl Interpreter Command Reference

Tcl/Tk-based XCircuit Commands

The command-line functions are summarized below. The GUI interface by attaching these commands as callback functions to buttons and other window events.

Click here for a discussion of interpreters and a brief history of XCircuit's interpreter options. The other interpreter command-line interface pages can be found here: Python, and original.

Quick Alphabetized Command Index:

action	cursor	fill	loadfont	path	redo	spline	zoom
arc	delete	flip	move	polygon	refresh	standardaction
bindkey	deselect	graphic	netlist	pop	rotate	start
border	edit	here	object	promptsavepage	schematic	symbol
color	element	instance	page	push	select	tag
config	eventmode	label	pan	quit	simple	technology
copy	filerecover	library	parameter	quitnocheck	spice	undo

Syntax:

boldface type

indicates a keyword which is typed verbatim into the interpreter command-line

italic type

indicates a variable which should be substituted with a value.

[ words in brackets ]

are optional (zero or one occurrence)

vertical | bar

indicates a choice of either the item to the left of the bar or the item to the right of the bar.

ellipses...

indicate one or more occurrences of the item to the left

{boldface braces}

indicate a Tcl list

"boldface double quotes"

indicate a keyword containing a space, which must be double-quoted in Tcl so that it will be interpreted as a single item. These may also be set in braces (a Tcl list).

Built-in commands (C source)

Elements

Primary commands to create and manipulate objects. The element command is partly a superset of the individual elements, when the command is given a handle value and the element type is unknown. A handle is an integer pointer to the element's location in memory. The notation handle... represents a list of one or more handles to elements. If more than one handle is in the list, the list must be constructed as a Tcl list, inside braces ({}). handle can also be the keyword selected, in which case it implies all selected elements. The handle is represented as a new Tcl type called "handle", and has an "H" followed by an 8-digit hexidecimal number. The "H" distinguishes it from integers and allows the command line to be parsed correctly. It also discourages the practice of manipulating handles, as arithmetic cannot be performed directly on handle types.

Only one option, type, does not apply to individual elements.

When no handle is supplied, the option operates on all currently selected elements in the drawing. If no handle is supplied and no elements are currently selected, xcircuit will generally report a syntax error.

As of xcircuit version 3.4, commands will accept (where appropriate) a hierarchical notation for elements. This notation consists of a slash-separated series of hierarchically nested object instance handles, with an element handle following the last slash. Certain commands reporting point positions will return point positions relative to the current top-level schematic.

element [handle...] type

Returns the type of the element, which may be one of label, polygon, instance, spline, path, graphic, or arc.

element [handle...] option

Performs operations on the various element types. element may be any of the keywords element (see above), label, polygon, instance, spline, path, graphic, or arc. Option option may be an option relevant to the specific element chosen, or else it must be one of the following:

deselect

deselect the indicated element(s).

element [handle...] parameter option... [switch...]

Option may be one of the following:

allowed

List the parameter types which are allowed for the indicated element type.

make type [key value]]

Generate a parameter of the indicated type for the indicated element. type may be one of: position, "x position", "y position", style, justification, "start angle", "end angle", radius, "minor axis", rotation, scale, linewidth, or color. Items with more than one word must be quoted. The key is automatically generated and the existing value is given to the parameter.

make type key value

Generate a parameter of the indicated type for the indicated element. type may be one of: numeric, expression, or substring. Because these types are not attached to a specific property of an element, the key and initial value are required arguments. value must be a number for type numeric. For the substring type, a Tcl list representation of an XCircuit string is parsed directly, while all other values will be converted into a simple string representation. The expression type takes a Tcl expression as a value. The parameter value will be a string representation of the return value from the evaluation of the Tcl expression.

get [type | key]

List the parameters of the indicated element(s). If type is given, get the instance value of the parameter type type (see above). If the parameter takes the default value, a null list is returned. If the parameter type does not exist for the element, an error is generated. The parameter may also be specified by key key.

default [type | key]

Get the default value of the indicated parameter type type or key key (see above).

forget type | key

Delete the parameter of the indicated parameter type type or key key from the indicated element.

Switch may be one of the following:

-forward

When used with a selected object instance, specifies that the parameter commands refer to parameters of the instance, not of the top level. This switch allows parameters of an instance to be modified without editing the object.

-indirect

When used with parameter set, argument value is treated as the keyword of a parameter in the parent object. The parameter key in the child object then inherits the value of parameter value in the parent.

-verbatim

When this switch is used with parameter get, parameters which are indirectly referenced will return the key of the referenced parameter, and parameters which are type expression will return the expression instead of the result.

delete

Deletes the indicated element(s).

copy [relative] position

Makes a copy of the indicated element(s). position is a list of 2 elements representing absolute X and Y positions, unless the keyword relative is present, in which case they represent positions relative to the current element position. If more than one element is specified, the position must be indicated as relative.

move [relative] position

Moves the indicated element(s). position is a list of 2 elements representing absolute X and Y positions, unless the keyword relative is present, in which case they represent positions relative to the current element position. If more than one element is specified, the position must be indicated as relative.

flip horizontal| vertical [position]

Flips the indicated element(s) around the horizontal or vertical axis. If position is specified, then element or element group will be flipped around the indicated point. position may be a single number, representing an X value for horizontal flips and a Y value for vertical flips.

rotate angle [position]

Rotates the indicated element(s) by the specified angle (in degrees). Positive angles are clockwise, negative angles are counterclockwise. If position is specified, then element or element group will be rotated around the indicated point.

select

Selects the specified element(s).

snap [direction]

Snaps the indicated elements onto the snap grid. If direction is specified (one of the keywords n, s, e, w, ne, nw, se, or sw), elements will be snapped in that direction. Otherwise, elements will be snapped to the closest point.

raise [all]

Raise the position of the indicated or selected element(s) toward the drawing front (end of list; last to be drawn) by one position. If "all" is specified, it is raised to the front of the drawing. Any elements in the set that are already at the front of the drawing stack will not be moved.

lower [all]

Lower the position of the indicated or selected element(s) toward the drawing back (beginning of list; first to be drawn) by one position. If "all" is specified, it is lowered to the back of the drawing. Any elements in the set that are already at the back of the drawing stack will not be moved.

color option

Where option may be one of the following:

get

Returns the color of the specified element(s), or the current default color, if nothing is selected or indicated.

set [idx|name]

Sets the color of the specified element(s) to value idx, an index into xcircuit's color table, or name, an X11 defined color name. If nothing is selected, then the default color is changed.

add [name]

Add a new color (a defined X11 name) to the color table.

override

Override the loading of the default table of colors on startup. This function only has any effect when used in the startup script (.xcircuitrc file).

element [handle] edit

Puts the specified element into interactive edit mode. Because xcircuit knows how to edit only one element at a time, only one handle can be specified, or one element selected.

element [[handle1] [handle2]] exchange

This particular command differs from the others in that it requires zero, one, or two handles. If no handles are specified, then exactly one or two objects must be previously selected. If only one handle is specified or only one object previously selected, the behavior is to raise it to the front of the drawing, unless it is already at the front of the drawing, in which case it is moved to the back. If two elements are specified, or two elements are selected, the commands exchanges the positions of the two elements in the display list.

path_element [handle...] option

Perform operations on various path-like elements, where path_element may be any of polygon, spline, arc, or path. Option option may be one of the following:

border [value]

Set the border linewidth scaling to floating-point value value, or return the current scale if value is not given.

border [type]

Set the border style of the indicated element(s) to type, or return the type (or list of types) if type is not given. type may be one of the keywords solid, dashed, dotted, unbordered, unclosed, closed, bbox, square, round, or clipmask.

fill [type]

Set the fill style of the indicated element(s) to type, or return the type (or list of types) if type is not given. type may be a fill percentage (representing a stipple pattern) or one of the keywords opaque or transparent.

segmented_element [handle...] point option

Perform operations on various segmented elements, where segmented_element may be any of polygon, spline, or path. Option option may be one of the following:

point [number] insert [after|before] [relative] [position]

Insert a new point before or after point number or the current point if editing interactively. If non-interactive, the point must be given a position as a list of size 2, which is either an absolute position, or a relative position if the keyword relative is given.

point [number] delete [number]

Delete point number, or the current point if editing interactively.

point [number] parameter

Parameterize the position of point number, or the current point if editing interactively.

point [number] break

Break the element at point number, or at the current point if editing interactively. Returns a handle to the new element generated by the break.

point [number] next

Return the point following point number, if specified, or move to the next point if editing interactively.

point [number] snap [direction]

Snap the indicated point number to the snap-to grid. Snapping is in the indicated direction, if supplied, or the closest point, if not. direction may be one of the keywords n, s, e, w, ne, nw, se, or sw.

instance make object_name [position]

Place an instance of the object named object_name. If position is indicated, the new instance is placed at that position. Otherwise, interactive placement is invoked.

instance [handle] push

Edit the indicated instance by "pushing" down in the hierarchy. Exactly one handle must be specified or one object instance selected prior to executing the command. This command operates like object push except that if any values in the object are parameterized, the instance values will be changed, not the default values.

instance [handle...] option

Perform operations on one or more object instances. Option option may be one of the following:

scale [value]

Change the scale of the indicated instance(s) to value. If no value is specified, return the current scale of the instance.

center [position]

With no optional argument, return the center position of the object instance as an {x y} coordinate pair list. If position is given and is a list of two coordinate values, then the position of the instance will be modified according to the new position.

linewidth [type]

With no optional argument, return the method of determining object instance linewidth, either "scale_variant" or "scale_invariant". If argument type is given, then it must be one of "scale_variant" or "scale_invariant", and the method of determining object instance linewidth will be set accordingly. Scale variant linewidth means that if the object size doubles, then the linewidth doubles. Scale invariant linewidth means that the linewidth remains the size that it would be for an instance scale of 1, regardless of the instance scale. This is useful for making large or small versions of a component in a schematic while still maintaining the same stroke width for lines as the rest of the components in the schematic.

bbox [recompute]

Without the optional argument, return a list of four values representing the coordinates { llx lly urx ury } of the bounding box of the instance, in the coordinates of the object. The optional argument recompute forces a re-evaluation of the bounding box.

object [name]

With no optional argument name, return the name of the object that the element is an instance of. If name is specified, then change the object instance to be an instance of the object named name. Parameters will be preserved between the old and new objects, where parameters match between the two.

graphic make filename position scale

Read a PPM (portable pixmap) graphic from the file filename and place it at the indicated position and with the indicated scale relative to xcircuit internal units.

graphic make gradient position scale [top_color bottom_color]

Create an in-line graphic in the form of a linear gradient color field. Without color options, the field is white-to-black. With color options, the field fades from top_color on top to bottom_color on the bottom (XCircuit 3.7 or higher only). The graphic is a fixed 100x100 square area, but may be modified by flipping, rotating, and clipping.

graphic [handle] option

Perform operations on graphic images. For these options, exactly one handle must be specified or exactly one label selected. Option option may be one of the following:

position position

Reposition the graphic image at the indicated point

scale scalefactor

Scale the graphic image to the indicated size.

label option

The following label (text) element commands take no handle as an argument. Option option may be one of the following:

make

Interactively create a new label element.

make [pin|global|info] string_list position

Create a new label element with the text specified by string_list and origin at position. Optional keywords pin, global, or info make the label a schematic pin type. string_list is a list of string parts or a single string. See section below on string lists.

label [handle] option

Perform label (text) operations. For these options, exactly one handle must be specified or exactly one label selected. Option option may be one of the following:

text

Return the contents of the label as a single character string. This is useful for regular expression parsing of label contents.

list

Return the contents of the label as a Tcl list. Each part of the string is a 2-part list. The first part is the type of the string part (e.g., "Text" or "Font"), followed by the contents (e.g., a simple string for text parts, or the name of a font for font declarations).

append string_list

Add string_list to the end of the indicated label.

insert position string_list

Insert string_list into the indicated label at the indicated position.

delete start end

Delete a substring of the indicated label beginning at position start and ending before position end.

get start end

Return the substring (list) between beginning at position start and ending before position end

label [handle...] option

Perform operations on one or more label (text) elements. Option option may be one of the following:

replace string_list

Replace the contents of the label or labels with the contents of string_list. Note that by using "label replace" in conjunction with "label list", any manipulation of an xcircuit string can be done with Tcl regular expression and string manipulation commands.

scale [value]

Change the scale of the indicated label. Return the scale if value is not specified.

justify [hjust] [vjust]

Change the justification of the indicated label, where hjust may be one of the keywords left, center, or right, and vjust may be one of the keywords top, middle, or bottom. If neither hjust nor vjust is specified, the command returns a list of size 2 containing the horizontal and vertical justifications.

flipinvariant [true|false]

Set the flip-invariance of the indicated label. If no value is supplied, return the state of the flip-invariance on the label.

style [font_style]

Set the label style to font_style, which may be one of the keywords normal, bold, italic, or bolditalic. If no style is specified, return the current font style.

family [font_family]

Set the label font family to font_family. If no font family is specified, return the current font family.

encoding [font_encoding]

Set the label encoding to font_encoding, which may be one of the keywords standard, special, or ISO-Latin1 through ISO-Latin6. If no font encoding is specified, return the current font encoding.

polygon option

All operations on polygons not covered in the "element" section take no handle as an argument. Option option may be one of the following:

make [box]

Interactively create a new polygon element. A rectangle is created if box is specified. Otherwise, the polygon is generated point by point, in wire-drawing mode.

make N position1 position2 ... positionN

Create a new polygon element with N points. Each position is a list of size 2 with X, Y coordinates.

make box position1 position2 position3 position4

Create a new polygon element with 4 points and with border style closed. Each position is a list of size 2 with X, Y coordinates.

spline option

All operations on splines (actually, Bezier curves) not covered in the "element" section take no handle as an argument. Option option may be one of the following:

make

Interactively create a new spline element.

make [position1 position2 position3 position4]

Create a new spline object with endpoints position1 and position4 and control points position2 and position3.

arc option

The following commands take no handle as an argument. Option option may be one of the following:

make

Interactively create a new arc element.

make [position radius [minor] [angle1 angle2]]

Create a new arc element with the indicated values. By default, minor is set to the value of radius, angle1

is zero, and angle2 is 360. Angle values are in degrees.

arc [handle...] option

A few remaining arc element options can take one or more handles as arguments. Option option may be one of the following:

radius|minor [value]

Specify the major or minor axis radius for the indicated arc.

angle start|end [value]

Specify the start and end angles for the indicated arc.

path make [handles...]

Generate a path element from the indicated components.

object make [handle...] [library] [name]

Creates a new object out of the elements specified by handle..., or from the selected elements if handle... is not specified. The new object is placed into library library, or the User Library, if not specified. The object is given the name name, if specified; otherwise the user is prompted for a name.

object handle name

Return the handle of the indicated object named name.

object [handle] option

The following options act on objects (not object instances!). These commands may take only one selected item, or exactly one object, referenced by handle. Use the "object handle" command (see above) to get an object by name. Option option may be one of the following:

push

Edit the indicated object. This is like an instance edit except that it is the library object itself, with default values for parameters, that is edited. If the object takes no parameters, then there is no difference between editing an object and editing any of its instances.

center [position]

Set the object's origin to position (a list of X, Y values). If position is not specified, then return the coordinates of the center of the object's bounding box.

copy [library] [name]

A copy of the object is made and placed in the named library, or in the User Library if not specified. The new copy is given the name name, or the original name prepended with an underscore if the name is not specified. If the originating and destination libraries are the same, the copy will be a "virtual" copy.

library [library]

Without option [library] (the name or number of a library), report which library the object is in. If a library is specified that is different from the library that the object is in, move the object to the indicated library.

hide

Hide the object from view in its library, unless hiding the object would render the object unaccessible.

unhide

Allow a hidden object to become visible in the library again.

parts

Return a list of handles of all the elements in an object.

Text String Lists

The label command makes reference to string lists, which refer to XCircuit's complicated but flexible way of describing text for labels. A string is made up of a sequence of segments, where each segment contains a directive. The simplest directive is the text directive, which contains a portion of plain text. A label's contents can be retrieved in Tcl/Tk with the label list option, which returns a list of directives, in sequence order. Each directive is itself a list, except for a few single-word options. The complete set of directives is as follows:

{Text {any text string}}

Simple text, including all ASCII characters. Non-ASCII characters are presented as Tcl-style escapes.

{Parameter parameter_name}

Insert a parameter. The parameter is given by name, not value. Use the parameter get command option to determine the value of the parameter. If the parameter is a substring, the parameter get command option will generate a list like that returned by label list. Numerical and expression parameters may also be inserted into text strings, where the values are promoted to a string when displayed.

{Font font_name}}

Change the font to the font named font_name

{{Font Scale} value}

Change the size of the font to size value

{Kern x_value y_value}

Reposition the text following the kern directive by an amount x_value in the x direction and y_value in the y direction. Kerns and text rescales can be used for any custom formatting.

{Color {R_value G_value B_value}}

Change the text color to the indicated RGB color

{{Margin Stop} value}

Mark a margin stop with a width value of value. All text following the margin stop will be restricted to a width of value, and the text string will be automatically formatted with linefeeds to keep the text within the set margin. Note that margins can be resized within a text string (NOTE: Margin stops are available in XCircuit version 3.8.13 and higher).

{Tab Stop}

Mark a tab stop at the current text position. This affects the behavior of subsequent tab-forward and tab-backward directives

{Tab Forward}

Reposition next text at next occuring tab stop

{Tab Backward}

Reposition next text at last occurring tab stop

Return

Carriage Return

Subscript

Begin subscripted text

Superscript

Begin superscripted text

Normalscript

Cancel a subscript or superscript directive

Underline

Begin underlining text

Overline

Begin overlining text

Noline

Cancel an overline or underline directive

{Half Space}

A space of half the width of a normal word-space character

{Quarter Space}

A space of quarter the width of a normal word-space character

Functions

Functions that act on elements are described under the element command (see above). These commands are exactly like the element subcommands except that the arguments are rearranged: "element [handle...] command options..." is equivalent to "command [handle...] options...". In addition, these commands can take a position list position (list of size 2 containing X and Y values) in place of the handle, in which case the command attempts to select an element at the indicated position and apply the command to that element. The keyword here in place of a handle indicates to select an element at the current cursor position. If the handle refers to an element for which the indicated action is not appropriate, an error is generated.

select [handle...|here|get]

The additional subcommand get returns a handle or list of handles of all currently selected elements.

delete [handle...|here]

Remove the element by handle, selected elements, or an element close to the cursor.

deselect [handle...|here|selected]

Unselect the element by handle, selected elements, or an element close to the cursor.

copy [handle...|here] [[relative] {x y}]

Make a copy of elements indicated by handle, selected elements, or an element close to the cursor. If a coordinate position is given, the indicated elements are copied and moved to the indicated location. If relative is also specified, then the copies are placed relative to the original elements by a displacement of x and y. If no coordinate position is given, then the elements are copied and selected for an interactive move.

edit [handle|here]

Edit the element indicated by handle, a selected element, or the element close to the cursor. Unlike other functions, this one (currently) only acts on a single element, there being no method for editing multiple elements at the same time.

parameter option [switch...]

Manipulate parameters. option may be one of the following keywords:

allowed

Returns a list of parameter types that are allowed

get [key]

Returns the instance parameter value of the parameter named key. If no key is given, the all instance parameter values are returned in a list.

type [key]

Returns the parameter type of the parameter named key. If no key is given, then returns all parameter types in a list.

default key

Get the default value of the parameter key. If no key is given, then all default parameter values are returned in a list.

set key value

Set the value of the parameter named key to the value value. When switch -forward is used, the value is the instance value of the parameter.

make type [key [value]]

Create a new parameter of type type having the name key and a default value of value. Element parameter types (such as "style" and "justification", see below) generally do not take a key (a standard parameter key name is used) and only take a value if the value is a Tcl expression that evaluates to a number. Only parameter types substring, numeric, and expression take both key and value strings. The value must be of the appropriate type for the parameter type, although automatic type conversion takes place between substring and numeric types. Numeric values may be either integer or floating-point. "key" may be used in an element parameter to force several elements to use the same parameter value.

make position|"x position"|"y position" point [key]

This is a specific variant of the "parameter make" option to deal with polygons and splines. "point" is a value from 0 to one less than the number of points in a polygon, or 0 to 3 for a spline. The indicated point is parameterized.

replace type

Replaces text with the instance value (when type is substring), or replaces an element parameter with the instance value by unparameterizing the element (for all other types).

forget|delete key

Removes the parameter named key from the object, destroying all references to that parameter made by elements inside the object.

One or more switches may be specified, as follows:

-verbatim

Indicates that if the parameter is an expression, we want the value given as the expression itself, and not the result of that expression.

-indirection

Indicates that the parameter is an indirect parameter, that is, a parameter whose value is derived from a parameter of its parent object.

-forward

Indicates that we want to apply the parameter option to the selected object instance, not to the current object or page schematic in the window. Any selected element must be an object instance.

Parameter types required for the type field are as follows (those which are more than one word must be in quotes). The first list contains parameter types that can be applied only to objects, and which must be given a key and a value when created.

substring

A Tcl string (simple character string in quotes), or an XCircuit string (a Tcl list with strings and embedded escapes). As a Tcl list representing an XCircuit string, it may contain font changes, color changes, etc.

numeric

A simple integer or floating-point number. If used in a label, the number is type-cast into a string according to the rules of the C syntax "%g" string conversion.

expression

Any valid Tcl expression, including XCircuit command-line commands. The value of the parameter is the Tcl expression itself. However, when the parameter is used inside a label, it is the evaluated result of the expression that is printed. Typical uses are the Tcl "expr" command to evaluate mathematical expressions, and the "set" or "puts" commands to display the value of a Tcl variable. Expressions may make reference to other parameters, most conveniently by the syntax "%parameter_key". These escapes are substituted with the corresponding parameter value prior to passing to the Tcl interpreter for evaluation.

In addition to the parameter key escapes, there are a few other "%" escapes that area recognized in expression parameters:

p_rotation

Substitutes the rotation of the object instance

p_scale

Substitutes the scale of the object instance

p_xposition

Substitutes the x coordinate of the object instance

p_yposition

Substitutes the y coordinate of the object instance

p_color

Substitutes the color index of the object instance

p_top_rotation

Substitutes the rotation relative to the top-level drawing

p_top_scale

Substitutes the scale relative to the top-level drawing

p_top_xposition

Substitutes the x coordinate relative to the top-level drawing

p_top_yposition

Substitutes the y coordinate relative to the top-level drawing

The second list contains the parameter types that can be associated with properties of specific element types. Once an element inside an object is parameterized, the specified property of that element can be different for each instance of the object. A typical use is to counter-rotate text inside symbols so that the text becomes rotation-invariant (at least through one level of hierarchy) in addition to the built-in flip invariance. Position parameters can be used to allow the labels in an object to be moved around individually for each instance, to make the schematic cleaner and easier to read. Most element parameters are self-explanatory.

"x position" [cycle], "y position" [cycle]

Parameterize the X or Y position of a point. The cycle is the position of the point in the point list, starting at zero, which means that it must be strictly less than the number of points in a line, or from 0 to 3 inclusive for a spline curve. cycle applies only to lines and splines. It is optional when in line or curve edit mode (where the cycle is determined by the current edit point).

position [cycle]

This is not a true parameter, but simply a convienence keyword that indicates that both X and Y positions should be parameterized for the same point. cycle is interpreted as above, for lines and splines only. Note that an individual line or spline point position can be parameterized by typing "p" while editing the element.

style

Parameterize the border style (dotted, dashed, closed, etc.) of a polygon, arc, spline, or path.

justification

Parameterize the justification of a label (also includes various flag bits embedded in the justification word, including flip invariance).

"start angle"

Parameterize the start angle of an arc.

"end angle"

Parameterize the ending angle of an arc.

radius

Parameterize the radius of an arc.

"minor axis"

Parameterize the minor axis length of an arc.

rotation

Parameterize the rotation of an instance, graphic, or label.

scale

Parameterize the scale of an instance, graphic, or label.

linewidth

Parameterize the border linewidth of a polygon, arc, spline, or path.

color

Parameterize the color of any element.

push [handle|here]

Descend (push) into the object of the object instance indicated by handle, a selected object instance, or the object instance closest to the cursor. Unlike other functions, only one element can be listed or selected, and it must be type object instance.

pop

Return from a push into an object. This function has no options.

move [handle...|here] [[relative] {x y}]

Pick up the elements indicated by handle, selected elements, or an element close to the cursor. If a coordinate position is given, the indicated elements are moved to the indicated location. If relative is also specified, then the elements are placed relative to their original positions by a displacement of x and y. If no coordinate position is given, then the elements are selected for an interactive move.

rotate [handle...|here] angle [center]

Rotate the elements indicated by handle, selected elements, or elements close to the cursor. The rotate command must specify the angle, in degrees, of the rotation, where a positive angle indicates a clockwise rotation, and a negative angle indicates a counterclockwise rotation. If a center position is specified, then the center of rotation is about that coordinate position. Otherwise, the rotation is around the cursor position for all groups of elements and most single elements, but around the origin of a single object instance or label.

flip [handle...|here] horizontal|vertical [center]

Flip the elements indicated by handle, selected elements, or elements close to the cursor. The flip command must specify whether the flip is horizontal or vertical. If a center position is specified, then the flip is across the axis running through that coordinate position. Otherwise, the flip is around the axis defined by the cursor position for all groups of elements and most single elements, but around the axis running through the origin of a single object instance or label.

Undo mechanism

undo

Undo the last action. XCircuit registers drawing events and places them on a stack where they can be retrieved. Some exceptions:

• A few events that alter many things at once, like clearing a page or loading a new drawing, cannot be undone.
• Events that don't change the drawing itself are not recorded, such as zoom and pan functions.
• A few minor events have not been incorporated into the undo mechanism.

undo series start|end

Start or finish an "undo" monolithic series. Use this in a script to make all the commands in a procedure be undone by a single "undo" command. "undo series start" begins recording a series of events as a single "undo" event, and "undo series end" completes it. If any series is not ended, XCircuit's undo mechanism is effectively disabled.

redo

Redo the last action.

Pages

page

Returns the current page

page directory

Go to the page directory listing (interactive command)

page [number|name]

Same as page [number|name] goto (see below)

page make [name]

Make a new page, giving it the optional name name if supplied. If name is not present, the page will be given the default name "Page X" where X is the page number. Generate a new menu button entry for the indicated page. Go to the indicated page.

page [number|name] option

Where the page may be specfied either by page number or by page name (page label). If neither number or name is supplied, then the current page is assumed. Option option may be one of the following:

load filename... [-replace [library]] [-target library]

Load the xcircuit file named filename into the indicated page. The -replace option causes objects in the file that differ from library objects of the same name to be overwritten by the library object. If the name of a specific library is provided, replacements will only be made for objects having the same name as objects on that specific library page.
The -target option causes objects in the file to be placed into the named library page instead of the default library page, which is the User Library.

import filename...

Import the xcircuit file named filename into the indicated page.

background filename

Read the PostScript file named filename into the indicated page as a background image.

update

Update the bounding box of the page to capture any outstanding changes, and auto-fit the page to the output page size, if auto-fit has been selected.

save [filename]

Save the indicated page as filename. Normally, filename is not specified and the filename given to the page by the filename command is used.

goto

Go to the page directory listing (interactive command)

handle

Return the object handle for the current or indicated page.

reset

Resets (clears) the indicated page, or the current page if no arguments are given.

links [option...]

Without any option specified, returns the page labels of all pages which have the same filename as the current or indicated page. Options are as follows:

independent

Returns the number of independent top-level schematic pages. These are pages that netlist separately, but all have the same filename, and so are saved together.

dependent

Returns the number of schematic pages that are subcircuits of another schematic page.

total

The sum of independent and dependent pages.

linked

Returns the number of schematic pages that are linked to the top-level schematic through the "link" parameter.

pagedependent

Returns the number of pages that are subcircuits of the current top-level schematic.

all

Returns the total number of non-empty pages in xcircuit.

sheet

Returns the sheet number of the current page.

load [-replace library] [link_key]

Load all schematics that are used by the current top-level page, and that can be found (e.g., are in the current working directory or the file search path (see config search)). Schematic dependencies are determined by the presence of parameter link_key in a symbol, which defaults to the parameter name "link". Normally, a symbol's parameter link will have the special parameter value "%n", indicating that the schematic file has the same name (minus extension) as the symbol. The page links load function does not load dependencies of dependencies. However, the function returns the number of new pages that were loaded, so all nested dependencies can be resolved using while {[page links load]}{}, which is the command used by the menu button "File->Load Dependencies". the -replace option functions the same way as it does for the page load command.

pending [link_key]

This function is identical to page links load except that it only reports the number of dependent schematics that would be loaded by the page links load command, but does not actually load any new pages.

bbox [all]

Return the bounding box of the page, in internal (integer) units. The value is a list of two points representing the lower left and upper right corners. Each point is a list of X and Y values. Without the option "all", the bounding box excludes pins and information labels, that is, elements of an object that do not show up when the object is seen from a higher level of the hierarchy.

changes [number]

Report the number of changes made to the page since the last time the page was saved to disk. With an argument, forces the number of changes on the page to be recorded as number. This can be used to force a write of all pages, regardless of whether or not they have been edited.

fit [true|false]

If true or false is given, sets or clears the auto-fit function for the current page. If no value is given, then it rescales the drawing to fit the output page. Only valid in "full page" mode.

filename [name]

Sets the filename of the current page to name. With no argument, returns the filename of the current page.

label [name]

Sets the name (page label) of the current page to name. With no argument, returns the page label of the current page.

scale [value]

Sets the scale of the current page to value. With no argument, returns the scale of the current page.

width [value]

Sets the scale of the current page such that the width is value. With no argument, returns the width of the object in the current page.

height [value]

Sets the scale of the current page such that the height is value With no argument, returns the height of the object in the current page.

size [dimension]

Sets the size of the output page for full-page mode to the given dimension, which can be a list of size 2 containing the page width and height, or a string in the format "width x height". With no argument, returns the size of the current page as a string in the format "width x height".

Libraries and Technologies

library

Returns the current library, or none if none is being viewed.

library directory

Go to the library directory (interactive command).

library make [name]

Make a new library, giving it the optional name name if supplied, otherwise giving it the default name "Library: X" where X is the library number. Generate a new menu button entry for the indicated library.

library [number|name] option

Where the library is specified by number or by name. If no library is specified, then the current library is assumed if a library page is currently in the xcircuit drawing window, or the User Library is assumed if not. Option option may be one of the following:

load filename

Load the library from file filename into the indicated library page. In version 3.5 and higher, filename may be a regular (.ps) file as well as a specific library (.lps) file. If so, any objects defined in the file will be loaded into the specified library page, ignoring the page definitions.

import filename objectname

Load a specific single object named objectname from the library file filename into the indicated library page.

goto

Go to the indicated library page (interactive command).

next

Go to the next library page in round-robin fashion.

override

Prevent the default loading of libraries as defined in the system startup script "xcstartup.tcl". This command only has an effect when it is put at the top of the ".xcircuitrc" startup file in a user's home directory or current working directory. Note: This prevents the wholesale reading of the system startup file, and so also prevents loading of fonts. The preferred method is now to set variable XCOps(liboverride) at the top of the .xcircuitrc script.

list

Return a list of all the objects on the specified library page (fully-qualified names, with technology prefixes).

handle

Return a list of handles to objects on the library page. This is equivalent to "library list" followed by "object handle" applied to each name in the list.

compose

Force a library to regenerate itself. Normally, this should not be necessary.

library filename [number]

Backward compatibility; same as library [number] load filename

technology list

Return a list of all technology namespaces currently known to XCircuit.

technology used [page]

Return a list of all technology namespaces currently used by objects that are descendants of the schematic page. page defaults to the current page if not specified.

technology technology [option ...]

Handle library files, which correspond to technology namespaces. The technology namespace technology must be a valid namespace known to XCircuit, that is, an item in the list returned by the "technology list" command. Options are as follows:

objects

Return a list of the library objects belonging to technology technology

objects list

Change the technology of all the objects in list from their original technology namespace to the new namespace technology. This is useful for collecting a number of objects into a single technology namespace to save as a new technology file.

save [new_name]

With no arguments, writes all objects belonging to technology technology (and any dependent objects from other technologies) to the file from which they came. With an argument, the filename of the library file is changed to new_name and the objects saved to the new file.

filename [new_name]

With no argument, return the filename of the library file which defines the objects in technology technology. With argument new_name, change the filename associated with technology technology to new_name.

changed [true|false]

With no argument, returns TRUE if any object in technology technology has been modified, FALSE otherwise. If an argument is given, the then technology file is forced to be considered modified or unmodified, respectively.

writable [true|false]

With no argument, returns TRUE if the library file that defines the objects in technology technology is writable, FALSE if not. If an argument is given, then the technology file is set to either read-only or read-write, accordingly.

Options

config option

Main option setting. Option option may be one of the following:

axis|axes [on|off]

Turn axis drawing on or off. If no argument supplied, on is assumed.

grid [on|off]

Turn grid drawing on or off. If no argument supplied, on is assumed.

grid spacing value

Set the grid spacing to value. value is a number representing distance in the current coordinate system. Currently, coordinate system specifiers like in and cm may be included but are ignored.

snap [on|off]

Turn snap point drawing on or off. If no argument supplied, on is assumed.

snap spacing value

Set the snap spacing to value. value is a number representing distance in the current coordinate system. Currently, coordinate system specifiers like in and cm may be included but are ignored.

bbox [on|off]

Turn bounding box drawing on or off. If no argument supplied, on is assumed.

editinplace [on|off]

Turn edit-in-place on or off. If no argument supplied, on is assumed. When on, the entire drawing is drawn from the top level when the drawing hierarchy is descended, but everything above the current edit level is drawn in gray.

clipmasks [show|hide]

Turn clipmask outline drawing on or off. The default is to show clipmask outlines so that the clipping element is not invisible. Turn off to see the view as it will appear on the printed output page.

pinpositions [on|off]

Turn pin position drawing on or off. If no argument is supplied, on is assumed. When on, pin positions inside an object instance appear in levels of the drawing hierarchy outside of the object.

pinattach [on|off]

Force wires attached to pins on object instances or pin labels to remain attached when the element is moved.

linewidth value

Set global line scaling. All linewidths in the drawing are determined relative to this overall scaling value (default 1.0).

colorscheme normal|inverse

Set the overall colorscheme. Keyword normal is black-on-white. inverse is white-on-dark gray.

drawingscale scale

Set the drawing scale. scale is represented as divisor:multiplier. Positions reported in the message bars are scaled by multiplier/divisor with respect to the scale of the actual output.

manhattan [on|off]

Sets the style of polygon drawing. When on, lines can only be drawn vertical and horizontal. If no argument is supplied, on is assumed.

filter [type [true|false]]

Sets the selection filter for particular element types. With no arguments, returns a list of element types which are enabled in the selection filter. With one argument, type, returns the status (true or false) of the selection filter for that particular type. type may be one of: instances, polygons, arcs, splines, paths, or labels. With two arguments, sets the selection filter status for the indicated element type.

boxedit manhattan|rhomboidx| rhomboidy|rhomboida|normal

Sets the style of polygon editing. manhattan forces lines to remain vertical or horizontal, but does not affect lines which are already diagonal. normal places no restrictions on line position. The rhomboid styles place manhattan restrictions on horizontal or vertical lines, but not both, and are of limited practicality.

pathedit tangents on|off

Sets the behavior for editing multiple spline curves in a path. When on (the default), and a control point is edited that belongs to the shared endpoint of two neighboring splines, the control points of the two splines will move in opposite directions. This will maintain the angle between the two lines, in particular to keep smooth (non-kinked) transistions between curves. When off, the control points of neighboring curves can be edited independently.

coordstyle "decimal inches"|"fractional inches"|centimeters|"internal units"

Sets the coordinate measurement system to metric or standard. "fractional inches" reports values in whole number fractions when possible. "internal units" reports in absolute integer numbers. All other types are scaled relative to the output; that is, they report actual distances as measured on the output page, given the current output scale value. The origin, however, is always the internal axis origin, and all positions are measured relative to this point. All values (including internal units) are additionally scaled according to the "drawing scale" (see option "drawingscale" above). The default value is "internal units".

buschar [character]

Set or report the delimiter character used to indicate a but. By default, this is a bracket "[" character. If the character is a parenthesis, bracked, brace, or less-than symbol, the delimiters are assumed to consist of matching pairs of left- and right- symbols. Otherwise, the same symbol is assumed to be used on both sides of the sub-bus values.

centering [true|false]

Report or set the option of whether newly created objects take the origin of the parent as their own origin ("centering false") or get a new origin that is calculated as the center point of all elements in the object.

search file|library [list]

Create or modify the search paths for schematic files and library files. list is a colon (":") separated list of directory names to search, in the order that they should be searched. A null list ("{}") disables the indicated search path and reverts to the default behavior used at startup. Default behavior for schematic files is to search the current working directory only. Default behavior for libraries is to search the current working directory, the directory pointed to by the environment variable XCIRCUIT_LIB_DIR, and the installation target directory (normally, something like /usr/local/lib/xcircuit-3.5/. These default search locations are disabled when config search is used, so they need to be included in the path list if needed.

init windowname

Creates a new data structure for a drawing window. windowname must be a valid Tk window path name to a window to be used as the drawing window.

focus [windowname]

Sets focus on the given window windowname. All commands and actions will apply to the specified window until a new focus command is issued. If windowname is not given, then the command returns the name of the window currently having focus.

delete windowname

Remove the data structure associated with the drawing window windowname.

windownames

Returns a list of windows that have been created with config init.

hold [on|off]

Returns or sets the "hold" mode, which affects whether or not XCircuit responds to the "hold" key modifier. When enabled, XCircuit's bindkey command can bind functions to keys with the key modifier "Hold", which treats a key or button differently when it is pressed and held down as opposed to being tapped quickly. Users not used to the "hold" function may find it disconcerting, and occasionally, when using XCircuit over a network there may be enough network delay to prevent XCircuit from properly distinguishing button and key taps from holds. In such cases, the function "config hold off" will cause XCircuit to ignore all "Hold" bindings. XCircuit's default key bindings are configured in such a way that no functionality is lost by disabling Hold modifiers.

suspend [true|false]

Without an argument, returns the current drawing state, which is one of: "normal drawing", "drawing suspended", "refresh pending", and "drawing locked". Executing "config suspend true" causes all graphics drawing operations to be suspended until either the suspend is removed by execution of "config suspend false", or a key or mouse button event is received. The state "refresh pending" indicates that XCircuit received at least one request to redraw the display while suspended. Calling "config suspend true" twice locks out keystrokes, preventing all display redraws until the "config suspend false" command is executed. The "config suspend" command is often used inside Tcl scripts to prevent drawing during execution of a monolithic sequence of procedure calls.

database window

Regenerate the database of colors, fonts, etc., from Tk options. The Tk "option" command can be used to set various options in the style of X11 Resources. Those options that apply to Tk windows are handled by Tk and take effect immediately. Those options that are handled by XCircuit (options for the XCircuit layout window) will not take effect until the "config database" command is executed. window is the full Tk path name of the XCircuit drawing window.

backup [true|false]

If set to true, the "config backup" command causes XCircuit's backup files to be left after exiting xcircuit. By default, this option is set to false, in which backup files are removed during normal program exit, and will only be left during a catastrophic failure such as a system reset, segmentation fault, or a kill signal. Keeping backup files gives more security at the expense of cluttering up the /tmp directory with accumulating backup files. If this option is set to true, it is probably a good idea to make sure that your system runs a nightly or weekly cron job to clean out the /tmp directory!

technologies [on|off]

If on, this option causes all object names displayed on the library pages to print both the technology prefix and the object name. If off (the default), only the object name is printed on the library page, unless the name is being edited.

color option

Color manipulation (see also the use of color as an element command option). options is one of the following:

add color

This is essentially the same as the "color index" option

get

Get the current default color. The value returned is either an integer index into XCircuit's color table, or the keyword "inherit".

set color

Sets the current default color to the indicated color value.

value color

Returns the integer color value of the indicated color. Typically, this command option is only used in an expression parameter that sets the color of an element.

index color

Returns the index into XCircuit's color table of the indicated color. If color is the word "inherit", then the command returns the value -1.

override

Force an override of XCircuit's color allocation in the system startup file. This assumes that the local startup file will define an alternate palette of colors. Note that black and white will always be allocated regardless of any overrides as a necessary minimum color palette.

The argument color may be either a color index from XCircuit's color table (as returned by the "color index" command, a color name (either a string such as "red" or an RGB color in the X11 notation "#RRGGBB", for example, "#ff0000" for the color red); or the keyword "inherit" (indicating a color that is inherited from an object instance's color value).

fill [option|fillfactor]

Given an integer between 0 and 100 inclusive, sets the fill style to the given fillfactor. Values are rounded to the nearest known fillfactor value. Known values are 0, 12, 25, 37, 50, 62, 75, 87, and 100. Other options include keyword solid (equivalent to 100), opaque, and transparent. With no arguments, returns a list of all the fill styles of the currently selected element, or the default fill style if nothing is selected.

border [option]

Sets the border style to the given option, which is one of the keywords solid, dashed, dotted, unbordered, "bounding box", clipmask, square, round, closed, and unclosed. The two-word "bounding box" must be quoted or in braces ({}). "bounding box" and clipmask both take an additional argument, true or false. With no option, returns a list of all border styles of the currently selected element, or the default border style if nothing is selected. With an option, sets the border style of the currently selected element, or the default border style used when creating new elements. The clipmask and "bounding box" options only apply to selected elements, and cannot be set as a default style.
Options square and round set the endcap type on drawn lines. The default is round.

Netlist

netlist option [-quiet]

Perform various netlist functions. Normally, when a netlist cannot be found or cannot be generated, an error message is returned. This can interfere with use of commands like netlist get in expression parameters to be computed on-the-fly, so the -quiet option allows the netlist command to return nothing when encountering an error. Options are:

write format [spice_end] [options]

Generate a netlist output file in one of the following formats: spice, sim, or pcb. If "spice_end" is true, then xcircuit will write a ".end" statement at the end of the file, which is also the default behavior if unspecified. false omits it, although a specific informational label in the schematic can be used to declare the end statement. Other options begin with a dash and declare how hierarchy should be handled:

-hier

This option forces a hierarchical output format

-flat

This option forces a flat output format

-pseudo

This option forces a format in which everything above the topmost level is flattened. It is used, for example, to generate a subcircuit definition in SPICE.

highlight [position|name]

Highlight connectivity of any selected network element (wire or pin), or the network at the indicated position, or the network with the indicated name.

select [position|name]

Select all elements of the indicated network (as opposed to highlighting them).

position [name]

Return the position of the first element in the indicated (named or selected) network.

make

Generates and returns a Tcl list element representing the netlist for the current circuit schematic. The list is heavily nested. The outermost list contains four elements: The string globals, a list of global networks, the string circuit, and a list of circuit netlists. These are further subdivided into hierarchical lists, a description of which is not contained here.

connect primary [secondary]

Connect pages together as representing the same schematic. One page is the primary schematic, and all others are secondary schematics. If both are given, then the schematic pages are connected together. If only one is given, then the current page is connected as a secondary schematic to the given primary schematic.

unconnect [secondary]

Disconnect a secondary schematic page (default if not specified is the current page) from its primary schematic.

autonumber

Automatically substitues indices for unnumbered circuit components.

ratsnest

This is an experimental command in which all polygons representing netlist wires are deleted and replaced with straight-line connections between named pins of the network (rats-nest representation). Rats-nest wires are displayed in a brown color. Note that this action is not undoable.

parse mode

Return the netlist output of the current page object, that is, the ASCII text of all "info labels" on the object, after all parameter and escape sequence substitutions have been made. mode indicates the subset of "info labels" to return (e.g, "spice", "sim", "pcb", and so forth). The mode should (normally) not include any ordering number (e.g., "spice1") or the following colon (e.g., "spice:"), but should include any specially-parsed characters (e.g., "spice@" and "spice-").

goto hierarchical_net_name

Go to the schematic page containing the indicated hierarchical net name. A hierarchical net name may be specified as a slash- ("/") separated list of component names and indices (e.g., "X2/X1/") or in canonical form, using the name of the symbol and the component index in parentheses (e.g., "dut(2)/opamp(1)/". The list may or may not end with a network name, which is ignored. The hierarchy of schematics and symbols is pushed on the current view stack, meaning that use of the "pop" function ("<" key) will move up the stack to the top of the hierarchy. The stack created by netlist goto replaces any existing view stack.

get [selected|here|name] [-up] [-hier] [-canon]

Return the net name of the network containing the selected or indicated element.
Option -up returns the network name relative to the level of the hierarchy above the current object. This is useful for designing trivial (non-network) symbols that report the name of the network to which they are connected.
Option -hier returns a hierarchical name (see the netlist goto option). What value is returned is dependent upon the current view and how it was arrived at using various "push" and "schematic goto" commands (">" key and "/" key macro functions). When using -hier, it is possible to use an object instance as the selected element, or no selection at all, in which case the hierarchy up to the current page is returned.
Option -canon, when used with -hier, returns "canonical" names (see netlist goto above).

schematic | symbol option

Perform various netlist functions. symbol is simply an alias for schematic. Whether the command operates on a symbol or a schematic is determined purely from context. Option option may be one of the following:

associate [name]

Associate the schematic with the symbol named name. If name is not specified, xcircuit starts an interactive method for selecting a symbol for association.

disassociate

Disassociate any existing symbol from the schematic.

make [name]

Generate a new symbol associated with the current schematic. The new symbol will be named after the page. If the current page has not been named, then option name must be provided.

goto

Change the current page to the associated symbol, if it exists

get

Return the name of the associated symbol, or {} (empty list) if no symbol is associated.

type [value]

Return the type of the current page, which may be one of the keywords schematic, symbol, trivial, or fundamental. If value is specified, change the current type to value. It is only possible to change types between symbol, trivial, and fundamental, which are all symbol classes. It is not possible to change symbols to schematics and vice versa.

spice command [options]

Send a simulation command to "ngspice" via pipe. All command options except "start" require that an ngspice process be active, which occurs when the "spice start" command is executed. Options are as follows:

start

Executes ngspice as a forked process and sets up a communication pipe between ngspice and XCircuit. The ngspice process expects to read, as its input, a SPICE deck output from the top-level page in XCircuit.

exit

Exit the ngspice process and remove the communication pipe.

run

Start an ngspice simulation in the background.

break

Suspend a running ngspice simulation.

resume

Resume an ngspice simulation if it has been suspended with the spice break command.

send command [options...]

Send an ngspice command-line command to the ngspice process. Ignore any result.

print command [options...]

This is like the "send" command, but sets the Tcl result to any output from the ngspice process.

flush

Grab any pending input in the pipe from the ngspice process, and discard it.

get

Grab any pending input in the pipe from the ngspice process, and set the Tcl result to whatever was grabbed.

status

Return the status of the ngspice process. The status returned will be one of three values: "init" if the ngspice process is nonexistant or idle, "busy" if the ngspice process is running, and "ready" if the ngspice process is waiting for input.

GUI

action action_name

Because XCircuit had its own key binding system before the Tcl-based version, it has a built-in set of "standard actions" in response to keystrokes, which depend on which mode xcircuit is in. When action is more than one word, it must be quoted. Action entries below that are marked with an asterisk ("*") expect the action name to include a number, such as "Page 1" or "Rotate 90".

Action names are case-sensitive. Valid action names are:

action name	action description	default binding
"Page" number	Go to indicated page	1 through 9, 0
"Justify" number	Text justification	KP_1 through KP_9
"Superscript"	Start text superscripting	KP_Add
"Subscript"	Start text subscripting	KP_Subtract
"Normalscript"	End text sub- or superscript	KP_Enter
"Font" number	Switch to specified font	Alt_f
"Boldfont"	Change to boldface font	Alt_b
"Italicfont"	Change to italic font	Alt_i
"Normalfont"	Change to normal font	Alt_n
"Underline"	Start text underline	Alt_u
"Overline"	Start text overline	Alt_o
"ISO Encoding"	Change to ISO-Latin1 encoding	Alt_e
"Halfspace"	Insert half-space	Alt_h
"Quarterspace"	Insert quarter-space	Alt_q
"Special"	Insert special character	\
"Tab Stop"	Define tab stop	Alt_Tab
"Tab Forward"	Tab forward	Tab
"Tab Backward"	Tab backward	Shift_Tab
"Text Return"	Finish text edit	Enter
"Text Delete"	Delete last character	Delete
"Text Right"	Move right one character	Right
"Text Left"	Move left one character	Left
"Text Up"	Move up one line	Up
"Text Down"	Move down one line	Down
"Text Home"	Move to label beginning	Home
"Text End"	Move to label end	End
"Text Split"	Break text into two labels	Alt_x
"Text Delete Param"	Remove a parameter from a label string
"Linebreak"	Insert carriage-return	Alt_Enter
"Parameter"	Insert parameter value	Alt_p
"Parameterize Point"	Parameterize the point position	p
Break at Point"	Break polygon at point	x
"Delete Point"	Delete polygon point	d, Delete
"Insert Point"	Insert polygon point	i, Insert
"Append Point"	Append point to polygon	(unbound)
"Next Point"	Go to next edit point	e
"Attach"	Attach edit point to element	A
"Next Library"	Go to next library	l
"Library Directory"	Go to library directory	L
"Library Move"	Move objects within library	M
"Library Copy"	Return to page in copy mode	c
"Library Edit"	Edit an object name	E
"Library Delete"	Delete a library object	D
"Library Duplicate"	Duplicate a library object	C
"Library Hide"	Hide a library object	H
"Library Pop"	Return from library	>
"Library Virtual Copy"	Create a virtual instance of a library object	V
"Page Directory"	Go to page directory	P
"Virtual Copy"	Create a virtual instance from an object selected on a page	V
"Help"	Generate help window	h, ?
"Redraw"	Redraw the drawing window	Space
"View"	Center the current drawing	v
"Zoom In"	Enlarge the view	Z
"Zoom Out"	Shrink the view	z
"Pan"	Move window center to cursor position	p
"Double Snap"	Double the snap spacing	+
"Halve Snap"	Halve the snap spacing	-
"Write"	Pop up output properties window	W
"Rotate" number	Rotate element	r, R, o, O
"Flip X"	Flip element horizontal	f
"Flip Y"	Flip element vertical	F
"Snap"	Snap element to snap grid	S
"Snap To"	Turn snapping on or off
"Pop"	Return from current edit	<
"Push"	Edit object	>
"Delete"	Delete element	Delete
"Select"	Select element	Button2
"Box"	Generate box	b
"Arc"	Generate arc	a
"Text"	Generate label	t
"Exchange"	Exchange order of elements	X
"Copy"	Make copy of an element	c
"Move"	Move an element	m
"Join"	Join elements into a path	j
"Unjoin"	Separate path into elements	J
"Spline"	Generate a Bezier curve	s
"Edit"	Edit an element	e
"Undo"	Undo last action	u
"Redo"	Redo last action	U
"Select Save"	Create new library object	M, m
"Unselect"	Unselect an element	x
"Dashed"	Change border to dashed style	|
"Dotted"	Change border to dotted style	:
"Solid"	Change border to solid style	_
"Prompt"	Prompt for interpreter command	(unbound)
"Dot"	Create a "solder dot"	.
"Wire"	Start a wire (polygon)	w, Button1
"Cancel"	Cancel command (general)	Button3
"Nothing"	Null command (general)	Button3
"Exit"	Quit XCircuit	Control_Alt_q
"Netlist"	Generate TCL netlist	Alt_q
"Swap"	Move schematic <--> symbol	/
"Pin Label"	Generate local "Pin" label	T
"Pin Global"	Generate global "Pin" label	G
"Info Label"	Generate "Info" label	I
"Graphic"	Load a graphic (PPM) image
"Rescale"	Change the scale of a scalable element
"Select Box"	Generate a selection box	Hold_Button2
"Connectivity"	See network connectivity	Alt_w
"Continue Copy"	Place elements and continue copy	Button1
"Continue Element"	Behavior depends on element type	Button1
"Finish Copy"	Place elements and end copy	Button2, Shift_Button1
"Finish Element"	End element generation	Button3
"Finish"	General-purpose, depends on ongoing action	Button2, Shift_Button1
"Cancel Last"	Cancel one part of a multi-part edit	Button3
"Sim"	Generate "sim" format output
"SPICE"	Generate "SPICE" format output
"PCB"	Generate "PCB" format output
"SPICE flat"	Generate flattened "SPICE" format output

Those actions indicated with "number" take a parameter as part of the action name; e.g., "Page 1" and "Page 2" are two different bindings, as is "Rotate 15" (rotate clockwise 15 degrees) and "Rotate -15" (rotate counterclockwise 15 degrees).

standardaction key|button down|up|key state

Standard actions for key and button responses. Standard actions may be redefined using either the "bindkey" command (see below), or the Tk "bind" command, to bind keys to Tcl procedures. The parameters key, button, and state are generally passed from Tk by the escape sequences %k, %b, and %s, respectively. For example, the standard action binding for keys (defined in wrapper.tcl) is:

bind .xcircuit.mainframe.mainarea.drawing <KeyPress> {standardaction %k key %s}

bindkey [-compatible] key [action]

This command associates a key, button, key-modifier combination, or button-modifier combination to a specific action. action is one of the known actions as listed above. Argument key generally follows the convention used in /usr/include/X11/keysymdefs.h, except for the following:

• Modifiers are allowed. Valid modifiers are "Shift_", "Alt_", "Control_", "Hold_", "Meta_", and "Capslock_".
• Modifiers may be used in combination.
• The "XK_" prefix is optional.
• "Shift_" is not used in conjunction with ASCII characters, unless in combination with other modifiers. e.g., "A" is used instead of "Shift_a", but "Control_Shift_q" is used instead of "Control_Q".
• Mouse buttons may be indicated as "Button1", "Button2", and "Button3", respectively. Modifiers can be added to buttons.

If action is not specified, then all actions associated with the indicated key are listed. If the option "-compatible" is given, then only the actions binding that is compatible with the current state (see eventmode, below) is printed.

Note that this method and syntax is entirely different from the Tk bind command. However, from XCircuit version 3.1.20, all button and key actions are interpreted by the Tk binding method, which by default calls "standardaction" (see above) for all button and key presses and button releases. The Tk bind command may be used to override this default action for specific keys and buttons, and bind them to Tcl procedures. The proper way to bind keys to Tcl procedures is to use keybind (see below).

eventmode

Diagnostic: prints a text version of the mode xcircuit thinks it's in. This is used by the procedure keyaction to determine if the user is calling a key macro or typing text into a label. It may also be used to determine if the user is viewing the catalog, or editing an element, etc.

refresh

Redraws the current window. Automatically substitues indices for unnumbered circuit components.

zoom

Same as zoom view (see below).

zoom option

Perform a zoom operation on the window. Option option may be one of the following:

in [amount]

Zoom in by current zoom factor or by [amount].

out [amount]

Zoom out by current zoom factor or by [amount].

box

prompt for zoom box. Zoom occurs as soon as box is drawn and the mouse button is released.

view

Fits the drawing to the xcircuit window.

factor

Returns the current zoom factor.

factor amount

Sets the current zoom factor to amount. amount is a floating-point number representing a scale multiplier. Values greater than 1.0 imply a zoom "in", while values less than one imply a zoom "out". Zero or negative values not allowed.

pan [option|position]

Pan the image in the window. option may be one of the following keywords:

center

The drawing window is centered on the cursor position.

here

This is the same as "pan center" except that the cursor is warped to the screen center in addition to moving the image in the drawing window.

follow

Make the window view follow the cursor.

left|right|up| down [fraction]

Move the window view in the indicated direction, by an amount equal to fraction times the width or height of the current view. If fraction is not given, the default fraction is 0.3.

Otherwise, position is a list of size 2 with X and Y values, and the drawing window is centered on this position. Note that pan does not refresh the view by default.

quit

Quit xcircuit, with a prompt if any files with outstanding changes have not been saved.

promptsavepage [page_number]

Start the page output dialog. Currently, page_number, if present, must be the current page number.

here

Returns a list size two with the X and Y position of the cursor relative to the XCircuit coordinate system.

cursor name

Set the XCircuit cursor to be one of the known cursor glyphs, by name. Known glyph names are: "arrow", "cross", "scissors", "copy", "rotate", "edit", "text", "circle", "question", "wait", and "hand".

Files

loadfont fontname

Loads an xcircuit font. Expects to see file fontname.xfe (Xcircuit Font Encoding) in the default system library path. Note that the special case "loadfont override" can be placed at the top of the user's .xcircuitrc file to prevent the xcircuit startup script from loading its default set of fonts. However, as of version 3.3.33, it is preferred to use the Tcl command "set XCops(fontoverride)" to do the equivalent thing.

filerecover

Recovers files from a crash or Ctrl-C exit that are left in the /tmp directory.

General

quitnocheck

Immediate exit from xcircuit

start args

XCircuit startup. Usually called internally from the wrapper script. However, for purposes of debugging problems, it can be called manually from the Tcl command after loading the shared object file xcircuit.so.

simple pathname

This is a Tk extension which generates a "simple" window, a blank area into which a C-source application is supposed to draw.

tag name [procedure]

Attach a procedure to a command, such that the procedure is executed after every call to the command name. The procedure may name a Tcl procedure or it may be entirely inline. procedure may make use of several inline substitutions, as follows:

%0 through %5

Substitute the argument passed to name.

%N

Substitute all arguments, concatenated into a list.

%#

Substitute the number of arguments passed to the command.

%W

Substitute the Tk window name of the window from which the command originated.

%r

Substitute the Tcl result from name. The result is transparent; any result produced by the tag procedure will be ignored and the calling function will get back the original result (%r).

%R

Substitute the Tcl result from name. The result is absorbed, and the tag function generates a new result which is passed back to the calling function.

%%

Substitute a single percent character.

All other uses of the percent character within the tag procedure will be evaluated as-is. With only one argument, name, the tag command will return the procedure currently attached to that command. Tagging a procedure to a command which is already tagged will cause the new tag procedure to overwrite the old one. Any tag procedure which calls the function to which it is tagged should wrap the entire procedure inside

if {[info level] >= 1} {Tcl procedure}

to prevent infinite recursion.

Scripted commands (Tcl source)

Namespace (Toolscript)

pushnamespace namespace

Makes all commands in namespace available in the current namespace. Conflicting commands names are not pushed.

popnamespace namespace

Revert command names back to original set.

Dialogs

promptobjectsize

Dialog to ask for object size

promptborderwidth

Dialog to ask for element border width

promptlinewidth

Dialog to ask for overall linewidth scaling

promptgridspace

Dialog to ask for grid spacing

promptdrawingscale

Dialog to ask for drawing scale

promptsnapspace

Dialog to ask for snap spacing

promptmakeobject

Dialog to ask for object name before making new library entry

promptsavelib library_number|library_name

Dialog to ask for filename of library to save.

promptloadlibrary

Dialog to ask for filename of library to load

promptaddlibrary

Dialog to ask for filename of library to add to current library page

promptloadfile

Dialog to ask for filename of xcircuit file to load

promptimportfile

Dialog to ask for filename of xcircuit file to add to current page

promptimportbackground

Dialog to ask for filename of PostScript file to use as background

promptexecscript

Dialog to ask for filename of Tcl file to execute

prompttextsize

Dialog to ask for label scaling

promptnewfont

Dialog to ask for name of font to load

promptkern

Dialog to ask for X Y kerning values inside a label

promptmakesymbol

Dialog to ask for a name for a page, if the page has not yet been named, before generating a matching symbol of the same name.

Menu manipulation

These functions should only be called from inside xcircuit, as they change only the menu appearance and callbacks and not xcircuit's internal data structures.

newcolorbutton r g b idx

Adds a new button to the color menu r g and b are color components, and idx is the position in xcircuit's color table.

newencodingbutton encodingname

Adds a new button to the font encoding menu. Valid encoding names are special, standard, and ISO-Latin1 through ISO-Latin6.

newfontbutton familyname

Adds a new button to the font family menu.

newlibrarybutton libraryname

Adds a new button to the library menu with a callback to switch to the indicated library.

newpagebutton pagename

Adds a new button to the page menu with a callback to switch to the indicated page.

renamelib number libraryname

Changes the name and callback function of the indicated library menu button. number is the index position of the button in the library menu.

renamepage number pagename

Changes the name and callback function of the indicated page menu button number is the index position of the button in the page menu.

xschema true|false

Turns the netlisting functions on or off.

toolbar true|false

Turns the toolbar functions on or off.

Command tag callbacks:

These functions are attached to specific xcircuit commands using the "tag" command, and execute after the tagged command has executed. This keeps the GUI synchronized with commands called from the command-line.

pageupdate [subcommand]

Updates the file output window to match the current page status. subcommand is the first argument passed to the command and defaults to none. This command should be tagged to the page command.

setsymschem

Updates the schematic and symbol buttons, and the netlist menu options, to match the current page. This command is called internally, so it is implicitly tagged to commands such as schematic and page.

Key binding:

This function aid in binding keys to Tcl procedures.

keybind keyname procedure

Binds or rebinds the key keyname to the Tcl procedure procedure. The keybind script ensures that keystrokes are captured by XCircuit when typing text into labels (direct use of the Tk "bind" function is discouraged).

Tcl Script Examples

panzoom.tcl

This script (provided by Ed Casas, along with the keybind script) changes the behavior of the zoom keys "z" and "Z" such that the resulting image is centered on the position of the cursor at the time of the keypress. Note that with the "keybind" function (see above), the whole panzoom script is simply the two procedure calls

keybind Z { pan here ; zoom in }
keybind z { pan here ; zoom out }

Also see the GUI generator script wrapper.tcl and the startup script xcircuit.tcl.

References

For more information about Tcl, see http://www.tcl.tk.

Back to the xcircuit home page. . .

email:

Last updated: October 24, 2018 at 9:01pm