DOCUMENTATION

Overall Program Philosophy.

Etch-n-Paint is a program which operates on "objects." The background is an object, and the various shapes which can be created are also objects. For example, if the user creates a dot, that dot is an object. If the user creates another dot, that dot is another object. The objects are drawn on the canvas. The program retains the properties of all the objects, so that they can later be deleted or transformed.

System Requirements.

Developed in Java and Java 2D for Windows XP and Internet Explorer. Mac users: confirmed to work on Seamonkey and Safari for Mac. Does not work on Explorer for Mac or Mozilla for Mac.

Main Components.

Upon program startup, the user is presented with the canvas on the left, on which the user can create objects. The window in which the canvas is rendered is called the viewport. (The canvas actually extends to infinity in all directions, and the user is viewing a portion of the canvas through the viewport.) On the right is the control panel, which is used to set the properties of the objects or the viewport. There is a menu bar across the top.

Programming Language and Environment Used.

The program is written in Java, and makes use of the Java 2D API, as well as the Swing classes. NetBeans is being used as the development environment. Originally this project was conceived as a GUI for the Java 2D API, and it has evolved into a graphic arts/paint program.

The Canvas.

Objects are drawn on the canvas. The user can change his view of the canvas by going into transform mode and then selecting "translate" or "scale," depending on whether he wants to translate (move) the viewport across the canvas, or scale (zoom in/out) his view of the canvas.

Pixels versus Vectors.

The program is not oriented around pixels, but, rather vectors, i.e., the various objects are described by key points on the canvas and vectors (lines, curves, ellipses), along with strokes and fills. For this reason, the user may zoom-in (by scaling the viewport with translate|scale) indefinitely, and never reach the point where he is operating on individual pixels. The program uses a process called anti-aliasing to render smooth lines and curves on the screen.

Object Types Featured.

The following shapes are currently featured: dot, line, curve, freeform, polygon, ellipse and rectangle. There is also a text object.

Control Panel.

The control panel is located on the right-hand side of the applet.

At the top of the control panel is the location of the mouse on the canvas. If the mouse is hovered over this part of the control panel, a tooltip shows the dimensions of the viewport (in pixels). (Hovering the mouse over any part of the control panel or canvas gives the user a "tooltip" on that control.)

Next, going down the control panel, is the program mode. This is a drop-down list. The user currently can choose from Dot, Line, Curve, Freeform, Polygon, Ellipse, Rectangle, Text, Background, Transform and List. This controls how the program will respond to mouse clicks on the canvas, and also changes the appearance of the rest of the control panel. The rest of the control panel allows the user to control strokes, paint schemes, and other properties, depending on the program mode.

General Properties of Objects.

The objects in Etch-n-Paint, in general, consist of a stroke (with a paint scheme) and a fill. This idea comes from Java 2D, which was used to code the program. Objects can be transformed in various ways: translation, flipping, rotation, scaling and shearing.

Properties of a Stroke.

A stroke, in general, is specified by the stroke's open/closed parameter, the stroke's width, its end caps, its dash pattern, and its line join property. The open/closed parameter indicates whether the shape should be closed (the end of the stroke connected to the beginning) or left open. The stroke width is given in pixels. The dash pattern is a sequence of numbers. More details on end caps, dash pattern and line join are given below.

Properties of a Fill.

A fill consists of a paint scheme, which is either a solid (plain) color or a color gradient.

Initial state of Object.

Initially, any object's color (i.e., the color of the stroke or the fill) is a solid color. After creating an object, the user may go into transform/paint mode in order to "paint" the object with a color gradient.

Alpha Component of Color.

The program supports the alpha component of color, which is an expression of color mixing. When two colors share the same point on the canvas, the colors are mixed according to the colors' alpha. The alpha is a number between zero and 255. When the alpha is 255, the color on top completely hides the color(s) underneath. When the alpha is zero, the color is completely transparent and invisible. When the alpha is 127 (half-way between zero and 255), the color is mixed half-and-half with the color(s) underneath it on the screen. Background colors always have an alpha of 255.

Alpha has a number of applications, such as creating transparency effects or the feel of watercolor. If the user desires an invisible or non-existent stroke or fill, the alpha can be set to zero.

Gradient Paint Schemes.

A gradient paint scheme is defined by two colors, and two points on the canvas. The two colors are blended linearly between the two points on the canvas. Future versions of the program may support radial gradients and other kinds of gradients.

Stroke End Caps.

A stroke, in general, has two ends, and the end caps express how to render those ends. An end cap is either square or round. I.e., the end is either squared-off or rounded. The effect is not noticeable in very thin strokes, or strokes which end where they began (closed strokes).

Stroke Dash Pattern.

The stroke dash pattern is a property built into Java 2D and is rather complex. It is somewhat correct to say that each number specifies, from the beginning of the line, the change from opaque to transparent. The user is invited to experiment with different patterns. For example, "10" means the line changes from opaque to transparent 10 pixels from the beginning, and then after 10 pixels, changes back to opaque. "10 30" means to change from opaque to transparent, and then after 20 more pixels (30 from the beginning), change back to opaque, and the cycle repeats. There is no specific upper limit to the number of values in the dash pattern.

Note that if the number(s) in the dash pattern are small compared to the stroke with, the pattern may have no effect on the stroke.

Stroke Line Join.

The stroke line join expresses how a joint between two lines is rendered. For example, in the rendering of a polygon, the stroke line join effects the appearance of the corners of the polygon. The line joins are either miter, bevel or round.

Description of Each Object Type.

Background. The background is a paint scheme covering the entire canvas, upon which all other objects (shapes and text) are rendered.

Dot. A dot is simply a small circle which has a given width (in pixels) and is filled-in with a paint scheme. In practice, the width of the dot can be as large as the user desires, making the dot more like a large circle than a dot. The user may click and drag the mouse to create a chain of dots.

Line. A line consists of a stroke and a color scheme. The user may click and drag to create a line, or the user may click at the beginning of the line, and click at the end of the line. (In general, this applies to all objects--the user may click-and-drag, or click-and-click--it works either way.)

Curve. A curve consists of a stroke (with a color scheme) and a fill. There are two kinds of curves to choose from: quadratic and cubic. A quadratic curve has one control point; a cubic curve has two control points. A quadratic curve requires three mouse clicks: one at each end of the curve, and another to set the control point. A quadratic curve requires a fourth mouse click, to set the second control point. Note that the fill on curves defaults to having an alpha of zero, which makes the fill invisible. The alpha of the fill can be changed by clicking on "fill" (in the stroke color/stroke/fill list box) and the "alpha" button (in the lower right).

Freeform Object. A freeform object consists of a stroke (with a color scheme) and a fill. The user clicks the mouse to start rendering the object. As the user moves the mouse, the stroke follows the mouse movement. When the user clicks the mouse again, the freeform object is complete.

Polygon. A polygon consists of a stroke (with a color scheme) and a fill. The lines which make up the polygon are either straight lines or curves. The Curves checkbox is checked by the user to indicate that the lines are curves (otherwise they are straight lines). The user clicks the mouse to start rendering the polygon. The user then moves the mouse to the location of the first apex of the polygon, and clicks there. If the polygon is curved, the mouse is moved and clicked again to determine the amount of curve (if a straight line is desired, the mouse is clicked again without moving). The user repeats this process to render each line of the polygon. After creating the final line in the polygon, the user presses the Esc key to complete the polygon.

Note about polygons: on some platforms, the program is prone to losing the keyboard focus. This will be apparent if the program does not respond to the Esc key. In this case, move the mouse to the Edit menu and click on Undo. This will complete the polygon.

Ellipse. An ellipse also consists of a stroke (with a color scheme) and a fill. The user clicks the mouse to start rendering the ellipse. As the user moves the mouse, a framing rectangle (or bounding box) is created, which contains the ellipse. (The framing rectangle is not actually visible, just the ellipse.) The dimensions of the ellipse framing rectangle are shown on the control panel, and can aid the user, for example, in creating a perfect circle. There are three arc-type check-boxes on the ellipse control panel: open arc, closed arc/chord and pie slice. One of these boxes is checked if the user wants to create an arc instead of a full ellipse. When creating an arc, four clicks are required on the viewport: two to create the ellipse which defines the arc, another to set the beginning of the arc, and a fourth click to set the end of the arc.

Rectangle. A rectangle also consists of a stroke (with a color scheme) and a fill. The user clicks the mouse to start rendering the rectangle, and clicks again to define the opposite corner of the rectangle. The user may also choose to create a rounded rectangle, and in this case an extra mouse click is required to set the rounding. The rounding is set relative to the upper-left-hand corner of the rectangle, and consists of a quarter ellipse which is rendered in each corner of the rectangle.

Note about ellipses and rectangles: these shapes are always initially rendered parallel to the sides of the viewport. The user can use transform/rotate to change the orientation of the shape. (See the transform modes below.)

Text. A text object consists of a textual string rendered in a color scheme and a font. The textual string is entered in a box on the control panel. The text object is positioned with the mouse at the desired location in the viewport. A text object is initially positioned horizontally, and transform mode may then be used on the text object, for example, to rotate the object.

Hybrid. A hybrid object consists of a combination of one or more of the above objects. See List Mode/Combine below.

Transform Mode.

Transform mode is used to transform the current object or viewport in various ways: painting, changing the stroke properties, flipping the object, translating, scaling, rotating and shearing.

The Context button on the transform control panel is used to indicate whether the canvas should show only the object being transformed or all objects. This can be useful if the user loses track of which object is being transformed. In background mode, the context button temporarily clears away all the shapes and text objects, giving a clear view of the background.

Transform/Paint Mode.

The current object can be "painted" by using paint mode. In this mode, the user can choose either a plain paint scheme, or a graded paint scheme. A graded paint scheme consists of a "color 1" and a "color 2." The user clicks anywhere on the canvas to specify the point for "color 1," and then clicks on a different spot for "color 2."

The background may also be painted in the same manner (in background mode).

If the user wants to apply graded paint and other transforms such as translate or scale, the user should apply the paint first, and then the other transforms. Otherwise the positioning of the points for color 1 and color 2 is difficult.

Paint mode does not apply to hybrid objects. Objects should be "painted" before being combined into a hybrid.

Other Transform Modes.

The user can change the properties of the current object or viewport as follows. (Only translate and scale apply to the viewport.)

Stroke. The stroke control panel appears, just as when the object was first created. This mode does not apply to text objects, hybrid objects or the viewport.

Translate. Translation (or moving of the object) is accomplished by clicking the mouse on the canvas, moving the mouse and clicking again. The object is translated in the X (horizontal) and Y (vertical) directions corresponding to the mouse movement. The user may also click on the X and Y buttons and enter the desired translation. The user may click on "Translate the Viewport" if the user wants to translate the viewport rather than the current object.

Flip. The user can flip the current object in a horizontal or vertical manner, by clicking on one of the check boxes on the control panel.

Shear. Shearing is defined as the shifting of X-coordinates as a function of Y-coordinates, and Y-coordinates as a function of X-coordinates. The user clicks the mouse on the canvas, and moves the mouse. The motion of the mouse changes the shear in that direction, i.e., moving right increases the X-shear, moving left decreases the X-shear, moving up increases the Y-shear and moving down decreases the Y-shear. The user may also click on the X and Y buttons and enter the desired shearing.

Scale. Scaling in the X and Y directions happen independently, by moving the mouse as described above in shear mode, or by clicking on the buttons and entering the desired scaling.

The user may click on "Scale the Viewport" if the user wants to scale the viewport rather than the current object. Note that when the viewport is scaled, the X-scaling and Y-scaling are always equal. If the user scales the viewport with the mouse, only up-and-down mouse movements are recognized.

Rotate. The rotation angle is specified by clicking on the rotation button and entering an angle (in degrees). Or the user may click the mouse on the canvas and rotate the current object around its center.

List Mode.

List mode brings up a list of all the objects which have been created. The current object has *asterisks* around it in the list. (By default, this is the object at the bottom of the list, which is the last-created object.) Upon entering list mode, the current object is selected, and only it is visible on the canvas. As the user selects other objects from the list, they appear on the canvas. Multiple objects can be selected with the control or shift keys. The Delete button is provided to delete all selected objects.

The Current button is provided to change the current object to the one selected in the list. If more than one object is selected in the list, only the top-most selected object is made current. If the user switches to transform mode, the current object is the one to be transformed.

The Copy button makes an exact copy (of the current object) and places it on the canvas on top of the current object. If more than one object is selected, copies are made of all selected objects. The user may transform the copied object(s) in any way the user wishes (in transform mode), such as translating or rotating.

The Combine button combines all the selected objects into a single object. The new hybrid object can then be translated, rotated, sheared and scaled in transform mode as a single unit. (Note that the paint and stroke transforms do not apply to hybrid objects.)

Up, Down, Top and Bottom buttons are provided to move objects in the list. The user may want to move objects up or down to change the rendering order of objects on the canvas. The object at the top of the list is rendered first, and each object is rendered in order going down the list. So, if the user finds that an object is covering up another object, the user can use these buttons to change the rendering order.

Undo.

On the Edit menu, Undo may be used in any mode to take away the last object in the object list. There is also a shortcut key for undo: control-z. Each object can be undone one by one until all objects are gone.

Undo All takes away all objects, leaving nothing but the background.

Canceling the Creation of a Shape.

During the creation of a shape, the user may decide that the shape is not desirable, and press the Esc key. This cancels the rending of the shape. However, this does not apply to polygons, since pressing the Esc key completes the polygon. In the case of polygons, the user must use "Undo" to take away the polygon.

Opening a Separate Frame.

On the File menu, the user may press Open Separate Frame in order to open a new window on top of the applet. This new window is movable and resizable. All the objects on the canvas are automatically transferred to the new window. Multiple separate frames may be opened, each with its own canvas and objects.

Saving to Disk.

The applet does not support saving to disk, since browsers normally would consider this to be a security violation. The program is available, however, for local running, which allows the viewport image to be saved to disk as a bmp, jpeg or gif file.

The locally-run version of the program also supports the saving of "project files," which contain all objects, so that the user can pick up a project where he left off. Also supported is the use of image files as the background ("textured" background).

About the Author.

Scott Valenti worked full-time as a computer programmer for various American corporations from 1983 to 2004. He is not currently affiliated with any corporations or academic institutions. He resides on a farm in the midwestern U.S.A., where he devotes himself to his wife and son, his Etch-n-Paint project, and the game of poker.

*********

Any comments or questions about the documentation (or the program) are welcome, and should be sent via email: scott@etch-n-paint.com

Thank you for your interest in Etch-n-Paint!

Copyright © 2009 Scott Valenti. All rights reserved.

(End)