Using XCircuit

Using XCircuit

Table of Contents

Running the program

Usage:
xcircuit [options] [filename]
Where filename is the name of an XCircuit file (usually a file with extension ".ps") or an XCircuit library (a file with extension ".lps"), and options can be zero or more of the following:
-noconsole
Run the Tcl/Tk version directly from the terminal, not using the "tkcon" console window. When running the console (the default), the actual executable is "wish", the Tk shell, which in turn loads XCircuit as a shared object library. In "noconsole" mode, the executable is "xcircexec", a standalone wrapper for wish.
-nowindow
Run without generating or displaying a window. This mode can be used to run xcircuit as a filter.
-2
Use 2-button mouse key bindings. This modifies the default key bindings. Functions bound to the middle button are moved to the right button, and functions bound to the right button are moved to the "BackSpace" key.
-exec filename
Run XCircuit as a filter (batch mode), processing commands from the Tcl script filename.
-r
Replace any library symbols local to the input file filename with the corresponding symbol from the xcircuit library pages when the names match but the object contents are not the same. Similar behavior is provided by the Tcl variable XCOps(technology) (see below).
--help
Print a short Usage message and exit.
--version
Print the version and revision numbers of XCircuit and exit.

Crash Recovery

XCircuit saves a copy of current work in the /tmp directory. This file is usually removed upon exiting the program. An unexpected exit such as a program or system crash, or a termination of the program via a kill signal, will leave this file. To recover the contents of the file, it is necessary only to start xcircuit without any options:
xcircuit
If there are any crash backup files found in the /tmp directory, XCircuit will prompt the user asking if they should be recovered.

Files are backed up periodically, either once every ten minutes or after a certain number of changes have been made to the schematic. Thus, after a crash, one may lose the last few changes made to the file.

Variables affecting run-time behavior

XCIRCUIT_LIB_DIR
This variable can be set to tell XCircuit to look in a place other than the install directory for the run-time files. To test XCircuit after compilation but before install, do:
setenv XCIRCUIT_LIB_DIR ./lib
Before running the program. In the case of the Tcl/Tk-based version, you will also need to do:
setenv XCIRCUIT_SRC_DIR ./lib/tcl
and then run the launching script "lib/tcl/xcircuit.sh" from the command line.
XCOps()
XCWinOps()
XCOps(window)
This variable needs to be set when, and only when, an XCircuit window is to be used inside a Tk window structure other than the usual GUI wrapper. This tells XCircuit not to expect the scrollbars, menu buttons, toolbar, and so forth. The variable should be set to the Tk window name of the Tk "simple" window to be used as the XCircuit drawing window.
XCOps(library)
When set to a library page name, this variable forces XCircuit to place any new symbols (objects) defined in a schematic file being read onto the library page defined by this variable. By default, the value is "User Library".
XCOps(technology)
When set to a technology name, this variable forces XCircuit to replace any symbols (objects) local to a schematic file with the version from the named technology (library). This is similar to the "-r" switch, although substitutions are made only from the indicated technology, whereas the "-r" switch makes substitutions from all technologies. By default, the value is "(user)", which makes replacements from any symbols that do not declare a specific technology.

The startup script

The startup script is a file of XCircuit command-line commands that is executed during program startup. It is named .xcircuitrc and is searched for in the current working directory, followed by the user's home directory. Only the first one found is executed. Any valid Tcl command available to XCircuit may be used in the file. Note, however, that the ordering of certain statements is critical. There is a system startup script that is executed during the user startup. When XCircuit starts reading the user's startup script, no fonts, colors, or libraries are loaded. Upon encountering the first request to access a color, font, or library, XCircuit reads the system startup script. To prevent the system startup from setting up colors, fonts, or libraries, "override" variables may be declared (see below). When these variables are present, it is the responsibility of the user or project startup script to define the colors, libraries, or fonts. This is most often used to set up project libraries.
global XCOps
Since XCOps() is a Tcl array variable, it is necessary to declare it "global" in the startup file so that the interpreter will handle the settings below correctly.
XCOps(liboverride)
Do not install the system libraries. The startup script will define and load its own libraries using the "library create" and "library load" commands.
XCOps(fontoverride)
Do not install the system fonts. The startup script will define and load its own fonts using the "loadfont" command. If no fonts are loaded, XCircuit will automatically load the "Helvetica" font to be able to print labels, symbol names, and other text in the drawing window.
label family font-name
Declare the default font to be font-name.
config database window
Re-load the Tk resource database. The window is any XCircuit window path name (usually ".xcircuit") and is irrelevant since all windows share these resources. Resources are set using the Tk command "option add", with the following valid options (non-inclusive list):
*window-name.width
Window width (and equivalently, height . This can be set per-window with window-name= xcircuit, xcircuit1, xcircuit2, for successive windows.
*xcircuit*gridcolor
Color of grid lines (light gray)
*xcircuit*axescolor
Color of x=0 and y=0 axis origin lines (light tan)
*xcircuit*selectcolor
Color of selections (gold)
*xcircuit*pageforeground
Color used for the page foreground. This is defined as the color used by all elements having the color "inherited", and is by default black as defined by the PostScript page output.
*xcircuit*pagebackground
Color used for the page background. The default is white, to match the printed page.
One good use of the configuration database is to darken the grid and axes colors, which are designed for CRT displays but often come out too light on flat-panel displays. A good setup for flat-panel monitors is the following:
option add *xcircuit*gridcolor "gray90"
option add *xcircuit*axescolor "#e0d0ab"
config database .xcircuit
Note, however, that values pertaining to the Tk menus and window decorations are default values, and changing these defaults will not affect the values being used on windows that have already been created, but only those windows that have not been created. To alter values for menu and popup window fonts and colors, settings need to be changed in the file resource.tcl in the runtime library directory (e.g., /usr/local/lib/xcircuit-3.8/.
config search lib dir-list
Set the search path for libraries to the ordered, colon-separated list of directories dir-list. This overrides the default search path, which is the current working directory, followed by the location where XCircuit's run-time files were installed.
library page-name load filename [-replace]
Load a technology file filename (".lps" extension file) into the library page page-name. If the option "-replace" is used, library objects from the file whose names conflict with existing library objects will be discarded.
library make page-name
Library pages may be loaded with the library load command one at a time. However, if libraries need to be loaded out of sequential page order (potentially necessary when the "-replace" option is used, as described above), empty libraries must first be created with the "library make" command. It is generally a good idea to create the library page structure with this command first, before loading objects.

Features of the XCircuit window

The XCircuit window looks like the picture below:

The initial window configuration when starting XCircuit, showing one of the library pages.

The features of the xcircuit window are as follows:
  1. Along the top of the screen are buttons for pull-down menus called "File", "Edit", "Text", "Options", "Window", and "Netlist".
  2. At the top, beside the menu buttons, is a welcome message in the message window telling you the version and revision numbers of the program (Version 3.4, Revision 0). When manipulating elements in the drawing window, the message indicates the cursor position.
  3. On the bottom left are two buttons that give some information about what type of schematic object you are currently editing, and allowing one to switch quickly from a schematic to its symbol representation, if applicable. To the right of these buttons is a label that indicates the drawing mode (the action bound to a left mouse button tap), which is "Wire Mode" by default. To the right of this is a message window telling you that you are currently editing "Page 1".
  4. On the rest of the bottom is another message window telling you that xcircuit has just loaded the library "/usr/local/lib/xcircuit-3.2/analoglib2.lps" (this may be in a different directory if xcircuit has not been installed in the default directories). In the non-Tcl version of XCircuit, this message will disappear after about 10 seconds. Various status, result, warning, and error messages get posted to this subwindow.
  5. At the right is a toolbar with various functions (and a couple of menus). Some of them (like the Wire and Pan buttons) represent "modes" (see Item 3, above) that change the action invoked by a tap of the left mouse button. Others (like the Delete and Copy buttons) will change modes, but if elements are selected, they will perform the action (e.g., delete or copy) on those selected items immediately, without changing modes. The remaining buttons either generate pop-up menus (e.g., Color and Line Style buttons) or perform immediate actions (e.g., Zoom and Library buttons).
  6. At the left and along the bottom are two scrollbars which report (by their length and location) the position of the drawing relative to the main window, and can be used to reposition the drawing by clicking on the bar with any mouse button, and optionally dragging the bar. The black square at the junction of the two scrollbars is also a button. Pressing it will center the drawing in the window and set the zoom factor to fit the drawing to the size of the window.
  7. In the center is a white drawing area with lightly-colored grid and axis lines, with red points marking snap-to positions.

Input Methods

XCircuit operates with three largely interchangeable input methods:
Key and Button bindings
Most actions can be accessed by single keystrokes or mouse buttons, the fastest and most convenient method for drawing in XCircuit.
Menus and Toolbar
Some less frequently used options can be found only in the menu hierarchy. The toolbar is somewhere between the key and button bindings and the menus in terms of convenience.
Command Line
The command-line interface may also be used as an input method, usually used for writing scripts to add new functions to XCircuit or for running XCircuit in batch mode.
XCircuit has one input method that is very useful but not widely used in GUI interfaces. When a key or button is pushed and released quickly, it is interpreted as a "tap" (in other words, a normal key or button press event). When a key or button is pushed and held down, it is interpreted as a "press" or "hold" event. These two events can be treated as separate events in XCircuit and bound to entirely different actions. In the wire drawing mode, for example, the mouse left button tap action is bound to the "start/continue wire" action, but the mouse left button hold action is bound to the "select and drag" action.

XCircuit key and button bindings use the modifier name "Hold" to indicate bindings that operate by a key or button press. XCircuit does not use double-clicking by default, although the Tcl/Tk version can make use of the Tk "bind" command, which allows binding of double, triple, and quadruple clicks. Personally, I find multiple click methods annoying, which is why you won't find any such methods in the default button bindings.

Generally speaking, the key macros are more convenient than the toolbar buttons, which are more convenient than entering commands into the console. Key macros require a bit of memorization but are the fastest way to draw in XCircuit.

XCircuit and the Tcl/Tck interpreter

The Tcl/Tk-based version of XCircuit diverged from the Xw-widget-based version, which lacked the simplicity and convenience of scripting new GUI functions.


The Tcl console window, in the Tcl-enabled version of XCircuit. This window can be generated with the "%" key macro, or with the menu selection "File->Tcl Console".


For help with remembering keyboard macros and their functions, select the menu item "Options->Help!". You will get a popup window to the right of the screen which lists all of the available keyboard functions. Tap the "Done" or "Dismiss" button when you no longer need the help menu.

The Tcl version of the Help window has some help text about each function. Click on the function name to get the help text about that function.


The help menu in the Tcl version of XCircuit.


Back to the xcircuit home page. . .

email:

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