The XCircuit Tutorial

Table of Contents

• Task 1 Running XCircuit
• Task 2 Change an option from the menu
• Task 3 Draw a line
• Task 4 Move an object
• Task 5 Change the properties of a polygon
• Task 6 Change the page
• Task 7 Select an object from the user library
• Task 8 Use a keyboard macro to create an arc
• Task 9 Zooming and panning
• Task 10 Selection of multiple objects
• Task 11 Saving a file
• Task 12 Loading a file
• Task 13 Entering Text
• Task 14 Making curves and paths
• Task 15 Dealing with over/under arrangement of elements
• Task 16 Making user-defined objects
• Task 17 Editing objects and elements
• Task 18 Generating complex geometric shapes
• Task 19 Investigating other xcircuit commands
• Schematic Capture Tutorial
• xcircuit list of features
• Troubleshooting xcircuit

Getting started

Task 1: Run the program

The features of the xcircuit window are as follows:

1. Along the top of the screen are buttons for pull-down menus called "File", "Edit", "Text", "Options", and "Window".
2. At the top, beside the menu buttons, is a welcome message in the message window telling you the version number of the program (Version 2.0).
3. On the bottom left is a message window telling you that you are currently editing "Page 1".
4. On the rest of the bottom is a message window telling you that xcircuit has just loaded the library "/usr/local/lib/xcircuit/builtins.lps" (this may be in a different directory if xcircuit has not been installed in the default directories). This message will disappear after about 10 seconds.
5. At the left and along the bottom are two scrollbars which report the position of the drawing relative to the main window, and can be used to reposition the drawing by clicking on the bar with any mouse button. Note: Due to the length of time necessary to refresh the drawing window, the scrollbars cannot be "dragged".
6. In the center is a white drawing area with lightly-colored grid and axis lines.

Note: Xcircuit does not use double-clicking.

Task 2: Change an option from the menu

1. Press the button labeled "Options" with mouse button 1 and hold down the button while you drag the cursor around with the mouse.
2. Keeping the mouse button pressed down, move down to the "Elements" button. Each button will highlight as you pass through it.
3. Put the cursor on top of the arrow icon at the right side of the "Elements" button. You should see a secondary menu titled "Elements" pop up. The title is the topmost entry of the menu. It has no function and does not highlight when the cursor is overtop it.
4. Keep moving down to the "Color" button and again move the cursor over the arrow icon. The third and final menu of colors will pop up. Note that one item, "Inherit Color" has a check mark on it. The check mark denotes that this entry is the current default color.
5. Move down to the purple color button and release the mouse button there. The menus will disappear. You have just changed the default drawing color to purple.
6. Repeat the procedure up to step 4. When you enter the "color" menu you will see that the purple color button is now checked, showing that purple is the default drawing color.

Task 3: Draw a line

1. Tap mouse button 1 anywhere in the drawing area and release it immediately. If you wait too long to release the button, xcircuit will interpret it as trying to "grab" an element on the screen, and nothing will happen (because there aren't any elements yet to grab).
2. Move the cursor around the screen. A purple line (because you chose purple to be the default color in Task 2) will appear between the origin point and will track with the cursor.
3. Tap mouse button 1 again to finish a line segment. A new line will begin at the point the first one left off. Do this several times to form a polygon. Finish the polygon by tapping mouse button 2.
4. Repeat steps 1 through 3 but finish by tapping mouse button 3. The line you have just created will disappear. You have just cancelled the operation.

For most operations in xcircuit, tapping mouse button 1 will begin or continue an operation, tapping mouse button 2 will finish it, and tapping mouse button 3 will cancel it. The behavior can be slightly different depending on the circumstance, and the behavior for pressing buttons 1 and 2 is very different, as demonstrated in Tasks 4 and 5.

Task 4: Move an object

1. Press mouse button 1 close to a line of the polygon you just drew. Hold down the button. The line should turn gold colored, indicating that it has been "selected". If instead nothing happens, then the cursor is too far away from the line. Releasing the button releases the object.
2. Try grabbing and releasing the polygon from different distances to get a feel for how close you must be to the object in order to grab it.
3. Now grab the polygon, and with the mouse button held down, move the cursor across the screen. The polygon will follow the cursor. This is how you move an object in xcircuit.

Task 5: Change the properties of a polygon

1. Select the object by tapping mouse button 2 with the cursor near to the object. The object will turn gold, indicating that it has been selected.
2. Tap mouse button 3, and the selection will be canceled.
3. Investigate the other form of selection by pressing mouse button 2 starting below and to the left of the polygon, and dragging the cursor to the top and right of the polygon. A green box will follow the movement of the cursor.
4. When the box completely surrounds at least one of the endpoints of any line segment of the polygon, release the button. The polygon should be selected.
5. Click mouse button 3 to deselect the object.
6. Repeat steps 3 through 5, noting that if no endpoint of the polygon is contained within the select box, then the polygon will not be selected.
7. Select the polygon but do not deselect it.
8. Go to the "Options->Elements->Border" submenu and select option "Dashed". When you release the button, the polygon will be drawn in dashed lines, and it will no longer be selected.
9. Experiment with the different Colors, Fill-styles, and Border-styles available in the menus. Some of the many varieties are shown below.

Task 6: Change the page

1. Select the menu item "Window->Goto Page->Page 2". The polygon you just drew on Page 1 will disappear, and you will be on a clean page, with the bottom left-hand window saying that you are editing "Page 2".
2. Go back to Page 1 using the keyboard macro: With the cursor in the drawing area, press the "1" key. You will be back on page one.
3. Keys "1" through "9" and "0" will get you instantly to pages 1 through 10, respectively.
4. End this task on Page 2, which is currently empty.

Task 7: Select an object from the user library

1. Select the "Window->Show Library" button from the menu, or press the "l" (that's "ell" as in "library") key in the drawing window. Note that the menu button has "(l)" written after "Show Library", indicating that the keyboard macro "l" has the same function as the menu button. Generally, keyboard macros, once memorized, are more convenient to use than their menu button counterparts. Almost always, the letter or symbol used for the macro is meaningful and easy to remember (like "a" for "arc", "s" for "spline", "p" for "pan", "c" for "copy", etc.).
2. A page will appear, showing a number of circuit objects in the built-in object library.
3. Grab one object by moving the cursor over top it and pressing and holding mouse button 1. As soon as the button is pressed, the object library will disappear, and you will be dragging the object around Page 2, from which you called up the library. When you release the button, the object will be deselected. Place it away from the polygon you drew in the previous tasks.
4. Select the object by tapping on it with mouse button 2. Try changing the border style to dashed. You will see that nothing happens. This is because object instances from the library are made up of basic elements like polygons, arcs, and splines, but they are composite objects which do not have properties like "Fill-style" and "Border-style". However, object instances do have the property of color, and also the property "size" which simple elements like the polygon do not have.
5. Select the object again (if you have not already done so), and then select the menu item "Options->Elements->Object Size".
6. A window will pop up asking you for an object size. Place the cursor somewhere inside the popup window and change the default size of "1.00" to "1.5".
7. Press the "Okay" button. The popup window will disappear and the object will now be 1.5 times its original size (that is to say, its length and width will each be 1.5 times their previous value).

Part of the default circuits built-in library.

Task 8: Use a keyboard macro to create an arc

1. Select the menu item "Edit->Make Arc".
2. The information window at the bottom will say "Click button 1 and drag to create arc".
3. Place the cursor where you want the arc center to be and press it. While holding it down, drag the cursor around the screen. An arc will follow the cursor.
4. Release the mouse button. You will now be editing the angle of the first endpoint. If you just want a circle, tap mouse button 2 to end. If you keep pressing mouse button 1, you will be able to edit, in turn, all the properties of the arc such as endpoint positions and ellipse axis.
5. Now, create an arc by tapping the "a" key while the cursor is in the drawing area. The main difference is that mouse button 1 is not held down while you form the radius of the arc. Otherwise, the arc can be edited as before.

Task 9: Zooming and panning

1. Pan the screen to be centered on the arc by placing the cursor close to the center of the arc and tapping the "p" key.
2. Pan the screen by selecting menu item "Window->Center Pan" and then tapping mouse button 1 on the point of the drawing area that you want to be the new center of the screen.
3. Tap the "Z" and "z" keys to zoom in and out, or select the menu items "Window->Zoom In" and "Window->Zoom Out". Note how the scrollbars on the side and bottom of the screen change with the scale of the drawing.
4. Pan the screen by tapping any mouse button on either of the scrollbars. Note how this function is similar to the "Pan" function.
5. Zoom to a selected area of the screen by making a green selection box like you did in Task 5, step 3. However, instead of releasing the button in order to make the selection, type the "Z" key while the mouse button is still pressed down. The screen area will zoom to the area of the green box.
6. Alternately, choose "Window->Zoom Box" from the menu. Then press any mouse button and drag to generate the green selection box. When the button is released, the screen area will zoom to the area of the green box.

Task 10: Selection of multiple objects

1. Clear the current page by choosing the menu item "File->Clear Page". There is no keyboard macro for this command, to prevent accidental erasure of the screen (which cannot be undeleted).
2. Grab several objects from the library (see Task 7) and place them on top of each other in the middle of the page.
3. Decide on one object which you will move, leaving the others where they are.
4. Now press mouse button 1 as if you were going to select the object you want to move. Because the command is ambiguous---the program doesn't know which one or ones of the objects you really want to select---the program will query you one by one for which objects you want to select.
5. One object will turn blue, the cursor will become a question mark, and the information bar at the bottom will read, for example, "Click to accetp/reject: 1 of 3" if the program found three objects under the cursor. Release the mouse button at this point.
6. If the object that you want to select and move is colored blue, click mouse button 2. If an object that you don't want to select and move is colored blue, click mouse button 3.
7. When you have chosen or rejected each of the objects, the cursor will become a circle. You may now press and hold mouse button 1 and continue with the intended move.
8. Try this several times to get used to it.

Three objects simultaneously selected.

Message window when selecting multiple objects.

Task 11: Saving a file

1. Choose a page which you have been drawing on, or create a drawing to save.
2. Select the menu item "File->Write Xcircuit PS". You will get a popup window that looks like the figure below.
   
   The file properties popup window.
3. If you tap the button labeled "Write". You will get a message in the bottom message window saying "Warning: Enter a new name". Nothing has been written at this point.
4. Change the filename. Move the cursor over the window containing the filename. Delete the current file name and type in a new one. When you are done, either hit the RETURN key or tap the button labeled "Okay" (both actions have the same effect).
5. Important note: If the name has no extension, an extension ".ps" will automatically be added when the file is written. If an extension, for instance ".eps", is written in the filename, then it will be used.
6. When you change the filename, the page label will be changed to match the filename, and the bottom left-hand message window will now say "Editing: " followed by the page label name, followed by the page number in parentheses.
   
   Changes to scale and filename.
7. If the filename you chose already exists on the disk, the button which previously was labeled "Write File" will now say "Overwrite File", the computer will beep, and the bottom message window will say "Warning: File exists".
8. Tap the button labeled "Close". The window disappears; because you did not tap the "Write File" button, nothing was written, although the filename change has been registered.
9. Select "File->Write Xcircuit PS" again to bring the window back. This time, tap the "Write File" button. The file will be written to the disk current directory, and the button which previously said "Close" will now say "Done".
10. The file which has just been saved is already in a PostScript format. You may view it with any PostScript previewer (ghostview is recommended).

Task 12: Loading a file

1. Go to a new, unused page.
2. Select menu item "File->Read Xcircuit PS". You will get a screen that looks something like the following:
   The load-file popup window.
3. If the file list is larger than the window, you may scroll up and down the list by clicking mouse button 1 or 2 on the scrollbar at the right side of the window and dragging it up and down.
4. A green box will be drawn around each filename as your cursor passes over it.
5. Find the file that you just saved in the last task. When the green box is over this filename, tap mouse button 1. The filename will turn green, and at the same time will be copied into the text edit box.
6. Tap the "Okay" button to load the file.
7. If you do not wish to use the scrolling menu, you may type the filename, with or without the ".ps" extension, in the text edit box, followed by the RETURN key or tapping the "Okay" button.
8. Selecting a directory name in the file list box, including "../" for the directory one level up, will go to that directory. Entering a directory name in the text edit box followed by the RETURN key will also go to that directory.
9. If you know where the xcircuit source is kept, then select the "File->Read Xcircuit PS", go to the source directory, go to the "examples" directory, and load one of the example files, such as "vcoblock.ps".

Task 13: Entering Text

1. Go to a new, unused page.
2. Let's say you want to type in a fairly complicated expression, like
   "f(x) = sin(2*pi*omega_c*t)" (except with Greek letters, of course).
3. If you've read your TeX manual thoroughly, and understand all the finer points of mathematical equation typesetting (if you haven't, you should), then you know that all the variables should be in italic type.
4. Select menu item "Text->Style->Italic". The default text font is now italic style.
5. Select menu item "Text->Font->Times Roman" if it is not checked already. The default text font is now Times Italic (Times font + Italic style).
6. Select menu item "Text->Make Label" and click on mouse button 1 anywhere in the drawing area.
7. Alternately, you can just tap the "t" key in the drawing area.
8. The green line marks the pointer position, and the "x" marks the origin (justification) of the text.
9. Select menu item "Text->Justification->Middle Justified". You will see the green "x" move to the center of the line, showing that the text is vertically centered on its point of origin.
10. Alternately, you could type keypad key "6" (on some systems, Shift-keypad 6) to get center-left justified text.
11. Type "f". In the bottom message window, the letter "f" and a vertical bar "|" appear, showing what's in the string relative to the text cursor.
12. Select menu item "Text->Insert->1/4 Space". This is the proper thing to do for "italic correction", an extra bit of space necessary after an italic character followed by an upright character, particularly tall ones such as "f" and "t" which lean leans rather far to the right of their character bounding boxes.
13. Select menu item "Text->Style->Normal".
14. Type "("
15. Select menu item "Text->Style->Italic".
16. Type "x"
17. Select menu item "Text->Style->Normal".
18. Type ") = sin(2"
19. Select menu item "Text->Style->Italic".
20. Select menu item "Text->Font->Symbol".
21. Type "\". A page with the 256 character encodings for the Symbol font will appear, replacing the current page, as shown in the figure below.
    
22. Click on the "pi" symbol. The screen will immediately return to the original page, with the "pi" added to the text line.
23. Type "\", then click on the "omega" symbol in the encoding vector.
24. Select menu item "Text->Font->Times-Roman"
25. Select menu item "Text->Style->Subscript" (or keypad-minus)
26. Type "c"
27. Select menu item "Text->Style->Normalscript" (or keypad-enter)
28. Type "t"
29. Select menu item "Text->Insert->1/4 Space" for another italic correction.
30. Select menu item "Text->Style->Normal".
31. Type ")"
32. Before typing <RETURN> to complete the text, use the left- and right-arrow keys to move the cursor around inside the text string. Note how font- and style- changing commands embedded in the text string can be seen in the message window. Their position relative to the text cursor is important when anticipating the effect of deleting (<DELETE> key) a text command.
33. Yes, this is very complicated, but it is also very powerful.

Task 14: Making curves and paths

1. Go to a new, unused page.
2. Type "s" to start a curve (you can think of "s" as standing for "spline", although these are Bezier curves, not splines, or you can just think of the curvy "s" shape. The key "c" is reserved for copying). The first thing you will see is two dotted lines ending in little "x" marks. These are the curve control points.
3. Move the cursor around. Right now you are positioning the end of the curve but have no control over the control points.
   
4. Place the curve endpoint. If you are satisfied with the shape of this curve, you can tap mouse button 2 to finish the curve and quit. However, we'll say that you have more to do to this curve, so tap mouse button 1 instead.
5. You get a message saying "Adjust control point", and the cursor moves overtop the nearest "x" mark. Now when you move the cursor, you change the shape of the curve.
6. Move the control point two grid blocks to the left of where it started (make the control line horizontal with a length of 4 grid blocks).
   
7. Click mouse button 2 to finish the curve.
8. Now we will make a simple path. But it takes more than one element to form a path. Put the cursor over the curve and tap the "c" key.
9. When you move the cursor, a copy of the curve will follow you.
10. While you are dragging the curve copy, flip it by tapping the "f" key and then the "F" key (one horizontal plus one vertical flip).
11. Place the curve with its endpoints overtop the original curve. The result should look like the figure below.
12. Select both curves by tapping mouse button 2 on top of each one, or by forming a selection box (see Task 5).
13. Tap the "j" key in order to "join" the two curves into a single path.
14. If you now move or select the path, you will find that both curves act as a single entity.
15. Select the path and then select menu item "Options->Elements->Fill->(black box)". The path will then become solid black. If you color it blue, it will look something like the right side of the figure below.

Task 15: Dealing with over/under arrangement of elements

1. Clear the current page (menu option "File->Clear Page") or go to a new, unused page.
2. Start a box with the "b" key (this is a convenience for drawing rectangles and squares).
3. Click mouse button 2 to finish the box.
4. Select the box and choose menu item "Options->Elements->Fill->(black box)", where the "black box" is the first menu item in the list. You will now have a black box. (note that to select the box, the cursor must be near the edge of the box, not in the middle).
5. Select the box again and choose menu item "Options->Elements->Color->(orange box)". You will now have a solid, orange box.
6. Go to the built-in library ("l" key) and bring back a circuit object (say, a "nand" gate).
7. Place the gate on top of the orange box.
8. Make a copy the box ("c" key) and place it beside the first. mouse button 2 ends the copy command.
9. You will notice that the library object suddenly disappeared. This is because the "copy" command moved the orange box to the end of the drawing list. Because it is drawn after the library object, the library object is hidden underneath.
10. To get the library object on top again, select everything in the area of the orange box by forming a selection box around the orange box (mouse button 2). Tap the "X" key (Shift-X) to exchange the drawing order of the two elements. The library object will now be visible on top of the orange box.

Over- and Under- arrangements of elements.

Task 16: Making user-defined objects

Say we wish to create a new circuit component, a dependent current source.

1. Clear the current page or go to a new page.
2. We want the dependent current source to look something like the independent current source (isource) in the builtin library file. Go to the library and bring back an "isource" object for reference.
3. Draw a polygon, as in Task 3. Make it diamond-shaped and three grid spaces high, two wide (see the figure below).
4. Add a line of height one-half-grid space on the top and bottom of the diamond.
5. Now we will do something unusual. We will grab the arrow from inside the isource object. Edit the original "isource" object by placing the cursor over it and typing the ">" key (push object). The page you were on will disappear, and you will see only the object "isource".
6. Using the multiple-selection mechanism described in Task 10, select the arrowhead and line in the middle of "isource", but not the surrounding object.
7. Make a copy of these two elements with the "c" key.
8. While still dragging around the copy of the arrow, return to the main page by typing the "<" key (pop object). You will be returned to the original drawing, still dragging the arrow with you.
9. Place the arrow inside the diamond.
10. Using a selection box, select all of the components of the "dependent current source" object you have just constructed.
11. Type the "m" key to make the object out of the selected components.
12. You will get a popup box asking for a name for the object. Type something obvious like "depsource" or "disource". Spaces are not allowed (if you use them, they will be converted to underscores).
13. Tap the "Okay" button. Now, if you click on the dependent source, it will be treated just like one of the builtin objects.
14. Type the "L" key to go to the User Library. You will see that the new object you created is now located there. You can click on it to bring back another copy, just like the builtin objects.

Steps in creating a new user-defined object.

Task 17: Editing objects and elements

1. To edit the object, "push" into it using the ">" key, as you did for the "isource" in the last task.
2. Make the polygon shorter. Put the cursor close to the top of the diamond and type "e" for "edit".
3. Use the multiple-selection mechanism to select only the diamond.
4. Now you will be editing the point position. Move the point down one-half grid space, and tap mouse button 2 to complete the edit.
5. Do the same for the bottom point. Where the two ends of the polygon meet, you will need to adjust both of the points.
6. Extend the lines on the top and bottom to meet the diamond by editing the endpoints just like you did for the diamond.
7. When you are done, return to the main page by "popping" out of the object page, using the "<" key.

Steps in editing the user-defined object.

Task 18: Generating complex geometric shapes

1. Start with a clean page.
2. Create an ellipse as follows:
   1. Type macro a to start an arc.
   2. Drag the arc out to some desired size.
   3. Click the first mouse button three times (to bypass endpoint editing and go to ellipse axis editing). The position of the cursor will move from the side of the circle to the top.
   4. Drag the ellipse minor axis to the desired size and click the second mouse button to end.

Creating a path object (solid cylinder): top ellipse.
3. The whole ellipse becomes the top of the "cylinder". To make the bottom of the cylinder:
   1. Copy the first arc and place it well below the first.
   2. Type macro e to edit (or select edit from the menu and click on the lower ellipse).
   3. Immediately type e again or click on the first mouse button to go to endpoint editing mode.
   4. Drag the endpoint around to the other side until the result is the bottom half of an ellipse. Click the second mouse button to finish.

Creating a path object (solid cylinder): bottom (half) ellipse.
4. Draw two lines to create the sides of the cylinder.
5. Select the bottom and sides of the cylinder, and type the j key to "join" these segments into a single "path".
6. Select everything. If you (individually) select any component of the path (either the side lines or the bottom ellipse), the whole path will be highlighted.
7. Copy (with the c macro) and place the copy to the side.

Creating a path object (solid cylinder): Two cylinder frames.
8. Select the path (lower part) of the rightmost cylinder.
9. Choose menu item "Options->Elements->Fill->(black box)". Now you can see how to create arbitrary filled shapes.

Creating a path object (solid cylinder): Two cylinders, the right one consisting of a filled path.
10. Finish the cylinder in the following manner:
    1. Color the path shape dark gray.
    2. Select the ellipse located above the colored cylinder and perform the same steps to make it filled solid and colored light gray.
    3. Use the X keyboard macro to correctly arrange the elements, with the light gray ellipse on top of the dark gray path object.
    4. Place the black wire frame cylinder on the left on top of the solid cylinder on the right. Hint: Move the wire frame halfway on top of the solid cylinder, then arrange the top-to-bottom order of the elements so that the wire frame ends up on top, then move the wire frame the rest of the way.

Creating a path object (solid cylinder): Finished cylinder.

Task 19: Investigating other xcircuit commands

For help with remembering keyboard macros and their functions, select the menu item "Options->Help!". You will get a popup window to the right of the screen which lists all of the available keyboard functions. Tap the "Done" bottom at the bottom when you no longer need the help menu.

Back to the xcircuit home page. . .

email: tim@bach.ece.jhu.edu