1XCircuit(1) General Commands Manual XCircuit(1)
2
3
4
6 xcircuit - Draw circuit schematics or almost anything; make circuit
7 netlists from schematics.
8
10 xcircuit [filename[,...]]
11
13 The program xcircuit is a generic drawing program tailored especially
14 for making publication-quality renderings of circuit diagrams (hence
15 the name). The output is pure PostScript, and the graphical interface
16 attempts to maintain as much consistency as possible between the X11
17 window rendering and the final printer output.
18
19 xcircuit is mouse, menu, and keyboard-driven, with the emphasis on sin‐
20 gle-character keyboard macros.
21
23 filename[,...]
24 Begin running xcircuit by loading in the PostScript file file‐
25 name. If filename does not have a .ps extension, xcircuit will
26 attempt to look for both the filename as entered and, upon
27 failure, with the .ps extension. The file must be in xcircuit
28 format. filename may also be a comma-separated list of files.
29
30
32 There are five drawing elements. These are as follows:
33
34 a) polygon (multiple lines which may or may not be closed and filled)
35
36 b) arc (ellipse segment which may be closed and/or filled as above)
37
38 c) label (any text)
39
40 d) curve (based on the PostScript "curveto" algorithm)
41
42 e) object instance (see below)
43
44 There are two composite elements, which are:
45
46 f) path (a connected series of polygons, arcs, and curves)
47
48 g) object (something containing polygons, arcs, labels, curves, paths,
49 and instances of other objects)
50
51
53 The mouse button system, the object library, and the paged buffer sys‐
54 tem are loosely based on the Caltech circuit-simulation program "log"
55 (either "analog" or "diglog").
56
57 The general idea is to make the most commonly-used functions the easi‐
58 est to perform, and (to the extent possible) to scale (inversely) the
59 complexity of performing a function with the frequency of that task.
60 Because this program is tailored to circuit drawing, the most common
61 functions are drawing lines and moving object instances. The next most
62 common function is selection of elements singly or in groups.
63
64 Mouse button 1 can be tapped to start a connected chain of lines, the
65 most common drawing function. In addition, button 1 has a function
66 called "grab", which occurs after the button has been continually
67 pressed for a short length of time (about 1/5 second). As the name
68 implies, "grab" grabs hold of an element which can then be moved around
69 the screen.
70
71 Button 2 can be used to select an item if tapped, and if pressed and
72 held down, a box will be drawn and everything inside that box selected
73 when the button is released. In all other cases, button 2 will com‐
74 plete a command. For users who have only two mouse buttons and do not
75 emulate the middle mouse button with the combination of buttons 1 and
76 3, use the combination of the Shift key and mouse button 1 to emulate
77 mouse button 2.
78
79 Button 3 will normally abort a command. During editing of an arc,
80 spline, or polygon, button 3 will revert back to the previous form, or
81 abort if there is no remaining edit history.
82
83 All other commands are available from the pulldown menus and/or from
84 the keyboard using single-key macros (with easy-to-remember mnemonics).
85 Keyboard commands are quicker, since they act on the present cursor
86 position, whereas menu commands require an extra step.
87
88
90 The library is intended to provide a convenient way to store and
91 retrieve elements of a picture which will be used more than once. For
92 the application of circuit drawing, a built-in library provides basic
93 objects such as transistors, amplifiers, resistors, capacitors, arrows,
94 circles, power and ground symbols, and the like. This file is a com‐
95 posite of several library files (such as "builtins.lps", "analog.lps",
96 and "digital.lps") which are called by the startup script
97 ("xcstartup.tcl") The program first looks for the startup script in the
98 current directory, and then searches in the directory given by the
99 environment variable "XCIRCUIT_LIB_DIR", and finally, in the hard-coded
100 global directory (/usr/lib64) if it could not find it elsewhere. Thus
101 each user can add to or modify the file of builtins to reflect personal
102 taste. Since the PostScript output contains all object definitions,
103 these changes to the built-in functions are inherently transferrable.
104 Xcircuit will automatically resolve conflicts between objects having
105 the same name but different contents.
106
107 The library is accesible from the pull-down menu or with the "l" key‐
108 board macro. When inside the library, clicking the first mouse button
109 on an object "grabs" that object and returns the graphics state immedi‐
110 ately to the page being edited, so that the object will be placed when
111 the mouse button is released.
112
113
115 Xcircuit has unconstrained zooming and snap-to positioning. Objects
116 scale completely: line widths and text sizes will increase/decrease
117 proportionally with the zoom, as well as dot/dash spacing and all other
118 features. Xcircuit does have a minimum integer grid in coordinate
119 space, which translates to 0.005 inches at an output scale of 1. The
120 maximum zoom scale gives a screen size translating to about 100 by 100
121 inches at an output scale of 1. The effective scale can be varied by
122 changing the output scale (reached from the "File/Write" menu selec‐
123 tion) in order to fit a drawing to a page or to get a grid matched to a
124 specific dimension. A separate scale parameter changes the scale of
125 the reported position relative to the output scale (as it will appear
126 on a printed page).
127
128
130 The snap-to grid is an all-important feature for circuit drawing,
131 wherein it is critical that elements line up properly with one another.
132 In xcircuit, there is no way to get off the snap-to grid except by
133 turning the snap function off and physically pushing elements off the
134 grid. Generally, it is most convenient to leave the snap functon on
135 and use key macros "+" and "-" to double/halve it as necessary. In any
136 case, objects can always be returned to the snap grid with the "snap"
137 function (key macro "S").
138
139
141 Objects are selected using a variety of search methods. The select box
142 (formed by holding down mouse button 2 and dragging the pointer) uses
143 the simplest method, searching for curve/polygon segment endpoints, arc
144 centers, and label and object bounding boxes falling within the select
145 box frame. General object selection is more complicated. Polygons,
146 Arcs, and Curves are selected by their outer edges, not the interiors.
147 Currently this is also true for filled instances of those types. A
148 line is selected if the pointer is in a region describing a box around
149 it, which is adusted according to the scale (zoom factor). Every
150 object has an associated bounding box, which is rectangular but may be
151 rotated with respect to the top level window. An object instance is
152 selected if the pointer falls within its bounding box. Each label also
153 has a bounding box carefully calculated from the width of the text
154 string.
155
156 Often the selection mechanism will find multiple elements in range of
157 the pointer. In this case, each object in turn will be presented, col‐
158 ored in blue (or the specified "querycolor" in the defaults file), and
159 the user has the option of accepting the highlighted element for selec‐
160 tion using the mouse button 1, or rejecting it with mouse button 3.
161 When all the elements under consideration have been accepted or
162 rejected, the program proceeds to execute whatever function was in
163 progress. This selection method takes a little while to get used to,
164 but is sensible and seems to work well.
165
166
168 Color in xcircuit is implemented with the idea of "color inheritance".
169 Every page has a "default color" of black. All elements which have
170 color value "Inherit" will inherit the default color, black. If an
171 object instance is painted blue (for instance), all components in that
172 object which have color value "Inherit" will inherit its color, blue.
173 The reason for this is that it allows different object instances to be
174 painted different colors (such as if one part of a circuit is high‐
175 lighted for emphasis), while making it possible for object instances to
176 be multicolored, if necessary. Changing the color of an object
177 instance will have no observable effect on the drawing if none of the
178 components of the object inherit that color. An object may have both
179 normally colored components and components which inherit their color,
180 in which case only those components with the "Inherit" value will
181 change color when the color of the object instance is changed.
182
183
185 XCircuit implements a sophisticated schematic capture. Unlike virtu‐
186 ally all schematic capture software currently available, xcircuit
187 allows the designer to draw the circuit in a "natural" way, making use
188 both of schematic hierarchies and simple hierarchies created simply by
189 grouping elements together. If the chosen netlist format is hierarchi‐
190 cal (like SPICE), both hierarchical forms will be retained in the out‐
191 put. For element grouping, input/output ports connecting into to the
192 group will be determined automatically, from context. A schematic cap‐
193 ture tutorial is available from the xcircuit website,
194 http://opencircuitdesign.com/xcircuit/tutorial/tutorial2.html.
195
196 Netlist types currently available are "SPICE", "sim", and "PCB".
197
198
200 Basic keyboard commands:
201
202 Z Zoom in by a factor of 3/2. If this key is pressed while a
203 selection box is active (created with the middle mouse but‐
204 ton), then acts like Zoom Box function.
205
206 z Zoom out by a factor of 3/2.
207
208 p Pan the screen so that the point under the mouse is brought
209 to the center of the program window. This function can
210 also be conveniently performed by clicking on the scroll‐
211 bars. The scrollbars cannot be moved continuously due to
212 the slow time for screen refresh.
213
214 cursors The arrow keys perform a pan of one-half window size in the
215 direction of the arrow pressed.
216
217 l Go to the Library of built-in objects. From the library,
218 use mouse button1 to grab an object and bring it back to
219 the edit screen, or button3 to return without selecting an
220 object instance. While in the library screen, the zoom and
221 pan functions can be used to move around.
222
223 > Push into an on-screen object in order to edit that object
224
225 < Return from editing an object. Object pushes and pops can
226 be stacked indefinitely.
227
228 space Refresh the screen.
229
230 digits 0-9 Switch to one of the first ten editing pages. Pages
231 greater than 10 can be reached from the "Window/Goto Page"
232 menu selection.
233
234 + and - Change snap-to grid spacing by a factor of two up or down.
235
236 | : and _ (Bar, colon, and underline) Change style on the currently
237 selected object to dashed, dotted, and solid, respectively.
238
239 h or ? Print a help page summary of commands
240
241 Commands to create elements:
242
243 a Arc. Center is fixed at the initial position of the cursor. The
244 mouse position changes the radius of the circle. In snap-to mode
245 the arc boundry will pass through the snap point closest to the
246 cursor. Mouse button 1 cycles from controlling the radius to con‐
247 trolling the starting point, the ending point, and separately con‐
248 trolling the minor axis to create ellipse. Mouse button 2 com‐
249 pletes the arc.
250
251 b Box. This is a convenience function for generating rectangular
252 closed polygons. Creates a rectangle with one corner fixed at the
253 position of the cursor. Subsequent movement of the cursor defines
254 the point diametrically opposed. Mouse buttons 1 or 2 complete the
255 box.
256
257 s Spline curve. The first endpoint is defined by the initial cursor
258 position. Mouse position adjusts the other endpoint of the curve.
259 Mouse button 1 cycles from controlling position of the endpoint to
260 controlling positions of the curve control points and the curve
261 starting point. Mouse button 2 completes the curve.
262
263 t Text. Text starts out justified according to the styles chosen in
264 the pull-down menu. Text can be rejustified using the menu or by
265 typing the numbers on the keypad (shift-keypad-1 through shift-key‐
266 pad-9). The position of the keys on the keypad matches the justi‐
267 fication. Subscripts, superscripts, font changes, text size
268 changes, underlining, and overlining are all available from the
269 pull-down menu. Text edit mode recognizes Home and End keys to
270 move to the beginning and end of the string, respectively. If the
271 X11 environment maps control key sequences to character encodings
272 (such as ISO-Latin1), these may be used to insert non-ASCII text.
273 Another method of inserting non-ASCII characters is the use of the
274 backslash character, which duplicates the action of the
275 Text/Insert/Character menu button.
276
277 M, m
278 Make object. Takes all the elements currently selected and com‐
279 piles them into an object. The object is then placed in the user
280 library. The elements just selected are deleted from the screen
281 and replaced by the new object. The center point of the resulting
282 object is chosen as the closest snap-to point to the center of the
283 object's bounding box; if another center is desired, then the
284 object can be edited using the ">" command and its contents moved
285 with respect to its origin. Note: Objects cannot have the same
286 name as PostScript commands or have the same name as any other
287 object in memory. If such a name is found, an underscore ("_")
288 will be prepended to the name as many times as is necessary to dif‐
289 ferentiate it from all other known objects. The name also cannot
290 contain special PostScript characters such as slash; any such char‐
291 acters found will be replaced with underscores.
292
293
294 Major editing commands:
295
296 d Delete. Select the nearest element or elements and delete it/them.
297
298 u Undelete. Xcircuit saves up to 10 delete events to be recovered.
299 Delete events are stored in order of occurrence, and the most
300 recent delete event is the first to be recovered. When multiple
301 elements are deleted at the same time, all of them are stored as
302 one delete event, and restored together.
303
304 x Deselect. Elements which have been selected can be deselected on a
305 per-item basis. In order not to be too confusing, deselect does
306 not query if multiple items are found under the cursor; it just
307 deselects them all.
308
309 c Copy. Make a copy of the object(s) nearest the cursor. Object is
310 automatically grabbed for moving to a new position. The next but‐
311 ton1 or button2 press will place the element. Button2 will end the
312 copy, and button1 will continue the copy function.
313
314 e Edit. The action of Edit is dependent on the type of element
315 selected. These are detailed below:
316
317 Label Returns to text editing mode, starting with the cursor at
318 the end of the string. Mode is like regular text entry
319 except that Button 3 returns text to its original string.
320
321 Polygon Grabs one point of a polygon for repositioning. Button 1
322 cycles between points, button 2 accepts the new polygon,
323 and button 3 returns to the previous state, unless there is
324 no remaining edit history, in which case it aborts the com‐
325 mand. Key macros available during polygon edit are:
326
327 "x"---Breaks the polygon at the given point.
328
329 "e"---Moves edit position to the next point.
330
331 "i" or "Insert"---Inserts a new point at the position.
332
333 "d" or "Delete"---Deletes the current edit point.
334
335 There are four modes for polygon editing; see the "Polygon
336 Edit" section below for details.
337
338 Arc Allows resizing of the radius. Mouse button 1 or the "e"
339 key will cycle between control of the radius, the endpoint
340 angles, and the ellipse minor axis. Mouse button 2 accepts
341 the new arc. Button 3 returns to the previous editing
342 state, unless there is no remaining edit history, in which
343 case it aborts the command.
344
345 Curve Allows repositioning of one end of the curve. Originally,
346 the starting angle of the curve is kept fixed. Mouse but‐
347 ton 1 or the "e" key cycles between the four control points
348 of the curve, allowing control over the angle of the curve
349 at its endpoint and the shape of the curve. Mouse button 2
350 accepts the new curve. Button 3 reverts back to the previ‐
351 ous edit state unless there is no remaining edit history,
352 in which case it terminates the command.
353
354 Object instance
355 Object instances have no properties to change except scale,
356 and do not respond to the "edit" command. Scale can be
357 changed by selecting "Options/Other/Object Size" from the
358 menu.
359
360
361 Minor editing commands:
362
363 R Rotate the selected element(s) or element under the cursor counter‐
364 clockwise in 15 degree intervals.
365
366 r Rotate the selected element(s) or element under the cursor clock‐
367 wise in 15 degree intervals.
368
369 O Rotate the selected element(s) or element under the cursor counter‐
370 clockwise by 5 degree intervals. This is currently the smallest
371 angle resolution available to xcircuit.
372
373 o Rotate the selected element(s) or element under the cursor clock‐
374 wise by 5 degree intervals.
375
376 f Flip an element around a vertical axis defined by an object's ori‐
377 gin for an object instance, or across an axis defined by the
378 pointer position for arcs, polygons, and curves.
379
380 F Flip an element around a horizontal axis defined similarly to the
381 "f" command.
382
383 X If two elements are selected, their order is exchanged (this is
384 only relevant if one element occludes another). If one element is
385 selected, it is raised up one in the stack, and if it is already on
386 top of the stack, it is shuffled to the bottom.
387
388 S Snap the nearest object to the snap-to grid. For curves the con‐
389 trol and endpoints are snapped; for polygons, each point is
390 snapped; for arcs, the centerpoint is snapped; for labels and
391 object instances, the designated point of origin is snapped.
392
393 j Join polygons together. This only makes sense if it is possible to
394 make a single continuous (open or closed) polygon from the selected
395 parts. Otherwise a warning will be posted and the parts will
396 remain separate.
397
398 A Attach an element to a polygon, arc, or curve. The element to be
399 attached must be the one currently grabbed (either by a "drag",
400 copy command, or edit command). Until it is released, it will be
401 forced to align its center (object, arc), endpoint (polygon,
402 curve), or position (label) with the closest polygon, arc, or
403 curve. Note that this is a very powerful tool for generating, for
404 example, lines tangent to a curve, or objects arranged in a circle
405 or along a line.
406
407
408 Library editing commands:
409
410 D Delete. The selected objects will be deleted from the library
411 unless other library objects or pages contain references to that
412 object. Note: Unlike deleting object instances with the "d" com‐
413 mand, this command deletes the actual object and releases all mem‐
414 ory associated with that object, so the object cannot be undeleted.
415
416 C Copy. Makes a copy of an object from either library page and
417 places the new copy in the user library. The new object will be
418 renamed to avoid naming conflicts.
419
420 M Move. If one object has been selected, it is moved to the position
421 of the cursor. If two objects have been selected, their positions
422 in the library are exchanged.
423
424 E Edit label. Edit the object name whose label is under the cursor.
425 After editing, the object name will be checked for conflicts with
426 other object names, and altered if necessary.
427
428 H Hide object. If the object is a sub-instance of another object,
429 but is not meant to be used by itself, it can be "hidden" so that
430 it will not appear by itself on the library page.
431
432
434 Write Postscript (W)
435 This command brings up a popup menu with a number of options.
436 First, it gives the name of the file if one exists, or else it
437 gives the default name of the buffer (usually Page n, where n is
438 the number of the buffer). Next, it gives a preview of the picture
439 scale and output styles, which include Landscape/Portrait orienta‐
440 tion and Encapulated/Unencapsulated (full page) PostScript modes.
441 The former allows adjustment of the nominal size of the picture
442 when drawn in PostScript. The default scale is 1.00, which makes
443 the text scale of 1.0 about 14 points on the PostScript page. The
444 width and height of the resulting picture are also given, in
445 inches, and any of the three values can be changed. The values of
446 the other two will be updated accordingly. Pages which have the
447 same name will be grouped together into a single file, allowing
448 multiple pages to be stored in the same PostScript file. However,
449 as Encapsulated PostScript does not make sense for this kind of
450 file, it is not an option.
451
452 The Write File button writes the current page to an output file.
453 If the page has a name other than the default, the file will auto‐
454 matically be saved under that name. Otherwise, it is necessary to
455 change the name of the buffer. If a file of that name already
456 exists on the disk, the button will read Overwrite File.
457
458 Read PostScript
459 Reads in a file of Xcircuit format. The file name is requested by
460 a popup prompt, and an extension of ".ps" will be added if neces‐
461 sary. The file is read into the current page, which is cleared
462 first if anything is in it. If the file is a multiple-page file,
463 the current page will be overwritten with the first page from the
464 file, but other pages will be loaded into empty buffers. Xcircuit
465 can also read "lgf"-format files from the Chipmunk CAD tools pro‐
466 grams "analog" and "diglog".
467
468 Import PostScript
469 Acts like "Read PostScript" except that the page is not reset
470 first, so graphics are added on top of existing graphics on the
471 page.
472
473 Clear Page
474 Clears the current page of all elements and resets the name. The
475 contents cannot be recovered.
476
477 Alt Color
478 Switches between the two xcircuit color schemes. The color schemes
479 can be redefined through XDefaults (see below). The default color
480 schemes are black-on-white and white-on-black. The latter is less
481 straining to the eyes, but the former matches the black ink on
482 white paper PostScript output. Any color scheme other than black-
483 on-white is not recommended for drawings with color, as the actual
484 output does not match the observed xcircuit screen.
485
486 Grid
487 Turns the grid lines on and off.
488
489 Axes
490 Turns the axis lines on and off. The axes mark the origin (0,0) of
491 the page. On the top level (TopObject), the origin has no particu‐
492 lar relevance, since encapsulated output will define its own bound‐
493 aries, and full-page (unencapsulated) output will be centered on
494 the output page, not according to the Xcircuit coordinate system.
495
496 Grid spacing
497 Changes the spacing of the grid lines. Default spacing is 1/6
498 inch, which is about the width of the letter 'W' in default text
499 scale.
500
501 Grid type/display
502 This is a submenu allowing the coordinates and coordinate grid to
503 be specified in alternate units. Listing of coordinates in the top
504 window can be in default fractional inches, decimal inches, or cen‐
505 timeters. Default spacing of grid lines is either one-quarter inch
506 or one-half centimeter. Selecting an A:B scale With option "Draw‐
507 ing Scale" causes all listed coordinates to be multiplied by the
508 scale. Note: Xcircuit will make an attempt to keep objects on the
509 snap/grid spacing when switching between inch and centimeter
510 scales. In order to do this, it will change the output scale by
511 the ratio of 2.54 to 2.5, thus keeping a closer correspondence
512 between inches and centimeters. To get true centimeters on the
513 output page, the output scale (from the "File/Write Xcircuit PS")
514 can be reset to 1.0 at the expense of having all objects intended
515 for the inch grid displaced off of the snap grid.
516
517 Snap-to
518 Turns the snap-to grid on and off. When the grid is on, movement
519 and placement of elements is restricted to points on the snap-to
520 grid.
521
522 Snap spacing
523 Determines the spacing of the points in the snap-to grid. Default
524 is 1/12 inch, which is half the grid line spacing.
525
526 Linewidth
527 Controls the default linewidth against which all linewidths in the
528 drawing are scaled.
529
530 Polygon Edit
531 The options in this submenu control how the position of lines are
532 affected when a point in a polygon is selected for editing. "Rhom‐
533 boid-X" mode moves adjoining points as necessary to keep all hori‐
534 zontal lines horizontal; "Rhomboid-Y" mode acts similarly to keep
535 all vertical lines vertical. "Rhomboid-A" is similar to Manhattan
536 mode but also tracks non-Manhattan lines. The default mode is
537 "Manhattan Box Edit", which is a combination of Rhomboid-X and
538 Rhomboid-Y. In "Normal" mode, only the point being edited can be
539 moved.
540
541 Arc/Box/Curve Border
542 The options under this menu determine the border style of arcs,
543 polygons, and curves. If an element is selected, it will be modi‐
544 fied; otherwise, if no objects are selected, the style chosen is
545 made default for all subsequent arcs, polygons, and curves. Ele‐
546 ments may be drawn with or without borders (but for obvious reasons
547 cannot be made both borderless and unfilled, which would be invisi‐
548 ble) The borders may be closed or unclosed. For an arc, closed
549 means that a chord is drawn connecting the two endpoints, if the
550 beginning and ending angles do not complete a full circle. Borders
551 may be solid, dashed, dotted, and of varying width.
552
553 Arc/Box/Curve Fill
554 The options under this menu determine the fill style of arcs, poly‐
555 gons, and curves. Fill style may be solid, empty, or one of 7
556 stipple patterns varying from light to dark, which are drawn both
557 in xcircuit and PostScript as stipple patterns. Stipples can be
558 transparent or opaque. Warning: Transparent stipples are NOT
559 inherent to PostScript and the hacks necessary to implement them
560 cause slow rendering on a printer or PostScript previewer. Due to
561 the device-dependent nature of the routines, patterns will look
562 abnormally large on PostScript previewers. This transparancy fea‐
563 ture has been added with the expectation that most circuit schemat‐
564 ics will not rely heavily upon halftoning. Complicated color pat‐
565 terns can be created using transparent colored, stippled elements
566 on top of solid-color elements. Note: Ordering of elements is
567 according to order created. A different ordering can be achieved
568 using the "X" (exchange) command. This method is not especially
569 easy to work with, and hopefully something better will be imple‐
570 mented in the future.
571
572 Arc/Box/Curve Color
573 See the COLOR section above for a discussion of color inheritance.
574 This menu shows all the colors available to xcircuit with the
575 option of adding more colors. Currently the entry style for colors
576 is by name or by RGB content in the X11 style of #rrggbb where rr,
577 gg, and bb are hex values ranging from 00 to FF. The only limit to
578 the number of colors is the X Server's colormap depth. If the col‐
579 ormap is full, xcircuit attempts to allocate the closest possible
580 color to the one requested.
581
582 Zoom Box
583 This zoom feature requests the user to create a box (using either
584 mouse button 1 or 2, expanding the box while holding down the but‐
585 ton). When the button is released, the view will zoom to the area
586 of that box.
587
588 Full View
589 This zoom feature calculates the bounding box of the entire picture
590 and adjusts the scale to make it fit comfortably inside the program
591 window.
592
594 Xcircuit's ability to handle text is arguably the most complicated part
595 of the program, and also of the PostScript output. Careful attention
596 to text justification and style is the key to a good drawing.
597
598 Text Size
599 Alters the size of the labels. The value is a scale, with a
600 default of 1.0 which translates to 14 points on the PostScript page
601 if the default page scale of 1 is used. If a label is selected,
602 only that label is affected. If a label is being edited, scale
603 changes starting at the edit position. Otherwise, it becomes the
604 default size for all subsequent labels. Size affects the entire
605 text string. Text size can be changed anywhere inside of a string.
606 However, text sizes inside a string are all given relative to the
607 label size, not as an absolute point size. Sizes of subscripts and
608 superscripts are given relative to the natural size of the sub‐
609 script or superscript (2/3 the size of the text for which it is a
610 modifier).
611
612 Text Font
613 Standard printer fonts Times-Roman, Helvetica, Courier, and Symbol,
614 are readily available. "User-defined" fonts can also be added;
615 however, support is currently limited, and requires a font object
616 (.lps) file and encoding (.xfe) file, examples of which are found
617 in the fonts subdirectory of the xcircuit library directory.
618
619 Text Style
620 Four standard font styles are available, matching the standard
621 printer font variations: Normal, Italic (or oblique), Bold, and
622 BoldItalic. PostScript matrix manipulation allows slanted versions
623 of any font, such as Symbol, for which none is otherwise available.
624
625 Text Insert
626 The Insert menu allows insertion of special characters which are
627 otherwise not (necessarily) allowed from the keyboard. These
628 include tab-stop, tab-forward, tab-backward, kern, half-space,
629 quarter-space, and "Character". The latter option brings up a page
630 showing the 256-character encoding vector for the font, allowing
631 point-and-click entry of any character in the font. "Kern"
632 instructions allow characters to be offset vertically or horizon‐
633 tally relative to the rest of the text.
634
635 Text Encoding
636 Two standard font encodings are available by default, Standard
637 (Adobe) Encoding, and ISO-Latin1 encoding. ISO-Latin2 and ISO-
638 Latin5 encodings exist in the library directory, but require the
639 use of the program "ogonkify" (not included) to produce correct
640 output on a printer.
641
642 Super and Subscripts
643 Superscript and subscript are designed to closely match those in
644 TeX output, though they lack the proper context-dependent kerning
645 and other fancy features of TeX. A superscript following a sub‐
646 script results in a superscripted subscript. To get a superscript
647 on top of a subscript, use the backspace character (see below).
648 The Normalscript style is the way to get out of a sub or super‐
649 script and return to the normal size and position. Quick
650 super/sub/normalscripting is available from the keypad with the "+"
651 (plus), "-" (minus), and "Enter" keys, respectively.
652
653 Overline and Underline
654 Overlining and underlining styles remain in effect until the next
655 occurrence of a style or font change. Overlining is lower if all
656 the characters are lowercase and do not include the "tall" lower‐
657 case characters. Overlining or underlining can be stopped at any
658 time using the No Line style. Over and Underlining is *always*
659 preferable to using a line. PostScript will adjust the over or
660 underline to the text size and extent and actually grab the "_"
661 character and compute its thickness in order to draw the line.
662
663 Tabbing
664 From version 2.3, xcircuit allows embedded tab stops. Tab stops
665 must be defined before using tab-forward or tab-backward. The
666 "Tab" keyboard key inserts an embedded tab-forward instruction into
667 a label. Tab-stop and tab-backward can be inserted using the
668 Text->Insert menu. A tab-forward instruction moves the cursor to
669 the first defined tab stop forward of the current position. A tab-
670 backward instruction moves the cursor to the first defined tab stop
671 backward of the current position. If no appropriate tab stop
672 exists, the instruction has no effect.
673
674 Backspace
675 The use of the backspace character is deprecated from xcircuit ver‐
676 sion 2.3. The effect of an embedded backspace is more reliably
677 produced using tab-stop and tab-backward.
678
679 Halfspace and Quarterspace
680 These options allow fine control over spacing, particularly useful
681 when writing equations.
682
683 Justification
684 Text justification always starts with the default, chosen from the
685 options in the menu, but may be changed at any time using the num‐
686 bers on the keypad. The position of the keys on the keypad reflect
687 the point of justification: 1, 4, and 7 are right-justified, 7, 8,
688 and 9 are bottom justified, 5 is centered in both directions.
689 Since the letters drawn by xcircuit are optimized for the Helvetica
690 font, correct justification is the main way to get text to come out
691 on the PostScript page in the desired way, relative to objects or
692 boxes or whatever.
693
695 Certain parameters of the xcircuit program can be initialized from a
696 file called .xcircuitrc, which is first searched for in the current
697 directory, and then in the user's home directory as defined by the
698 environment variable $HOME.
699
700
701 The startup file is written in Tcl. The command-line interface can be
702 found in the online documentation on the website
703
704 http://www.opencircuitdesign.com/xcircuit/.
705
706
707
709 XCircuit implements a crash recovery system by which a copy of the cur‐
710 rent file is made every 15 minutes (see Xdefaults, below, for changing
711 this value). XCircuit deletes this file upon a normal exit. If, how‐
712 ever, XCircuit crashes or is terminated by Control-C or other sudden
713 death, the backup copy will remain. On startup, XCircuit checks the
714 /tmp directory for any XCircuit backup files belonging to the user. If
715 one is found, XCircuit will prompt the user for recovery. Note that
716 the backup is unique in that it contains a copy of the entire user
717 space at the time of the crash. Filenames may get overwritten, as the
718 backup will treat all pages as belonging to the same file.
719
720
722 As noted above, keys can be bound and unbound through command-line
723 functions "bind" and "unbind". Default key bindings are used through‐
724 out this manual page. Key names use the notation of
725 /usr/X11R6/include/keysymdef.h, but with the notation "XK_" being
726 optional, and including the addition of prefixes "Shift_", "Control_",
727 "Capslock_", and "Alt_", which may be used in any combination. Note
728 that "Shift_" is not used for ASCII characters (e.g., "A" is used
729 instead of "Shift_a") unless used in combination with other special
730 keys (such as "Control_Shift_A" to distinguish from "Control_a", should
731 that be desired). "Button1", "Button2", and "Button3" are also valid
732 names indicating functions attached to the mouse buttons in normal
733 drawing mode. Valid functions which may be bound are as follows, with
734 their default values given:
735
736
737 Function name Function performed Default key binding
738 ---------------------------------------------------------------------
739 "Page", change page, Number keys 1-9 and
740 0
741 "Justify", change text justification, Keypad keys 1-9
742 "Superscript", set text superscript, Keypad +
743 "Subscript", set text subscript, Keypad -
744 "Normalscript", cancel sub/superscript, Keypad Enter
745 "Nextfont", change to next font, Alt-f
746 "Boldfont", change to bold font, Alt-b
747 "Italicfont", change to italic font, Alt-i
748 "Normalfont", cancel italic/bold, Alt-n
749 "Underline", generate underline, Alt-u
750 "Overline", generate overline, Alt-o
751 "ISO Encoding", change to ISO encoding, Alt-e
752 "Return", embedded return character, Alt-Enter
753 "Halfspace", embedded half-space, Alt-h
754 "Quarterspace", embedded quarter-space, Alt-q
755 "Special", special character, Alt-c
756 "Parameter", embedded parameter, Alt-p
757 "Edit Break", break at point, x
758 "Edit Delete", delete point, d, Delete
759 "Edit Insert", insert point, i, Insert
760 "Edit Next", go to next point, e
761 "Attach", attach line to object, A
762 "Next Library", go to next library, l
763 "Library Directory", library directory, L
764 "Library Move", arrange library objects, M
765 "Library Copy", get object in copy mode, c
766 "Library Edit", edit library name, E
767 "Library Delete", delete library object, D
768 "Library Duplicate", duplicate object, C
769 "Library Hide", hide library object, H
770 "Page Directory ", page directory, P
771 "Library Pop", return from library, <
772 "Help", generate help screen, h, ?
773 "Redraw", redraw the window, space
774 "View", fit page to window, v
775 "Zoom In", zoom in, Z
776 "Zoom Out", zoom out, z
777 "Pan", center pan, p
778 "Double Snap", increase snap space, +
779 "Halve Snap", decrease snap space, -
780 "Pan Left", pan left one-half page, Left arrow
781 "Pan Right", pan right one-half page, Right arrow
782 "Pan Up", pan up one-half page, Up arrow
783 "Pan Down", pan down one-half page, Down arrow
784 "Write", popup output window, W
785 "Rotate", Rotate, r,R,o,O
786 "Flip X", Flip horizontal, f
787 "Flip Y", Flip vertical, F
788 "Snap", Snap to grid, S
789 "Pop", Return from object edit, <
790 "Push", Edit object, >
791 "Delete", Delete element, d
792 "Select", Select element, Select
793 "Box", Create box, b
794 "Arc", Create arc, a
795 "Text", Create label, t
796 "Exchange", Exchange vertical order, X
797 "Copy", Copy element, c
798 "Join", Join into path, j
799 "Unjoin", Split path into elements, J
800 "Spline", Create spline, s
801 "Edit", Edit element, e
802 "Undelete", Undelete last deleted, u
803 "Select Save", Make object from selected, M,m
804 "Unselect", Unselect element, x
805 "Dashed", Set line style to dashed, |
806 "Dotted", Set line style to dotted, :
807 "Solid", Set line style to solid, _
808 "Prompt", Execute from command line, %
809 "Dot", Place dot at location, .
810 "Exit", Exit xcircuit Ctrl-Alt-q
811 "Netlist", Generate a netlist, Alt-q
812 "Swap", Swap schematic, symbol, /
813 "Pin Label", Create pin label, T
814 "Info Label", Create info label, I
815 "Connectivity", Show wire connectivity, Alt-w
816 "Sim", Generate sim netlist, Alt-s
817 "SPICE", Generate SPICE netlist, Alt-S
818 "PCB", Generate PCB netlist, Alt-p
819 "SPICE Flat" Generate flattened SPICE, Alt-f
820 ------------------------------------------------------------------
821
822 2-Button mouse users may find it useful to forego the Shift-Button1
823 combination and instead put the following commands in the startup
824 script:
825
826 bind('Escape', 'Cancel')
827 unbind('Button3', Cancel')
828 bind('Button3', 'Finish')
829
830 This will move the 3rd mouse button bindings to the "Escape" key, and
831 duplicate the 2nd mouse button bindings onto the 3rd.
832
833
835 The color scheme of xcircuit has a default setup, but accepts alternate
836 color schemes using the following keywords which can be put in the X
837 Defaults (.Xdefaults, .Xresources) file, such as:
838
839 !
840 ! Sample X defaults for xcircuit, black-on-white version
841 !
842 xcircuit*foreground : Black
843 xcircuit*background : White
844 xcircuit*gridcolor : Gray85
845 xcircuit*snapcolor : Orange
846 xcircuit*selectcolor : Blue
847 xcircuit*querycolor : Green
848 xcircuit*axescolor : NavajoWhite3
849 xcircuit*offbuttoncolor : Gray30
850 xcircuit*auxiliarycolor : MediumOrchid1
851
852 Two color schemes are supported at a time, ostensibly for those people
853 who prefer the lessened eye strain of a white-on-black scheme. The
854 names of the secondary colors are the same as those for the primary
855 colors, but followed by "2", e.g., "xcircuit*foreground2".
856
857
858 One other resource defines the number of minutes between automatic
859 saves to the temporary file (in case of a crash or emergency Ctrl-C
860 exit):
861
862 xcircuit.timeout : 15
863
864 Xcircuit also recognizes the core resources, such as width and height:
865
866 xcircuit.width : 600
867 xcircuit.height : 500
868
869 All xcircuit foreground and background colors are taken from the Xde‐
870 faults foreground and background. To get, for instance, white-on-black
871 menus and buttons with a black-on-white drawing area, use the follow‐
872 ing:
873
874 xcircuit*foreground : White
875 xcircuit*background : DarkSlateGray
876 xcircuit.foreground : Black
877 xcircuit.background : White
878 This will ensure that only the drawing area is black-on-white, but all other
879 windows will appear in the less eye-straining white-on-black.
880 Five different fonts can be specified in the Xdefaults. helpfont is
881 the style of fonts on the help popup window. filefont is the style
882 of fonts in the list of files in the file selection popup window. textfont
883 is the style of font for entering text in the popup dialog boxes. titlefont
884 is the style of font for the cascade menu titles. All other fonts take the
885 type font. For example:
886 xcircuit*font : *times-bold-r-normal--14*
887 xcircuit*helpfont : *times-medium-r-normal--12*
888 xcircuit*filefont : *times-medium-r-normal--14*
889 xcircuit*textfont : *courier-medium-r-normal--14*
890 xcircuit*titlefont : *times-bold-r-normal--18*
891
893 The file path used by xcircuit to find library files is system-
894 dependent (i.e., can be changed at compile time), and can be overridden
895 in many ways (in .xcircuitrc or by the XCIRCUIT_LIB_DIR environment
896 variable), but by default is:
897
898
899 /usr/lib64
900
901
902 xcircps2.pro PostScript prolog appended to each file
903
904 xcstartup.tcl This startup script contains commands of the type
905 library name number which cause the designated library
906 name to be immediately loaded into library page number.
907 The startup script is also responsible for loading
908 fonts, and may also be used to load colors on the color
909 palette, set other options, and execute commands.
910
911 generic.lps, analog.lps, digital.lps, avlsi.lps, analoglib2.lps
912 Files containing pre-compiled circuit elements. The
913 .lps extension is unique for xcircuit libraries.
914
915 fonts This subdirectory contains font definition files for
916 xcircuit's vector-drawn fonts. Characters are defined
917 by xcircuit objects and stored in a .lps library. The
918 encoding scheme and other font information is stored in
919 a .xfe ("xcircuit font encoding") file.
920
921 ~/.xcircuitrc or ./xcircuitrc
922 Personal xcircuit initializer; commands are outlined
923 above. Libraries listed in this file will be appended
924 to the builtin libraries.
925
927 xcircuit understands the following environment variables:
928
929
930 TMPDIR Directory for temporary (e.g., backup) files (defaults
931 to TEMP_DIR).
932
933
934 XCIRCUIT_LIB_DIR
935 Directory where xcircuit libraries and startup files can
936 be found (defaults to BUILTINS_DIR).
937
938
939 XAPPLRESDIR Directory where the xcircuit application defaults can be
940 found (defaults to RESOURCES_DIR)
941
942
943 HOME Directory where xcircuit will look for startup files,
944 after searching the current directory.
945
946
947 HOST, HOSTNAME, USER
948 Environment variables which xcircuit uses to fill in
949 header information in the PostScript output (HOST and
950 HOSTNAME are equivalent).
951
952
954 PostScript printers have device-dependent limits on the number of
955 statements within a "def" definition. If an object definition has an
956 unusually large number of components, xcircuit will flag a warning when
957 writing the file. However, there is no way to ensure that a file will
958 be accepted by a given printer. The best way to avoid the problem is
959 to make sure that large drawings make good use of hierarchically nested
960 user-defined objects. Note that printer errors arising from this
961 problem have not been observed in practice, and given the typical size
962 of on-board memory on most modern laser printers, probably never will
963 be.
964
965 A list of bugs can be found in the Manifest file in the source
966 directory.
967
969 Look for the xcircuit online tutorial at
970
971 http://opencircuitdesign.com/xcircuit/tutorial/tutorial.html
972
974 xfig(1), another powerful freeware drawing program worthy of mention
975 (see www.xfig.org). Another schematic capture package worth noting is
976 "gschem" from the gEDA package (see www.geda.seul.org).
977
979 PostScript is a registered trademark of Adobe Systems Incorporated.
980 XCircuit Copyright (c) 2002 Tim Edwards. XCircuit is freely
981 distributed under a generous public license. See the source
982 distribution for details.
983 Xw widget set Copyright (c) 1988 by Hewlett-Packard Company and the
984 Massachusetts Institute of Technology.
985
987 Tim Edwards <tim@opencircuitdesign.com>. Thanks to Tomas Rokicki for
988 the PostScript routine which manufactures a Symbol-Oblique font.
989 Thanks to Dave Gillespie and John Lazzaro for the program "analog" on
990 which the graphical interface of xcircuit is (roughly) based. Thanks
991 to many beta-testers, some of whom were kind enough to send patches.
992 Most contributors have been named in the Manifest file in the source
993 distribution.
994
995
996
997X11R6 January 5, 2000 XCircuit(1)