XCircuit Extended Tcl Interpreter Reference



Introduction

Somewhere around xcircuit version 2.2, it became painfully obvious that the ".xcircuitrc" file which dictates a user-specific environment for running xcircuit, was turning into a badly-written interpreter. I had the choice of continuing to extend the ad-hoc syntax of this pseudo-interpreter, or taking the painful but more satisfactory approach of using a standard interpreter. Because XCircuit is open-source software, the interpreter would have to be, too. The primary choices were Tcl, a well-established interpreter intended for use in exactly the way needed by xcircuit, and Python, a more recent development. Python came with an example on how to embed itself in an application, and I happened at the time to be working on a project using Python scripting at work, so embedded Python became the first choice for development, beginning with xcircuit version 2.2.1 (see the xcircuit Python reference page).

Beginning with XCircuit version 3.1, XCircuit can be compiled as an "extension" of the Tcl interpreter. This is in direct contrast to the Python interface, which is an "embedded" interpreter. So what's the difference? Well, one difference is that when an interpreter is embedded, it links itself into the code either at compile-time or at runtime. If it links at compile-time, all the resources needed by the interpreter become part of the application executable, which tends to blow the size of it up to gigantic proportions. If a shared-object library is available, it can link at runtime. But the primary difference is that the application program drives an embedded interpreter, whereas an extended interpreter drives the application program. In the Python-based xcircuit, Python is initialized at startup, and then is not heard from again until it is called upon to process a command-line command (either from the startup script file "xcstartup.py", the user-specific environment script ".xcircuitrc", from the command line ("^" macro), or from a command or macro defined by the Python interface. Most extended interpreter applications operate by defining their own execution main loop and wresting control from the interpreter's main loop. XCircuit (and the other CAD tools which I have ported to Tcl: magic, irsim, and netgen) use a fundamentally different method. In Xcircuit's extended interpreter, the interpreter is called first, not the application (under Tcl, this means invoking "wish", the Tcl/Tk shell). The interpreter then loads the application as a shared-object library, or "module", and runs its initialization procedure. The responsibility of the initialization procedure is mainly to define all the commands used by the application and add them to the interpreter's command parser. After that, the procedure returns to the interpreter's command-line prompt and waits for user input.

Most users want to run xcircuit as if it were a standalone graphics application, not as an extra set of commands in an interpreter. To this end, the executable "xcircuit" is actually a script. The script runs the Tcl interpreter and passes to it a few commands. The first command sources a script that defines the GUI environment for xcircuit. The second command executes the "start" command, which is a secondary initialization procedure that runs everything dependent on the existence of the GUI. Then xcircuit returns (again) to the interpreter. However, the GUI is up and running, and all keyboard and button events in the GUI window will be processed by the interpreter. The application's window and and the interpreter command-line prompt tend to look like two processes running in parallel. Actually they are a single process which is continuously "polled" for either keyboard events (line-based, not character-based) or window events (which come from the X11 server). However, from the standpoint of the end user they can be viewed as two independent ways to control the application. The command-line can be ignored and XCircuit operated as a standalone graphics application. Or, the GUI can be ignored and XCircuit can be operated entirely by commands entered on the command line.

The most useful feature of the extended interpreter is that more than one program can be loaded into the interpreter at a time, allowing applications to share a single interpreter and to run each other's commands. This is by far the most powerful way to integrate different CAD tools. For example, a network can simultaneously be selected in a layout (magic), highlighted in the corresponding schematic (xcircuit), and its simulated output graphed (irsim), all as the result of a single keystroke. There is one drawback to this method, which is that it makes each application dependent on the stability of all the others. Any program which crashes brings all the applications down with it.

Tcl-XCircuit Command Summary

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

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.
elipses...
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, then the program goes into an interactive mode, prompting for an element to select and apply the option to.

element [handle...] type
Returns the type of the element, which may be one of label, polygon, instance, spline, path, 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, or arc. Option option must be one of the following:

deselect
deselect the indicated element(s).

element [handle...] parameter option...
Option may be one of the following:

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

make type
Generate a parameter of the indicated type for the indicated element. type may be one of: position, substring, "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 initial value given to the parameter is the default.

get [type]
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.

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

forget type
Delete the parameter of the indicated parameter type type from the indicated element.

Note that one cannot set parameter values with the parameter command. It is expected that parameter values will be set or changed by manipulating elements. This is necessary because an element handle is devoid of any information regarding the instance of an object in which that element is to have its parameter changed.

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 [number]
Raise the position of the indicated element(s) toward the drawing front (end of list; last to be drawn). If number is specified, it is raised in front of the next number elements in the list. If no number is specified, it is raised to the front of the drawing.

lower [number]
Lower the position of the indicated element(s) toward the drawing back (beginning of list; first to be drawn). If number is specified, it is lowered behind the next number elements in the list. If no number is specified, it is lowered to the back of the drawing.

color [idx]
Sets the color of the specified element(s) to value idx, an index into xcircuit's color table. With no arguments, returns the color of the indicated element.

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, or closed.

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...] scale [value]
Change the scale of the indicated instance(s) to value. If no value is specified, return the current scale of the instance.

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.

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:

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:

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 [name] option
The following options act on objects (not object instances!). These commands may take only one selected item, or exactly one object, referenced 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.

move [library]
Move the object to the indicated library, or the User Library if library is not specified.

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

Actions

Actions 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] options
The additional subcommand get returns a handle or list of handles of all currently selected elements.

delete [handle...|here] options

undelete [handle...|here] options

deselect [handle...|here] options

copy [handle...|here] options

edit [handle...|here] options

parameter [handle...|here] options

push [handle...|here] options

pop [handle...|here] options

rotate [handle...|here] options

flip [handle...|here] options

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...
Load the xcircuit file named filename into the indicated page.

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.

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)

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

links
Returns the page labels of all pages which have the same filename as the current or indicated page.

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

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.

save filename
Save the indicated library to the file filename.

goto
Go to the indicated library (interactive command).

library filename [number]
Backward compatibility; same as library [number] load filename

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.

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.

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.

coordstyle "decimal inches"| "fractional inches"|centimeters
Sets the coordinate measurement system to metric or standard. "fractional inches" reports values in whole number fractions when possible.

color [inherit|idx]
Sets color to the indicated color index (from xcircuit's color table). Keyword inherit is the same as idx=-1, and represents a color which is inherited from the parent element in the drawing hierarchy. No arguments: returns the color of the currently selected element, or the default color if nothing is selected.

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. Know 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", closed, and unclosed. The two-word "bounding box" must be quoted or in braces ({}). "bounding box" takes 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.

Netlist

netlist option
Perform various netlist functions. Options are:
write format
Generate a netlist output file in one of the following formats: spice, spiceflat, sim, or pcb.

highlight
Highlight connectivity of any selected network element (wire or pin), or start an interactive method for selecting a network to highlight.

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.

autonumber
Automatically substitues indices for unnumbered circuit components.

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.

GUI

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 [here|position]
Center the drawing window on the indicated position. If here, position is centered on the cursor. Otherwise, position is a list of size 2 with X and Y values.

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

promptchecksavelib [library_number]
Start the library save popup, checking first to see if the indicated library is empty.

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.

Files

loadfont fontname
Loads an xcircuit font. Expects to see file fontname.xfe (Xcircuit Font Encoding) in the default system library path.

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.

image create xpm name -file filename.xpm
This is an extension to the Tk image command which allows images to be generated from "xpm"-format files. Since xpm files contain all color and size information, the options are fixed (although it might be nice to add things like color substitutions).

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.

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

Tcl Script Examples

There are no useful script examples at the moment other than 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: August 5, 2016 at 6:57pm