XCircuit Reference Manual
(Page under construction)
Table of Contents
XCircuit Keyboard and Menu Commands
XCircuit internal structure
XCircuit files
Python Embedded Interpreter Reference
XCircuit PostScript Reference
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 ("|").
- Make Polygon (Mouse Buttons)
Basic operation for drawing lines and polygons. This
is the only drawing command that has neither a keyboard
macro or a menu button. A ``tap'' (brief press) of
Mouse button 1 fixes the endpoint of a line segment.
The pointer position after subsequent pointer motion
determines the other endpoint.
Mouse button 1 finishes the line segment and begins a new one.
Mouse button 2 completes the line segment and ends the command.
Mouse button 3 deletes the last line segment and returns the
cursor to the endpoint position of the previous line segment,
or cancels the command if there are no line segments left to edit.
- Make Box (b) Edit->Make Box
Convenience function for closed, rectangular polygons.
The position of the cursor when the key or mouse button
is pressed marks one corner of the box. The pointer
position during subsequent pointer motion defines the
diagonally opposite corner.
Mouse button 2 completes the arc and ends the command.
Mouse button 3 cancels the command.
- Make Arc (a) Edit->Make Arc
Create a circle or ellipse. The position of the
cursor when the key or mouse button is pressed
marks the center of the arc or ellipse. Subsequent
pointer motion defines the radius.
Mouse button 2 completes the arc and ends the command.
Mouse button 1 switches between radius, endpoint, and
ellipse minor axis editing.
Mouse button 3 cancels the command.
- Make Spline (s) Edit->Make Spline
Create a curve. The position of the cursor when the key
or mouse button is pressed marks one endpoint of the
curve. The pointer position during subsequent pointer motion
defines the other endpoint. The control points are
initially fixed.
Mouse button 2 completes the curve and ends the command.
Mouse button 1 switches between endpoint and control point
editing.
Mouse button 3 cancels the command.
Note: The Bézier curve generating algorithm
uses the parametric form described in the Adobe PostScript
Language Reference Manual. It is not a spline, though I
have abused the terminology because it makes the "s" macro
easier to remember. "c" stands for "copy", not "curve"!
- Make Text (t) Text->Make Label
See ``Creating and Editing Text'', below.
- Make User Object (m) Edit->Make User Object
This is a powerful feature of Xcircuit. This command creates
new objects which act just like built-in library objects. An
instance of the object is kept on the User Library page, where
it can be grabbed whenever a new instance is required.
All elements which are currently selected when the command is
executed by key or button press will be compiled into a new
user object. The individual elements will be replaced by the
new object. The user is prompted for a name for the new
object.
The Cancel button on the popup window cancels the command.
The Okay buton on the popup window completes the command.
Note: For efficiency in the PostScript output, it is
recommended that an object be created for any part of a drawing
which is used more than once. However, any single object should
not have more than about a hundred components, or it may
exceed the capabilities of the PostScript rendering device.
The PostScript internal limit is device-dependent and cannot
be known a priori. Xcircuit will flag a warning if an
object contains an unusually large number of components, but
the condition is not treated as an error.
- Make Path (join elements) (j) Edit->Join
Paths are another powerful feature of Xcircuit. A path is
a linked set of line segments, curves, and arc segments which
is treated as a single unit. The unit can be colored, stippled,
filled, and bordered like a single polygon, arc, or curve.
All elements (may only be polygons, arcs, and curves) which
are currently selected when the command is executed by key
or button press will be compiled into a single path, provided
that a single path can be found. If the path has more than
two free endpoints, then a single path cannot be constructed
and the command will fail.
The Make Path command cannot be canceled but can be undone
using the ``unjoin'' command (see below).
Path points can be edited directly with the ``edit'' command,
although editing of arcs inside a path can have unexpected
and/or undesirable results, as the endpoints of the arc are
not guaranteed to match the adjoining portions of the path.
Note: In some pathological cases, a path which crosses
itself too many times may have a perfectly good solution which
xcircuit cannot find. If this occurs, the path will have to be
divided into two or more subpaths.
Unless otherwise stated, all of the commands below have the following
behavior which depends on the way they are called:
Menu button:
The user is prompted to click mouse button 1 or 2 on the
object upon which to perform the command. If an element or
elements are already selected, they will also be acted upon by
the command. Mouse button 3 will cancel the command.
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.
- Delete (d) Edit->Delete
Deletes elements. Note that when object instances are deleted,
it is the specific instance of the object, not the object itself,
which is removed (see the library Delete function below).
- Undelete (u) Edit->Undelete
While xcircuit does not have a comprehensive ``undo'' function,
it is possible to undo the command with the greatest potential
for disaster, i.e., Delete. Xcircuit keeps a copy of the last
ten deletions (whether single or multiple elements).
- Copy (c) Edit->Copy
Used to make a copy or copies of elements. After the command
is chosen, a copy of all the selected elements is made and
may be dragged around the screen to the desired position using the
pointer.
Mouse button 1 places the current copy at the position of the
pointer, then immediatly creates a new copy and continues the
copy function.
Mouse button 2 places the current copy at the position of the
pointer and completes the command.
Mouse button 3 removes the current copy and ends the command.
Previous copies which have been made are not affected.
- Deselect (x) Edit->Deselect
Removes items from the group of selected elements. Un-selection
differs from selection in that no prompting is given for choosing
between multiple elements found near the pointer position; all
elements which qualify are deselected.
- Rotate CW 15 degrees (r)
Rotation is self-explanatory, but the exact behavior depends
on the elements chosen to be rotated:
Object instances are rotated around the object's center point,
defined by the (0,0) position inside the object.
Text is rotated around the text's origin as defined by the
text justification. Paths cannot, at present, be rotated.
Arcs are rotated about their center, meaning that the angles
of the endpoints are rotated. This is true for ellipses,
too: ellipses are only defined with the major and minor
axis perpendicular to the drawing window axes. However,
entire ellipses can be rotated by using "Make User Object" (see
above) to turn the ellipse into an object, and then rotating the
object. Splines and polygons are rotated around their point
of origin (endpoint). Note that due to roundoff errors, this
can cause distortion in the polygon or spline and is not
recommended. Rotation which exactly preserves relative point
coordinates is better effected by making an object out of
the polygon (or curve, or path), and then rotating the object,
as described above for ellipses.
Elements may be rotated while they are being held and dragged
around the window.
- Rotate CCW 15 degrees (R)
Counter-clockwise rotation. Behavior the same as above.
- Rotate CW 5 degrees (o)
More finely-spaced clockwise rotation.
- Rotate CCW 5 degrees (O)
Finely-spaced counterclockwise rotation.
- Flip Horizontal (f)
Like rotation, flipping behavior depends upon the type of
element being flipped: Object instances are flipped around
the object's point of origin, and flipping is relative to
the object's own Y-axis, not (necessarily) the axis of the
drawing window. Arcs, curves, polygons, and paths are
all flipped around the Y-axis defined by the X-position
of the pointer. Text cannot be flipped, though if backwards
text is desired for some reason, it can be made by creating
an object ("Make User Object") out of the text and then
flipping the object. However, watch out for the inverse
situation: If an object contains text, flipping or rotating
that object will flip or rotate the text.
- Flip Vertical (F)
Vertical flipping acts exactly like horizontal flipping
except that flipping occurs across the X-axis.
- Snap to grid (S)
Causes the selected elements to be aligned to the snap-to
grid. Object instance and label origins will be moved
to the closest snap-to point, as will arc centers and radii,
spline endpoints and control points, and all points of polygons.
- Dashed/Dotted/Solid Border (|,:,_)
Options->Elements->Border->Solid | Dashed | Dotted
Changes border style for arcs, polygons, curves, and paths.
The menu also has a style choice of "Unbordered". Note that
it is not allowed to make an object both unfilled and
unbordered, as this would render the object invisible.
- Disassemble Path (un-join) (J)
This command disassembles all selected paths, and
returns all polygons, arc segments, and curves to the state
of separate, individual elements.
- Push into object (edit) (>)
Edit->Push Selected
This is the proper way to edit an object. Xcircuit is hierarchical,
and objects can be nested. After a push, the selected object becomes
the top level page. There is no difference between pushing into an
object from any page or the library containing the object,
unless the object has a parameterized string. If so, pushing
into the object from the library substitutes the parameter's default
value, and editing the string alters that default value. Pushing
into the object from a page substitutes the value specific to that
object instance. Subsequently, editing the string alters
the object instance's value, not the default.
- Pop out of object (<) Edit->Pop hierarchy
Returns to the originating page from which a push command
was executed.
- Transferring elements between pages
Any element can be moved between pages. This requires an active
``grab,'' in which the element(s) is (are) selected, then grabbed;
while holding down the mouse button, type a new page number
(keys 1 through 9 and 0 for Page 10). The
elements will be deleted from the originating page and moved to
the target page.
- Change object size Options->Elements->Object Size
Allows an object instance to be scaled. The scaling affects
linewidths inside the object, so use of object scaling is not
recommended for circuit elements (due to potential mismatch of
wire lines) unless the linewidths of the object are inversely
scaled to match.
- Change object color Options->Elements->Color->(color)
Selected elements will take on the chosen color. The special
color entry ``Inherit Color'' lets the element take its color
from its parent object instance. Color inheritance is meaningful
only for object instances; elements on top-level pages always
inherit the color black. So, attempting to set the color of
an object instance only works on those elements of the object
which inherit their color.
- Edit (e) Edit->Edit
Edit mode is dependent on the type of element selected. See
below.
- Polygon The edit warps the cursor to the closest polygon
point. The point can then be moved independently of the rest
of the polygon but depending on the policy set by the
Options->Elements->Polygon Edit selection. With ``Normal''
edit, only the point being edited is moved. With ``Manhattan''
edit, the two nearest neighbors to the point in question are also
moved to maintain manhattan geometry (i.e., both lines are either
vertical or horizontal). From edit mode, mouse buttons function
as follows:
- Cycles between the points of the polygon.
- Ends the edit.
- Undoes the last edit action and returns to the previously
edited point. If the current point was the first to be
edited, then the edit command ends.
In addition to the mouse-based functions, there are several
keyboard functions which operate as follows:
- i Insert a new point into the polygon. The
initial point position will be on top of the current
edit point, but subsequent cursor movement will
reveal the new point.
- d Delete the point from the polygon. This
works as long as there are more than two points
(one line) in the polygon; otherwise, nothing happens.
- x Breaks the polygon into two parts at the edit
point. The edit session will continue with one of the
two resulting polygons.
- A Sometimes it is desirable to have a line terminate
at a particular point along another line, arc, or curve,
rather than on a specific grid point. To do this, place
the edit point over another polygon, arc, or curve, and
type ``A''. The point will then be constrained to
terminate on the selected element. Typing ``A'' a second
time will release the attachment constraint.
- Arc The edit warps the cursor to the nearest arc endpoint
(it has two, even if the arc is a closed circle). The arc can
then be altered according to the edit cycle, as defined below.
- Cycles between the radius length, first arc endpoint,
second arc endpoint, and ellipse minor axis. The center
point can only be changed by moving the whole arc, not
from the edit mode.
- Ends the edit.
- Undoes the last edit action and returns to the previously
edited point. If the current point was the first to be
edited, then the edit command ends.
- Curve The edit warps the cursor to the nearest curve
endpoint. The curve can then be altered according to the edit
cycle, as defined below.
- Cycles between the two Bézier curve endpoints and
the two control points.
- Ends the edit.
- Undoes the last edit action and returns to the previously
edited point. If the current point was the first to be
edited, then the edit command ends.
- Path The edit command warps the cursor to the nearest
point of the nearest path object, where edit continues as
described above for the element type found (polygon, arc, or
curve). Only one element in a path can be edited at a time;
the edit command must be terminated before another path element
is edited. Path components cannot be added or deleted; that
can only be accomplished by disassociating the path components
using the ``un-join'' command (``J'' macro).
Caveats: Using the `x' key on a polygon inside a path
has unpredictable results. Editing an arc inside a path can
also be tricky, since the arc centerpoint cannot be moved.
Altering the arc's position requires that the path elements be
disassociated, moved, then re-joined.
- Change element fill style
Options->Elements->Fill->(fill type)
Fill style results in ``transparent'' (stippled) fill patterns.
In general, this is not recommended, as the PostScript output
becomes device-dependent, and output rendering becomes much slower.
However, it is the only way to get transparent effects in PostScript.
- Make element opaque/transparent
Options->Elements->Fill->Opaque
With the above fill styles, ``opaque'' gives a solid white background
to the stipple, eliminating the transparency effect. This is not a
useful function except in rare cases.
- Change element color Options->Elements->Color->(color)
Color is changed to the selected color. One special entry is called
``Inherit Color'', which causes the element in question to inherit
its color from the level above in the drawing hierarchy. This allows
an entire object to be set to a given color. Interesting effects
can be generated using combinations of inherited and fixed colors
inside an object. Top-level elements inherit their color from the
top-level page, which is always defined as black.
- Edit Object Name (E)
This is the only way to change the name of an object (apart from
altering the PostScript file). Acts very much like the edit (``e'')
command for labels, except that special characters and functions are
disallowed, because the object name must follow the same rules of
syntax as a PostScript name. Disallowed normal characters (such as
whitespace) will be replace by underscores. If the object's name is
the same as any other object, it will be altered to make it unique
by appending an underscore.
- Move Object (M)
This command allows objects in the library to be rearranged.
Because clicking on an object returns the user to the originating
page, objects cannot be moved around like they are on a regular
page. This method works in two ways:
- Select any two objects and type ``M''. The objects will be
swapped.
- Select one object, move the cursor to the desired target
position, and type ``M''. The object will be moved to the
target position, diplacing all other objects on the page
as necessary to fit.
This command also works on the "Page Directory" page in the same
way, allowing pages to be rearranged. This determines the order
of output in multiple-page files. No such method exists for the
"Library Directory" page.
- Delete Object (D)
Unlike deletion from a page, which deletes an object instance,
deletion from the library deletes the object itself. This is a
non-recoverable function: all memory allocated to the object
is freed. Deletion is disallowed if the object has an instance
on any page in xcircuit.
- Hide Object (H)
Sometimes objects are best constructed in parts, where its parts
may also be objects. It is not always desirable to have these
sub-parts to show up as library objects, because they are not
useful to the end-user by themselves. In such cases, the object
may be declared ``hidden'', and does not appear in the library.
Object hiding is disallowed if the object is not a sub-part of
any library object, because the object would become inaccessible.
- Copy Object (C)
Object copy is different from copying object instances for the
same reason that object deletion is different from object
instance deletion. When an object is copied, a new object
is created on the ``User Library'' page, which is a separate
but duplicate version of the original. An underscore is prepended
to the object name to maintain a distinction between the two (but
it can be altered afterward with the ``E'' edit command, above).
- Create Virtual Object (V)
From version 2.5.2, xcircuit allows multiple instances of a
single object to appear on a library page, provided that the
object has parameters. The idea is that this works as a
convenience function for inserting specific parameters into
an object. For instance, it can be used to pre-assign pin
numbers to different gates on a multiple-gate chip such as
a 7400 quad NAND. Note that parameterized pin names only
generate correct netlist output from xcircuit version 2.5.2.
- Refresh Screen ( ) Edit->Refresh
Occasionally ``bit trash'' (sometimes known as ``mouse
droppings'') are left behind on the screen. The space bar
will do a complete refresh of the screen.
- Zoom Out (z) Window->Zoom Out
Zooms out to view a larger area, with the previous view centered on
the screen. Scale is reduced by a factor of 1.5.
- Zoom In (Z) Window->Zoom In
Zooms in to view a smaller area, with the new screen centered with
respect to the previous view. Scale is multiplied by a factor of 1.5.
- Zoom Box Window->Zoom Box
The second mouse button generates a box which then bounds the new
full-screen view. Where the aspect ratio of the zoom box and window
don't match, the new view is sized to include all of the zoom box,
and the zoom box area is centered in the new view. Zoom box can
also be executed by creating a box with the second mouse button,
and with the button still held down, type the "Z" key. There is
also a "zoom out box" enabled by creating a box with the second
mouse button, and then typing the "z" key with the mouse still
held down. The new view will be set such that the previous
full-screen view fits into the zoom box.
- Pan (p) Window->Center Pan
The position of the cursor becomes the new center of the full-screen
view.
- Half-page pan (Arrow Keys)
Arrow keys on the keyboard scroll the window in the direction
indicated by half a screen width.
- Scrollbars
Scrollbars allow an alternative way to pan the screen. Scroll
bars may be tapped to pan instantaneously to the indicated
position, or they may be dragged for a smooth scroll.
XCircuit does not render on a window larger than the active
display window, so smooth panning only displays the part of
the screen already drawn; off-screen portions will be blank
until scrolling ends and the entire screen is redrawn.
- Go to Page Directory (P) Window->Page Directory
Display a window which shows all of the pages defined. This includes
the first ten pages (whether or not they have content), plus any others
which have been added by loading files or with the
Window->Goto Page->Add New Page menu selection. Click the left
mouse button on one of the pages displayed to go to that page.
- Go to Page Window->Goto Page->(page)
Go to the page indicated by the menu selection. Menu buttons list the
pages by name.
- Quick Goto Page (Keys 1 to 9 and 0)
Simple way to get to any of the first 10 pages. For higher-numbered
pages, use the menu. Alternatively, key bindings can be added for
higher-numbered pages (such as Ctrl-numbers or Alt-numbers).
- Add New Page Window->Goto Page->Add New Page
On startup, XCircuit defines ten pages. If more are required, use this
function to add them. Pages will be added automatically if loading a
file exceeds the existing page count.
- Go to Library Directory (L) Window->Library Directory
Display a window which shows all of the available libraries.
From the Library Directory, click the left mouse button in one of the pages
shown to go directly to that library.
- Go to Library (l) Window->Goto Library->(library)
Go to the library indicated by the menu selection. Menu buttons list the
libraries by name.
- Add New Library Window->Goto Library->Add New Library
Create a new (empty) library page. The "user library" page will be
bumped up by one and the new library page will be inserted in front of
it. Contents can be loaded into the new library with the
File->Add To Library menu selection. Note that the menu selection
File->Load New Library is equivalent.
- Grid On/Off Options->Grid->Grid
Controls the visibility of the light grid lines on the screen.
- Axes On/Off Options->Grid->Axes
Controls the visibility of the light axis lines indicating the
coordinate system origin.
- Change Grid Spacing Options->Grid->Grid Spacing
Grid spacing may be altered to any value. Grid lines are not
the same as snap points, but are for visual reference only.
Changing their value to anything other than a multiple of the
snap spacing is unlikely to be useful.
- Change Grid Display Type
Options->Grid->Grid type/display->Decimal Inches | Fractional
Inches | Centimeters
The Grid display can be made to show units in centimeters or
inches, and with a cute algorithm can be made to print out
fractional inch units as well. A picture can be converted
from inches to cm and back again; however, for ease of use of
library objects it is necessary that the grid spacing should
remain the same between the two so that the snap-to grid is
not offset from its original position. However, it seems
more normal to work with a grid size which is always in
whole-number units or small proper fractions of units.
Instead of setting 1 inch = 2.54 cm, I have decided to
let xcircuit make the conversion of 1 grid space = 1/6
inch = 2/5 cm, with a default snap space of 1/12 inch
and 1/5 cm, respectively. This is equivalent to a
conversion factor of 1 in = 2.4 cm, which is off by a
"fudge factor" of 1.05833. This factor is made up in
the (user-transparent) scaling between xcircuit units
and PostScript units in the output, so that the size
measurements listed by xcircuit should be exactly equal
to the size measurements of the printed output.
So when a page is converted from inches to centimeters,
everything on the page is resized by the fudge factor.
If under odd circumstances, it is necessary to
maintain the exact size through the conversion, the
output scale (in the "write xcircuit postscript"
popup window) can be changed from 1 to the fudge
factor (or inverse thereof). Under normal circumstances,
however, the output is either Encapsulated Postscript,
in which the scaling is often relative to the document
in which it will be placed, or the drawing must be
rescaled anyway to adjust the fit between an A4 page
and a letter page.
When converting from inches to centimeters, the
definition of a "full page" of output (in the
"write xcircuit" popup window) is changed from letter
(8.5" x 11") to A4 (21cm x 27.4cm).
- Change Drawing Scale
Options->Grid->Grid type/display->Drawing Scale
The drawing scale is separate from the output scale: it
defines the ratio between measurements as printed in the top
right-hand corner message window and the actual measurements
of the printed output. For instance, if the drawing scale is
set to 10:1, then every 10 inches listed in the coordinate
position reporting window will be equal to 1 inch on the
printed page.
- Snap-to On/Off Options->Snap-to->Snap-to
Toggles visibility of the red dots which indicate the snap-to
points which keep elements on a linear positioning grid.
- Change Snap-to Spacing (+,-)
Options->Snap-to->Snap spacing
Alters the snap spacing. This should be altered only with
great caution! More useful are the key macros ``+'' and ``-''
which multiply the snap spacing by a factor of 2 and 1/2,
respectively. Additionally, the key macros may be used in the
middle of editing commands and active-grab moves for quick
positioning. Increase of snap spacing (``+'') during an active
grab is normally followed by the ``S'' key macro to reposition
the grabbed element on the new grid.
- Change Top-level Linewidth Options->Linewidth
- Alternate Color Scheme Options->Alt Colors
Color schemes are defined by the X-Defaults file. The X-Defaults
file which installs itself with xcircuit defines the normal
color scheme as black-on-white, and the alternative color scheme
as white-on-dark gray. Grid and axis colors are altered to match
the new scheme. The foreground of the color scheme corresponds to
the "default color" of the top-level page being viewed. As a
consequence, colors in a drawing other than "default" will remain
the same under the alternative color scheme.
- Add New Font Text->Font->Add New Font
Add a new font to the list. Because xcircuit draws its fonts by a
vectored method, it defines all of its own fonts as xcircuit files.
All fonts with defined vectors (Times, Helvetica, Courier, and Symbol)
are loaded on startup by default. Therefore, new fonts will have to
use one of the existing fonts for its vector description, and will not
correspond exactly to the output. Note also that XCircuit does not
actually define fonts in the output file, so any new font names declared
must be understood by the printer or viewer displaying the output file.
"Add New Font" can be useful on occasion to add ``Zapf Dingbats'' glyphs
to a file, for instance.
- Add New Color Options->Elements->Color->Add New Color
Add a new color to the list of colors. Colors may be specified by
name, corresponding to the usual ``rgb.txt'' file which comes with
X11 distributions, or they may be specified by component, in the
format "#RGB" where R, G, and B are hexidecimal numbers in the range
0x00 to 0xff, exactly two digits each.
- Manhattan Draw Style Options->Elements->Manhattan Draw
Polygons (wires) can be forced to adhere to vertical and horizontal
orientation by turning this option on. This style is enforced during
drawing, and is separate from the handling of polygons during editing
(see below).
- Polygon Edit Styles
Options->Elements->Polygon Edit->Manhattan Edit | Rhomboid X |
Rhomboid Y | Rhomboid A | Normal
Sets the behavior of xcircuit when polygons are being edited.
- Normal
- Any line segment may have any orientation.
- Manhattan
- All line segments are forced to have vertical or horizontal
orientation. Existing diagonal lines will remain diagonal
until edited into a manhattan orientation, at which point
they will be ``locked'' in that orientation.
- Rhomboid X
- Horizontal line segments are locked in orientation and length, but
all other lines may take a diagonal or vertical orientation.
- Rhomboid Y
- Vertical line segments are locked in orientation and length, but
all other lines may take a diagonal or horizontal orientation.
- Rhomboid A
- Vertical and horizontal line segments are locked in orientation
but may vary in length; diagonal segments are locked in length
but may vary in orientation.
- Key Macro Help Screen Options->Help!
Generate a simple window showing all of the key bindings in effect for
defined functions.
- Edit In-Place Options->Edit in place
When selected, all levels of the drawing hierarchy are drawn, regardless
of how far down in the hierarchy the current edit object is. Parts of
the drawing not in the current edit object instance or any of its
sub-objects are drawn in lightly, uncolored, in a light gray. This
can be very helpful when an object needs to be edited to match some
feature of the object in the hierarchy above it. If the non-edit
objects are visually distracting, the option can be turned off.
Note that in the original version of edit-in-place (xcircuit version
2.3.6), page orientation is always in the frame of reference of the
current edit object. The hierarchy above is rotated to match the
edit object, rather than the other way around. Problems with skewed
grid lines may make this difficult to implement the "natural" way.
- Show Pin Locations Options->Show Pin Positions
(Schematic capture system only) Show the location of pins which exist
below the current level of the hierarchy. Pin labels (text) are not
shown. The purpose is to show where wires need to connect to pins on
an object.
The following commands are available from the menu for loading and saving files:
- Load Xcircuit or LGF Files File->Read Xcircuit PS
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 "Add to Library" command (see below).
- Import Xcircuit File File->Import Xcircuit PS
Merges an XCircuit file with the current page.
- 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: Since XCircuit version 2.5.3, rev. 1, the PostScript
background renderer corrects for page scale and orientation. While
XCircuit does not (yet!) allow direct control over the background
position, rotation, and scale (things in XCircuit must be manipulated
to match the background, not the other way around), it can be assumed
that changes made in the file output dialog box will maintain the
relationship between the background and the xcircuit geometry as seen
on the page. Versions prior to 2.5.3r1 require that the page orientation
be set to ``Portrait'' and the output scale be set to 1.0 for the
final output to match what appears in the xcircuit window before saving.
- Add to Library File->Add To Library
If called from a library page, add the selected library (.lps) file
to the current library. Otherwise, the file will be added to the
"User Library" (last library page, by definition).
- Load New Library File->Load New Library
Create a new library page and load the selected library (.lps) file
to it. The library page will take the name of the file.
- Save Library File->Save Library
If called from a library page, will save the library page to a
(.lps) file. Otherwise, it will save the "User Library" page.
- Write Xcircuit File File->Write Xcircuit PS
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.
- Run a command script File->Execute script
This command reads in a script of commands matching the syntax
described below in "The XCircuit Command
Line" section.
- Clear Page File->Clear Page
Erases everything from the current page. This kind of delete
cannot be undone!
The following are properties of each xcircuit page. 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.
- Filename The file name to write to. The trailing ".ps" is
optional, though any alternative suffixes (such as ".eps") must be
included to override the default suffix ".ps". See the
item "saving multiple pages", below, for more information.
- Page Label This string names the object, and will also become
the label for the page in PostScript (this shows up, for instance, in
the page index for Ghostview). By default, the page label takes the
name of the filename, without prefixes or suffixes. In a multiple-page
file, any page name matching the file name will be appended with a
colon and the page number, such that there will be a unique label on
each saved page.
- Scale Page scale only affects the overall scale of the output.
The result of scaling is reflected in the X and Y sizes printed below
the scale. Changing any one immediately alters the others.
- X/Y Size The maximum width and height of the drawing on the
output page, as determined from the overall scale. X and Y cannot
be (and never should be!) altered independently.
- Orientation Toggles between "Landscape" and "Portrait".
- PostScript Mode Toggles between "Embedded (EPS)" and "Full Page".
"Embedded" is the same as "encapsulated" and would typically apply to
single-page figures to be incorporated into a document. Multiple-page
xcircuit files (for example, entire schematics) are "Full Page" by
definition, regardless of the mode selected, because encapsulated
PostScript is not particularly meaningful for multiple-page files.
By default, a full-page drawing is centered on the output page.i
However, this behavior can be subverted by drawing a box to act
as the figure's bounding box, and selecting
"Options->Elements->Border->Bounding Box" from the menu.
- Auto-fit This option is only available in "Full Page" mode.
When selected, the output will be automatically rescaled to fill the
output page (less 1-inch margins). Aspect ratio is preserved, so where
the figure width or hight is shorter than the maximum page width or
hight, the figure is centered on the output page.
- Saving multiple pages All pages in the current xcircuit
environment which have the same filename will be grouped together and
saved as a single xcircuit file. An exception is a circuit schematic,
in which the circuit hierarchy will be searched for all schematic
pages which are subcircuits of the page from which the "Write"
command was called. All subcircuit pages will then have their
filename entry changed to match that of the current page. Any other
pages having the same filename will also be saved. Multiple pages
are written in the order encountered, from Page 1 forward. Page
ordering can be altered from the page library using the "M" macro.
The existence of a
multiple page file and the number of pages is indicated by a check
box at the top of the output properties window. If the filename
of a multiple-page file is changed, the filename will be changed
for all of the pages in the file. To subvert this behavior and
separate a single page for saving/printing under a different
filename, click the check box. The filename will be reset to
a null string, which can be edited to indicate a unique filename
for the single page.
XCircuit has a (partially implemented) command-line feature intended to
duplicate the menu and keyboard functions in xcircuit. A command line
can be executed in three different ways:
- Read as part of the .xcircuitrc file on program startup
- Read as part of an executable script run from the menu selection
File->Execute script
- Entered directly into the message window as a result of typing
the "%" key macro.
The command line functions are written in Python, if Python has been
compiled into xcircuit. Whether this is true is indicated by the
command-line prompt when the '%' macro is chosen, which is a question
mark ('?') if the interpreter is the old-style xcircuit interpreter,
and the usual Python prompt ('>>>') if the interpreter is Python.
The old xcircuit command line syntax is as follows:
- override [default] option
Override system startup defaults. Necessarily, these commands
are only useful when included in the .xcircuitrc file,
and have no effect when run from the command line or executed
from a script. option can be one of:
- library
Don't load libraries from the startup script.
Libraries are expected to be listed individually using
the "library" command. No libraries are loaded otherwise.
Library elements will be loaded as usual into the "User
Library" page from input files.
- color
Don't use the pre-defined set of colors.
Colors are expected to be listed individually using the
"color" command. Necessarily for basic operation, black
and white will always be defined. Colors will also be
loaded as required from input files.
- font
Don't load fonts from the startup script. Instead,
a list of fonts is expected to follow with the
"font" command. Necessarily for basic operation,
one font will be loaded so that object names can be
listed. Other fonts will be loaded as required from
input files.
- enable | disable option
Where option can be one of:
- grid makes grid lines visible or invisible
- snap makes snap-spacing dots visible or invisible
- axis makes axis lines visible or invisible
- xschema turns the schematic capture system on or off
- toolbar turns the toolbar on or off
- set [default] option
Sets the designated xcircuit global (default) option. The keyword
"default" is redundant. option can be one of:
- font [fontname |
scale value]
Set the default font of fontname, which will be loaded
if it does not already exist in the list of fonts. The font
name incorporates font style (italic, bold) and encoding
(Adobe standard, ISO).
Or, set the default text scale to
floating-point value value.
- color colorname
Set the default drawing
color to colorname, which will be added to the color
list if it is not there already.
- colorscheme [normal | inverse]
Switch between the
normal (black-on-white) and inverse (white-on-black) color
schemes.
- boxedit [normal | manhattan | rhomboid-a |
rhomboid-y | rhomboid-x ]
Set the polygon
edit style to the specified type.
- linewidth value
Set the default linewidth
to the given floating-point value value.
Alternately, the set command sets the designated option for
the current page. The keyword "default" is redundant. Options for
new pages are taken from the first page. On program startup, the
current page is set to the first page, so this command acts on the
default page.
option can be one of:
- coordstyle [cm | in] Coordinate system is in inches
or centimeters
- orient [landscape | portrait] Landscape or portrait
orientation of output
- pagestyle [encapsulated | full] Encapsulated or
full-page PostScript output.
- gridspace value Grid spacing set to value.
- snapspace value Snap-to spacing set to value.
- library filename [number]
Add filename (a .lps file) to the User Library (default),
or to the library page designated by number. If the
designated library page does not exist, it will be created.
- font fontname
Add fontname to the list of known fonts. Preferably
there should be corresponding font encoding and vector files
for accurate character drawing, but this is not a necessity.
- color colorname | #RGB
Add color colorname to the list of known colors.
- beep [on | off]
Turn warning bell on or off.
The Python command line syntax accepts any valid Python code.
Special functions in the embedded interpreter, imported as a module,
link the Python interpreter to internal xcircuit variables. These
special commands are summarized in The Python
Interpreter page.
Note on Key Bindings: The new key bindings scheme includes a
difference from the original behavior. Originally, the
BackSpace and Delete keys were both interpreted
as "Delete". In the new key bindings scheme, only Delete
deletes the previous character, while BackSpace acts like
the left arrow cursor (moves one space to the left). If you prefer
the original behavior, it can be emulated with the following
commands (Python version) (to be put, for instance, in your
home .xcircuitrc file):
unbind("BackSpace", "Text Left")
bind("BackSpace", "Text Delete")
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.
A summary of the syntax for all element types in the PostScript output file
can be found here: XCircuit PostScript reference.
- Simple elements
- Polygon
- Arc
- Curve
- Text
- Object instance
- Composite elements
- Select box
- Button 2 Tap
- Button 1 Grab
- Un-selecting
- The Delete stack
- Page buffers
- The edit stack
- The matrix stack
- Page Label
- General Messages and Command-Line prompt window
- Cursor Position
- xcircuit*foreground : Black
- xcircuit*background : White
- xcircuit.foreground : Black
- xcircuit.background : White
- xcircuit.gridcolor : Gray95
- xcircuit.snapcolor : Orange
- xcircuit.selectcolor : Gold3
- xcircuit.querycolor : Turquoise
- xcircuit.axescolor : Antique White
- xcircuit.offbuttoncolor : Gray30
- xcircuit.auxiliarycolor : Green3
- xcircuit.barcolor : Tan
- Alternate color scheme
- xcircuit*font : *times-bold-r-normal--14*
- xcircuit.width : 950
- xcircuit.height : 760
- xcircuit.geometry : 950x760
- xcircuit.borderWidth : 2
- xcircuit.borderColor : Red
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:
- xcircps2.pro PostScript Prologue
The file of PostScript definitions prepended to every saved
file.
System startup files:
- startup.script or xcstartup.py Startup script
The master list of fonts and libraries to load on program startup.
Which one is used depends on whether the source was compiled with
the Python interpreter enabled.
- .xcircuitrc Secondary startup script
Commands to run on startup. The syntax of this file depends
on whether the source was compiled with the Python interpreter
enabled.
The difference between ".xcircuitrc" and "startup.script" 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. "startup.script"
always runs, although default libraries and fonts listed therein can
be forcibly ignored by the user with the "override" command. Thus, it
is recommended that "startup.script" restrict itself to loading fonts
and libraries, and that ".xcircuitrc" be used for all other commands,
unless the administrator has totalitarian tendencies and wishes to force
a consistent interface among users, such as for an instructional course.
The following files are loaded by default.
- generic.lps
Generic elements pertaining to all schematic types:
jumper, dot, circle (port), arrow and arrowhead
- analog.lps
Basic analog circuit components.
- digital.lps
Basic digital circuit components (logic gates).
- avlsi.lps
Special circuit components from "Analog VLSI and Neural Systems"
(Carver Mead): Simple and wide-range amplifiers with bias port.
- analoglib2.lps
Analog circuit elements with parameterized values for SPICE and
sim netlist output.
The remaining files are put in the system library for access if warranted;
they may be added, for instance, to the system "startup.script" file.
- signal.lps
Simple elements for signal flow diagrams
- musiclib.lps
Library of elements for music typesetting
- lgf.lps
Library of elements for loading ".lgf" files from program analog
(diglog).
As listed for automatic loading in the default startup script.
- helvetica.lps
- helveticaiso2.lps
- times_roman.lps
- times_romaniso2.lps
- courier.lps
- courieriso2.lps
- symbol.lps
As listed for automatic loading in the default startup script.
- helvetica.xfe
- helveticaiso.xfe
- times_roman.xfe
- times_romaniso.xfe
- courier.xfe
- courieriso.xfe
- symbol.xfe
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.
- helveticaiso2.xfe
- times_romaniso2.xfe
- courieriso2.xfe
- helveticaiso5.xfe
- times_romaniso5.xfe
- courieriso5.xfe
PostScript is a registered trademark of
Adobe, Inc.
Back to the xcircuit home page. . .
email: tim@bach.ece.jhu.edu