1
.TH XCircuit 1 "January 5, 2000" "X11R6"
3
xcircuit - Draw circuit schematics or almost anything; make
4
circuit netlists from schematics.
6
.B xcircuit [\fIfilename\fP[,...]]
8
The program xcircuit is a generic drawing program tailored
9
especially for making publication-quality renderings of
10
circuit diagrams (hence the name). The output is pure
11
PostScript, and the graphical interface attempts to maintain
12
as much consistency as possible between the X11 window
13
rendering and the final printer output.
15
\fIxcircuit\fP is mouse, menu, and keyboard\-driven, with the emphasis
16
on single-character keyboard macros.
19
.B \fIfilename\fP[,...]
20
Begin running xcircuit by loading in the PostScript file
21
filename. If filename does not have a .ps extension,
22
xcircuit will attempt to look for both the filename
23
as entered and, upon failure, with the .ps extension.
24
The file must be in xcircuit `format'. \fIfilename\fP
25
may also be a comma-separated list of files.
28
There are five drawing elements. These are as follows:
31
polygon (multiple lines which may or may not be closed and filled)
34
arc (ellipse segment which may be closed and/or filled as above)
40
curve (based on the PostScript "curveto" algorithm)
43
object instance (see below)
45
There are two composite elements, which are:
48
path (a connected series of polygons, arcs, and curves)
51
object (something containing polygons, arcs, labels,
52
curves, paths, and instances of other objects)
55
The mouse button system, the object library, and the paged buffer
56
system are loosely based on the
57
Caltech circuit-simulation program "log" (either "analog" or "diglog").
59
The general idea is to make the most commonly-used functions the
60
easiest to perform, and (to the extent possible) to scale (inversely)
61
the complexity of performing a function with the frequency of that task.
62
Because this program is tailored to circuit drawing, the most common
63
functions are drawing lines and moving object instances. The next most
64
common function is selection of elements singly or in groups.
66
Mouse button 1 can be tapped to start a connected chain of lines, the
67
most common drawing function. In addition, button 1
68
has a function called "grab", which occurs after the button has
69
been continually pressed for a short length of time (about 1/5 second).
70
As the name implies, "grab" grabs hold of an element which can then
71
be moved around the screen.
73
Button 2 can be used to select an item if tapped, and if pressed
74
and held down, a box will be drawn and everything inside that box
75
selected when the button is released. In all other cases, button 2
76
will complete a command. For users who have only two mouse buttons
77
and do not emulate the middle mouse button with the combination of
78
buttons 1 and 3, use the combination of the Shift key and mouse
79
button 1 to emulate mouse button 2.
81
Button 3 will normally abort a command. During editing of an arc,
82
spline, or polygon, button 3 will revert back to the previous form,
83
or abort if there is no remaining edit history.
85
All other commands are
86
available from the pulldown menus and/or from the keyboard using
87
single-key macros (with easy-to-remember mnemonics).
88
Keyboard commands are quicker, since they act on the present cursor
89
position, whereas menu commands require an extra step.
92
The library is intended to provide a convenient way to store and
93
retrieve elements of a picture which will be used more than once.
94
For the application of circuit drawing, a built-in library provides
95
basic objects such as transistors, amplifiers, resistors, capacitors,
96
arrows, circles, power and ground symbols, and the like. This file
97
is a composite of several library files (such as "builtins.lps",
98
"analog.lps", and "digital.lps") which are called by the startup
100
ifelse(HAVE_PYTHON,1,`("xcstartup.py")',`("startup.script")')
101
The program first looks for the startup script in
102
the current directory, and then searches in the directory given by
103
the environment variable "XCIRCUIT_LIB_DIR", and finally, in the
104
hard-coded global directory (LIBDIR) if it could not find it elsewhere.
105
Thus each user can add to or modify the file of builtins to reflect
106
personal taste. Since the PostScript output contains all object
107
definitions, these changes to the built-in functions are inherently
108
transferrable. Xcircuit will automatically resolve conflicts between
109
objects having the same name but different contents.
111
The library is accesible from the pull-down menu or with the "l"
112
keyboard macro. When inside the library, clicking the first mouse
113
button on an object "grabs" that object and returns the graphics
114
state immediately to the page being edited, so that the object
115
will be placed when the mouse button is released.
118
Xcircuit has unconstrained zooming and snap-to positioning. Objects
119
scale completely: line widths and text sizes will increase/decrease
120
proportionally with the zoom, as well as dot/dash spacing and all
121
other features. Xcircuit does have a minimum integer grid in
122
coordinate space, which translates to 0.005 inches at an output scale
123
of 1. The maximum zoom scale gives a screen size translating to
124
about 100 by 100 inches at an output scale of 1. The effective
125
scale can be varied by changing the output scale (reached from the
126
"File/Write" menu selection) in order to fit a drawing to a page or
127
to get a grid matched to a specific dimension. A separate scale
128
parameter changes the scale of the reported position relative to
129
the output scale (as it will appear on a printed page).
132
The snap-to grid is an all-important feature for circuit drawing,
133
wherein it is critical that elements line up properly with one another.
134
In \fIxcircuit\fP, there is no way to get off the snap-to grid except by
135
turning the snap function off and physically pushing elements off
136
the grid. Generally, it is most convenient to leave the snap functon
137
on and use key macros "+" and "-" to double/halve it as necessary.
138
In any case, objects can always be returned to the snap grid with
139
the "snap" function (key macro "S").
141
.SH SELECTION MECHANISM
142
Objects are selected using a variety of search methods. The
143
select box (formed by holding down mouse button 2 and dragging
144
the pointer) uses the simplest method, searching for
145
curve/polygon segment endpoints, arc centers, and label
146
and object bounding boxes falling within the select box frame.
147
General object selection is more complicated. Polygons, Arcs,
148
and Curves are selected by their outer edges, not the interiors.
149
Currently this is also true for filled instances of those types.
150
A line is selected if the pointer is in a
151
region describing a box around it, which is adusted according
152
to the scale (zoom factor). Every object has an
153
associated bounding box, which is rectangular but may be rotated
154
with respect to the top level window. An object instance is
155
selected if the pointer falls within its bounding box. Each
156
label also has a bounding box carefully calculated from the width
159
Often the selection mechanism will find multiple elements in
160
range of the pointer. In this case, each object in turn will be
161
presented, colored in blue (or the specified "querycolor" in the
162
defaults file), and the user has the option of accepting the
163
highlighted element for selection using the mouse button 1, or
164
rejecting it with mouse button 3. When all the elements under
165
consideration have been accepted or rejected, the program
166
proceeds to execute whatever function was in progress. This
167
selection method takes a little while to get used to, but is
168
sensible and seems to work well.
171
Color in xcircuit is implemented with the idea of "color inheritance".
172
Every page has a "default color" of black. All elements which have
173
color value "Inherit" will inherit the default color, black. If an
174
object instance is painted blue (for instance), all components in
175
that object which have color value "Inherit" will inherit its color,
176
blue. The reason for this is that it allows different object
177
instances to be painted different colors (such as if one part of
178
a circuit is highlighted for emphasis), while making it possible for
179
object instances to be multicolored, if necessary. Changing the
180
color of an object instance will have no observable effect on the
181
drawing if none of the components of the object inherit that color.
182
An object may have both normally colored components and components
183
which inherit their color, in which case only those components with
184
the "Inherit" value will change color when the color of the object
187
.SH SCHEMATIC CAPTURE
188
XCircuit implements a sophisticated schematic capture. Unlike
189
virtually all schematic capture software currently available,
190
xcircuit allows the designer to draw the circuit in a "natural"
191
way, making use both of schematic hierarchies and simple
192
hierarchies created simply by grouping elements together. If
193
the chosen netlist `format' is hierarchical (like SPICE), both
194
hierarchical forms will be retained in the output. For element
195
grouping, input/output ports connecting into to the group will
196
be determined automatically, from context. A schematic capture
197
tutorial is available from the xcircuit website,
199
http://xcircuit.ece.jhu.edu/tutorial/tutorial2.html.
202
Netlist types currently available are "SPICE", "sim", and "PCB".
204
.SH KEYBOARD COMMANDS
207
\fBBasic keyboard commands:\fP
210
Zoom in by a factor of 3/2. If this key is pressed while a
211
selection box is active (created with the middle mouse
212
button), then acts like Zoom Box function.
215
Zoom out by a factor of 3/2.
218
Pan the screen so that the point under the mouse is brought
219
to the center of the program window. This function can also
220
be conveniently performed by clicking on the scrollbars.
221
The scrollbars cannot be moved continuously due to the slow
222
time for screen refresh.
225
The arrow keys perform a pan of one-half window size in the
226
direction of the arrow pressed.
229
Go to the Library of built-in objects. From the library,
230
use mouse button1 to grab an object and bring it back to
231
the edit screen, or button3 to return without selecting
232
an object instance. While in the library screen, the
233
zoom and pan functions can be used to move around.
236
Push into an on-screen object in order to edit that object
239
Return from editing an object. Object pushes and pops can
240
be stacked indefinitely.
246
Switch to one of the first ten editing pages. Pages greater
247
than 10 can be reached from the "Window/Goto Page" menu
251
Change snap-to grid spacing by a factor of two up or down.
254
(Bar, colon, and underline) Change style on the currently
255
selected object to dashed, dotted, and solid, respectively.
258
Print a help page summary of commands
261
\fBCommands to create elements:\fP
264
Arc. Center is fixed at the initial position of the cursor.
265
The mouse position changes the radius of the circle.
266
In snap-to mode the arc boundry will pass through the snap point
267
closest to the cursor. Mouse button 1 cycles from controlling
268
the radius to controlling the starting point, the ending point,
269
and separately controlling the minor axis to create ellipse.
270
Mouse button 2 completes the arc.
273
Box. This is a convenience function for generating rectangular
274
closed polygons. Creates a rectangle with one corner fixed at
275
the position of the cursor. Subsequent movement of the cursor
276
defines the point diametrically opposed. Mouse buttons 1 or 2
280
Spline curve. The first endpoint is defined by the initial cursor
281
position. Mouse position adjusts the other endpoint of the curve.
282
Mouse button 1 cycles from controlling position of the endpoint
283
to controlling positions of the curve control points and the curve
284
starting point. Mouse button 2 completes the curve.
287
Text. Text starts out justified according to the styles chosen
288
in the pull-down menu. Text can be rejustified using the menu
289
or by typing the numbers on the keypad (\fBshift-keypad-1\fP through
290
\fBshift-keypad-9\fP). The position of the keys on the keypad
291
matches the justification. Subscripts, superscripts, font
292
changes, text size changes, underlining, and overlining are all
293
available from the pull-down menu. Text edit mode recognizes
294
\fBHome\fP and \fBEnd\fP keys to move to the beginning and end
295
of the string, respectively. If the X11 environment maps
296
control key sequences to character encodings (such as ISO-Latin1),
297
these may be used to insert non-ASCII text. Another method of
298
inserting non-ASCII characters is the use of the backslash
299
character, which duplicates the action of the
300
Text/Insert/Character menu button.
303
Make object. Takes all the elements currently selected and
304
compiles them into an object. The object is then placed in the
305
user library. The elements just selected are deleted from the
306
screen and replaced by the new object. The center point of the
307
resulting object is chosen as the closest snap-to point to the
308
center of the object's bounding box; if another center is desired,
309
then the object can be edited using the ">" command and its contents
310
moved with respect to its origin. \fINote:\fP Objects cannot have
311
the same name as PostScript commands or have the same name as any
312
other object in memory. If such a name is found, an underscore ("_")
313
will be prepended to the name as many times as is necessary to
314
differentiate it from all other known objects.
315
The name also cannot contain special PostScript characters such as
316
slash; any such characters found will be replaced with underscores.
319
\fBMajor editing commands:\fP
322
Delete. Select the nearest element or elements and delete it/them.
325
Undelete. Xcircuit saves up to 10 delete events to be recovered.
326
Delete events are stored in order of occurrence, and the most
327
recent delete event is the first to be recovered.
328
When multiple elements are deleted at the same time, all of them
329
are stored as one delete event, and restored together.
332
Deselect. Elements which have been selected can be deselected on
333
a per-item basis. In order not to be too confusing, deselect does
334
not query if multiple items are found under the cursor; it just
338
Copy. Make a copy of the object(s) nearest the cursor. Object
339
is automatically grabbed for moving to a new position. The
340
next button1 or button2 press will place the element. Button2
341
will end the copy, and button1 will continue the copy function.
344
Edit. The action of Edit is dependent on the type of element
345
selected. These are detailed below:
348
Returns to text editing mode, starting with the cursor
349
at the end of the string. Mode is like regular text entry
350
except that Button 3 returns text to its original string.
353
Grabs one point of a polygon for repositioning. Button 1 cycles
354
between points, button 2 accepts the new polygon, and button 3
355
returns to the previous state, unless there is no remaining edit
356
history, in which case it aborts the command.
357
Key macros available during polygon edit are:
359
"x"---Breaks the polygon at the given point.
361
"e"---Moves edit position to the next point.
363
"i" or "Insert"---Inserts a new point at the position.
365
"d" or "Delete"---Deletes the current edit point.
367
There are four modes for polygon editing; see the
368
"\fBPolygon Edit\fP" section below for details.
371
Allows resizing of the radius. Mouse button 1 or the "e" key
372
will cycle between control of the radius, the endpoint angles,
373
and the ellipse minor axis. Mouse button 2 accepts the new
374
arc. Button 3 returns to the previous editing state,
375
unless there is no remaining edit history, in which case it
379
Allows repositioning of one end of the curve.
380
Originally, the starting angle of the curve is kept fixed.
381
Mouse button 1 or the "e" key cycles between the four
382
control points of the curve, allowing control over the
383
angle of the curve at its endpoint and the shape of the
384
curve. Mouse button 2 accepts the new curve. Button 3
385
reverts back to the previous edit state
386
unless there is no remaining edit history, in which case
387
it terminates the command.
390
Object instances have no properties to change
391
except scale, and do not respond to the "edit" command.
392
Scale can be changed by selecting "Options/Other/Object Size"
396
\fBMinor editing commands:\fP
399
Rotate the selected element(s) or element under the cursor
400
counterclockwise in 15 degree intervals.
403
Rotate the selected element(s) or element under the cursor
404
clockwise in 15 degree intervals.
407
Rotate the selected element(s) or element under the cursor
408
counterclockwise by 5 degree intervals. This is currently
409
the smallest angle resolution available to xcircuit.
412
Rotate the selected element(s) or element under the cursor
413
clockwise by 5 degree intervals.
416
Flip an element around a vertical axis defined by an object's
417
origin for an object instance, or across an axis defined by
418
the pointer position for arcs, polygons, and curves.
421
Flip an element around a horizontal axis defined
422
similarly to the "f" command.
425
If two elements are selected, their order is exchanged
426
(this is only relevant if one element occludes another).
427
If one element is selected, it is raised up one in the
428
stack, and if it is already on top of the stack, it is
429
shuffled to the bottom.
432
Snap the nearest object to the snap-to grid. For
433
curves the control and endpoints are snapped; for polygons, each
434
point is snapped; for arcs, the centerpoint is snapped; for labels
435
and object instances, the designated point of origin is snapped.
438
Join polygons together. This only makes sense if it is possible
439
to make a single continuous (open or closed) polygon from the
440
selected parts. Otherwise a warning will be posted and the parts
441
will remain separate.
444
Attach an element to a polygon, arc, or curve.
445
The element to be attached must be the one currently grabbed
446
(either by a "drag", copy command, or edit command).
447
Until it is released, it will be forced to align
448
its center (object, arc), endpoint (polygon, curve), or
449
position (label) with the closest polygon, arc, or curve.
450
Note that this is a very powerful tool for generating, for
451
example, lines tangent to a curve, or objects arranged in
452
a circle or along a line.
455
\fBLibrary editing commands:\fP
458
Delete. The selected objects will be deleted from the library
459
unless other library objects or pages contain references to that
460
object. \fBNote:\fP Unlike deleting object instances with the
461
"\fBd\fP" command, this command deletes the actual object and
462
releases all memory associated with that object, so the
463
object cannot be undeleted.
466
Copy. Makes a copy of an object from either library page and
467
places the new copy in the user library. The new object will
468
be renamed to avoid naming conflicts.
471
Move. If one object has been selected, it is moved to the
472
position of the cursor. If two objects have been selected,
473
their positions in the library are exchanged.
476
Edit label. Edit the object name whose label is under the
477
cursor. After editing, the object name will be checked for
478
conflicts with other object names, and altered if necessary.
481
Hide object. If the object is a sub-instance of another object,
482
but is not meant to be used by itself, it can be "hidden" so
483
that it will not appear by itself on the library page.
488
.B Write Postscript (W)
489
This command brings up a popup menu with a number of options.
490
First, it gives the name of the file if one exists, or else it
491
gives the default name of the buffer (usually \fBPage\fP \fIn\fP,
492
where \fIn\fP is the number of the buffer).
493
Next, it gives a preview of the picture scale and output
494
styles, which include Landscape/Portrait orientation and
495
Encapulated/Unencapsulated (full page) PostScript modes.
496
The former allows adjustment of the nominal size of the picture
497
when drawn in PostScript. The default scale is 1.00, which
498
makes the text scale of 1.0 about 14 points on the PostScript
499
page. The width and height of the resulting
500
picture are also given, in inches, and any of the three
501
values can be changed. The values of the other two will
502
be updated accordingly. Pages which have the same name
503
will be grouped together into a single file, allowing
504
multiple pages to be stored in the same PostScript file.
505
However, as Encapsulated PostScript does not make sense
506
for this kind of file, it is not an option.
508
The \fBWrite File\fP button writes the current page to an
509
output file. If the page has a name other than the default,
510
the file will automatically be saved under that name. Otherwise,
511
it is necessary to change the name of the buffer. If a file of
512
that name already exists on the disk, the button will read
513
\fBOverwrite File\fP.
516
Reads in a file of Xcircuit `format'. The
517
file name is requested by a popup prompt, and an extension
518
of ".ps" will be added if necessary. The file is read
519
into the current page, which is cleared first if anything
520
is in it. If the file is a multiple-page file, the current
521
page will be overwritten with the first page from the file,
522
but other pages will be loaded into empty buffers.
523
ifelse(LGF,1,`Xcircuit can also read "lgf"-`format' files from
524
the Chipmunk CAD tools programs "analog" and "diglog".',`')
527
Acts like "Read PostScript" except that the page is not
528
reset first, so graphics are added on top of existing
529
graphics on the page.
532
Clears the current page of all elements and resets the
533
name. The contents cannot be recovered.
536
Switches between the two xcircuit color schemes. The
537
color schemes can be redefined through XDefaults
538
(see below). The default color schemes are black-on-white
539
and white-on-black. The latter is less straining to the
540
eyes, but the former matches the black ink on white paper
541
PostScript output. Any color scheme other than black-on-white
542
is not recommended for drawings with color, as the actual
543
output does not match the observed xcircuit screen.
546
Turns the grid lines on and off.
549
Turns the axis lines on and off. The axes mark the
550
origin (0,0) of the page. On the top level (TopObject),
551
the origin has no particular relevance, since encapsulated
552
output will define its own boundaries, and full-page
553
(unencapsulated) output will be centered on the output
554
page, not according to the Xcircuit coordinate system.
557
Changes the spacing of the grid lines.
558
Default spacing is 1/6 inch, which is about
559
the width of the letter 'W' in default text scale.
562
This is a submenu allowing the coordinates and coordinate
563
grid to be specified in alternate units. Listing of
564
coordinates in the top window can be in default fractional
565
inches, decimal inches, or centimeters. Default spacing
566
of grid lines is either one-quarter inch or one-half
567
centimeter. Selecting an A:B scale With option
568
"\fBDrawing Scale\fP" causes all listed coordinates to be
569
multiplied by the scale. \fINote:\fP Xcircuit will make
570
an attempt to keep objects on the snap/grid spacing when
571
switching between inch and centimeter scales. In order
572
to do this, it will change the output scale by the ratio
573
of 2.54 to 2.5, thus keeping a closer correspondence between
574
inches and centimeters. To get true centimeters on the
575
output page, the output scale (from the "File/Write Xcircuit PS")
576
can be reset to 1.0 at the expense of having all objects
577
intended for the inch grid displaced off of the snap grid.
580
Turns the snap-to grid on and off. When the grid
581
is on, movement and placement of elements is restricted
582
to points on the snap-to grid.
585
Determines the spacing of the points in the
586
snap-to grid. Default is 1/12 inch, which is half
587
the grid line spacing.
590
Controls the default linewidth against which
591
all linewidths in the drawing are scaled.
594
The options in this submenu control how the position of
595
lines are affected when a point in a polygon is selected
596
for editing. "\fBRhomboid-X\fP" mode moves adjoining
597
points as necessary to keep all horizontal lines horizontal;
598
"\fBRhomboid-Y\fP" mode acts similarly to keep all vertical
599
lines vertical. "\fBRhomboid-A\fP" is similar to Manhattan
600
mode but also tracks non-Manhattan lines.
601
The default mode is "\fBManhattan Box Edit\fP",
602
which is a combination of Rhomboid-X and Rhomboid-Y. In
603
"\fBNormal\fP" mode, only the point being edited can be moved.
605
.B \fPArc/Box/Curve\fB Border
606
The options under this menu determine the
607
border style of arcs, polygons, and curves. If an element
608
is selected, it will be modified; otherwise, if
609
no objects are selected, the style chosen is made
610
default for all subsequent arcs, polygons, and curves.
611
Elements may be drawn with or without borders (but
612
for obvious reasons cannot be made both borderless
613
and unfilled, which would be invisible)
614
The borders may be closed or unclosed. For an arc,
615
closed means that a chord is drawn connecting the two
616
endpoints, if the beginning and ending angles do not
617
complete a full circle. Borders may be solid, dashed,
618
dotted, and of varying width.
620
.B \fPArc/Box/Curve\fB Fill
621
The options under this menu determine the
622
fill style of arcs, polygons, and curves.
623
Fill style may be solid, empty, or one of 7 stipple
624
patterns varying from light to dark, which are drawn
625
both in xcircuit and PostScript as stipple patterns.
626
Stipples can be transparent or opaque.
627
\fIWarning\fP: Transparent
628
stipples are NOT inherent to PostScript and the hacks
629
necessary to implement them cause slow rendering on
630
a printer or PostScript previewer. Due to the
631
device-dependent nature of the routines, patterns
632
will look abnormally large on PostScript previewers.
633
This transparancy feature has been added with the
634
expectation that most circuit schematics will not
635
rely heavily upon halftoning. Complicated color
636
patterns can be created using transparent colored,
637
stippled elements on top of solid-color elements.
638
\fINote\fP: Ordering of elements is according to
639
order created. A different ordering can be achieved
640
using the "\fBX\fP" (exchange) command. This method
641
is not especially easy to work with, and hopefully
642
something better will be implemented in the future.
644
.B \fPArc/Box/Curve\fB Color
645
See the COLOR section above for a discussion of color
646
inheritance. This menu shows all the colors available
647
to xcircuit with the option of adding more colors.
648
Currently the entry style for colors is by name or by
649
RGB content in the X11 style of #rrggbb where rr, gg,
650
and bb are hex values ranging from 00 to FF. The only
651
limit to the number of colors is the X Server's colormap
652
depth. If the colormap is full, xcircuit attempts to
653
allocate the closest possible color to the one requested.
656
This zoom feature requests the user to create a box
657
(using either mouse button 1 or 2, expanding the box
658
while holding down the button). When the button is
659
released, the view will zoom to the area of that box.
662
This zoom feature calculates the bounding box
663
of the entire picture and adjusts the scale to make
664
it fit comfortably inside the program window.
666
Xcircuit's ability to handle text is arguably the
667
most complicated part of the program, and also of
668
the PostScript output. Careful attention to text
669
justification and style is the key to a good drawing.
672
Alters the size of the labels. The value is
673
a scale, with a default of 1.0 which translates to
674
14 points on the PostScript page if the default page
675
scale of 1 is used. If a label is selected, only that
676
label is affected. If a label is being edited, scale
677
changes starting at the edit position. Otherwise, it
678
becomes the default size for all subsequent labels. Size
679
affects the entire text string. Text size can be changed
680
anywhere inside of a string. However, text sizes inside
681
a string are all given relative to the label size, not as
682
an absolute point size. Sizes of subscripts and superscripts
683
are given relative to the natural size of the subscript or
684
superscript (2/3 the size of the text for which it is a
688
Standard printer fonts Times-Roman, Helvetica,
689
Courier, and Symbol, are readily available.
690
"User-defined" fonts can also be added; however,
691
support is currently limited, and requires a font
692
object (.lps) file and encoding (.xfe) file,
693
examples of which are found in the fonts subdirectory
694
of the xcircuit library directory.
697
Four standard font styles are available,
698
matching the standard printer font variations: Normal,
699
Italic (or oblique), Bold, and BoldItalic.
700
PostScript matrix manipulation allows slanted versions
701
of any font, such as Symbol, for which none is otherwise
705
The Insert menu allows insertion of special characters
706
which are otherwise not (necessarily) allowed from the
707
keyboard. These include tab-stop, tab-forward, tab-backward,
708
kern, half-space, quarter-space, and "Character". The latter
709
option brings up a page showing the 256-character encoding
710
vector for the font, allowing point-and-click entry of any
711
character in the font. "Kern" instructions allow characters
712
to be offset vertically or horizontally relative to the rest
715
.B \fPText\fB Encoding
716
Two standard font encodings are available by default,
717
Standard (Adobe) Encoding, and ISO-Latin1 encoding.
718
ISO-Latin2 and ISO-Latin5 encodings exist in the
719
library directory, but require the use of the program
720
"ogonkify" (not included) to produce correct output on
723
.B Super and Subscripts
724
Superscript and subscript are
725
designed to closely match those in TeX output, though
726
they lack the proper context-dependent kerning and
727
other fancy features of TeX. A superscript following
728
a subscript results in a superscripted subscript.
729
To get a superscript on top of a subscript, use the
730
backspace character (see below).
731
The Normalscript style is the way to get
732
out of a sub or superscript and return to the normal
734
Quick super/sub/normalscripting is available from the
735
keypad with the "\fB+\fP" (plus), "\fB-\fP" (minus),
736
and "\fBEnter\fP" keys, respectively.
738
.B Overline and Underline
739
Overlining and underlining styles
740
remain in effect until the next occurrence of a style
741
or font change. Overlining is
742
lower if all the characters are lowercase and do not
743
include the "tall" lowercase characters. Overlining
744
or underlining can be stopped at any time using the No
745
Line style. Over and Underlining is *always* preferable
746
to using a line. PostScript will adjust the over or
747
underline to the text size and extent and actually grab
748
the "_" character and compute its thickness in order to
752
From version 2.3, xcircuit allows embedded tab stops.
753
Tab stops must be defined before using tab-forward or
754
tab-backward. The "Tab" keyboard key inserts an
755
embedded tab-forward instruction into a label. Tab-stop
756
and tab-backward can be inserted using the Text->Insert
757
menu. A tab-forward instruction moves the cursor
758
to the first defined tab stop forward of the current
759
position. A tab-backward instruction moves the cursor
760
to the first defined tab stop backward of the current
761
position. If no appropriate tab stop exists, the
762
instruction has no effect.
765
The use of the backspace character is deprecated from
766
xcircuit version 2.3. The effect of an embedded backspace
767
is more reliably produced using tab-stop and tab-backward.
769
.B Halfspace and Quarterspace
770
These options allow fine control over spacing, particularly
771
useful when writing equations.
774
Text justification always starts with the
775
default, chosen from the options in the menu, but may
776
be changed at any time using the numbers on the keypad.
777
The position of the keys on the keypad reflect the
778
point of justification: 1, 4, and 7 are right-justified,
779
7, 8, and 9 are bottom justified, 5 is centered in both
780
directions. Since the letters drawn by xcircuit are
781
optimized for the Helvetica font, correct justification
782
is the main way to get text to come out on the PostScript
783
page in the desired way, relative to objects or boxes or
786
Certain parameters of the xcircuit program can be
787
initialized from a file called \fB.xcircuitrc\fP, which
788
is first searched for in the current directory, and then
789
in the user's home directory as defined by the environment
791
ifelse(HAVE_PYTHON,1,`The XCircuitrc file is written in
792
Python (see www.python.org), with certain commands whose
793
main purpose is to transfer data structures between
794
the Python interpreter and XCircuit.
795
These commands are as follows:
797
.B library("\fIlibname\fP" [, \fInum\fP])
798
Loads a library named \fIlibname\fP (with or without .lps
799
extension) into the set of built-in objects. \fInum\fP,
800
if specified, puts the specified library onto library page
801
\fInum\fP (starts at 1).
803
.B override("library")
804
Causes the default libraries defined in "builtins.lps"
805
\fInot\fP to be loaded.
807
.B override("colors")
808
Causes the default colors \fInot\fP to be loaded; this will
809
not override the allocation of black and white, however,
812
.B font("\fIfontname\fP")
813
Adds a font named \fIfontname\fP (as recognized by a
814
printer) to the menu of selectable fonts.
816
.B color("\fIcolorname\fP")
817
Adds a color named \fIcolorname\fP (standard X11
818
conventions) to the menu of selectable colors.
820
.B bind("\fIkey\fP", "\fIfunction\fP")
821
Binds the key (or button) named \fIkey\fP to the function named
822
\fIfunction\fP. If only one argument is given, it can be
823
either a key name or a function name, and bind() returns
824
the associated binding(s). If no argument is given, then
825
bind() returns a dictionary of all key bindings.
826
Valid function names are listed in section "KEY BINDINGS" below.
828
.B unbind("\fIkey\fP", "\fIfunction\fP")
829
Unbinds the key (or button) named \fIkey\fP from the function named
831
Valid function names are listed in section "KEY BINDINGS" below.
833
.B set("\fItype\fP", "\fIvalue\fP")
834
Sets internal xcircuit variables, where \fItype\fP can be one of:
838
Where \fIvalue\fP is one of "manhattan", "rhomboid-x", "rhomboid-y",
839
or "normal". Determines the default way manhattan-aligned polygon
840
edges are manupulated during edits.
844
Where \fIvalue\fP is a real number indicating the default
847
set("\fBbeep\fP", "on"|"off")
849
Where \fIvalue\fP can be \fBon\fP or \fBoff\fP, depending on
850
whether or not you want the machine beeping at you when it
851
gives critical warnings.
853
set("\fBcolorscheme\fP", "normal"|"inverse")
855
Where \fIvalue\fP is \fBinverse\fP to swap the two color schemes
856
and make the second scheme appear as default.
858
\fIh\fP = newelement("\fIname\fP")
860
Creates a new element and returns a handle (pointer) \fIh\fP to it which
861
can be used to get and set element attributes. Valid names are
862
"Arc", "Spline", "Polygon", "Object Instance", "Label", and "Path".
864
\fId\fP = getattr(\fIh\fP)
866
Creates a dictionary \fId\fP of attributes for the element with handle
867
\fIh\fP. Dictionary keys depend on the element.
869
setattr(\fIh\fP, \fId\fP)
871
Applies the dictionary \fId\fP key:value pairs to the element pointed to
874
\fId\fP = getpage(\fIvalue\fP)
876
Returns a dictionary \fId\fP containing information about the page \fIvalue\fP.
877
If \fIvalue\fP is not specified, returns information about the current page.
878
The dictionary includes a list "\fIparts\fP" of handles to every element drawn
879
on the indicated page.
881
\fId\fP = getlibrary(\fIname\fP)
883
Returns a dictionary of objects for the indicated library,
884
referenced by \fIname\fP, or by page number. The dictionary contains a
885
list "\fIobjects\fP" of names of every object in the library.
887
\fId\fP = getobject(\fIname\fP)
889
Returns a dictionary containing all information about an object, which
890
is referenced by \fIname\fP. The dictionary contains keys "\fIname\fP",
891
containing the object name, "\fIwidth\fP" and "\fIheight\fP", a
892
list "\fIparts\fP" containing handles to each element comprising the
893
object, and a list "\fIparameters\fP" containing all the parameters
894
defined for the object and their default values.
898
Zooms by amount \fIfactor\fP. Values greater than 1 indicate a zoom in;
899
values less than 1 indicate a zoom out.
903
Centers the screen on the (user) coordinate \fIposition\fP, which can be
904
either a (X,Y) tuple or two integers X, Y.
908
Refreshes the screen. The screen is automatically refreshed after every
909
Python command, but the \fBrefresh()\fP function can be used along with the
910
\fBpause()\fP function for animation effects.
914
Pauses for \fIdelay\fP seconds (is a floating-point number). Useful in
915
conjunction with \fBrefresh()\fP for animation effects.
917
\fIt\fP = getcursor()
919
Returns a tuple \fIt\fP containing the current X and Y position of the cursor.
922
\fIt\fP = getwindow()
924
Returns a tuple \fIt\fP containing the current window width and height.
926
popupprompt(\fIprompt\fP, \fIfunction\fP)
928
Generates a popup window with text entry. \fIprompt\fP will be printed above
929
the text entry window. Python function \fIfunction\fP (referenced by name)
930
will be called when clicking the "Okay" button or pressing the Return key
931
ends the text entry. The function will be passed the contents of the text
932
window as its (only) parameter.
934
filepopup(\fIprompt\fP, \fIfunction\fP)
936
Operates exactly like \fBpopupprompt()\fP, except that the window is a file
937
browser instead of a simple text entry window.
940
simplepopup(\fIprompt\fP, \fIfunction\fP)
942
Operates exactly like \fBpopupprompt()\fP, except that there is no text entry
943
window, only a prompt string and the choice of "Okay" and "Cancel".
945
newbutton(\fIparent\fP, \fIname\fP, \fIfunction\fP)
947
Generates a new menu button under the menu cascade labeled \fIparent\fP.
948
The new button will display the label \fIname\fP, and pushing the button
949
will call the Python function \fIfunction\fP.
953
Go to the page numbered \fInumber\fP.
957
Erases the current page unconditionally, unless dependencies such as a link
963
.B library \fIlibname\fP
964
Loads a library named \fIlibname\fP (with or without .lps
965
extension) into the set of built-in objects.
967
.B override default library
968
Causes the default libraries defined in "builtins.lps"
969
\fInot\fP to be loaded.
971
.B override default colors
972
Causes the default colors \fInot\fP to be loaded; this will
973
not override the allocation of black and white, however,
976
.B font \fIfontname\fP
977
Adds a font named \fIfontname\fP (as recognized by a
978
printer) to the menu of selectable fonts.
980
.B color \fIcolorname\fP
981
Adds a color named \fIcolorname\fP (standard X11
982
conventions) to the menu of selectable colors.
984
.B set \fItype\fP \fIvalue\fP
985
Sets internal xcircuit variables, where \fItype\fP can be one of:
989
Where \fIvalue\fP is one of "manhattan", "rhomboid-x", "rhomboid-y",
990
or "normal". Determines the default way manhattan-aligned polygon
991
edges are manupulated during edits.
995
Where \fIvalue\fP is a real number indicating the default
1000
Where \fIvalue\fP can be \fBon\fP or \fBoff\fP, depending on
1001
whether or not you want the machine beeping at you when it
1002
gives critical warnings.
1006
Where \fIvalue\fP is \fBinverse\fP to swap the two color schemes
1007
and make the second scheme appear as default.
1011
XCircuit implements a crash recovery system by which a copy of the current
1012
file is made every 15 minutes (see Xdefaults, below, for changing this
1013
value). XCircuit deletes this file upon a normal exit. If, however,
1014
XCircuit crashes or is terminated by Control-C or other sudden death,
1015
the backup copy will remain. On startup, XCircuit checks the /tmp
1016
directory for any XCircuit backup files belonging to the user. If one
1017
is found, XCircuit will prompt the user for recovery. Note that the
1018
backup is unique in that it contains a copy of the entire user space at
1019
the time of the crash. Filenames may get overwritten, as the backup
1020
will treat all pages as belonging to the same file.
1023
As noted above, keys can be bound and unbound through command-line
1024
functions "bind" and "unbind". Default key bindings are used throughout
1025
this manual page. Key names use the notation of
1026
/usr/X11R6/include/keysymdef.h, but with the notation "XK_" being
1027
optional, and including the addition of prefixes "Shift_", "Control_",
1028
"Capslock_", and "Alt_", which may be used in any combination. Note
1029
that "Shift_" is not used for ASCII characters (e.g., "A" is used
1030
instead of "Shift_a") unless used in combination with other special
1031
keys (such as "Control_Shift_A" to distinguish from "Control_a",
1032
should that be desired). "Button1", "Button2", and "Button3" are
1033
also valid names indicating functions attached to the mouse buttons
1034
in normal drawing mode. Valid functions which may be bound are as
1035
follows, with their default values given:
1039
Function name Function performed Default key binding
1040
---------------------------------------------------------------------
1041
"Page", change page, Number keys 1-9 and 0
1042
"Justify", change text justification, Keypad keys 1-9
1043
"Superscript", set text superscript, Keypad +
1044
"Subscript", set text subscript, Keypad -
1045
"Normalscript", cancel sub/superscript, Keypad Enter
1046
"Nextfont", change to next font, Alt-f
1047
"Boldfont", change to bold font, Alt-b
1048
"Italicfont", change to italic font, Alt-i
1049
"Normalfont", cancel italic/bold, Alt-n
1050
"Underline", generate underline, Alt-u
1051
"Overline", generate overline, Alt-o
1052
"ISO Encoding", change to ISO encoding, Alt-e
1053
"Return", embedded return character, Alt-Enter
1054
"Halfspace", embedded half-space, Alt-h
1055
"Quarterspace", embedded quarter-space, Alt-q
1056
"Special", special character, Alt-c
1057
"Parameter", embedded parameter, Alt-p
1058
"Edit Break", break at point, x
1059
"Edit Delete", delete point, d, Delete
1060
"Edit Insert", insert point, i, Insert
1061
"Edit Next", go to next point, e
1062
"Attach", attach line to object, A
1063
"Next Library", go to next library, l
1064
"Library Directory", library directory, L
1065
"Library Move", arrange library objects, M
1066
"Library Copy", get object in copy mode, c
1067
"Library Edit", edit library name, E
1068
"Library Delete", delete library object, D
1069
"Library Duplicate", duplicate object, C
1070
"Library Hide", hide library object, H
1071
"Page Directory ", page directory, P
1072
"Library Pop", return from library, <
1073
"Help", generate help screen, h, ?
1074
"Redraw", redraw the window, space
1075
"View", fit page to window, v
1076
"Zoom In", zoom in, Z
1077
"Zoom Out", zoom out, z
1078
"Pan", center pan, p
1079
"Double Snap", increase snap space, +
1080
"Halve Snap", decrease snap space, -
1081
"Pan Left", pan left one-half page, Left arrow
1082
"Pan Right", pan right one-half page, Right arrow
1083
"Pan Up", pan up one-half page, Up arrow
1084
"Pan Down", pan down one-half page, Down arrow
1085
"Write", popup output window, W
1086
"Rotate", Rotate, r,R,o,O
1087
"Flip X", Flip horizontal, f
1088
"Flip Y", Flip vertical, F
1089
"Snap", Snap to grid, S
1090
"Pop", Return from object edit, <
1091
"Push", Edit object, >
1092
"Delete", Delete element, d
1093
"Select", Select element, Select
1094
"Box", Create box, b
1095
"Arc", Create arc, a
1096
"Text", Create label, t
1097
"Exchange", Exchange vertical order, X
1098
"Copy", Copy element, c
1099
"Join", Join into path, j
1100
"Unjoin", Split path into elements, J
1101
"Spline", Create spline, s
1102
"Edit", Edit element, e
1103
"Undelete", Undelete last deleted, u
1104
"Select Save", Make object from selected, M,m
1105
"Unselect", Unselect element, x
1106
"Dashed", Set line style to dashed, |
1107
"Dotted", Set line style to dotted, :
1108
"Solid", Set line style to solid, _
1109
"Prompt", Execute from command line, %
1110
"Dot", Place dot at location, .
1111
"Exit", Exit xcircuit, Ctrl-Alt-q
1112
"Netlist", Generate a netlist, Alt-q
1113
"Swap", Swap schematic, symbol, /
1114
"Pin Label", Create pin label, T
1115
"Info Label", Create info label, I
1116
"Connectivity", Show wire connectivity, Alt-w
1117
"Sim", Generate sim netlist, Alt-s
1118
"SPICE", Generate SPICE netlist, Alt-S
1119
"PCB", Generate PCB netlist, Alt-p
1120
"SPICE Flat" Generate flattened SPICE, Alt-f
1121
------------------------------------------------------------------
1124
2-Button mouse users may find it useful to forego the Shift-Button1
1125
combination and instead put the following commands in the startup
1129
bind('Escape', 'Cancel')
1131
unbind('Button3', Cancel')
1133
bind('Button3', 'Finish')
1136
This will move the 3rd mouse button bindings to the "Escape" key, and
1137
duplicate the 2nd mouse button bindings onto the 3rd.
1141
The color scheme of xcircuit has a default setup, but accepts
1142
alternate color schemes using the following keywords which can be put
1143
in the X Defaults (.Xdefaults, .Xresources) file, such as:
1148
! Sample X defaults for xcircuit, black-on-white version
1152
xcircuit*foreground : Black
1154
xcircuit*background : White
1156
xcircuit*gridcolor : Gray85
1158
xcircuit*snapcolor : Orange
1160
xcircuit*selectcolor : Blue
1162
xcircuit*querycolor : Green
1164
xcircuit*axescolor : NavajoWhite3
1166
xcircuit*offbuttoncolor : Gray30
1168
xcircuit*auxiliarycolor : MediumOrchid1
1171
Two color schemes are supported at a time, ostensibly for those people
1172
who prefer the lessened eye strain of a white-on-black scheme. The
1173
names of the secondary colors are the same as those for the primary
1174
colors, but followed by "2", e.g., "xcircuit*foreground2".
1177
One other resource defines the number of minutes between automatic saves
1178
to the temporary file (in case of a crash or emergency Ctrl-C exit):
1181
xcircuit.timeout : 15
1184
Xcircuit also recognizes the core resources, such as width and height:
1187
xcircuit.width : 600
1189
xcircuit.height : 500
1192
All xcircuit foreground and background colors are taken from the
1193
Xdefaults foreground and background. To get, for instance, white-on-black
1194
menus and buttons with a black-on-white drawing area, use the following:
1197
xcircuit*foreground : White
1199
xcircuit*background : DarkSlateGray
1201
xcircuit.foreground : Black
1203
xcircuit.background : White
1205
This will ensure that only the drawing area is black-on-white, but all other
1206
windows will appear in the less eye-straining white-on-black.
1208
Five different fonts can be specified in the Xdefaults. \fihelpfont\fp is
1209
the style of fonts on the help popup window. \fifilefont\fp is the style
1210
of fonts in the list of files in the file selection popup window. \fitextfont\fp
1211
is the style of font for entering text in the popup dialog boxes. \fititlefont\fp
1212
is the style of font for the cascade menu titles. All other fonts take the
1213
type \fifont\fp. For example:
1215
xcircuit*font : *times-bold-r-normal--14*
1217
xcircuit*helpfont : *times-medium-r-normal--12*
1219
xcircuit*filefont : *times-medium-r-normal--14*
1221
xcircuit*textfont : *courier-medium-r-normal--14*
1223
xcircuit*titlefont : *times-bold-r-normal--18*
1225
The file path used by xcircuit to find library files is system-dependent
1226
(i.e., can be changed at compile time), and can be overridden in many
1227
ways (in .xcircuitrc or by the XCIRCUIT_LIB_DIR environment variable),
1235
PostScript prolog appended to each file
1237
ifelse(HAVE_PYTHON,1,`.B xcstartup.py',`.B startup.script')
1238
This startup script contains commands of the type
1239
ifelse(HAVE_PYTHON,1,`\fBlibrary\fP("\fIname\fP", \fInumber\fP)',dnl
1240
`\fBlibrary\fP \fIname\fP \fInumber\fP')
1241
which cause the designated library \fIname\fP to be immediately loaded
1242
into library page \fInumber\fP. The startup script is also responsible
1243
for loading fonts, and may also be used to load colors on the color
1244
palette, set other options, and execute commands.
1246
.B generic.lps, analog.lps, digital.lps, avlsi.lps, analoglib2.lps
1247
Files containing pre-compiled circuit elements. The \fB.lps\fP extension
1248
is unique for xcircuit libraries.
1251
This subdirectory contains font definition files for xcircuit's
1252
vector-drawn fonts. Characters are defined by xcircuit objects and
1253
stored in a \fB.lps\fP library. The encoding scheme and other font
1254
information is stored in a \fB.xfe\fP ("xcircuit font encoding")
1257
.B ~/.xcircuitrc \fPor\fB ./xcircuitrc
1258
Personal xcircuit initializer; commands are outlined above.
1259
Libraries listed in this file will be appended to the builtin libraries.
1260
.SH ENVIRONMENT VARIABLES
1261
\fBxcircuit\fP understands the following environment variables:
1265
Directory for temporary (e.g., backup) files (defaults to TEMP_DIR).
1269
Directory where xcircuit libraries and startup files can be found
1270
(defaults to BUILTINS_DIR).
1274
Directory where the xcircuit application defaults can be found
1275
(defaults to RESOURCES_DIR)
1279
Directory where xcircuit will look for startup files, after searching the
1283
.B HOST, HOSTNAME, USER
1284
Environment variables which xcircuit uses to fill in header information
1285
in the PostScript output (HOST and HOSTNAME are equivalent).
1288
PostScript printers have device-dependent limits on the number of
1289
statements within a "def" definition. If an object definition has an
1290
unusually large number of components, xcircuit will flag a warning when
1291
writing the file. However, there is no way to ensure that a file will be
1292
accepted by a given printer. The best way to avoid the problem is to make
1293
sure that large drawings make good use of hierarchically nested user-defined
1294
objects. Note that printer errors arising from this problem have not been
1295
observed in practice, and given the typical size of on-board memory on most
1296
modern laser printers, probably never will be.
1298
A list of bugs can be found in the Manifest file in the source directory.
1300
Look for the xcircuit online tutorial at
1302
http://xcircuit.ece.jhu.edu/tutorial/tutorial.html
1304
xfig(1), another powerful freeware drawing program worthy of mention
1306
Another schematic capture package worth noting is "gschem" from the
1307
gEDA package (see www.geda.seul.org).
1309
PostScript is a registered trademark of Adobe Systems Incorporated.
1311
XCircuit Copyright (c) 2002 Tim Edwards. XCircuit is freely distributed
1312
under a generous public license. See the source distribution for details.
1314
Xw widget set Copyright (c) 1988 by Hewlett-Packard Company and the
1315
Massachusetts Institute of Technology.
1317
Tim Edwards <tim@bach.ece.jhu.edu>. Thanks to Tomas Rokicki for
1318
the PostScript routine which manufactures a Symbol-Oblique font.
1319
Thanks to Dave Gillespie and John Lazzaro for the program "analog"
1320
on which the graphical interface of xcircuit is (roughly) based.
1321
Thanks to many beta-testers, some of whom were kind enough to send
1322
patches. Most contributors have been named in the Manifest file in
1323
the source distribution.