XCircuit(1)

📦
version 3.10.45 · 2 versions
, in fedora 43, fedora 44

💖 xcircuit(1) — General Commands Manual 💖

okay bestie, sit DOWN, because this is the manual for xcircuit and it's literally iconic. it's giving "I draw circuits AND I look cute doing it." grab a snack, this is a long one 🍓

✨ NAME ✨

xcircuit — draw circuit schematics or almost anything; make circuit netlists from schematics.

✨ SYNOPSIS ✨

xcircuit [filename[,...]]

✨ DESCRIPTION ✨

so. xcircuit is a generic drawing program, but it's tailored specifically for making publication-quality renderings of circuit diagrams — hence the name, iykyk 💅 The output is pure PostScript, and the graphical interface tries its absolute hardest to keep as much consistency as possible between what you see rendered in the X11 window and what actually comes out of the printer.

xcircuit is mouse-, menu-, and keyboard-driven, and the whole vibe is that single-character keyboard macros are the main character. 👑

✨ OPTIONS ✨

  • filename[,...] — start running xcircuit by loading in the PostScript file filename. If filename doesn't have a .ps extension, xcircuit will try to look for both the filename exactly as you entered it and, if that fails, with the .ps extension tacked on. The file must be in xcircuit format. filename can also be a comma-separated list of files, because why load one when you can load several 🫶

✨ BASIC ELEMENTS ✨

there are five drawing elements, bestie. five. count 'em:

  1. polygon — multiple lines which may or may not be closed and filled
  2. arc — an ellipse segment which may be closed and/or filled, same as above
  3. label — any text
  4. curve — based on the PostScript curveto algorithm
  5. object instance — see below 👀

and there are two composite elements, which are:

  1. path — a connected series of polygons, arcs, and curves
  2. object — something containing polygons, arcs, labels, curves, paths, and instances of other objects

✨ MOUSE BUTTONS ✨

ngl, the mouse button system, the object library, and the paged buffer system are loosely based on the Caltech circuit-simulation program log (either analog or diglog). love that for them.

the general idea is to make the most commonly-used functions the easiest to perform, and — to the extent possible — to scale (inversely) the complexity of performing a function with the frequency of that task. and because this program is tailored to circuit drawing, the most common functions are drawing lines and moving object instances. the next most common function is selecting elements, either one at a time or in groups.

  • mouse button 1 — can be tapped to start a connected chain of lines, which is the most common drawing function. also, button 1 has a function called "grab", which kicks in after the button has been continually pressed for a short length of time (about 1/5 second ⏱️). as the name implies, "grab" grabs hold of an element which can then be moved around the screen.
  • mouse button 2 — can be used to select an item if tapped, and if pressed and held down, a box gets drawn and everything inside that box gets selected when you release the button. in all other cases, button 2 completes a command. for those of you with only two mouse buttons who don't emulate the middle mouse button with the combination of buttons 1 and 3 — use Shift + mouse button 1 to emulate mouse button 2, periodt.
  • mouse button 3 — will normally abort a command. during editing of an arc, spline, or polygon, button 3 reverts back to the previous form, or aborts if there's no remaining edit history.

all other commands are available from the pulldown menus and/or from the keyboard using single-key macros (with easy-to-remember mnemonics, because they love us 💖). keyboard commands are quicker, since they act on the present cursor position, whereas menu commands require an extra step.

✨ BUILT-IN LIBRARY ✨

the library exists to provide a convenient way to store and retrieve elements of a picture which will be used more than once. for the application of circuit drawing, a built-in library provides basic objects such as transistors, amplifiers, resistors, capacitors, arrows, circles, power and ground symbols, and the like ⚡

this file is a composite of several library files (such as builtins.lps, analog.lps, and digital.lps) which are called by the startup script (xcstartup.tcl). the program first looks for the startup script in the current directory, and then searches in the directory given by the environment variable XCIRCUIT_LIB_DIR, and finally, in the hard-coded global directory (/usr/lib64) if it couldn't find it anywhere else. so each user can add to or modify the file of builtins to reflect personal taste 🎀 and since the PostScript output contains all object definitions, these changes to the built-in functions are inherently transferrable. xcircuit will automatically resolve conflicts between objects having the same name but different contents. slay.

the library is accessible from the pull-down menu or with the l keyboard macro. when you're inside the library, clicking the first mouse button on an object "grabs" that object and returns the graphics state immediately to the page being edited, so that the object will be placed when the mouse button is released. so satisfying honestly.

✨ ZOOMING ✨

xcircuit has unconstrained zooming and snap-to positioning. objects scale completely: line widths and text sizes will increase/decrease proportionally with the zoom, as well as dot/dash spacing and all other features. xcircuit does have a minimum integer grid in coordinate space, which translates to 0.005 inches at an output scale of 1. the maximum zoom scale gives a screen size translating to about 100 by 100 inches at an output scale of 1. 😭 the effective scale can be varied by changing the output scale (reached from the File/Write menu selection) in order to fit a drawing to a page or to get a grid matched to a specific dimension. a separate scale parameter changes the scale of the reported position relative to the output scale (as it will appear on a printed page).

✨ SNAP-TO GRID ✨

the snap-to grid is an all-important feature for circuit drawing, because it is critical that elements line up properly with one another. no cap.

in xcircuit, there is no way to get off the snap-to grid except by turning the snap function off and physically pushing elements off the grid. generally, it's most convenient to leave the snap function on and use key macros + and - to double/halve it as necessary. in any case, objects can always be returned to the snap grid with the "snap" function (key macro S).

✨ SELECTION MECHANISM ✨

objects are selected using a variety of search methods. the select box (formed by holding down mouse button 2 and dragging the pointer) uses the simplest method, searching for curve/polygon segment endpoints, arc centers, and label and object bounding boxes falling within the select box frame. general object selection is more complicated, bestie.

polygons, arcs, and curves are selected by their outer edges, not the interiors. currently this is also true for filled instances of those types. a line is selected if the pointer is in a region describing a box around it, which is adjusted according to the scale (zoom factor). every object has an associated bounding box, which is rectangular but may be rotated with respect to the top level window. an object instance is selected if the pointer falls within its bounding box. each label also has a bounding box carefully calculated from the width of the text string.

often the selection mechanism will find multiple elements in range of the pointer. when that happens, each object in turn will be presented, colored in blue (or the specified querycolor in the defaults file), and you have the option of accepting the highlighted element for selection using mouse button 1, or rejecting it with mouse button 3. when all the elements under consideration have been accepted or rejected, the program proceeds to execute whatever function was in progress. this selection method takes a little while to get used to, but it's sensible and seems to work well. 🦋

✨ COLOR ✨

color in xcircuit is implemented with the idea of "color inheritance". every page has a "default color" of black. all elements which have color value Inherit will inherit the default color, black. if an object instance is painted blue (for instance), all components in that object which have color value Inherit will inherit its color, blue.

the reason for this is that it allows different object instances to be painted different colors (such as if one part of a circuit is highlighted for emphasis), while making it possible for object instances to be multicolored, if necessary. changing the color of an object instance will have no observable effect on the drawing if none of the components of the object inherit that color. an object may have both normally colored components and components which inherit their color, in which case only those components with the Inherit value will change color when the color of the object instance is changed.

✨ SCHEMATIC CAPTURE ✨

xcircuit implements a sophisticated schematic capture. unlike virtually all schematic capture software currently available, xcircuit allows the designer to draw the circuit in a "natural" way, making use both of schematic hierarchies and simple hierarchies created simply by grouping elements together. if the chosen netlist format is hierarchical (like SPICE), both hierarchical forms will be retained in the output. for element grouping, input/output ports connecting into the group will be determined automatically, from context. 🧚

a schematic capture tutorial is available from the xcircuit website, http://opencircuitdesign.com/xcircuit/tutorial/tutorial2.html.

netlist types currently available are SPICE, sim, and PCB.

✨ KEYBOARD COMMANDS ✨

basic keyboard commands:

  • Z — zoom in by a factor of 3/2. if this key is pressed while a selection box is active (created with the middle mouse button), then it acts like the Zoom Box function.
  • z — zoom out by a factor of 3/2.
  • p — pan the screen so that the point under the mouse is brought to the center of the program window. this function can also be conveniently performed by clicking on the scrollbars. the scrollbars cannot be moved continuously due to the slow time for screen refresh. 💀
  • cursors — the arrow keys perform a pan of one-half window size in the direction of the arrow pressed.
  • l — go to the Library of built-in objects. from the library, use mouse button 1 to grab an object and bring it back to the edit screen, or button 3 to return without selecting an object instance. while in the library screen, the zoom and pan functions can be used to move around.
  • > — push into an on-screen object in order to edit that object
  • < — return from editing an object. object pushes and pops can be stacked indefinitely. 🤯
  • space — refresh the screen.
  • digits 0-9 — switch to one of the first ten editing pages. pages greater than 10 can be reached from the Window/Goto Page menu selection.

okay we're not done yet bestie, there's more where that came from 💜

  • + and - — bump the snap-to grid spacing up or down by a factor of two. lil zoomies for your grid ✨
  • |, :, and _ — (bar, colon, underline) restyle whatever's currently selected to dashed, dotted, or solid respectively. glow-up for lines 💅
  • h or ? — pops up a help page summary of the commands. your lil cheat sheet, bestie 🫶

✨ Commands to create elements ✨

  • a — Arc. Center is locked in at wherever the cursor started. Mouse position changes the radius of the circle. In snap-to mode, the arc boundary will pass through the snap point closest to the cursor. Mouse button 1 cycles from controlling the radius → controlling the starting point → the ending point → and separately controlling the minor axis to make an ellipse. Mouse button 2 completes the arc. 🌀
  • b — Box. This is a convenience function for generating rectangular closed polygons, fr fr. Makes a rectangle with one corner fixed at the cursor position. Moving the cursor after that defines the point diametrically opposed. Mouse buttons 1 or 2 complete the box. 📦
  • s — Spline curve. The first endpoint is defined by the initial cursor position. Mouse position adjusts the other endpoint of the curve. Mouse button 1 cycles from controlling position of the endpoint → controlling positions of the curve control points → the curve starting point. Mouse button 2 completes the curve. 🌊
  • t — Text. Text starts out justified according to the styles you chose in the pull-down menu. You can rejustify it using the menu, or by typing the numbers on the keypad (shift-keypad-1 through shift-keypad-9). The position of the keys on the keypad matches the justification — cute, right? Subscripts, superscripts, font changes, text size changes, underlining, and overlining are all available from the pull-down menu. Text edit mode recognizes Home and End keys to move to the beginning and end of the string, respectively. If the X11 environment maps control key sequences to character encodings (such as ISO-Latin1), those may be used to insert non-ASCII text. Another method of inserting non-ASCII characters is the backslash character, which duplicates the action of the Text/Insert/Character menu button. ✍️
  • M, m — Make object. Takes all the elements currently selected and compiles them into an object. The object is then placed in the user library. The elements you just selected are deleted from the screen and replaced by the new object. The center point of the resulting object is chosen as the closest snap-to point to the center of the object's bounding box; if you want a different center, then the object can be edited using the > command and its contents moved with respect to its origin.
Note: objects cannot have the same name as PostScript commands, or the same name as any other object in memory. If such a name is found, an underscore (_) will be prepended to the name as many times as is necessary to differentiate it from all other known objects. The name also cannot contain special PostScript characters such as slash; any such characters found will be replaced with underscores. 🚫

🛠 Major editing commands 🛠

  • d — Delete. Select the nearest element or elements and delete it/them. bye bestie 👋
  • u — Undelete. Xcircuit saves up to 10 delete events to be recovered. Delete events are stored in order of occurrence, and the most recent delete event is the first to be recovered. When multiple elements are deleted at the same time, all of them are stored as one delete event, and restored together. so you get 10 oopsie-doos, use them wisely 😭
  • x — Deselect. Elements which have been selected can be deselected on a per-item basis. In order not to be too confusing, deselect does not query if multiple items are found under the cursor; it just deselects them all. all of them. every single one. periodt 💀
  • c — Copy. Make a copy of the object(s) nearest the cursor. Object is automatically grabbed for moving to a new position. The next button1 or button2 press will place the element. Button2 will end the copy, and button1 will continue the copy function. 🫶
  • e — Edit. The action of Edit depends on the type of element selected. These are detailed below:
    • Label — Returns to text editing mode, starting with the cursor at the end of the string. Mode is like regular text entry except that Button 3 returns text to its original string.
    • Polygon — Grabs one point of a polygon for repositioning. Button 1 cycles between points, button 2 accepts the new polygon, and button 3 returns to the previous state, unless there is no remaining edit history, in which case it aborts the command. Key macros available during polygon edit are:
      • "x" — Breaks the polygon at the given point.
      • "e" — Moves edit position to the next point.
      • "i" or "Insert" — Inserts a new point at the position.
      • "d" or "Delete" — Deletes the current edit point.

There are four modes for polygon editing; see the "Polygon Edit" section below for details.

  • Arc — Allows resizing of the radius. Mouse button 1 or the "e" key will cycle between control of the radius, the endpoint angles, and the ellipse minor axis. Mouse button 2 accepts the new arc. Button 3 returns to the previous editing state, unless there is no remaining edit history, in which case it aborts the command.
  • Curve — Allows repositioning of one end of the curve. Originally, the starting angle of the curve is kept fixed. Mouse button 1 or the "e" key cycles between the four control points of the curve, allowing control over the angle of the curve at its endpoint and the shape of the curve. Mouse button 2 accepts the new curve. Button 3 reverts back to the previous edit state unless there is no remaining edit history, in which case it terminates the command.
  • Object instance — Object instances have no properties to change except scale, and do not respond to the "edit" command. Scale can be changed by selecting Options/Other/Object Size from the menu.

🎀 Minor editing commands 🎀

  • R — Rotate the selected element(s) or element under the cursor counterclockwise in 15 degree intervals.
  • r — Rotate the selected element(s) or element under the cursor clockwise in 15 degree intervals.
  • O — Rotate the selected element(s) or element under the cursor counterclockwise by 5 degree intervals. This is currently the smallest angle resolution available to xcircuit. 👑
  • o — Rotate the selected element(s) or element under the cursor clockwise by 5 degree intervals.
  • f — Flip an element around a vertical axis defined by an object's origin for an object instance, or across an axis defined by the pointer position for arcs, polygons, and curves.
  • F — Flip an element around a horizontal axis defined similarly to the "f" command.
  • X — If two elements are selected, their order is exchanged (this is only relevant if one element occludes another). If one element is selected, it is raised up one in the stack, and if it is already on top of the stack, it is shuffled to the bottom. 🔀
  • S — Snap the nearest object to the snap-to grid. For curves the control and endpoints are snapped; for polygons, each point is snapped; for arcs, the centerpoint is snapped; for labels and object instances, the designated point of origin is snapped.
  • j — Join polygons together. This only makes sense if it is possible to make a single continuous (open or closed) polygon from the selected parts. Otherwise a warning will be posted and the parts will remain separate. no forced friendships here 🥲
  • A — Attach an element to a polygon, arc, or curve. The element to be attached must be the one currently grabbed (either by a "drag", copy command, or edit command). Until it is released, it will be forced to align its center (object, arc), endpoint (polygon, curve), or position (label) with the closest polygon, arc, or curve. Note that this is a very powerful tool for generating, for example, lines tangent to a curve, or objects arranged in a circle or along a line. 🔥

📚 Library editing commands 📚

  • D — Delete. The selected objects will be deleted from the library unless other library objects or pages contain references to that object.
Note: unlike deleting object instances with the "d" command, this command deletes the actual object and releases all memory associated with that object, so the object cannot be undeleted. this is the permanent one, bestie, no take-backs 💀
  • C — Copy. Makes a copy of an object from either library page and places the new copy in the user library. The new object will be renamed to avoid naming conflicts.
  • M — Move. If one object has been selected, it is moved to the position of the cursor. If two objects have been selected, their positions in the library are exchanged. 🌀
  • E — Edit label. Edit the object name whose label is under the cursor. After editing, the object name will be checked for conflicts with other object names, and altered if necessary.
  • H — Hide object. If the object is a sub-instance of another object, but is not meant to be used by itself, it can be "hidden" so that it will not appear by itself on the library page. 🙈

Okay bestie, this is the big one — all the stuff you can click on in the menus. Buckle up 💖

  • Write Postscript (W) — not me pulling up a whole popup menu of options for this one 👑 First thing it does? It shows you the name of the file if one already exists, or else it gives you the default name of the buffer (usually Page n, where n is the number of the buffer). Next up, a little preview of the picture scale and the output styles, which include Landscape/Portrait orientation and Encapsulated/Unencapsulated (full page) PostScript modes. That first one — the scale — lets you tweak the nominal size of the picture when it's drawn in PostScript. Default scale is 1.00, which makes the text scale of 1.0 about 14 points on the PostScript page. The width and height of the resulting picture are also shown, in inches, and you can change any of those three values — the other two will update accordingly, slay ✨ Pages which have the same name get grouped together into a single file, which means you can stash multiple pages in the same PostScript file. BUT — and this is important — since Encapsulated PostScript doesn't make sense for that kind of file, it is not an option here.

The Write File button writes the current page to an output file. If the page has a name other than the default, the file gets automatically saved under that name. Otherwise? You gotta change the name of the buffer yourself. And if a file of that name already exists on the disk, the button will read Overwrite File instead. No surprises 💅

  • Read PostScript — reads in a file of Xcircuit format. It asks for the file name with a popup prompt, and it'll tack on an extension of ".ps" if necessary. The file gets read into the current page, which is cleared first if there's anything in it. If the file is a multiple-page file, the current page gets overwritten with the first page from the file, but the other pages get loaded into empty buffers. Bonus: Xcircuit can also read "lgf"-format files from the Chipmunk CAD tools programs "analog" and "diglog" 🦋
  • Import PostScript — literally acts like "Read PostScript" except the page is not reset first, so your new graphics just get added on top of whatever's already there on the page. Stacking, we love to see it 💜
  • Clear Page — clears the current page of all elements and resets the name. Heads up though: the contents cannot be recovered 😭 It's giving irreversible, bestie.
  • Alt Color — switches between the two xcircuit color schemes. You can redefine the schemes through XDefaults (see below). The defaults are black-on-white and white-on-black. The latter is less straining to the eyes, but the former matches the black ink on white paper PostScript output. And like — any color scheme other than black-on-white is not recommended for drawings with color, because the actual output does not match the observed xcircuit screen. Visual mismatch, we don't claim her 🙈
  • Grid — turns the grid lines on and off. Simple. Iconic.
  • Axes — turns the axis lines on and off. The axes mark the origin (0,0) of the page. On the top level (TopObject), the origin has no particular relevance, since encapsulated output will define its own boundaries, and full-page (unencapsulated) output will be centered on the output page — not according to the Xcircuit coordinate system. So like, don't stress about it ✨
  • Grid spacing — changes the spacing of the grid lines. Default spacing is 1/6 inch, which is about the width of the letter 'W' in default text scale. Cute little unit of measurement, honestly.
  • Grid type/display — this is a submenu, and it lets you specify the coordinates and coordinate grid in alternate units. Listing of coordinates in the top window can be in default fractional inches, decimal inches, or centimeters. Default spacing of grid lines is either one-quarter inch or one-half centimeter. Selecting an A:B scale with option "Drawing Scale" causes all listed coordinates to be multiplied by the scale. ⚠️ Note: Xcircuit will make an attempt to keep objects on the snap/grid spacing when switching between inch and centimeter scales. In order to do this, it will change the output scale by the ratio of 2.54 to 2.5, thus keeping a closer correspondence between inches and centimeters. To get true centimeters on the output page, the output scale (from the "File/Write Xcircuit PS") can be reset to 1.0 — at the expense of having all objects intended for the inch grid displaced off of the snap grid. Tradeoffs, bestie, tradeoffs 💀
  • Snap-to — turns the snap-to grid on and off. When the grid is on, movement and placement of elements is restricted to points on the snap-to grid. Structure, we stan 🎀
  • Snap spacing — determines the spacing of the points in the snap-to grid. Default is 1/12 inch, which is half the grid line spacing. Math is mathing ✨
  • Linewidth — controls the default linewidth against which all linewidths in the drawing are scaled. She's the blueprint, the main character, the standard 🫶
  • Polygon Edit — the options in this submenu control how the position of lines is affected when a point in a polygon is selected for editing.
    • "Rhomboid-X" mode moves adjoining points as necessary to keep all horizontal lines horizontal.
    • "Rhomboid-Y" mode acts similarly to keep all vertical lines vertical.
    • "Rhomboid-A" is similar to Manhattan mode but also tracks non-Manhattan lines.
    • The default mode is "Manhattan Box Edit", which is a combination of Rhomboid-X and Rhomboid-Y.
    • In "Normal" mode, only the point being edited can be moved.
  • Arc/Box/Curve Border — the options under this menu determine the border style of arcs, polygons, and curves. If an element is selected, it will be modified; otherwise, if no objects are selected, the style chosen is made default for all subsequent arcs, polygons, and curves. Elements may be drawn with or without borders — but for obvious reasons, they can't be made both borderless and unfilled, because that would be literally invisible 💀 The borders may be closed or unclosed. For an arc, closed means that a chord is drawn connecting the two endpoints, if the beginning and ending angles do not complete a full circle. Borders may be solid, dashed, dotted, and of varying width. The range of options? Chef's kiss 👑
  • Arc/Box/Curve Fill — the options under this menu determine the fill style of arcs, polygons, and curves. Fill style may be solid, empty, or one of 7 stipple patterns varying from light to dark, which are drawn both in xcircuit and PostScript as stipple patterns. Stipples can be transparent or opaque.
⚠️ Warning: Transparent stipples are NOT inherent to PostScript, and the hacks necessary to implement them cause slow rendering on a printer or PostScript previewer. Due to the device-dependent nature of the routines, patterns will look abnormally large on PostScript previewers. This transparency feature has been added with the expectation that most circuit schematics will not rely heavily upon halftoning. Not me warning you dramatically but also for real 🫠

Complicated color patterns can be created using transparent colored, stippled elements on top of solid-color elements. Note: ordering of elements is according to order created. A different ordering can be achieved using the "X" (exchange) command. This method is not especially easy to work with, and hopefully something better will be implemented in the future. Fingers crossed bestie 🤞

  • Arc/Box/Curve Color — see the COLOR section above for a discussion of color inheritance. This menu shows all the colors available to xcircuit, with the option of adding more colors. Currently the entry style for colors is by name, or by RGB content in the X11 style of #rrggbb, where rr, gg, and bb are hex values ranging from 00 to FF. The only limit to the number of colors is the X Server's colormap depth. If the colormap is full, xcircuit attempts to allocate the closest possible color to the one requested. So generous of her 💖
  • Zoom Box — this zoom feature requests the user to create a box (using either mouse button 1 or 2, expanding the box while holding down the button). When the button is released, the view will zoom to the area of that box. Draw the rectangle, get the zoom, periodt ✨
  • Full View — this zoom feature calculates the bounding box of the entire picture and adjusts the scale to make it fit comfortably inside the program window. Everything on screen, no cap 🌈

🎀 TEXT FEATURES 🎀

okay bestie, sit up for this one, because xcircuit's ability to handle text is arguably the most complicated part of the whole program, and it's also the most complicated part of the PostScript output. no cap. the key to a good drawing is careful attention to text justification and style. that's the whole vibe. 💅

Text Size ✨

this changes the size of your labels. the value is a scale, and the default is 1.0, which translates to 14 points on the PostScript page if you're using the default page scale of 1. here's the tea on who gets affected:

  • if a label is selected, only that label changes.
  • if a label is being edited, scale changes start at the edit position.
  • otherwise it becomes the default size for all subsequent labels.

size affects the entire text string. you can change text size anywhere inside of a string, bestie. BUT — and this is the part people miss — text sizes inside a string are all given relative to the label size, not as an absolute point size. and the sizes of subscripts and superscripts are given relative to the natural size of the subscript or superscript (2/3 the size of the text for which it is a modifier). okay? okay. 🫶

Text Font 🎀

the standard printer fonts Times-Roman, Helvetica, Courier, and Symbol are readily available. easy. slay.

"User-defined" fonts can also be added; however, support is currently limited, and requires a font object (.lps) file and encoding (.xfe) file, examples of which are found in the fonts subdirectory of the xcircuit library directory. so like, doable, but know what you're doing. 🙈

Text Style 💜

four standard font styles are available, matching the standard printer font variations:

  • Normal
  • Italic (or oblique)
  • Bold
  • BoldItalic

and PostScript matrix manipulation allows slanted versions of any font — such as Symbol — for which none is otherwise available. iconic behaviour honestly. 🌈

Text Insert 🌸

the Insert menu lets you insert special characters that aren't (necessarily) allowed from the keyboard. the lineup:

  • tab-stop
  • tab-forward
  • tab-backward
  • kern
  • half-space
  • quarter-space
  • "Character"

that last option, "Character", brings up a page showing the 256-character encoding vector for the font, so you can point-and-click your way into any character in the font. and "Kern" instructions let characters be offset vertically or horizontally relative to the rest of the text. cute, precise, obsessed. ✨

Text Encoding 🧚

two standard font encodings are available by default:

  • Standard (Adobe) Encoding
  • ISO-Latin1 encoding

ISO-Latin2 and ISO-Latin5 encodings exist in the library directory, but they require the use of the program "ogonkify" (not included) to produce correct output on a printer. so heads up, that's a whole side quest. 😭

Super and Subscripts 🦋

superscript and subscript are designed to closely match those in TeX output, though they lack the proper context-dependent kerning and other fancy features of TeX. so like, TeX-adjacent, not TeX. fr fr.

  • a superscript following a subscript results in a superscripted subscript.
  • to get a superscript on top of a subscript, use the backspace character (see below).
  • the Normalscript style is how you get out of a sub or superscript and return to the normal size and position.

and for quick super/sub/normalscripting, the keypad has your back: "+" (plus), "-" (minus), and "Enter" respectively. 💅

Overline and Underline ⭐

overlining and underlining styles remain in effect until the next occurrence of a style or font change. that's the rule, remember it.

  • overlining is lower if all the characters are lowercase and do not include the "tall" lowercase characters.
  • overlining or underlining can be stopped at any time using the No Line style.
Over and Underlining is always preferable to using a line. PostScript will adjust the over or underline to the text size and extent and actually grab the "_" character and compute its thickness in order to draw the line.

like, it's literally doing math for you. use it. 👑

Tabbing 🌈

from version 2.3, xcircuit allows embedded tab stops. tab stops must be defined before using tab-forward or tab-backward. no tab stops, no tabbing, bestie.

  • the "Tab" keyboard key inserts an embedded tab-forward instruction into a label.
  • Tab-stop and tab-backward can be inserted using the Text->Insert menu.
  • a tab-forward instruction moves the cursor to the first defined tab stop forward of the current position.
  • a tab-backward instruction moves the cursor to the first defined tab stop backward of the current position.
  • if no appropriate tab stop exists, the instruction has no effect.

Backspace 💀

the use of the backspace character is deprecated from xcircuit version 2.3. the effect of an embedded backspace is more reliably produced using tab-stop and tab-backward. so like… stop using it. it's giving legacy. 🙈

Halfspace and Quarterspace 🍓

these options allow fine control over spacing, which is particularly useful when writing equations. tiny adjustments, big payoff. ✨

Justification 💖

text justification always starts with the default, chosen from the options in the menu, but may be changed at any time using the numbers on the keypad. the position of the keys on the keypad reflects the point of justification:

  • 1, 4, and 7 are right-justified
  • 7, 8, and 9 are bottom justified
  • 5 is centered in both directions

and since the letters drawn by xcircuit are optimized for the Helvetica font, correct justification is the main way to get text to come out on the PostScript page in the desired way, relative to objects or boxes or whatever. it's the whole game, genuinely. 🫶

🧾 .XCIRCUITRC FILE 🧾

certain parameters of the xcircuit program can be initialized from a file called .xcircuitrc, which is first searched for in the current directory, and then in the user's home directory as defined by the environment variable $HOME. so it checks local first, home second. periodt.

the startup file is written in Tcl. the command-line interface can be found in the online documentation on the website

http://www.opencircuitdesign.com/xcircuit/.

🚨 CRASH RECOVERY 🚨

XCircuit implements a crash recovery system by which a copy of the current file is made every 15 minutes (see Xdefaults, below, for changing this value). XCircuit deletes this file upon a normal exit.

if, however, XCircuit crashes or is terminated by Control-C or other sudden death, the backup copy will remain. 💀

on startup, XCircuit checks the /tmp directory for any XCircuit backup files belonging to the user. if one is found, XCircuit will prompt the user for recovery. so you don't have to remember, it remembers for you. bestie behaviour fr. 🫶

note that the backup is unique in that it contains a copy of the entire user space at the time of the crash. filenames may get overwritten, as the backup will treat all pages as belonging to the same file.

so like, heads up on that one. 🌸

✨ KEY BINDINGS ✨

So like, remember how we said up there that keys can be bound and unbound through the command-line functions bind and unbind? Yeah. That. 💅 And all the default key bindings? They're the ones used all over this manual page, so if you see a key mentioned somewhere, this is where it comes from.

Key names use the notation from /usr/X11R6/include/keysymdef.h, but plot twist — the XK_ notation is optional. Also you get bonus prefixes: Shift_, Control_, Capslock_, and Alt_, and you can stack them in any combination you want. 🎀

Heads up bestie: Shift_ is not used for ASCII characters (so it's A, not Shift_a) unless you're combining it with other special keys — like Control_Shift_A to tell it apart from Control_a, if that's what you're into.

Also valid as names: Button1, Button2, and Button3 — those point at functions attached to the mouse buttons in normal drawing mode.

Here's every function you can bind, plus what it does and its default key binding. No skips, we're doing all of them 🫶

  • "Page" — change page → default: Number keys 1-9 and 0
  • "Justify" — change text justification → default: Keypad keys 1-9
  • "Superscript" — set text superscript → default: Keypad +
  • "Subscript" — set text subscript → default: Keypad -
  • "Normalscript" — cancel sub/superscript → default: Keypad Enter
  • "Nextfont" — change to next font → default: Alt-f
  • "Boldfont" — change to bold font → default: Alt-b
  • "Italicfont" — change to italic font → default: Alt-i
  • "Normalfont" — cancel italic/bold → default: Alt-n
  • "Underline" — generate underline → default: Alt-u
  • "Overline" — generate overline → default: Alt-o
  • "ISO Encoding" — change to ISO encoding → default: Alt-e
  • "Return" — embedded return character → default: Alt-Enter
  • "Halfspace" — embedded half-space → default: Alt-h
  • "Quarterspace" — embedded quarter-space → default: Alt-q
  • "Special" — special character → default: Alt-c
  • "Parameter" — embedded parameter → default: Alt-p
  • "Edit Break" — break at point → default: x
  • "Edit Delete" — delete point → default: d, Delete
  • "Edit Insert" — insert point → default: i, Insert
  • "Edit Next" — go to next point → default: e
  • "Attach" — attach line to object → default: A
  • "Next Library" — go to next library → default: l
  • "Library Directory" — library directory → default: L
  • "Library Move" — arrange library objects → default: M
  • "Library Copy" — get object in copy mode → default: c
  • "Library Edit" — edit library name → default: E
  • "Library Delete" — delete library object → default: D
  • "Library Duplicate" — duplicate object → default: C
  • "Library Hide" — hide library object → default: H
  • "Page Directory " — page directory → default: P
  • "Library Pop" — return from library → default: <
  • "Help" — generate help screen → default: h, ?
  • "Redraw" — redraw the window → default: space
  • "View" — fit page to window → default: v
  • "Zoom In" — zoom in → default: Z
  • "Zoom Out" — zoom out → default: z
  • "Pan" — center pan → default: p
  • "Double Snap" — increase snap space → default: +
  • "Halve Snap" — decrease snap space → default: -
  • "Pan Left" — pan left one-half page → default: Left arrow
  • "Pan Right" — pan right one-half page → default: Right arrow
  • "Pan Up" — pan up one-half page → default: Up arrow
  • "Pan Down" — pan down one-half page → default: Down arrow
  • "Write" — popup output window → default: W
  • "Rotate" — Rotate → default: r,R,o,O
  • "Flip X" — Flip horizontal → default: f
  • "Flip Y" — Flip vertical → default: F
  • "Snap" — Snap to grid → default: S
  • "Pop" — Return from object edit → default: <
  • "Push" — Edit object → default: >
  • "Delete" — Delete element → default: d
  • "Select" — Select element → default: Select
  • "Box" — Create box → default: b
  • "Arc" — Create arc → default: a
  • "Text" — Create label → default: t
  • "Exchange" — Exchange vertical order → default: X
  • "Copy" — Copy element → default: c
  • "Join" — Join into path → default: j
  • "Unjoin" — Split path into elements → default: J
  • "Spline" — Create spline → default: s
  • "Edit" — Edit element → default: e
  • "Undelete" — Undelete last deleted → default: u
  • "Select Save" — Make object from selected → default: M,m
  • "Unselect" — Unselect element → default: x
  • "Dashed" — Set line style to dashed → default: |
  • "Dotted" — Set line style to dotted → default: :
  • "Solid" — Set line style to solid → default: _
  • "Prompt" — Execute from command line → default: %
  • "Dot" — Place dot at location → default: .
  • "Exit" — Exit xcircuit → default: Ctrl-Alt-q
  • "Netlist" — Generate a netlist → default: Alt-q
  • "Swap" — Swap schematic, symbol → default: /
  • "Pin Label" — Create pin label → default: T
  • "Info Label" — Create info label → default: I
  • "Connectivity" — Show wire connectivity → default: Alt-w
  • "Sim" — Generate sim netlist → default: Alt-s
  • "SPICE" — Generate SPICE netlist → default: Alt-S
  • "PCB" — Generate PCB netlist → default: Alt-p
  • "SPICE Flat" — Generate flattened SPICE → default: Alt-f

Now, if you're a 2-button mouse girlie 🐭 (we respect it), you might find it useful to skip the whole Shift-Button1 combo situation and just drop these commands into your startup script instead:

bind('Escape', 'Cancel')
unbind('Button3', Cancel')
bind('Button3', 'Finish')

What this does: it moves the 3rd mouse button bindings over to the "Escape" key, and duplicates the 2nd mouse button bindings onto the 3rd. Iconic workaround, honestly. 👑

🎨 X DEFAULTS 🎨

The color scheme of xcircuit comes with a default setup, but it accepts alternate color schemes using these keywords, which you can put in your X Defaults (.Xdefaults, .Xresources) file. Like so:

!
! Sample X defaults for xcircuit, black-on-white version
!
xcircuit*foreground     : Black
xcircuit*background     : White
xcircuit*gridcolor      : Gray85
xcircuit*snapcolor      : Orange
xcircuit*selectcolor    : Blue
xcircuit*querycolor     : Green
xcircuit*axescolor      : NavajoWhite3
xcircuit*offbuttoncolor : Gray30
xcircuit*auxiliarycolor : MediumOrchid1

Two color schemes are supported at a time — ostensibly for the people who prefer the lessened eye strain of a white-on-black scheme. 🌙 The names of the secondary colors are the same as the primary colors, but with a "2" slapped on the end, e.g. "xcircuit*foreground2".

There's one other resource that defines the number of minutes between automatic saves to the temporary file (for when you crash or emergency Ctrl-C exit, oop 😭):

xcircuit.timeout         : 15

Xcircuit also recognizes the core resources, like width and height:

xcircuit.width      : 600
xcircuit.height          : 500

All xcircuit foreground and background colors are taken from the Xdefaults foreground and background. So if you want, say, white-on-black menus and buttons but a black-on-white drawing area? Do this:

xcircuit*foreground      : White
xcircuit*background      : DarkSlateGray
xcircuit.foreground      : Black
xcircuit.background      : White

This makes sure that only the drawing area is black-on-white, and every other window shows up in the less eye-straining white-on-black. Periodt. ✨

Five different fonts can be specified in the Xdefaults, and here's who's who:

  • helpfont — the style of fonts on the help popup window
  • filefont — the style of fonts in the list of files in the file selection popup window
  • textfont — the style of font for entering text in the popup dialog boxes
  • titlefont — the style of font for the cascade menu titles
  • everything else takes the type font

For example:

xcircuit*font           : *times-bold-r-normal--14*
xcircuit*helpfont     : *times-medium-r-normal--12*
xcircuit*filefont     : *times-medium-r-normal--14*
xcircuit*textfont     : *courier-medium-r-normal--14*
xcircuit*titlefont    : *times-bold-r-normal--18*

📂 FILES 📂

The file path xcircuit uses to find library files is system-dependent (i.e., it can be changed at compile time), and it can be overridden in so many ways (in .xcircuitrc or via the XCIRCUIT_LIB_DIR environment variable). But by default, it's:

/usr/lib64

  • xcircps2.pro — PostScript prolog appended to each file
  • xcstartup.tcl — This startup script contains commands of the type library name number which cause the designated library name to be immediately loaded into library page number. The startup script is also responsible for loading fonts, and may also be used to load colors on the color palette, set other options, and execute commands.
  • generic.lps, analog.lps, digital.lps, avlsi.lps, analoglib2.lps — Files containing pre-compiled circuit elements. The .lps extension is unique for xcircuit libraries.
  • fonts — This subdirectory contains font definition files for xcircuit's vector-drawn fonts. Characters are defined by xcircuit objects and stored in a .lps library. The encoding scheme and other font information is stored in a .xfe ("xcircuit font encoding") file.
  • ~/.xcircuitrc or ./xcircuitrc — Personal xcircuit initializer; commands are outlined above. Libraries listed in this file will be appended to the builtin libraries.

🌍 ENVIRONMENT VARIABLES 🌍

xcircuit understands the following environment variables, bestie:

  • TMPDIR — Directory for temporary (e.g., backup) files (defaults to TEMP_DIR).
  • XCIRCUIT_LIB_DIR — Directory where xcircuit libraries and startup files can be found (defaults to BUILTINS_DIR).
  • XAPPLRESDIR — Directory where the xcircuit application defaults can be found (defaults to RESOURCES_DIR)
  • HOME — Directory where xcircuit will look for startup files, after searching the current directory.
  • HOST, HOSTNAME, USER — Environment variables which xcircuit uses to fill in header information in the PostScript output (HOST and HOSTNAME are equivalent).

💀 BUGS 💀

Okay bestie, gather round, because we gotta talk about the limits of PostScript printers, and it's giving "the printer has a budget and it's not flexible." 😭

PostScript printers have device-dependent limits on the number of statements within a def definition. So if one of your object definitions has an unusually large number of components, xcircuit will flag a warning when writing the file. That's the heads-up. But — and this is the messy part — there is no way to ensure that a file will be accepted by a given printer. No cap.

The best way to dodge this whole situation? Make sure that large drawings make good use of hierarchically nested user-defined objects. That's the move. That's the slay. 🎀

And honestly? Note that printer errors arising from this problem have not been observed in practice, and given the typical size of on-board memory on most modern laser printers, probably never will be. So like. Breathe. 🧚

A list of bugs can be found in the Manifest file in the source directory. Periodt. 📋

🦋 ONLINE TUTORIAL 🦋

Not me about to hand you the actual lore. Look for the xcircuit online tutorial at

http://opencircuitdesign.com/xcircuit/tutorial/tutorial.html

Go read it. Iykyk. ✨

👀 SEE ALSO 👀

  • xfig(1) — another powerful freeware drawing program worthy of mention (see www.xfig.org). Respect where respect is due, fr fr. 💜
  • Another schematic capture package worth noting is "gschem" from the gEDA package (see www.geda.seul.org). Bestie lineup. 🔥

📝 NOTES 📝

PostScript is a registered trademark of Adobe Systems Incorporated. Important. Don't be weird about it. 💅

XCircuit Copyright (c) 2002 Tim Edwards. XCircuit is freely distributed under a generous public license. See the source distribution for details. 👑

Xw widget set Copyright (c) 1988 by Hewlett-Packard Company and the Massachusetts Institute of Technology. Iconic. 🌈

🌸 AUTHOR 🌸

Tim Edwards <tim@opencircuitdesign.com>. The main character, lowkey. 🫶

And the thank-you section, because this man does not gatekeep credit:

  • Thanks to Tomas Rokicki for the PostScript routine which manufactures a Symbol-Oblique font. Genuinely obsessed with that. ✨
  • Thanks to Dave Gillespie and John Lazzaro for the program "analog" on which the graphical interface of xcircuit is (roughly) based. The blueprint era. 💖
  • Thanks to many beta-testers, some of whom were kind enough to send patches. The real ones. 🥹
  • Most contributors have been named in the Manifest file in the source distribution. Go look, your faves might be in there. 📖
🎀 and that's the whole page, bestie!! 🎀 This gorgeous thing came from the X11R6 era, dated January 5, 2000, and it's filed under XCircuit(1). Older than most of us and still serving absolute looks. No notes. 💅✨💖
📦 where this page comes from