XCircuit Reference Manual

Table of Contents

XCircuit Keyboard, Toolbar, and Menu Commands
XCircuit files
Tcl Extended Interpreter Reference
Python Embedded Interpreter Reference
XCircuit PostScript Reference

Syntax

Comments about notation: Keyboard single-key macros for commands, if available, are listed in parentheses after the command name. Menu buttons, if available, follow in italics. The menu button is given as a list of submenu names to traverse separated by arrows ("->"); multiple choices are denoted by separating the choices by a vertical bar ("|").

The XCircuit Toolbar

The toolbar is a column full of icon buttons that is on the right-hand side of the window. Each button performs a simple function. The topmost buttons define various modes of operation in which the mouse buttons are bound to different functions. When a specific set of mouse button bindings is in effect, the corresponding tool button is highlighted with a heavy boundary, accented in green. The buttons in the middle are "tool/action" buttons. These can either act like the tool buttons described above, or as actions. An action happens when one or more elements in the drawing is selected when the toolbar button is pressed. The corresponding action happens for only those selected items, and mouse button bindings are modified only for the duration of that action. Any tool that was in effect prior to the action remains in effect after completion of the action. The buttons at the bottom are action-only buttons. They do not have corresponding mouse button bindings. They perform a single action, such as zooming in or out, popping up a window, or generating a pulldown menu. Each toolbar button is described below:
Pan tool
This tool makes the left mouse button act as a window panner. Tapping the left mouse button grabs the window and moves it with mouse motion. The middle mouse button ends the pan, and the right mouse button cancels it and returns to the original view.
Wire tool
This is the "traditional" XCircuit tool, and was the only set of mouse button bindings before the "tool" concept was added. The left mouse button starts a wire or adds another segment to a wire. The middle mouse button finishes the wire. The right mouse button cancels and removes the last wire segment. The escape key cancels and removes the entire wire, equivalent to pressing the right mouse button until there are no segments remaining.
Box tool
In this tool mode, tap the left mouse button to start a box. Press either the left or middle mouse button to finish the box. The right mouse button cancels and removes the box.
Arc tool
In this tool mode, tap the left mouse button to start a circle. Tapping the left mouse button again cycles through editing the circle diameter, start angle, end angle, and minor axis diameter. The middle mouse button finishes the circle/arc/ellipse. The right mouse button cancels the last edit operation. The escape key cancels and removes the arc, equivalent to pressing the right mouse button until no more edit operations are left to undo.
Spline tool
In this tool mode, tap the left mouse button to start a circle. Tapping the left mouse button again cycles through editing the circle diameter, start angle, end angle, and minor axis diameter. The middle mouse button finishes the circle/arc/ellipse. The right mouse button cancels the last edit operation. The escape key cancels and removes the arc, equivalent to pressing the right mouse button until no more edit operations remain to undo.
Text tool
In this tool mode, tap the left mouse button to start a label. Tap the left or middle mouse button to finish the label, and the right mouse button to cancel it. The type of label created is determined by the menu items Netlist-->Make Pin, Netlist-->Make Info Pin, Netlist-->Make Global Pin, and Text-->Make Label. When any of these menu options is chosen, the color of the letter "A" inside the icon changes to reflect the type of label being created: Black for normal labels, Red for pin labels, Gold for global pins, and Green for info labels.
Move tool/action
When no elements are selected, this button acts as a tool. The left mouse button selects the nearest object and starts to move it. Pressing the left or middle button completes the move, and the right mouse button cancels it. If one or more elements is selected, this button performs a move "action". The selected elements are immediately picked up and follow the pointer until placed with another left button or middle button click.
Copy tool/action
When no elements are selected, this button acts as a tool. The left mouse button selects the nearest object, creates a highlighted copy of it, and starts a move action. Pressing the left mouse button places the copied element, generates a new copy, and continues the move action. The middle mouse button completes the move and does not generate any more copies. The right mouse button cancels the last copy-and-move action, and the escape key cancels and removes all copies made. If one or more elements is selected when the toolbar button is pressed, this button performs a copy "action". The selected elements are immediately copied, highlighted, and follow the pointer until placed according to the button bindings described above.
Edit tool/action
When no elements are selected, this button acts as a tool. The left mouse button selects the nearest object and starts to edit it. Pressing the left button continues the edit by moving to the next editable point, depending on whether the element is a polygon, arc, curve, path, or label. The middle mouse button accepts and completes the edit. The right mouse button cancels the last edit operation on the element, and the escape key cancels all edit operations made on the element. If a single element is selected when the toolbar button is pushed, this button performs an edit "action". The selected element is edited according to the mouse button bindings described above. Currently, there is no method for editing multiple elements at the same time.
Delete tool/action
When no elements are selected, this button acts as a tool. The left mouse button selects the nearest object and deletes it. Pressing the middle button selects additional elements, all of which will be deleted on the next left mouse button press, and the right mouse button unselects all selected elements. If one or more elements is selected when the toolbar button is pressed, this button performs a delete "action". The selected elements are immediately deleted.
Rotate clockwise tool/action
When no elements are selected, this button acts as a tool. The left mouse button selects the nearest object and rotates it. Pressing the middle button selects additional elements, all of which will be rotated on the next left mouse button press, and the right mouse button unselects all selected elements. All groups of elements and most single elements are rotated about the cursor position. Single object instances, labels, and arcs, however, are rotated about their own points of origin. Unlike the "r" and "o" key bindings, which are specifically bound to rotation amounts of 30 and 5 degrees, respectively, the rotate tool rotates by the amount selected from the menu Edit-->Rotate/Flip-->Rotate CW. Note that rotation by increments by amounts less than 90 degrees may cause elements to get "off grid", which can make three rotations by 30 degrees not equivalent to a single rotation by 90 degrees. To keep objects on-grid through rotations, select Edit-->Rotate/Flip-->Rotate CW 90 from the menu and use the rotate tool/action button.
Rotate counterclockwise tool/action
This tool/action button behaves exactly like the clockwise rotate button (see above), except that rotations are in the counterclockwise direction, and rotation increment amounts are selected from the menu Edit-->Rotate/Flip-->Rotate CCW.
Flip horizontal tool/action
When no elements are selected, this button acts as a tool. The left mouse button selects the nearest object and flips it horizontally. Pressing the middle button selects additional elements, all of which will be flipped on the next left mouse button press, and the right mouse button unselects all selected elements. Flips of multiple elements and most single elements are made across an imaginary vertical line running through the cursor x position. Single object instances, labels, and arcs are flipped across the axis of their own origin. Note in particular that if an object instance is rotated by 90 degrees, the flip may appear to be a vertical flip, since it is relative to the object's coordinate system. If one or more elements is selected when the toolbar button is pressed, this button performs a flip "action". The selected elements are immediately flipped according to the rules outlined above.
Flip vertical tool/action
This tool/action button behaves exactly like the horizontal flip button, except that objects are flipped vertically across an imaginary horizontal line that is either through the cursor's y position or through the (single) element's origin.
Scale tool/action
This tool/action button changes the scale of selected elements (text, object instance, and in-line graphics). When used as a tool, click on the element to get a scale outline box to modify the scale interactively. The scale box may appear to be on a coarse snap grid due to the implementation of the scale algorithm. Reduce the snap space to get better resolution of the element scale. When used as an action on a selected element, a pop-up window will be generated, prompting for the element scale. This can be used to enter specific scales for items in mechanical or otherwise strictly scaled drawings.
Push (descend) tool/action
When no elements are selected, this button acts as a tool. The left mouse button selects the nearest object instance and descends into its object for editing. The middle mouse button will select multiple elements, but note that no more than one element can be selected when performing a "push".
Pop (return) action
This button performs a single action, returning to the level of hierarchy above the object being edited. If the object being edited was not reached via a "push" action, then no action is performed.
Make tool/action
When no elements are selected, this button acts as a tool. The left mouse button selects the nearest object and opens the "Make Object" dialog window. Pressing the middle button selects additional elements, all of which will be added to the new object on the next left mouse button press. The right mouse button unselects all selected elements. If one or more elements is selected when the toolbar button is pressed, this button generates the "Make Object" dialog. After completion of the dialog entry, the tool reverts back to the tool that was in effect prior to the action.
Join tool/action
When no elements are selected, this button acts as a tool. Pressing the middle button selects elements. The left mouse button adds the nearest element (if there is one) to the set of selections, then attempts to join all of the elements into a single polygon or path. The right mouse button unselects all selected elements. If more than one element is selected when the toolbar button is pressed, this button performs a join "action". The selected elements are immediately joined, if it is possible to do so, or else an error message is generated.
Unjoin tool/action
When no elements are selected, this button acts as a tool. The left mouse button selects the nearest path and breaks it into its separate components. Pressing the middle button selects additional paths, all of which will be disassembled on the next left mouse button press. The right mouse button unselects all selected elements. If one or more elements is selected when the toolbar button is pressed, this button performs an immediate "unjoin" action. "unjoin" has no effect on elements other than paths, and no message is generated.
Color menu
This button brings up the following menu, which is simply a conveniently located copy of the menu at Options-->Elements-->Color:
This menu can be used to select the currently active foreground color for new elements, or to add a new color to the list.
Line/Border menu
This button brings up the following menu, which is simply a conveniently located copy of the menu at Options-->Elements-->Border:
The border menu sets the line style for lines and polygon, spline, arc, or path borders. The "Square Endcaps" options allows control (individually, for each element) over whether XCircuit terminates line segments with rounded or square endcaps. The "Manhattan Draw" and "Manhattan Edit" options force wires and polygon line segments to stay in horizontal or vertical alignment, when creating wires or editing existing wires and polygons, respectively. The "Bounding Box" option makes the selected item (restricted to one polygon only) a bounding box, which will force the bounding area used when generating the output page (can be used to prevent the drawing from being centered on the output page, for example). The "Clipmask" option will make a selected element into a clipping mask, in which the element directly above it in the stacking order will be clipped to the boundary of the clipping element, showing only that part that intersects. Neither the clipmask or bounding box items can be selected as global options; they apply only to selected elements.
Fill menu
This button brings up the following menu, which is simply a conveniently located copy of the menu at Options-->Elements-->Fill:
The fill menu allows filled polygons to have stippled fills, giving them a sort of fake transparency. It is generally recommended not to use the transparent stipples unless necessary, as they tend to be compute-intensive when rendering and device-dependent (depending on the output device resolution).
Parameter menu
This button brings up the following menu, which is simply a conveniently located copy of the menu at Options-->Elements-->Parameters:
These are the numeric parameters. When they are selected for a specific element, when that element is part of a library object, that element's properties become instance-dependent. It has no obvious effect on elements on a top-level page. An example of numeric parameters can be seen on the analog elements page, where they are used to counter-rotate, reposition, and rejustify all the text in the rotated version of each component.
Parameter window
This button brings up the following window:
This window shows each key:value pair belonging to an object instance. It tracks selected object instances, displaying the parameters of their objects and the values of each of those parameters for the specific instance. When editing a page or object, with nothing selected, the display is the parameters of the page or object itself, and the values are the default values that are independent of any instance. To change a parameter value, click on the parameter value in the "Value" column. To insert a parameter into a label, click on the parameter key in the "Key" column.
Library
This button switches the current view to the currently active library page. If already on a library page, the button switches the view to the next library page. It is equivalent to typing the "l" key.
Library directory
This button switches to the library directory, showing all of the library pages at once. It is equivalent to typing the "L" key.
Page directory
This button switches to the page directory, showing all of the schematic pages at once. It is equivalent to typing the "P" key.
Zoom in
This button zooms in on the current view. It is equivalent to typing the "Z" key
Zoom out
This button zooms out on the current view. It is equivalent to typing the "z" key
Info window
This button brings up the following window:
This helper window gives basic information about the active key bindings and the functions they invoke.

Element construction and manipulation

Creating new elements

Element creation functions which are available from the toolbar are described in the section on the toolbar, above. The tools all map the "start" function for the element to the left mouse button. However, regardless of the tool, every element can also be generated from both a menu button selection in the main menu, that sets the tool and is equivalent to pressing one of the toolbar buttons, and with a key macro that substitutes for the left mouse button, but works in any tool mode. In the list below, each element creation function name is followed by a key binding, in parentheses, and optionally by the (text) path to a menu button, in italics.

There is a helper function for remembering the different button bindings for starting, completing, and canceling each element type. By clicking on the light blue button at the bottom of the window, which displays the name of the currently active toolbar tool, you will get a window that replaces the usual message window and instead displays the button bindings for each mouse button.

Creating and Editing text

Info Label Syntax for Netlists

Info labels tell XCircuit how to generate a netlist. They exist inside symbols or schematics. When XCircuit traverses the schematic hierarchy and finds a symbol containing an info label, it parses the info label, and dumps the result to the netlist file (or a structure, in the case of PCB netlists, which is in turn parsed to create the netlist). When XCircuit finds a schematic containing an info label, it parses the info label, and dumps the result along with the netlist information. The position of parsed info labels relative to the netlist information can be controlled.

Each info label is of the form:

net_type[prefix][index]:content
The net_type can be "spice", "sim", or "pcb". The index is optional. If not specified, then lines with the same net_type will be parsed and dumped to the netlist in the order they are encountered. To ensure a specific order, each line can be indexed with a number giving its relative order. In addition, the number may be preceded by a prefix, which may be one of the characters "@" or "-". Info labels with the prefix "@" are parsed prior to any netlist output for the subcircuit, including the subcircuit call. It is appropriate to use, for example, for include files that contain device subcircuit definitions for a specific process. Info labels with the prefix "-" are parsed within the subcircuit definition but after all netlist information has been written. If no prefix is given, then the line is parsed within the subcircuit definition but before any netlist information has been written.

The content text may contain any plain text in the XCircuit label format, including embedded parameters and other escapes. Parameters are substituted with their appropriate value when parsing the line. Most other text escapes are ignored, except for the following exceptions:

overline
Overlines are converted to a "!" character, which is a widely-accepted character meaning "logical NOT".
font
Most font changes are ignored. However, the symbol font character Greek "mu" as well as the ISO-Latin1 character "mu" are both checked and converted to "u" in the netlist output.
Naturally, the primary actions needed to be performed when parsing an info label are: Component parameters are either plain text if they don't change on a per-instance bases, or XCircuit parameters, if they are. Parameters can be inserted into the text by clicking on the appropriate parameter key in the parameters window ( in the toolbar). All other special actions are provided by "%" character escapes, as follows:
%ppin_name
Write the name of the network connected to pin pin_name to the output. The pin_name is normally the (ASCII text) name of the pin, but if the pin name is a parameterized string, it can also be given as the parameter value. If pin_name contains spaces, it should be put in quotes. There is no space between the "%p" and the pin name.
%i (deprecated)
Write the component index. There is no way to specify a component index using this method, which is why it is preferred to use a parameter to indicate the component index.
%n
Write the name of the symbol, without any technology prefix
%N
Write the fully-qualified name of the symbol, including the technology prefix.
%x
Write the X position of the symbol in the schematic.
%y
Write the Y position of the symbol in the schematic.
%Ffilename
Dump the contents of the file filename to the netlist output. Remember the name of the file. If the file is requested more than once, the requests are ignored.
%ffilename
Dump the contents of the file filename to the netlist output. The contents will be written every single time the line is encountered (thus, if the intention is to include SPICE model statements, for example, the %F escape is the correct one to use).
%vkey (deprecated)
Write the value of the parameter whose key is key. Normally, one would simply embed the parameter directly rather than include it by reference with the "%v" escape.
%r
Write a carriage return to the output. Note that an embedded carriage return (key Alt-Return) is also written to the output as a carriage return.
%t
Write a tab to the output. This is a standard ASCII tab character, and not to be confused with embedded tabs in XCircuit labels, which cannot be directly translated into ASCII.
%%
Write the ASCII character '%' to the output.
The component index should be specified using the special parameter name "index" with the special default value "?". XCircuit uses this information to automatically generate component index values. XCircuit uses base-36 encoding to handle component indexes. Base-36 encoding allows both alphabet characters and numbers, which is appropiate for legal SPICE names following a device type. When auto-numbering components, only decimal base numbers will be used. However, the base-36 parsing means that an index can be forcibly set to a non-numeric value (like "test1") without disturbing XCircuit's automatic generation of numeric component indices. Finally, there is a special syntax to lines for which the net_type is "pcb". Due to the special nature of the PCB netlist syntax, which ennumerates nets one at a time, and lists the component connections of each, XCircuit uses the info label line to determine the component name. PCB format lines use the syntax:
pcb[prefix][index]:{class}{index} [pin=net] ...
The "{class}" is some fixed class name like "C" for capacitors or "U" for integrated circuit chips. The "{index}" is the component index (as described above). Then optionally, there may be a space followed by pairs of pin names and net names. These are used to tell XCircuit what to do with pins that do not show up in the symbol. In the non-PCB info label types, a pin that does not appear in the symbol can simply be added to the info label as plain text. Since PCB netlists traverse the structure looking for pins, pins that are not explicitly drawn on the symbol must be recognized some other way. Normally, one would use this method to indicate connections of global pins like power and ground that one may not want to draw directly on the symbol in the schematic, to avoid unnecessary clutter. See the "quadparts" library in the XCircuit distribution for an example of this syntax.

Element editing

Unless otherwise stated, all of the commands below have the following behavior which depends on the way they are called:
Menu button/Toolbar button: The toolbar button, as described above, sets XCircuit into a specific mode in which the mouse buttons are bound to actions that related to the tool function. The menu button of the same name as the tool simply invokes the toolbar button. For toolbar buttons of the type "tool/action" (see description of toolbar buttons above), if elements are already selected when the button is pushed, or the menu button is selected, they will also be acted upon immediately by the function. The mouse right button will generally cancel the function, although similar but distinct functions are performed by the right mouse button, the escape key, and the "undo" command ("u" key).
Keyboard macro: If an element or elements are already selected, the macro will act upon them. Otherwise, the program will look for any elements close to or underneath the cursor, select them, and perform the function upon them. If no appropriate element is found near the cursor, then the command is ignored.

Editing arcs, polygons, and curves

Library creation and editing

An explanation of the difference between library pages, library files, and technologies

A fairly obvious source of confusion in XCircuit is the definition of libraries. It is important to understand the difference between library pages, library files, and technologies. These are defined as follows:
Library page
When XCircuit starts up, and you type "L", what you see is the set of library pages that have been loaded. XCircuit may have many library objects, and placing them in groups on pages is a good way to organize them and make specific objects easier to find.
Technology
Each library object has a name that is a concatenation of a technology prefix, a double colon ("::"), and the object name. The whole form, known as the "fully qualified name", must be unique, but objects in different technologies may have the same name. The prefix tells XCircuit which library file the object came from, even if the file has been split up among different pages, or if a page contains objects from more than one library file.
Library file
Objects are defined in library files, with the .lps extension (for "library postscript"; in other words, a postscript file containing only definitions, which will be acceptable as input to any postscript interpreter, but which will not produce any display or printout). Each library file defines, at the top, a technology name. It is legal for the file to contain objects from other technologies only if those objects are used by (contained in) objects belonging to the technology defined by the library file.

XCircuit saves library files by collecting together all objects belonging to a single technology, plus any dependent objects from other technologies, and writing them all to a single file. This is what happens when the menu option File-->Save Technology is selected. It is possible, but not wise, to have two library files with the same technology name but containing different sets of objects. It can be done for read-only files, but XCircuit will not be able to tell which object came from which library file, and so will not be able to write back the files as they were originally composed.

The Library Manager

The library manager is the best way to handle loading different technology files (or portions thereof), when adding new components or library pages needs to be done "on the fly". If libraries need to be loaded every time XCircuit starts up (such as for a project), this should be done by placing the appropriate command-line commands in the startup file. The library manager is divided into two halves. The left half concerns technology files, and the right half concerns library pages. The list "Search Directories" shows all of the directories that XCircuit will search when looking for available technology (.lps) files. By default, this list includes the installation directory where technology files included with the distribution are placed, and the current working directory. More directories can be added to this list either by clicking on the "Add Directory" button, or by changing the search path using the "config search" command (note that changes to the search directory list using config search are not immediately reflected in the library manager).

Clicking on the box below the title "Source Technology File" produces a list of all library files found in the search path. If you select one of these, a list of objects defined in that library will appear in the object list on the right side of the library manager. By default, only objects that have not yet been loaded into XCircuit are shown. If you want to see all objects, including those that have already been loaded, check the "Show Loaded" box on the bottom right corner of the library manager window.

Choose the target library page where new objects should go by clicking on the box below the title "Target Library Page". If you want objects to be put on a new page, then you should first select the button "Add New Library Page", and enter a name for the new library page at the prompt.

After all the unloaded objects in the library are shown, you have the option of selecting specific objects you need from the library, or load everything at once. You can select single or multiple items in the list. Click with the left mouse button to select single items, Shift+left mouse button to select a connected range of items, or Control+left mouse button to select any number of unconnected items. The "Load Selected" button then loads these objects onto the chosen target library page. Each library contains a dependency list, so if a selected object is imported that contains an instance of another object that is not selected, that object will also be loaded. The "Load All" button simply executes the "library load" command with the appropriate options for the chosen technology file and target library page. All objects are loaded regardless of whether or not they are selected in the library manager list.

Note that selecting all objects and pressing "Load Selected" differs from pressing "Load All" in that the former loads objects in the order that they are displayed in the "Objects" list (which is arranged alphabetically), whereas the latter loads objects in the order they appear in the technology file.

Library Manipulation Commandline Commands

Parameter Creation and Manipulation

General-purpose parameter types known to XCircuit:
substring
The substring parameter is a text label just like other text labels in XCircuit, except that it does not require the initial font designation that normal labels do. It can be embedded inside a text label, or used alone. When used alone, it is typically interpreted as a simple character string.
numeric
A numeric parameter represents a number, which can be either floating-point or integer. XCircuit handles these two cases separately, but this handling should be transparent to the end-user. Numeric parameters can be embedded in strings (in which case they are promoted to a string representation of the number), or used in expressions.
expression
In the non-Tcl version of XCircuit, expression parameters are just a simple character string, otherwise acting much like a substring parameter. In the Tcl version of XCircuit, the expression parameter is a Tcl statement or procedure. If the expression parameter is embedded in a text label, the (string) result of the Tcl statement gets displayed.
Specific-purpose parameter types known to XCircuit (in the below, "n" may be absent, or may any integer 2 or higher):
p_xpsn
X-position
p_ypsn
Y-position
p_styn
Style
p_jstn
Justification (labels only)
p_an1n
Angle1 (start angle on an arc)
p_an2n
Angle2 (end angle on an arc)
p_radn
Radius (radius of an arc)
p_axsn
Y-Axis (minor axis radius of an arc)
p_rotn
Rotation
p_scln
Scale
p_widn
Linewidth
p_coln
Color
These parameter keys are used to hold parameterized values of elements in an object instance. These keys should not be used for other purposes, to avoid conflicts. The parameters are always defined in an object instance, but they refer to the properties of individual elements inside the object, which then take different per-instance values according to the value of the parameter.

The above parameter types are also referred to as "numeric parameters" because they are plugged directly into an element's structure and must be a valid number (sometimes floating-point, such as scale and linewidth, otherwise integer). However, they can also be Tcl expression parameters, provided that the expression results in a valid number. This can be accomplished by selected the element to be parameterized and executing a command from the command line such as the following:

paramter make rotation {expr 0}
The above example prevents the element from being rotated, since its rotation is fixed and set to zero. The Tcl "expr" command is the best way to return a numeric value. However, any statement that results in a valid number is acceptable, such as
paramter make rotation {lindex {0 1 2 3} 0}
which does the same thing as the previous statement, albeit in an awkward manner. However, there is a use for the form above. XCircuit understands this specific form to indicate a choice of values. The Tcl list is the set of choices, and the index at the end is the default choice. When one selects the value of this parameter from the popup parameter window, instead of the usual text entry line, XCircuit will present a menu of the choices. This form is useful any time a parameter has a known, finite set of values which it may take.

One can place references to parameters inside expression parameters, although it is clearly an error for a parameter to attempt to refer to itself. A parameter reference may be made by evaluating the Tcl statement "parameter get". However, this statement is ambiguous because the result depends on any active elements selected, and the level of the hierarchy. An unambiguous form is available using the "%" character escape. A number of escape sequences are understood, as follows:

%parameter_key
Any valid parameter name can be used. The escape sequence will be substituted with the value of the parameter prior to passing the expression to Tcl interpreter for evaluation. This is similar to inserting the statement "parameter get parameter_key" but is unambiguous.
%p_rotation
The rotation of the instance is inserted into the expression. This is useful, for example, to make text that counter-rotates as the instance is rotated, making it rotationally invariant.
%p_scale
The scale of the instance is inserted into the expression.
%p_xposition
The X coordinate of the instance is inserted into the expression.
%p_yposition
The Y coordinate of the instance is inserted into the expression.
%p_color
The color index of the instance is inserted into the expression.
%p_top_rotation
The rotation of the instance relative to the top level of the schematic is inserted into the expression. This can be used to make some element (e.g., text) in the object have fixed orientation relative to the page, regardless of the hierarchy.
%p_top_scale
The scale of the instance relative to the top level of the schematic is inserted into the expression. This can be used to generate scale-invariant elements.
%p_top_xposition
The X coordinate of the instance relative to the top level of the schematic is inserted into the expression. This can be used to create position-invariant elements.
%p_top_yposition
The Y coordinate of the instance relative to the top level of the schematic is inserted into the expression. This can be used to create position-invariant elements.
When coupled with "%" embedded character escapes, the "lindex" choice provides a way to create a set of parameters conditionally dependent upon the value of a "master" parameter. For example:
parameter make expression rval {lindex {0 90 180 270} 0}
(select a rotatable element (object instance, label, graphic image))
parameter make rotation {lindex {0 1 2 3} %rval}
The above expression forces the selected element to take on only the specific rotations listed (multiples of 90 degrees), and the rotation can only be set by adjusting the master parameter "rval", and not by rotating the element using the "r" key or rotate toolbar tool.

Another special parameter form is used for parameterizing color. After a fashion, colors in XCircuit are treated like parameters even without setting an explicit parameter for color value, since colors in XCircuit use a model of inheritance from a parent instance with individual per-element exceptions. By declaring a parameter for color value, one can restrict the number of colors available to an element, or force the element to change color in response to the change in another parameter. For example, to make a square that toggles between red and black:

parameter make expression tcolor {lindex {black red} 0}
(select the square)
parameter make color {color value %tcolor}
The square will toggle between red and black when the parameter "tcolor" in the object instance containing the square is changed from the word "red" to the word "black".

Some hints on getting the expected Tcl expression result:

Use "expr" to return a result that is a number.
Use "list" with a single argument to return a result that is a string.
Use "lindex" to get a menu of selection choices when setting the parameter value
Use "color value" to get a color value for a parameterized color.
Avoid "return", which creates an error result.
Avoid "puts", which writes text to the XCircuit console, but does not return a value to the interpreter.
Some substring parameter keys have special significance to XCircuit:
index
Default value "?". Denotes the component index, which is a unique number given to each component in the netlist. If left default, then XCircuit will generate component indexes when it writes the netlist. Or, the Netlist->Auto-Number Components menu button can be used to automatically fill in these values. Netlist->Un-Number Components returns all index parameters to the default state.
link
Default value "%n". This parameter tells XCircuit where to find the schematic associated with the symbol (object instance) for which the parameter is defined. The default value indicates that the schematic comes from a file that has the same name as the symbol. If the name is different from the symbol, the parameter value can be set to the filename where the schematic can be found.
Recommended conventions for substring parameter keys:
class
Suggested to denote the letter in the standard letter-number pair used by many netlist formats to uniquely specify an instance of a component. By paramterizing the class, SPICE components can be easily changed from a component type such as capacitor ("C") or resistor ("R") to a subcircuit ("X"), which is often necessary (e.g., components operated at RF are often modeled as a subcircuit wrapper with extra components around the original device).
part
Suggested to denote a sub-part of an IC component, such as used when representing a single chip (e.g., 7400) as a set of separate logic gates (see the "quadparts" library that comes with the XCircuit distribution).

XCircuit Viewing Options

XCircuit Options

Loading and Saving files

Commands available from the menu for loading and saving files are described below. In the menu, buttons for file loading use the names "Read" and "Import". Functions that "read" a file always place elements onto the next available blank page. Functions that "import" data will place elements onto the current page, regardless of whether or not the current page already contains data.
Load Xcircuit Files File->Read Xcircuit File
Reads XCircuit files and libraries, and (if compiled in) ".lgf"-type files. The file type is determined automatically, and the appropriate action taken. If the file is a library (.lps), the load command functionally duplicates the "Load Technology" command (see below).
Write Xcircuit File File->Format Page Output
This command pops up a window containing the current settings for the PostScript output. These can be changed without affecting the output file (e.g., to change the object (page) name or the filename) by selecting "Close". A PostScript file will not be written until the "Write File" button is pressed. If the file already exists, then the button will read "Overwrite File". The other page options are summarized below.
Write All Modified Pages File->Write All
This function generates a pop-up dialog window showing each modified page and technology, and prompting the user for which ones to save. The pop-up window looks something like the following:
The "Pages" buttons can be used to bring up the "output properties" window for any page, for proper formatting prior to writing. For library files, the "Page" button will bring up the "Save Technology" pop-up window (see below), which can be used (for example) to change the filename of a read-only technology file so modifications can be written to a local copy of the file. The "Write?" checkbox can be used to select which files to write. Note that normally, files which have not been modified are not selected for writing. If unmodified pages are present, an additional button "Force" will force all pages and technologies to show up in the list, regardless of whether or not they have been modified.
Import Xcircuit File File->Import Xcircuit PS
Merges data from an XCircuit file with the current page.
Load Dependent Subcircuits File->Load Dependencies
For all objects that declare the parameter key name "link", the directory search path will be searched for filenames matching the value of parameter "link", and these files will be recursively loaded until no more unloaded dependency links remain. This function has no effect on objects that do not contain a parameter called "link".
Load Arbitrary PostScript to Background File->Import Background PS
Loads any PostScript file as the background to the current page. The file will be saved along with the xcircuit file as an encapsulated element.
Note: The PostScript background renderer corrects for page scale and orientation. XCircuit does not allow direct control over the background position, rotation, and scale: elements on the XCircuit page must be manipulated to match the background, not the other way around. Changes made in the file output dialog box (page scale, landscape vs. portrait, etc.) will maintain the relationship between the background and the xcircuit geometry as seen on the page. Generally speaking, the "import graphic image" feature (see below) is a better replacement for the background PostScript feature.
Create a Library Page File->New Library Page
XCircuit will prompt for a name for the library page. This name is independent of library technology names (although it can be the same), and typically relates to the group of objects to be loaded on the page (e.g., "generic", "digital", "analog", etc.). The new page is created empty.
Load a Library File File->Load Technology
This menu button generates the dialog window shown here:
The name of the file in the "Select technology to load" entry window should have a ".lps" (XCircuit library file) extension. The dialog prompts for the library page on which the objects defined in the library file should appear. By default, this is the "User Library" (always the last library page). Click on the library name to get a drop-down menu of library pages to select from.
Save a Library File File->Save Technology
This menu button generates the dialog window shown here:
Click on the button after "Save which technology" to indicate the technology group to save. This group consists of all objects having the same "technology prefix" in their fully-qualified names (see above description of library pages, files, and technologies). It does not necessarily correspond to a single or whole library page. When the technology is selected, the filename associated with the technology (if there is one) will be written into the entry window. This name may be changed if, for example, you want to add objects to and create a local copy of a read-only system library file.
Load a graphic image File->Import Graphic Image
This function reads "PPM" (portable pixmap) files, and is the best way to read arbitray graphic images (photos, logos, etc.) into XCircuit. The file must be in "raw" PPM format. Programs like "convert" (ImageMagick), "gimp", etc., can all be used to turn any image into a raw PPM format file. PDF and PostScript files should be converted at a reasonably high resolution to ensure a reasonable printout (actual printed density also depends on the scaling of the graphic image in XCircuit and the scaling of the output page). A good choice is to use at least 150 dpi conversion, e.g., "convert -density 150x150 filename.pdf filename.pnm".
The Tcl/Tk version of XCircuit scripts the conversion so that if the system has the "convert" program, most graphic types will be automatically converted and imported (gif, jpg, etc.).
Load an EDIF format schematic File->Read EDIF file
This command reads in an EDIF-2.0.0 format schematic file, such as might be produced by another EDA tool such as Composer. Its functionality is incomplete, but it should at least produce a readable schematic and complete library of symbols.
Run a command script File->Execute script
This command reads in a script of commands matching the command-line syntax. For the command-line syntax, see the reference pages. There are separate pages for the three different varieties of command-line syntax: TCL, Python, and the original (minimal) version.
Clear Page File->Clear Page
Erases everything from the current page. This kind of deletion cannot be undone!
Console Window File->TCL Console
This button de-iconifies the TCL console window. The console has several functions. One is to allow direct entry of command-line commands. The other is to keep a printout of all messages generated by XCircuit. The message window at the bottom of the window displays only the most recent message line generated by XCircuit. Error messages will automatically deiconify the console window, since it's undesirable to have potentially important error messages overwritten by other diagnostic or informational messages. When the Console window is present, the menu option changes to "Hide Console".

The Tcl command line syntax accepts any valid Tcl/Tk code. XCircuit functions imported into Tcl are summarized in Tcl-Based XCircuit page.

The following are properties of each XCircuit page, available from the properties window (the result of menu selection "File->Format Page Output" or the "W" key macro). Note that all page properties are independent of the xcircuit window view, which is why they are all listed in this popup window. Properties for each page are set independently of all other pages.

Exiting XCircuit

Beginning with XCircuit version 2.3.4 rev. 4, the method to prevent accidental exit (the use of the sub-menu selection "Quit->No Kidding") has been replaced with a check for unsaved changes. If any changes have not been saved, XCircuit will prompt the user for confirmation to exit.

XCircuit-Related Files

Xcircuit X-Defaults

Xcircuit configuration file (.xcircuitrc)

If a configuration file named ".xcircuitrc" exists in the current working directory (first place searched) or the user's home directory (second place searched) or the xcircuit library directory (last place searched), it will be loaded on startup. The syntax of the .xcircuitrc file is the same as an executable xcircuit script or command-line entry, and is described in the section "The XCircuit Command Line".

In addition to the configuration and X-defaults, some XCircuit behavior can be modified through shell environment variables. The environment variables which xcircuit makes use of are listed below:

TMPDIR
Directory for temporary (e.g., backup) files (defaults to TEMP_DIR).
XCIRCUIT_LIB_DIR
Directory where xcircuit libraries and startup files can be found (defaults to BUILTINS_DIR).
XAPPLRESDIR
Directory where the xcircuit application defaults can be found (defaults to RESOURCES_DIR)
HOME
Directory where xcircuit will look for startup files, after searching the current directory.
HOST, HOSTNAME, USER
Environment variables which xcircuit uses to fill in header information in the PostScript output (HOST and HOSTNAME are equivalent).

PostScript prologue:

System startup files:

The difference between ".xcircuitrc" and "xcstartup.tcl" in the library is that ".xcircuitrc" will be overridden if a file of the same name exists in a user's current working directory or home directory. "xcstartup.tcl" always runs, although default libraries and fonts listed therein can be forcibly ignored by the user with specific override options. Thus, it is recommended that "xcstartup.tcl" restrict itself to loading fonts and libraries, and that ".xcircuitrc" be used for all other commands. In cases where site-wide definitions are warrented, use the "site.tcl" file.

Standard xcircuit library files (technologies)

The following technologies (library .lps files) are loaded by default. The remaining files are put in the system library for access if warranted; they may be added, for instance, to the site-wide "site.tcl" file. They can also be imported in part or in whole using the "Load Technology" or "Library Manager" functions.

Standard xcircuit font vector files

As listed for automatic loading in the default startup script.

Standard xcircuit font encoding files

As listed for automatic loading in the default startup script.

Extended xcircuit font encoding files

Extends the fonts for ISO-Latin2 (Eastern Europe) and ISO-Latin5 (Turkey). I can generate new encodings for the remainder of the ISO-Latin set, but will not do so until I receive a request. These files are made available in the xcircuit system library, but are commented out of the default startup script.
PostScript is a registered trademark of Adobe, Inc.

Back to the xcircuit home page. . .

email:

Last updated: August 5, 2016 at 6:54pm