Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
XCircuit(1)		    General Commands Manual		   XCircuit(1)

       xcircuit	 -  Draw  circuit  schematics or almost	anything; make circuit
       netlists	from schematics.

       xcircuit	[filename[,...]]

       The program xcircuit is a generic drawing program  tailored  especially
       for  making  publication-quality	 renderings of circuit diagrams	(hence
       the name).  The output is pure PostScript, and the graphical  interface
       attempts	 to  maintain  as much consistency as possible between the X11
       window rendering	and the	final printer output.

       xcircuit	is mouse, menu,	and keyboard-driven, with the emphasis on sin-
       gle-character keyboard macros.

	       Begin  running xcircuit by loading in the PostScript file file-
	       name.  If filename does not have	a .ps extension, xcircuit will
	       attempt	to  look  for  both  the filename as entered and, upon
	       failure,	with the .ps extension.	 The file must be in  xcircuit
	       format.	filename may also be a comma-separated list of files.

       There are five drawing elements.	 These are as follows:

       a) polygon (multiple lines which	may or may not be closed and filled)

       b) arc (ellipse segment which may be closed and/or filled as above)

       c) label	(any text)

       d) curve	(based on the PostScript "curveto" algorithm)

       e) object instance (see below)

       There are two composite elements, which are:

       f) path (a connected series of polygons,	arcs, and curves)

       g) object  (something containing	polygons, arcs,	labels,	curves,	paths,
	  and instances	of other objects)

       The mouse button	system,	the object library, and	the paged buffer  sys-
       tem  are	 loosely based on the Caltech circuit-simulation program "log"
       (either "analog"	or "diglog").

       The general idea	is to make the most commonly-used functions the	 easi-
       est  to	perform, and (to the extent possible) to scale (inversely) the
       complexity of performing	a function with	the frequency  of  that	 task.
       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 selection of elements	singly or in groups.

       Mouse  button  1	can be tapped to start a connected chain of lines, the
       most common drawing function.  In addition, button  1  has  a  function
       called  "grab",	which  occurs  after  the  button has been continually
       pressed for a short length of time (about 1/5 second).  As the name im-
       plies,  "grab"  grabs hold of an	element	which can then be moved	around
       the screen.

       Button 2	can be used to select an item if tapped, and  if  pressed  and
       held  down, a box will be drawn and everything inside that box selected
       when the	button is released.  In	all other cases, button	 2  will  com-
       plete  a	command.  For users who	have only two mouse buttons and	do not
       emulate the middle mouse	button with the	combination of buttons	1  and
       3,  use	the combination	of the Shift key and mouse button 1 to emulate
       mouse button 2.

       Button 3	will normally abort a command.	 During	 editing  of  an  arc,
       spline,	or polygon, button 3 will revert back to the previous form, or
       abort if	there is 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).
       Keyboard	commands are quicker, since they act on	the present cursor po-
       sition, whereas menu commands require an	extra step.

       The  library  is	 intended to provide a convenient way to store and re-
       trieve 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 com-
       posite of several library files (such as	"builtins.lps",	 "analog.lps",
       and  "digital.lps")  which  are	called	by  the	 startup  script ("xc-
       startup.tcl") The program first looks for the  startup  script  in  the
       current	directory, and then searches in	the directory given by the en-
       vironment variable "XCIRCUIT_LIB_DIR", and finally, in  the  hard-coded
       global  directory  (/usr/local/lib)  if it could	not find it elsewhere.
       Thus each user can add to or modify the file  of	 builtins  to  reflect
       personal	 taste.	 Since the PostScript output contains all object defi-
       nitions,	these changes to the built-in functions	are inherently	trans-
       ferrable.   Xcircuit  will  automatically resolve conflicts between ob-
       jects having the	same name but different	contents.

       The library is accesible	from the pull-down menu	or with	the  "l"  key-
       board  macro.  When inside the library, clicking	the first mouse	button
       on an object "grabs" that object	and returns the	graphics state immedi-
       ately  to the page being	edited,	so that	the object will	be placed when
       the mouse button	is released.

       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	selec-
       tion) 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).

       The  snap-to  grid  is  an  all-important  feature for circuit drawing,
       wherein it is critical that elements line up properly with one another.
       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  is most convenient to leave the snap functon 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").

       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.   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 adusted according to the scale (zoom factor).   Every  ob-
       ject  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

       Often  the  selection mechanism will find multiple elements in range of
       the pointer.  In	this case, each	object in turn will be presented, col-
       ored  in	blue (or the specified "querycolor" in the defaults file), and
       the user	has the	option of accepting the	highlighted element for	selec-
       tion  using  the	 mouse	button 1, or rejecting it with mouse button 3.
       When all	the elements under consideration have  been  accepted  or  re-
       jected,	the  program  proceeds	to  execute  whatever  function	was in
       progress.  This selection method	takes a	little while to	get  used  to,
       but is sensible and seems to work well.

       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 ob-
       ject 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 high-
       lighted for emphasis), while making it possible for object instances to
       be  multicolored,  if  necessary.   Changing the	color of an object in-
       stance 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.

       XCircuit	implements a sophisticated schematic capture.	Unlike	virtu-
       ally  all  schematic capture software currently available, xcircuit al-
       lows 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 hierarchi-
       cal  (like SPICE), both hierarchical forms will be retained in the out-
       put.  For element grouping, input/output	ports connecting into  to  the
       group will be determined	automatically, from context.  A	schematic cap-
       ture tutorial is	available from the xcircuit website,

       Netlist types currently available are "SPICE", "sim", and "PCB".

       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 but-
		   ton), then acts like	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  scroll-
		   bars.   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 button1 to	grab an	object and bring  it  back  to
		   the	edit screen, or	button3	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.

       + and -	   Change snap-to grid spacing by a factor of two up or	down.

       | : and _   (Bar, colon,	and underline) Change style on	the  currently
		   selected object to dashed, dotted, and solid, respectively.

       h or ?	   Print a help	page summary of	commands

       Commands	to create elements:

       a   Arc.	  Center  is fixed at the initial position of the cursor.  The
	   mouse position changes the radius of	the circle.  In	 snap-to  mode
	   the	arc  boundry  will  pass through the snap point	closest	to the
	   cursor.  Mouse button 1 cycles from controlling the radius to  con-
	   trolling  the starting point, the ending point, and separately con-
	   trolling the	minor axis to create ellipse.	Mouse  button  2  com-
	   pletes the arc.

       b   Box.	  This	is  a  convenience function for	generating rectangular
	   closed polygons.  Creates a rectangle with one corner fixed at  the
	   position  of	the cursor.  Subsequent	movement of the	cursor defines
	   the point diametrically opposed.  Mouse buttons 1 or	2 complete the

       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 to
	   controlling positions of the	curve control  points  and  the	 curve
	   starting point.  Mouse button 2 completes the curve.

       t   Text.   Text	starts out justified according to the styles chosen in
	   the pull-down menu.	Text can be rejustified	using the menu	or  by
	   typing the numbers on the keypad (shift-keypad-1 through shift-key-
	   pad-9).  The	position of the	keys on	the keypad matches the	justi-
	   fication.	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), these may be used to insert  non-ASCII	 text.
	   Another  method of inserting	non-ASCII characters is	the use	of the
	   backslash character,	which duplicates the action  of	 the  Text/In-
	   sert/Character menu button.

       M, m
	   Make	 object.   Takes  all the elements currently selected and com-
	   piles them into an object.  The object is then placed in  the  user
	   library.   The  elements  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 another center is	desired, then the  ob-
	   ject	 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 have	the same name as any other ob-
	   ject	in memory.  If such a name is found, an	underscore ("_")  will
	   be prepended	to the name as many times as is	necessary to differen-
	   tiate it from all other known objects.  The name also  cannot  con-
	   tain	 special PostScript characters such as slash; any such charac-
	   ters	found will be replaced with underscores.

       Major editing commands:

       d   Delete.  Select the nearest element or elements and delete it/them.

       u   Undelete.  Xcircuit saves up	to 10 delete events to	be  recovered.
	   Delete  events  are stored in order of occurrence, and the most re-
	   cent	delete event is	the first to be	recovered.  When multiple ele-
	   ments  are  deleted at the same time, all of	them are stored	as one
	   delete event, and restored together.

       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 de-
	   selects them	all.

       c   Copy.   Make	a copy of the object(s)	nearest	the cursor.  Object is
	   automatically grabbed for moving to a new position.	The next  but-
	   ton1	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 is	dependent on the type of  element  se-
	   lected.  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 ex-
		   cept	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 com-
		   mand.  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  but-
		   ton 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	previ-
		   ous	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

       Minor editing commands:

       R   Rotate the selected element(s) or element under the cursor counter-
	   clockwise in	15 degree intervals.

       r   Rotate the selected element(s) or element under the	cursor	clock-
	   wise	in 15 degree intervals.

       O   Rotate the selected element(s) or element under the cursor counter-
	   clockwise 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	clock-
	   wise	by 5 degree intervals.

       f   Flip	an element around a vertical axis defined by an	object's  ori-
	   gin	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  con-
	   trol	 and  endpoints	 are  snapped;	for  polygons,	each  point is
	   snapped; for	arcs, the centerpoint is snapped; for labels  and  ob-
	   ject	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 re-
	   main	separate.

       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 un-
	   less	other library objects or pages contain references to that  ob-
	   ject.  Note:	Unlike deleting	object instances with the "d" command,
	   this	command	deletes	the actual object and releases all memory  as-
	   sociated with that object, so the object cannot be undeleted.

       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.

       Write Postscript	(W)
	   This	 command  brings  up  a	 popup	menu with a number of options.
	   First, it gives the name of the file	if  one	 exists,  or  else  it
	   gives  the  default	name of	the buffer (usually Page n, where n is
	   the number of the buffer).  Next, it	gives a	preview	of the picture
	   scale  and output styles, which include Landscape/Portrait orienta-
	   tion	and Encapulated/Unencapsulated (full page)  PostScript	modes.
	   The	former	allows	adjustment  of the nominal size	of the picture
	   when	drawn in PostScript.  The 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  given,  in
	   inches,  and	any of the three values	can be changed.	 The values of
	   the other two will be updated accordingly.  Pages  which  have  the
	   same	 name  will  be	 grouped together into a single	file, allowing
	   multiple pages to be	stored in the same PostScript file.   However,
	   as  Encapsulated  PostScript	 does  not make	sense for this kind of
	   file, it is not an option.

	   The Write File button writes	the current page to  an	 output	 file.
	   If  the page	has a name other than the default, the file will auto-
	   matically be	saved under that name.	Otherwise, it is necessary  to
	   change  the name of the buffer.  If a file of that name already ex-
	   ists	on the disk, the button	will read Overwrite File.

       Read PostScript
	   Reads in a file of Xcircuit format.	The file name is requested  by
	   a  popup  prompt, and an extension of ".ps" will be added if	neces-
	   sary.  The file is read into	the current  page,  which  is  cleared
	   first  if  anything is in it.  If the file is a multiple-page file,
	   the current page will be overwritten	with the first page  from  the
	   file,  but other pages will be loaded into empty buffers.  Xcircuit
	   can also read "lgf"-format files from the Chipmunk CAD  tools  pro-
	   grams "analog" and "diglog".

       Import PostScript
	   Acts	 like  "Read  PostScript"  except  that	 the page is not reset
	   first, so graphics are added	on top of  existing  graphics  on  the

       Clear Page
	   Clears  the	current	page of	all elements and resets	the name.  The
	   contents cannot be recovered.

       Alt Color
	   Switches between the	two xcircuit color schemes.  The color schemes
	   can	be redefined through XDefaults (see below).  The default color
	   schemes 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.  Any color scheme other than	black-
	   on-white  is	not recommended	for drawings with color, as the	actual
	   output does not match the observed xcircuit screen.

	   Turns the grid lines	on and off.

	   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 particu-
	   lar relevance, since	encapsulated output will define	its own	bound-
	   aries,  and	full-page  (unencapsulated) output will	be centered on
	   the output page, not	according to the Xcircuit coordinate system.

       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

       Grid type/display
	   This	is a submenu allowing the coordinates and coordinate  grid  to
	   be specified	in alternate units.  Listing of	coordinates in the top
	   window can be in default fractional inches, decimal inches, or cen-
	   timeters.  Default spacing of grid lines is either one-quarter inch
	   or one-half centimeter.  Selecting an A:B scale With	option	"Draw-
	   ing	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 be-
	   tween inches	and centimeters.  To get true centimeters on the  out-
	   put	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.

	   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

       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.

	   Controls the	default	linewidth against which	all linewidths in  the
	   drawing are scaled.

       Polygon Edit
	   The	options	 in this submenu control how the position of lines are
	   affected when a point in a polygon is selected for editing.	"Rhom-
	   boid-X"  mode moves adjoining points	as necessary to	keep all hori-
	   zontal 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

       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	 modi-
	   fied;   otherwise,  if no objects are selected, the style chosen is
	   made	default	for all	subsequent arcs, polygons, and	curves.	  Ele-
	   ments may be	drawn with or without borders (but for obvious reasons
	   cannot be made both borderless and unfilled,	which would be invisi-
	   ble)	 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.

       Arc/Box/Curve Fill
	   The options under this menu determine the fill style	of arcs, poly-
	   gons,  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  in-
	   herent  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 ab-
	   normally large on PostScript	previewers.  This transparancy feature
	   has	been  added  with the expectation that most circuit schematics
	   will	not rely heavily upon halftoning.  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 fu-

       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 op-
	   tion	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 col-
	   ormap is full, xcircuit attempts to allocate	the  closest  possible
	   color to the	one requested.

       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  but-
	   ton).   When	the button is released,	the view will zoom to the area
	   of that box.

       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

       Xcircuit's ability to handle text is arguably the most complicated part
       of  the	program, and also of the PostScript output.  Careful attention
       to text justification and style is the key to a good drawing.

       Text Size
	   Alters the size of the labels.  The value is	a scale,  with	a  de-
	   fault  of  1.0 which	translates to 14 points	on the PostScript page
	   if the default page scale of	1 is used.  If a  label	 is  selected,
	   only	 that  label  is  affected.  If	a label	is being edited, scale
	   changes starting at the edit	position.  Otherwise, it  becomes  the
	   default  size  for  all subsequent labels.  Size affects the	entire
	   text	string.	 Text size can be changed anywhere inside of a string.
	   However,  text  sizes inside	a string are all given relative	to the
	   label size, not as an absolute point	size.  Sizes of	subscripts and
	   superscripts	 are  given  relative  to the natural size of the sub-
	   script or superscript (2/3 the size of the text for which it	 is  a

       Text Font
	   Standard printer fonts Times-Roman, Helvetica, Courier, and Symbol,
	   are readily available.  "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.

       Text Style
	   Four	 standard  font	 styles	 are  available, matching the standard
	   printer font	variations:  Normal, Italic (or	 oblique),  Bold,  and
	   BoldItalic.	PostScript matrix manipulation allows slanted versions
	   of any font,	such as	Symbol,	for which none is otherwise available.

       Text Insert
	   The Insert menu allows insertion of special	characters  which  are
	   otherwise  not  (necessarily) allowed from the keyboard.  These in-
	   clude tab-stop, tab-forward,	tab-backward, kern, half-space,	 quar-
	   ter-space,  and  "Character".   The	latter option brings up	a page
	   showing the 256-character encoding vector for  the  font,  allowing
	   point-and-click  entry  of  any  character in the font.  "Kern" in-
	   structions allow characters to be offset vertically or horizontally
	   relative to the rest	of the text.

       Text Encoding
	   Two	standard  font	encodings  are	available by default, Standard
	   (Adobe) Encoding, and ISO-Latin1  encoding.	 ISO-Latin2  and  ISO-
	   Latin5  encodings  exist  in	the library directory, but require the
	   use of the program "ogonkify" (not  included)  to  produce  correct
	   output on a printer.

       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.	A superscript following	a sub-
	   script results in a superscripted subscript.	 To get	a  superscript
	   on  top  of	a  subscript, use the backspace	character (see below).
	   The Normalscript style is the way to	get out	of  a  sub  or	super-
	   script  and	return	to  the	 normal	 size and position.  Quick su-
	   per/sub/normalscripting is available	from the keypad	with  the  "+"
	   (plus), "-" (minus),	and "Enter" keys, respectively.

       Overline	and Underline
	   Overlining  and  underlining	styles remain in effect	until the next
	   occurrence of a style or font change.  Overlining is	lower  if  all
	   the	characters  are	lowercase and do not include the "tall"	lower-
	   case	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 un-
	   derline to the text size and	extent and actually grab the "_" char-
	   acter and compute its thickness in order to draw the	line.

	   From	version	2.3, xcircuit allows embedded tab  stops.   Tab	 stops
	   must	 be  defined  before  using  tab-forward or tab-backward.  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 ex-
	   ists, the instruction has no	effect.

	   The use of the backspace character is deprecated from xcircuit ver-
	   sion	 2.3.	The  effect  of	an embedded backspace is more reliably
	   produced using tab-stop and tab-backward.

       Halfspace and Quarterspace
	   These options allow fine control over spacing, particularly	useful
	   when	writing	equations.

	   Text	 justification always starts with the default, chosen from the
	   options in the menu,	but may	be changed at any time using the  num-
	   bers	on the keypad.	The position of	the keys on the	keypad reflect
	   the point of	justification: 1, 4, and 7 are right-justified,	7,  8,
	   and	9  are	bottom	justified,  5  is centered in both directions.
	   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.

       Certain	parameters  of	the xcircuit program can be initialized	from a
       file called .xcircuitrc,	which is first searched	for in the current di-
       rectory,	 and then in the user's	home directory as defined by the envi-
       ronment variable	$HOME.

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

       XCircuit	implements a crash recovery system by which a copy of the cur-
       rent file is made every 15 minutes (see Xdefaults, below, for  changing
       this  value).  XCircuit deletes this file upon a	normal exit.  If, how-
       ever, 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.  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.

       As noted	above, keys can	be  bound  and	unbound	 through  command-line
       functions  "bind" and "unbind".	Default	key bindings are used through-
       out this	manual page.  Key names	use  the  notation  of	/usr/X11R6/in-
       clude/keysymdef.h,  but with the	notation "XK_" being optional, and in-
       cluding the addition of prefixes	"Shift_", "Control_", "Capslock_", and
       "Alt_",	which  may  be used in any combination.	 Note that "Shift_" is
       not used	for ASCII characters (e.g., "A"	is used	instead	of  "Shift_a")
       unless  used  in	 combination  with  other  special keys	(such as "Con-
       trol_Shift_A" to	distinguish from "Control_a", should that be desired).
       "Button1",  "Button2",  and  "Button3"  are also	valid names indicating
       functions attached to the mouse buttons in normal drawing mode.	 Valid
       functions  which	may be bound are as follows, with their	default	values

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

       2-Button	mouse users may	find it	useful	to  forego  the	 Shift-Button1
       combination  and	 instead  put  the  following  commands	in the startup

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

       This will move the 3rd mouse button bindings to the "Escape"  key,  and
       duplicate the 2nd mouse button bindings onto the	3rd.

       The color scheme	of xcircuit has	a default setup, but accepts alternate
       color schemes using the following keywords which	can be put  in	the  X
       Defaults	(.Xdefaults, .Xresources) file,	such as:

	 ! 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 those	people
       who prefer the lessened eye strain of  a	 white-on-black	 scheme.   The
       names  of  the  secondary  colors are the same as those for the primary
       colors, but followed by "2", e.g., "xcircuit*foreground2".

       One other resource defines the  number  of  minutes  between  automatic
       saves  to  the  temporary  file (in case	of a crash or emergency	Ctrl-C

	 xcircuit.timeout	: 15

       Xcircuit	also recognizes	the core resources, such as width and height:

	 xcircuit.width		: 600
	 xcircuit.height	: 500

       All xcircuit foreground and background colors are taken from  the  Xde-
       faults foreground and background.  To get, for instance,	white-on-black
       menus and buttons with a	black-on-white drawing area, use  the  follow-

	 xcircuit*foreground	     : White
	 xcircuit*background	     : DarkSlateGray
	 xcircuit.foreground	     : Black
	 xcircuit.background	     : White
       This will ensure	that only the drawing area is black-on-white, but all other
       windows will appear in the less eye-straining white-on-black.
       Five different fonts can	be specified in	the Xdefaults.	helpfont is
       the style of fonts on the help popup window.  filefont is the style
       of fonts	in the list of files in	the file selection popup window.  textfont
       is the style of font for	entering text in the popup dialog boxes.  titlefont
       is the style of font for	the cascade menu titles.  All other fonts take 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*

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

       /usr/local/lib   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.

       xcircuit	understands the	following environment variables:

       TMPDIR	      Directory	for temporary (e.g., backup)  files  (defaults
		      to TEMP_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.

		      Environment variables which xcircuit  uses  to  fill  in
		      header  information  in  the PostScript output (HOST and
		      HOSTNAME are equivalent).

       PostScript printers have	 device-dependent  limits  on  the  number  of
       statements  within  a "def" definition.	If an object definition	has an
       unusually large number of components, xcircuit will flag	a warning when
       writing	the file.  However, there is no	way to ensure that a file will
       be accepted by a	given printer.	The best way to	avoid the  problem  is
       to make sure that large drawings	make good use of hierarchically	nested
       user-defined objects.  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

       A  list	of  bugs  can  be  found  in  the  Manifest file in the	source

       Look for	the xcircuit online tutorial at

       xfig(1),	another	powerful freeware drawing program  worthy  of  mention
       (see  Another schematic capture package worth noting is
       "gschem"	from the gEDA package (see

       PostScript is a registered trademark of Adobe Systems Incorporated.
       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.

       Tim  Edwards  <>.  Thanks to Tomas Rokicki for
       the  PostScript	routine	 which	manufactures  a	 Symbol-Oblique	 font.
       Thanks  to  Dave	Gillespie and John Lazzaro for the program "analog" on
       which the graphical interface of	xcircuit is (roughly)  based.	Thanks
       to  many	 beta-testers,	some of	whom were kind enough to send patches.
       Most contributors have been named in the	Manifest file  in  the	source

X11R6				January	5, 2000			   XCircuit(1)


Want to link to this manual page? Use this URL:

home | help