mCAD Version 1.2.5 5/12/87 by Tim Mooney 120 Purefoy Rd. Chapel Hill, NC 27514 --------------------------------------------------------------------------- mCAD is SHAREWARE. This means that you are free to play around with mCAD for as long as it takes you to decide whether or not you are willing to pay for it. It also means that you are also free to decide what price you are willing to pay. Finally, it is possible for you to use mCAD and pay nothing, although this violates the moral contract between you and me that you enter by reading this message. If you send me $20 or more, you will become a registered user. I'll be grateful for your support and I will: 1) Send you notice of new versions as I write them. 2) Allow you personal use of the source code. 3) Support your use by answering questions and considering your requests for improvements to mCAD. Since some requests are more difficult than others to satisfy, and since some improvements may be impossible to implement without adversely affecting mCAD's performance in other respects, I can promise nothing more than serious consideration. 4) Send you the latest versions of public domain software that I either wrote or am maintaining. Currently, the list includes: mp - a 2-D data plotting routine which can extract data by "column" from a text file. tdp - a 3-D data plotting routine with hidden line removal. vt640 - a tektronix 4010 emulator that is derived from "TEK4010" and the latest version of "VT100" available to me. long.font - an 8 X 16 font that works well with interlaced screens and with my favorite (customized) version of MicroEmacs. d - a directory listing program (five-up, sorted, with sub- directories in an alternate color) derived from the public domain program "ld". Whatever you decide to do, you will not be paying for marketing, promotion, or copy-protection. Final note: if you want me to send you the latest version of mCAD, source code, or anything else on disk, please send either a blank disk or an additional $5. --------------------------------------------------------------------------- mCAD is an object-oriented drawing program. It has a small set of graphics primitives (like "line", "box", and "text") and a small set of editing functions (like "move", "size", and "rotate"). While drawing and editing, the user can call on other functions to modify the display -- to zoom in, slide around, superimpose a grid, etc. The one powerful feature of mCAD is that primitives can be grouped and ungrouped; the editing functions operate on groups of (one or more) primitives. In these instructions, "group" and "object" will mean either a single primitive or a group of primitives. Most (surely all!) Amiga users know how to use the mouse to draw pictures. In mCAD, the mouse does mostly what you're accustomed to from programs like GraphiCraft. There are three differences: 1) In mCAD, you are called on to SELECT objects for treatment with one of the editing tools. Since mCAD can't know for which of two or more overlapping objects your SELECT click was intended, it runs through a list of all the possibilities, highlighting each in turn. In this context, the MENU button means "No, not that one", the SELECT button means "Yes, the highlighted object is the one I want". 2) While drawing a primitive (exception: text) or editing a group (exceptions: coloring, setting line type), mCAD gives you a chance to abort the whole operation. In this context, the MENU button means "Abort", the SELECT button means "The highlighted object is drawn as I want it, make it permanent." 3) Certain editing functions, "Size" for example, require additional information and indicate this by drawing a highlighted object. You are asked to click on (SELECT button) e. g., one corner of a box. So, generally, when the mouse buttons don't have their Intuition meanings, the SELECT button means "Yes/ok/do it...", and the MENU button means "No/abort/get me out of this". This follows the accepted Amiga convention that "left" breaks new ground while "right" is conservative and safe. If you get lost in -- or called away in the middle of -- a sequence of mouse clicks, a couple of MENU button clicks will get you out of it. ********************************************************************* FILES: mCAD wants the files mCAD.txt and mCAD.rgb to be in your default directory. If mCAD.txt doesn't exist, text will not work. If mCAD.rgb doesn't exist, default colors will be used. mCAD expects the default directory to contain a subdirectory named "part". If this subdirectory doesn't exist, mCAD may think you have the wrong disk, and you may have to type in the name of the directory you are using to save parts in. If you intend ever to render a drawing on a dot-matrix printer, the file mCAD.prtdef must exist in your default directory. ********************************************************************* THE COMMAND LINE: to call up the program ***************** mCAD ? Help mCAD filename Create/Edit a drawing named "filename". (You need not type the filename if you intend to load the file from within mCAD.) ********************************************************************* THE MENU: menu items that don't work or aren't yet implemented are described by "*" ********* ************* PROJECT New Erases the current drawing. Open Opens a drawing which exists on disk for viewing and/or editing. MicroSmith's file requester is used to specify the file name. Save Saves the drawing to disk using the current drawing name. The current drawing name is either the name that occurred on the command line, or the name of the file most recently "Open"ed. The default drawing name is "mCAD.out". SaveAS Saves the drawing to disk. MicroSmith's file requester is used to specify the file name. Plot Saves the (entire) drawing as a plot file in the Hewlett Packard Graphics Language. Instructions are included in the file to enable XON/XOFF handshaking with the plotter. To actually make the plot, copy the plot file to SER: The plot file name has the same root as the current drawing name, and the extension ".plt" ..1 Pen Similar to "Plot", except that a separate file is made for each of the 16 colors. The files are named as for "Plot", but a hex number (0..f) is tacked onto the end to indicate the pen color. The file whose extension is ".plt0" is special; it contains the plotter initialization and MUST be sent to the plotter first. The pen number used in all files is 1. See "HINTS..." below for more information on this item. PrtScrn Prints the current screen on a dot-matrix printer. Information about the printer and your choice of scale and orientation are read from the file mCAD.prtdef. See "PRINTERS" below for more information on this file. About Toggles display of the screen title bar. Quit Quits mCAD. If you have made any changes to the current drawing, you will be asked if you want to save it. ************* PART mCAD expects the current directory to contain a sub-directory called "part". MicroSmith's file requester will let you change directories, however. If the sub-directory "part" is not found, the file requester will say "Wrong disk?". Open Includes an mCAD drawing, which was previously saved to disk, in the current drawing. You will use MicroSmith's file requester to specify the part name. Save Saves a group to disk using the current part name. Select the group you want to save with the mouse as described above. SaveAs Saves a group to disk by name. When you've selected the group to be saved, MicroSmith's file requester will display itself and accept the file name. Group Groups objects together for treatment with an editing tool or to be saved as a "part". Draw a box completely enclosing the objects you want treated as a group. An object can be in only one group at a time; if an enclosed object is already part of a group, the entire group will merge into the new group. UnGroup Select a group by clicking on any of its members. On the confirming SELECT click, the group will be dismembered. ************* OPTIONS Replot Redraws the screen. Zoom 1) Draw a box around the region you want to see up close. mCAD will zoom in to the biggest region consistent with both the box you drew and the aspect ratio of the drawing. Note: in this version the aspect ratio cannot be changed by any command. 2) Click twice in the same spot. mCAD will zoom out by a factor of two. Slide Draw a line. On your second SELECT click mCAD redraws the picture as if your first click had grabbed a hold of the page. FullPlot Zooms out to show the whole drawing. Axes This is a toggle switch that puts axes on the display. Setting this switch does NOT cause the screen to be redrawn. Grid This is a toggle switch that puts a grid over the display. Setting this switch does NOT cause the screen to be redrawn. X-Hair This is a toggle switch. The mouse pointer is replaced by a crosshair. (Notice what happens when you press the MENU button and move the mouse.) GridSnap This is a toggle switch. Primitives (exceptions: text, circle, arc) drawn with GridSnap enabled will snap to the grid on your *final* SELECT click. When enabled, menu item reads "GRIDSNAP". DataSnap This is a toggle switch. Primitives (exceptions: text, circle, arc) drawn with DataSnap enabled will snap to previously drawn objects (if they are close enough) on your final SELECT click. Points are more "attractive" than lines connecting those points. When enabled, menu item reads "DATASNAP" nTics*2 Increases the density of tics / grid lines. A maximum is enforced. Selecting this item causes the screen to be redrawn nTics/2 Decreases the density of tics / grid lines. A minimum is enforced. Setting this item causes the screen to be redrawn ShowXY Calls up a numeric readout in the current plot color of the pointer position. The readout is in USER coordinates (the numbers which are drawn when you select "Axes" are in USER coordinates.) The readout consists of the absolute X (horizontal) and Y coordinates and the distances from the location of the most recent SELECT click. ************* DRAW Line Draw a sequence of (one or more) connected lines. Click twice on your final point. Box Draw a box by clicking on two corners. Circle Draw a circle by clicking on the center position, moving the mouse to change the size, and clicking again when the size is right. Arc Draw an arc with three mouse clicks: the first click sets the center; the second click sets the radius and starting angle; the third click sets the ending angle. Measure * Clone Select a group by clicking on any of its members. A duplicate will follow the mouse pointer until you press either the MENU button ("abort") or the SELECT button. TextSize Draw a box indicating the size/aspect of the letters you plan to type onto the screen. Cursor SELECT the location of the text cursor. ************* EDIT In every case, you first select a group for treatment. Erase SELECT a highlighted group to erase it. Size SELECT a highlighted group. mCAD draws the smallest enclosing rectangle (possibly a line). You SELECT a corner of the rectangle to begin sizing. The group is scaled as the mouse moves. Press the SELECT button, when you like what you see, or the MENU button to abort. Move Select a group by clicking on any of its members. The group will follow the mouse pointer until you press either the MENU button ("abort") or the SELECT button. Rotate The selected object is rotated about its "center". Vary the angle by moving the mouse and click SELECT to finish or MENU to abort. Rot +90 The selected object will be rotated counter- clockwise by 90 degrees. Rot -90 The selected object will be rotated clockwise by 90 degrees. Point Select a group. While the group you want to modify is highlighted, click on the point you would like to move. The point and lines connecting it to adjacent points will follow the mouse. Click SELECT to finish or MENU to abort. Color Select a group. The selected group immediately turns to the current plot color. (No chance for abort here.) SetLType Select a group. The selected group will be re-rendered in the current line type. (No chance for abort here.) ************* COLORS color boxes Your menu selection becomes the current plot color. Initially, the current color is #4 (first box in second row of the palette). Modify Colors Call up Microsmith's Palette tool (a very nice tool written by Charlie Heath). Save Colors Save current colors to the file "mCAD.rgb" which is read by mCAD on startup. ************* LINETYPE Line types are represented pixel-by-pixel using underscores. (Pretty crude, huh?) Your menu selection becomes the current line type. Text is rendered in solid lines regardless of the current line type, but you can use the editing function "SetLType" on text as well as any other primitive. ************************************************************************ NEW FEATURES Version 1.2.5 Support for some dot-matrix printers has been added. Printers with more than eight addressable printing pins are NOT supported because I have no information about them. Printers with eight or fewer addressable pins are likely to work if a ".prtdef" file can be written for them. See "PRINTERS" below for information about this file. I have written ".prtdef" files for the graphics-capable version of the Epson MX-80, and for the Star Gemini-10X. A few more bugs have been fixed. Version 1.2.4 A selection of line types has been added. These are designed to approximate the line types available in HPGL. Text defaults work. mCAD now "picks up" the cross-hair/point before drawing and puts it back down after. No more litter on the screen. Version 1.2.3 Screen scaling is completely redone. mCAD now uses the entire screen instead of reserving space for axes. When axes (which also have been redone) are selected, they are just plopped on top of the drawing. Plot scaling has been modified so that no coordinates larger than 10000 are generated. Version 1.2.2 File input and output from within mCAD has been added. Thanks to Charlie Heath and MicroSmith's for the file requester and, while I'm at it, for their palette tool. This is the hard stuff, folks. If I had had to write these tools myself, you can be sure that they wouldn't be such a pleasure to use, and that I would be asking for more of a donation than $20. Point editing has been added. This feature allows you to move a single point of a group without affecting other points. A shortcut for rotating by 90 degrees has been added. (The original motive for this was to rotate entire drawings before plotting.) Several bugs that once caused mCAD to crash have been fixed. mCAD now realizes that mouse clicks are being queued up "behind its back" and that disabling them doesn't erase queued messages. Groups work right. In previous versions, the result of grouping objects that were already in different groups depended on the order in which those groups had been formed. (See "HINTS..." for the full story.) mCAD can now read a file and add the objects in that file to its linked list of objects. In other words, the "Parts" menu is fully implemented. It may be useful to know that there is no difference, to mCAD, between a "part" file and a "cad" file. You can treat a whole drawing as a part and vice-versa. You can also use the outputs of the programs "mp" and "tdp" as either parts or drawings. Tab, backspace, and carriage return now do more nearly what one would expect. Backspace does not erase, however. Also, see "BUGS...". ************************************************************************ HINTS, SUGGESTIONS ... 1) mCAD's input file format is very simple. You can make an mCAD file by hand or with a simple program in "c", Basic, etc. The following lines could be used as an mCAD file. 100 100 This is a box.. 100 200 200 200 200 100 100 100 *> The object above this mark is in a group with the object below it. *C 4 The object above is in color 4 *L 2 The object above is to be rendered in line type 2 125 150 This is a line.. 175 150 *C 5 -------------------------- 2) I prefer a "fast" mouse for most programs, but would like a slower one for doing fine work with mCAD. I haven't implemented a mechanism for changing the mouse speed while in the program, but an acceptable substitute is using the Amiga-arrow keys. You may have forgotten about this keyboard alternative since it is so rarely useful. Also, don't forget about Amiga-alt for mouse buttons. (Sometimes, I inadvertently move the mouse while clicking a mouse button.) 3) Grouping objects: Since the only way to indicate which objects you want in your group is to draw an enclosing rectangle, you may be having trouble getting just the objects you want. You don't have to enclose all the desired objects at once, however. Two or more rectangles can be used. If you group objects which already are parts of separate groups, the groups will be merged. 4) When X-Hair is not selected, the Intuition pointer is supplemented with a dot at the current location of the graphics cursor. (You may know that the Intuition pointer is implemented in low resolution and therefore cannot, with precision, select a point on a high resolution screen. The dot is a remedy for this.) To make effective use of the dot -- indeed, too SEE it -- your pointer should have its "hot spot" on one of the "transparent" pixels. In Preferences, use the "Set Point" option while you "Edit Pointer". 5) To keep a constant text size in your drawing through many edits, or from drawing to drawing, you might consider making a box of the desired text size and saving it as a part called "textsize". When you want to set your text size, then: open the "textsize" part; select "TextSize" from the "Draw" menu; and draw a box exactly like the "textsize" box. 6) If your drawing has more colors than your plotter has pens, you will probably want to use the "Project" menu item "..1 Pen" to write your plotter files. mCAD will make 16 files, one for each color, which you can send separately to the plotter -- manually changing pens between sends. The file "sendplt" is an "Execute" script to take the drudgery out of this procedure. An example: I've made, say, a drawing named "mypic.cad" and used "..1 Pen" to make the files "mypic.plt0", "mypic.plt1", ... "mypic.pltF"; I'm connected via the serial port to a plotter, and have loaded a pen I think of as "pen 0" in what that plotter considers the "pen 1" slot; I can now use the Amiga "Execute" command like so: "Execute sendplt mypic" When this file reports: "sending mypic.plt0" I hit the space bar (or any key) and wait until the plotter has finished drawing. (Since I've typed into the CLI window, the Amiga politely waits until I either erase what I've typed, or hit , before continuing to execute "sendplt" -- because what sendplt wants to do next is write to that same CLI window.) I now change pens and hit , whereupon sendplt continues to execute and says: "sending mypic.plt1" I repeat the (hit key; wait; swap pen; hit ) procedure until the drawing is complete. 7) Those of you who are interested in writing plotter drivers or other software for converting mCAD output for use with other that HPGL plotters, please note: I haven't been concerned in the past with providing a stable format in the .plt file for your efforts. This means that a positional translation of a .plt file is likely to be useable only with the output of the mCAD version for which it was designed. If this is a problem, tell me. Maybe we can work something out. Let me also suggest an alternative: The mCAD input file (the .cad file) is likely to be more stable -- else one version of mCAD couldn't read the file saved by another. Also, the .cad file is MUCH easier to parse than the .plt file. In fact, a routine which parses it is available to you in getdat(). The only problem here is that there is no scaling information up-front; you have to read the whole file to find the limits of the data. If there is sufficient interest, I could provide that scaling information up-front in what mCAD would normally consider "comments". Finally, I'm not going to GUARANTEE the stability of either file just yet, though. mCAD takes too long to read and save files for my taste and if a different format would make a big difference, I'll change it and send you a translator.) ************************************************************************ PRINTERS mCAD can do a "screen dump" to printers which meet the following criteria: 1) There is an escape sequence which puts the printer in "graphics mode" -- i.e., tells the printer to expect some number of bytes of bit-mapped graphics which are to be printed from left to right on one line. 2) The pins on the print head can all be fired by sending a single byte to the printer (when it is in graphics mode.) The bottom-most pin is fired by sending the number 1 (i.e. hexadecimal 01), the pin above that by sending the number 2, the next by sending 4, and so on. I think most nine-pin printers work this way; If I'm wrong, please let me know. To use the screen dump capability with your printer, you will probably have to write an "mCAD.prtdef" file. This is really pretty easy, and I'll tell you exactly how to do it. There are seven lines in the file; I'll go line by line. You might want to look at the mCAD.prtdef file I wrote while you read this. (Experts: please don't be insulted by this long-winded discussion. Yes, this is easy, but there's a first time for everybody.) LINE 1: Write the mCAD version number 1.2.5 If you want the picture to appear sideways on the page, put the letter R before the version number. R 1.2.5 ******************************************************************** LINE 2: If your printer is connected to the Amiga parallel port, write PAR: else, write SER: You may put a file name here instead of a device name. This is useful for debugging. (The file may be very large, mCAD will not like it if the disk gets too full to write on.) ******************************************************************** LINE 3: Find out how many dots your printer can print on a single line in graphics mode. For the Epson MX-80, the number is 960. This number has to agree with what you will write in LINE 5, and may not be larger than 2000. 960 Decide how many rows of dots you want your picture to be made up of. For the Epson, 432 rows gives a picture with approximately the right aspect for unrotated screen dumps; 780 works ok for rotated dumps. 960 432 Find out how many user-addressable pins there are on your printer's print head. (Many printers have nine actual pins, but only seven or eight of them can be specified when in graphics mode. If you have a choice of seven or eight pins, choose eight.) 960 432 8 ******************************************************************** Open your printer manual to the section in which the "escape sequences" ("control codes", "function codes", etc.) are described. You are going to write four lines of numbers. The first number in each line will be decimal and the rest will be hexadecimal. The first number tells mCAD how many hexadecimal numbers there are in the line, so if you find you don't need any hexadecimal numbers, just put 0. LINE 4: Find the escape sequence which resets your printer. For an Epson, the sequence is @ which is a two byte sequence. The hexadecimal number which stands for is 1B. The hex number for @ is 40. As a (cryptic) reminder that these numbers are in base 16, put 0x in front of them. 2 0x1B 0x40 If your printer gives you a choice of using seven or eight pins for graphics, there is an escape sequence to specify your choice. For the Epson, the sequence specifying eight pins is # which is a two byte sequence. Adding these to line 4 yields: 4 0x1B 0x40 0x1B 0x23 If your printer is capable of printing in both directions (i.e., left-to-right and right-to-left) you need to find out how to tell it not to. If there is an escape sequence for "unidirectional printing", or some such, include it. For the Epson, the sequence is < or 0x1B 0x3C. 6 0x1B 0x40 0x1B 0x23 0x1B 0x3C Find the escape sequence which sets your printer's line spacing. (There probably are several different ways to do this.) You also need to determine what the line spacing should be so that successive sweeps of the print head form a continuous picture, without leaving blank lines or overprinting part of the previous sweep. The spacing depends, of course, on how many pins of the print head are used for graphics. For the Epson, using eight pins, the correct spacing is 8/72 in. The Epson allows the line spacing to be specified in multiples of 1/72 in. with the escape sequence 0x1B 0x41 0x08. 9 0x1B 0x40 0x1B 0x23 0x1B 0x3C 0x1B 0x41 0x08 There may be other escape sequences that your printer requires to put it in the appropriate frame of mind to accept graphics. If so, add them now. Finally, I've noticed that when I set the paper by hand to the top of a page, I usually get poor results from the first few passes of the print head. I get good results when I let the printer do a few line feeds before beginning to print. So, I recommend adding a few line feeds (0x0A's) to the initialization line. The finished product: 11 0x1B 0x40 0x1B 0x23 0x1B 0x3C 0x1B 0x41 0x08 0x0A 0x0A ******************************************************************** LINE 5: SENT BEFORE EACH LINE OF GRAPHICS Find the escape sequence that puts your printer in graphics mode. This code is almost certainly intended to be sent before EACH sweep of the print head. (If your printer has an escape sequence that prepares it for many sweeps, you might want to include that sequence in the initialization line and just put a 0 on this line and the next.) The "enter graphics mode" sequence probably has to be followed by two bytes which tell the printer how many columns of dots to print in the upcoming sweep of the print head. For the Epson, the sequence is K for a maximum of 480 columns, or L for a maximum of 960 columns. The actual number of columns is variable and is coded in two additional bytes. I chose 960 columns and the full sequence is: 4 0x1B 0x4C 0xC0 0x03 (960 = 0x03C0; the Epson wants the least significant byte first.) Your printer manual probably spells out in detail how to specify the number of columns for your printer. Probably, it shows you how to do it in BASIC using the CHR$ function. Remember that the CHR$ function takes a decimal number argument. ALSO, VERY IMPORTANT: THE NUMBER OF COLUMNS YOU TELL YOUR PRINTER TO PRINT MUST BE THE SAME AS THE FIRST NUMBER YOU SPECIFIED IN LINE 3. ******************************************************************** LINE 6: SENT AFTER EACH LINE OF GRAPHICS After a sweep of the print head, you probably have to do a line feed to prepare for the next line. You may have to send another code to tell your printer to print everything it has collected (whatever mCAD sent it) since LINE 5 was sent. For the Epson, a carriage return and a line feed are sufficient. 2 0x0D 0x0A ******************************************************************** LINE 7: SENT TO CLEAN UP AFTER A DRAWING You may not need to do anything here, but you'll probably want to send a form feed and reset the printer. For the Epson, 3 0x0C 0x1B 0x40 ******************************************************************** That's it. I volunteer to collect ".prtdef" files and include them in the mCAD distribution. I may modify them to keep them current as new versions of mCAD come out. Finally, I'd like to support 18 and 24 pin printers too. If I run across any info (hint, hint), I'll do it. ************************************************************************ BUGS, WARNINGS, ADDITIONAL NOTES ... Letters, in this version, are REALLY primitives; all points are connected together as though drawn with a single "Line" command. This means characters like [ ! = ? : ; " Q ] don't look so good. (Ok, they look awful!). Text is likely to improve in some future version. mCAD doesn't do ANY memory checking. It will crash the system or exit without returning allocated memory if it finds that there isn't enough memory to do whatever it wants to do. In a multi-tasking system with a ram disk, this is bound to happen to you sooner or later. This IS going to be fixed! Until it is fixed, I suggest you save your drawing often and keep an eye on the amount of ram available. If you select "Open" or "SaveAs" and nothing happens, you may be short on memory. MicroSmith's file requester may not be able to allocate enough memory to display itself. mCAD will have no idea what has happened, however. It receives the same message as it would if you had selected the requester's "Cancel" gadget. The only way to save under this circumstance is to select "Save" from the Project menu. (If you select "SaveAs" from the "Part" menu, remember that nothing will happen in any case until you select the object to be saved.) ************************************************************************ ETC. If you have a modem and are so inclined, you can leave me mail at the following bulletin board which I monitor regularly. "Deep Thought" (919) 471-6436 Registered users: I plan to move sometime in the fall of '87. When I do, I'll leave a forwarding address on the bulletin board mentioned above and with: Department of Physics and Astronomy Phillips Hall University of North Carolina Chapel Hill, NC 27514