Documentation of PED

Overview

PED has been designed with the needs of people who created technical or scientific drawings rather than for artists. Its standard repertory includes two types of curves, parabolic splines and cubic splines (in addition to circles and ellipses). Plots of arbitrary shapes can be provided by the user through a customizable function that is called from the main program.

Some drawing programs require the user to select a type of shape (e.g. line segment) from a menu each time the shape is to be drawn. In PED, once a type of shape has been selected, it is remembered and the user can draw several such shapes. The cursor icon reminds the user of the type of shape that is to be drawn. Actually, there only two shapes that can be drawn from scratch: polylines (open polygons) and right rectangles. These can be transformed to other shapes such as splines and ellipses by changing their attributes. The underlying polyline or rectangle is always plotted during editing using a light green color and they are the only means for accessing an object. Thus when we talk about the vertices of an object we refer either to the object itself (if it is a polyline or a rectangle) or to those of the underlying polygon. Attributes can be changed either by selecting an object first and then making a selection on the tool bar (as it is the common practice in other drawing programs) or by selecting first the new attribute from the toolbar and the applying the change on any object that is touched.

Because the term selection has a specific technical meaning (the selection is placed on the clipboard and is made available to other applications as well) we prefer to talk about touching an object or tagging an object.

Definition: An object is touched when the user presses the left mouse button near once of its vertices or sides.
Definition: An object is tagged by touching one of its vertices or sides, enclosing one of its vertices, or intersecting one of its sides with a rectangle while the tagging operation has been selected from the toolbar.

Thus in the sketch on the right the dashed line gray rectangle tags both the solid line shapes.

Tagged objects have all the properties of selections except for not being on the system clipboard. However, since they can be stored in a metafile, the difference is minor. In the future, we may add the step of copying the tagged objects to the clipboard, so the tagging will be completely equivalent to selection.

The Toolbar

All PED operations are done through the toolbar. The only exceptions are settings of user preferences that are done through a menu. Operations corresponding to toolbar buttons 1, 2, 3, 4, m, n, q, and r are performed immediately without any other action by the user. The remaining operations change the icon of the cursor into one similar to that of the toolbar button and require that the user presses the left mouse button either to start drawing (operations 5 and 6) or to select a figure by pressing the button on a vertex (operations 7-k and p). Operations marked with a * are standard in most Windows applications.
1*. Create a new PED Document.
2.* Open a PED Document.
3.* Save the edited PED Document.
4. Save the tagged objects in a metafile. If there are no tagged objects, save all the objects in a metafile. Since metafiles can be imported to several other programs this operation is similar to the usual COPY operation of Windows applications. The name of the metafile can be selected by the user through a dialogue box or allow PED to assign a name (see under Menu below).
5. Draw Polylines (pressing the left mouse button creates a vertex).
6. Draw Rectangles.
7. Grab and drag a polyline vertex.
8. Insert a new point in the polyline (or polygon) by replicating the vertex touched. The new vertex can be dragged while holding the left button down. If the two vertices are left to be the same they are surrounded by a double circle.
9. Delete the polyline (or polygon) vertex touched.
a. Pin down the polyline (or polygon) point touched. While pinned, a point cannot move. However if it is a double point, then pinning causes the two point to move together (feature added on 9/6/02).
b. Drag the object touched into a new location. If the SHIFT key is held down, the object is copied into the new location.
c. Resize the object touched. If one of its points is pinned, it is held fixed, otherwise the object's center of gravity is held fixed.
d. Tag one or more objects by enclosing them with a rectangle or by touching one of their vertices. Tagged objects are marked with a light blue square.

The following four operations are applied to all the tagged objects once a toolbar selection is made. If there are no such objects, the operation is applied to each object that is subsequently touched.
e. Delete an object.
f. Convert an object into a parabolic spline by using the vertices of the  polyline (or polygon) as control points. Rectangles are converted into ellipses (Toggle.)
g. Convert the object into a cubic spline by using the vertices of the  polyline (or polygon) as control points. (Toggle.)
h. Convert an open polyline into a polygon.
j.  Fill the interior of a shape with solid black color. (Toggle.)
k. Create a group from the tagged objects. No effect if there are no tagged objects. The interior of group objects is always filled with a solid color.
m. Undo. This operation pops a stack with the previous version of the last modified object.
n. Create a set of custom designed new objects by calling specialDraw().
p. Display description of any object that is touched.
q.* Help.
r.* Print.

The Menu

There are three menus: two are the standard for Windows applications, File and Help. The third is a PED Preferences menu. Currently this includes three options: (1) turning on and off the grid; (2) allowing for automatic selection of metafile names; and (3) display a Dialogue Box. If “AutoMetafile” is checked, then metafiles are saved in the current directory with names of the form data_N.emf, where N is a unique integer determined by PED. Otherwise, when a metafile is to be saved the usual Windows dialogue box pops up for file name specification. The dialogue box allows the user to specify parameters that are not likely to be changed frequently, so it should be used only rarely. Currently these parameter are: the size of the grid in pixels (default 10) and the directory where the help files are located. The default is null, so this must be set at least the first time the program is used. Parameter settings are saved in the Windows registry so they are remembered from session to session.

The File menu includes two operations that are not available from the toolbar, Save As, Print Preview, and Print Setup, as well as a list of the most recently used files. The "Save As" may be used only to rename a file, not to change its type.

Rules for User Defined Shapes

The prototype for specialDraw() is int specialDraw(POINT *vp, int buf_size, int *np, char *cp); The shapes are described in a way that provides arguments to the Windows functions that draw each shape. The array vp contains all the points of all the objects and its size (in terms of points) equals buf_size. It is the responsibility of the implementer of this function to make sure that this limit is not exceeded. In the current version of PED it is set to 8000. The array np contains the number of points for each shape and the array cp contains a character specifying, in effect, the Windows function to be used for drawing. The function returns the total number of objects which should not exceed 64. While it is probably to fill directly these arrays, a set of convenience functions are available to help the programming user. These functions are

void initialize(POINT *vpp, int *npp, char *cpp);	// must be called before any other convenience function
int rectangle(int x0, int y0, int x1, int y1, BOOL full);
int ellipse(int x0, int y0, int x1, int y1, BOOL full);
int line(int x0, int y0, int x1, int y1);
int path(POINT v[], int n, char type);
The flag type can have anyone of the following symbolic values with the expression in parenthesis denoting constrains on the number of points n
POLYLINE_SH, POLYGON_SH, POLYGON_FILLED_SH (>1)
OPEN_SPLINE_SH, CLOSED_SPLINE_SH, SPLINE_FILLED_SH (>2)
OPEN_CUBIC_SH, CLOSED_CUBIC_SH, CUBIC_FILLED_SH (>3)
ELLIPSE_SH, ELLIPSE_FILLED_SH (2)
RECTANGLE_SH, RECTANGLE_FILLED_SH (2)
ARC_SH (4)
The four points for an arc are the two opposite corners of the surrounding rectangle (of the full ellipse), the start of the arc and its end, assuming counter-clockwise drawing. A set of examples illustrates the use of the convenience functions as well as implementations of specialDraw() without them. The implementation of the convenience functions is in the file local.cpp that is part of the distribution.

What PED does not have

PED does not allow specification of arrows, line style, line thickness, or color (either of the lines or the fill). Also it has no provisions for entering text. While the original PED program had all these features, they have been deliberately omitted from the new version because it is assumed that its results will be imported into another drawing program.