\chapter{Basic Use Cases}
\markboth{Basic Use Cases}{}

A use case is classified according to its effect, whether the effect is on the session or on the IR. All the manipulations in a use case are based on the assumption that the program is running, unless otherwise specified. 

There are some basic dialog manipulations that happen in many use cases:
\begin{itemize}
\item The \wid{Cancel} button and the \wid{OK} button are used almost in every dialog. LMCing the \wid{Cancel} button closes the dialog without having any effect. LMCing the \wid{OK} button closes the dialog while causing the intended effect of the dialog.
\item The \wid{Default} button is given in dialogs in which values are to be input into fields. LMCing this button fills each field with the appropriate default value according to the purpose of the dialog.
\item The \wid{Reset} button is given in dialogs in which values are to be input into fields. LMCing this button clears every field. Then you can start filling the fields again.
\end{itemize}

\section{Affecting the session}
\markright{Affecting the session}

\subsection{Basic file manipulations}
There are four basic file manipulations: \usecase{New}, \usecase{Open}, \usecase{Save}, and \usecase{Save as}.

\begin{itemize}
\item \usecase{New}: create a new IR. There are three ways:
 \begin{itemize} 
 \item With the menu bar: select \menu{File}{New} from the menu bar.
 \item With the shortcut key: type \key{Ctrl}{N}.
 \item With the tool bar: LMC the \wid{New} button in the tool bar. 
 \end{itemize}
The IR is set to empty, and \program{Untitled} is established as the current file name.

\item \usecase{Open}: open an existing file, which is assumed to contain \program{pic} code.
 \begin{itemize}
 \item With the menu bar: select \menu{File}{Open} from the menu bar or select a recently opened files from \menu{File}{Recent Files}.
 \item With the shortcut key: type \key{Ctrl}{O}.
 \item With the tool bar: LMC the \wid{Open} button in the tool bar.	
 \end{itemize}
An \wid{Open} dialog, as illustrated in Figure 3.1, shows up on the screen. In any of the standard ways, indicate the name of the file you want to open. Then LMC the \wid{OK} button.

\begin{figure}
\begin{center}
\epsfig{figure=open.eps, width=2.0in}
\end{center}
\caption{\wid{Open} Dialog}
\end{figure}

The indicated file name is established as the current file name. The 
content of the named file is established as the IR and shows up in the EW. Finally, the picture corresponding to the complete IR is drawn on the canvas.
  
\item \usecase{Save}: save the current complete IR.
 \begin{itemize}
 \item With the menu bar: select \menu{File}{Save} from the menu bar.
 \item With the shortcut key: type \key{Ctrl}{S}.
 \item With the tool bar: LMC the \wid{Save} button in the tool bar.
 \end{itemize}
Normally \usecase{Save} is done when a file name is established. If there is no current file name established, a \wid{Save As} dialog, as illustrated in Figure 3.2, shows up. In any of the standard ways, indicate a file name. Then LMC the \wid{OK} button. The file name is taken as the current file name. In any case, the current complete IR is saved in the file named by the current file name.

\item \usecase{Save as}: establish a new current file name and save the current complete IR in the named file.
 \begin{itemize}
 \item With the menu bar: select \menu{File}{Save As} from the menu bar.
 \end{itemize}
A \wid{Save As} dialog, as shown in Figure 3.2, pops up. In any of the standard ways, indicate a file name. Then LMC the \wid{OK} button.

\begin{figure}
\begin{center}
\epsfig{figure=saveas.eps, width=2.0in}
\end{center}
\caption{\wid{Save As} Dialog}
\end{figure}

The indicated file name is taken as the current file name. Finally, the 
current complete IR is saved in the file named by the current file name.
\end{itemize}

\subsection{Standard \wid{Edit} menu items}
The \wid{Edit} menu has the following standard items:
\begin{itemize}
\item \wid{Undo} - to undo the last action in the edit window, 
\item \wid{Redo} - to redo the last action in the edit window, 
\item \wid{Copy} - to copy the selected content in the edit window to the clipboard, 
\item \wid{Paste} - to paste the content in the clipboard to the edit window, 
\item \wid{Cut} - to cut the selected content in the edit window, 
\end{itemize}

\wid{Undo} and \wid{Redo} are not always available. \wid{Undo} is enabled only when there has been some change made to the IR, \eg\ adding, deleting text. \wid{Redo} is enabled when \wid{Undo} has been done.

Please note that these standard items only work with the EW. You will see 
the use of other items in the \wid{Edit} menu, such as \wid{Change 
Attribute}, \wid{Reset Font}, \wid{Set CIP}, and \wid{Run External Editor} in later sections.

\subsection{Using external editor on the IR}
Besides using the EW to review and edit the IR, you can also specify any external text editor that is accessible from your system to work on the IR. The following steps show you how to set and work with such an external editor: 
\begin{enumerate}
\item Set the external editor. Two ways to do that are:
 \begin{itemize}
 \item Before starting \program{WD-pic}, run the following command or whatever command your host system uses to set shell variables:

\cmmdcon{setenv EDITOR} \cmmdvar{editorname} or \cmmdcon{set EDITOR =} \cmmdvar{editorname},\\
where \cmmdvar{editorname} is the name of the editor that you prefer to use.

 \item If you start \program{WD-pic} without having run the above command, choose \menu{Tool}{Set External Editor} from the menu bar. A \wid{Set External Editor} dialog, as illustrated in Figure 3.3, pops up. Enter the name of your preferred text editor. Then LMC the \wid{OK} button.

\begin{figure}
\begin{center}
\epsfig{ figure=exteditor.eps, width=2.5in}
\end{center}
\caption{\wid{Set External Editor} Dialog}
\end{figure}

 \end{itemize}
\item Run the external editor:
 \begin{itemize}
 \item With the menu bar: choose \menu{Editor}{Run External Editor} from the menu bar.
 \item With the shortcut key: type \key{Ctrl}{R}.
 \end{itemize}

The external editor launches. The current complete IR is copied as the 
file to be edited by the external editor. 

\item Edit the to-be-edited file as you wish.
\item Save and quit the external editor, causing the last version of the 
to-be-edited file to be taken as the IR.

\end{enumerate}
The saved IR is copied into the EW. The picture corresponding to the 
complete IR is drawn on the canvas.

Note that any time you need to modify the IR, you can do it either by 
direct manipulation editing of the EW or by use of an external editor. However, the advantage of using an external editor is that you are able to invoke a specialized editor with powerful commands or your favourite editor whose commands are most familiar to you.

\subsection{Selecting an object}
If you want to select an existing object, you can either LMC or RMC the object on the canvas that you want to select.

The indicated object is highlighted in a different color on the canvas, as illustrated in Figure 3.4. Also the related primitive in the EW of the object is highlighted in the same color.

\begin{figure}
\begin{center}
\epsfig{figure=select.eps}
\end{center}
\caption{Sample of selected object, the box on the left}
\end{figure}

\subsection{Defining grid}
In \program{WD-pic}, a picture could have several grids with different settings. Each grid is saved with a unique name given by you or the program by default. To define a new gird, choose \menu{Tools}{Define Grid} from the menu bar. A \wid{Grid Definition} dialog, as illustrated in Figure 3.5, shows up, initialized to the default values. 

\begin{figure}
\begin{center}
\epsfig{figure=griddef.eps, height=1.6 in}
\end{center}
\caption{\wid{Grid Definition} Dialog}
\end{figure}

The default values for the fields are:
\begin{itemize}
\item \wid{Name}: \code{NewGrid}
\item \wid{Center}: \code{(0,0)}
\item \wid{dX}: \code{movewid}
\item \wid{dY}: \code{moveht}
\end{itemize}

If you do not like the name \code{NewGrid} for the new grid, input a new grid name \widvar{n} of your choice by typing into the \wid{Name} field. Indicate the center of the grid by typing into the \wid{Center} field or selecting from the field's pop-up list. The center must be some point, and could be specified by a symbolic 
expression, such as \code{Box1.c}, or by a constant, such as \code{(0,0)}. Define the \wid{dX} and the \wid{dY} field values by typing into the fields or selecting from the fields' pop-up lists. After you are done, LMC the \wid{Save} button. The grid setting is saved with the given name \widvar{n}. You can activate the saved grid anytime later by giving its name, \widvar{n}. If you want to activate grid \widvar{n} right now, LMC the \wid{Activate Now} button. The just defined grid \widvar{n} is activated. The canvas is redrawn according to the current complete IR with grid \widvar{n} superimposed. If you do not see the grid superimposed on the canvas, you have made an error when defining the grid. Check the status bar for further information and re-define the grid. Section 3.1.6 describes how the grid is determined from the data of the grid setting.

To modify a previously defined grid, choose its name from the field's 
pop-up list. Make the changes. Then LMC the \wid{Save} button.

\subsection{Activating grid}
If you want to activate a previously defined grid, choose \menu{Tools}{Activate Grid} from the menu bar, or RMC the canvas and choose \wid{Activate Grid} from the pop-up menu. If there is not a previously saved grid, a warning dialog shows up. You are asked to define a grid. Otherwise, a \wid{Grid Activation} dialog, as illustrated in Figure 3.6, shows up. Select the name of the grid that you want to activate from the pop-up list of the \wid{Name} field. Then LMC the \wid{OK} button. The named grid is activated. The canvas is redrawn according to the current complete IR with the activated grid superimposed. This grid is determined by the previously defined \widvar{Center}, \widvar{dX}, and \widvar{dY} values in the \wid{Grid Setting} dialog. \widvar{Center} is the origin. A horizontal line and a vertical line cross at this origin. The distance between any two adjacent horizontal lines of the grid is \widvar{dX}, and the distance between any two adjacent vertical lines of the gird is \widvar{dY}.  

\begin{figure}
\begin{center}
\epsfig{ figure=gridact.eps, width=2.5 in}
\end{center}
\caption{\wid{Grid Activation} Dialog}
\end{figure}

\subsection{Setting gravity}
To set the gravity, choose \menu{Tools}{Set Gravity} from the menu bar. Or RMC the canvas and choose \wid{Set Gravity} from the pop-up menu. A \wid{Gravity Setting} dialog, as illustrated in Figure 3.7, shows up.

\begin{figure}
\begin{center}
\epsfig{ figure=gravity.eps, height=3.0in}
\end{center}
\caption{\wid{Gravity Setting} Dialog}
\end{figure}

Click \wid{On} or \wid{Off} to turn the gravity on or off. Whenever gravity is off, whatever (\emph{x, y}) coordinates are indicated by the mouse is taken as the indicated point. Gravity has three tightness radii: \wid{coarse} at 1/4 inch, \wid{medium} at 1/8 inch and \wid{fine} at 1/16 inch. Choose any one. Select \wid{gravitate to grid points} and \wid{gravitate to \program{pic} corners} to cause the grid points and corners of existing objects to be indicated. Whenever the gravity is on, and the distance between the approximate point and a grid point or a corner is within gravity's tightness radius of the grid point or the corner, the grid point or the corner is indicated. 

If a picture is scaled, the tightness radii are divided by the scale value at the CIP.

\subsection{Setting the current insertion point}
Normally, the CIP is just after the last inserted object, where the 
cursors are in the EW and on the canvas. There are two ways to change the CIP:
\begin{itemize}
\item Direct manipulation:
 \begin{itemize}
 \item With the pop-up menu: 
  \begin{enumerate}
  \item Point the mouse at the object whose definition in the IR is desired to position the CIP. 
  \item RMC the object, choose \wid{Set CIP} from the pop-up menu. 
  \end{enumerate}

 \item With the menu bar:
  \begin{enumerate}
  \item Select the object by LMCing it.
  \item Choose \menu{Edit}{Set CIP} from the menu bar.
  \end{enumerate}
 \end{itemize}
The cursor in the EW is moved to the new insertion point. The cursor on 
the canvas is moved too.

\item In the EW:  Move the cursor to the \program{pic} token after which you want the CIP to be positioned. The cursor on the canvas is moved too. 
\end{itemize}

\section{Affecting the IR}
\markright{Affecting the IR}

\subsection{Inserting an object}
There are two ways to insert an object at the CIP:

\begin{itemize}
\item With the palette: LMC the desired \program{pic} token on the palette.
\item With the keyboard: type the related \program{pic} primitive and signal the end of the object either by typing a \token{;} token, or by pressing the \wid{Enter} key.   
\end{itemize}

For example, if you want to draw a box, you can either LMC the \wid{box} button on the palette, or type \wid{b o x} and press the \wid{Enter} key from the keyboard. The \program{pic} code \code{box} is added to the IR at the CIP. The canvas is redrawn according to the complete IR. The result is that a box of default size is drawn after the previous CIP and the CIP follows the just added box. 

\subsection{Adjusting attributes during insertion}
There are several ways to change the attributes of an object during 
insertion: 

Assume a primitive has just been inserted into the IR.
\begin{itemize}
\item With the palette: 
All possible attributes of the primitive are shown in the attributes area of the palette as buttons. Figure 3.8 illustrates the palette after a box has been added to the IR. There are several types of buttons in the attributes area. 

 \begin{enumerate}
 \item an independent button, \eg\ \wid{fill} and \wid{invis}. LMCing one of these buttons will add its token, \eg\ \code{fill} and \code{invis} to the IR at the CIP. 
 \item a button with a value field, \eg\ \wid{wid}, \wid{ht} and \wid{at}. LMCing one of these buttons causes the addition of both its token and the value shown in the field to the IR. You can change a value by typing into its field. If a value field is empty, only the token is added to the IR. In this last case, \program{WD-pic} will be expecting that you will provide the required value by another means, \eg\ typing, typing into the EW, or direct manipulation. 
 \item a button in a set of buttons connected with \(\|\)s, \eg\ \wid{solid} \(\|\) \wid{dashed} \(\|\) \wid{dotted}. You can LMC only one of them to add its token to the IR. 
 \end{enumerate}

To change the attributes of the object, change the values in the fields if necessary and LMC the related buttons in the attributes area. 

\item With the keyboard: 
Type the attributes at the CIP. For the example, type \wid{w i d =} \picvar{expr}. End inputting the object by typing \wid{;} or pressing the \wid{Enter} key. \code{wid=}\picvar{expr}; is added to the IR at the CIP.

\end{itemize}

In either case, the picture on the canvas is redrawn according to the 
current complete IR.

\begin{figure}
\begin{center}
\epsfig{ figure=boxmain.eps, width=6.0in, height=4.5in}
\end{center}
\caption{\token{box} Attributes}
\end{figure}

\subsection{Indicating x, y coordinates}
There are two ways to indicate x, y coordinates, direct manipulation and textually. 

\begin{itemize}
\item Direct manipulation:
If you want to specify a point by direct manipulation, \eg\ after an \token{at}, \token{from}, or \token{to} token, you may wish to make sure the grid and gravity are set properly. Otherwise the exact point the mouse is at is taken as the indicated point and this will need to be expressed as a pair of real numbers, (\emph{x, y}). As mentioned in Section 3.1.7, when gravity is on, a grid point or a corner of an existing object could be taken as the indicated point. 

Move the mouse close to the point that you want to indicate on the canvas. Its exact (\emph{x, y}) coordinates of the point are shown at the right side of the status bar. LMC the point. There are three cases:

 \begin{itemize}
 \item Corner: If the indicated point is a corner of an object, the expression of this corner consisting of the object's label and the corner's designation, \eg\ \code{n}, \code{e}, or \code{ne}, is added to the EW. If the object has no label, a \wid{Label} dialog, as illustrated in Figure 3.9, shows up. Input a label for the object in the field. Then LMC the \wid{OK} button. 

\begin{figure}
\begin{center}
\epsfig{ figure=label.eps, width=2.5 in}
\end{center}
\caption{\wid{Label} Dialog}
\end{figure}

 \item Grid point: If the indicated point is a grid point, a symbolic 
expression for the indicated point, as specified below, is added to the IR at the CIP:
\begin{center} 
\picvar{Center + (n * dX, m * dY)}
\end{center}
where \textbar\picvar{n}\textbar\ is one less than the number of horizontal lines from the origin to the indicated point inclusive, and \picvar{n} = -\textbar \picvar{n}\textbar\ if the indicated point is to the left of \widvar{Center}; \textbar \picvar{m}\textbar\ is one less than the number of vertical lines from the origin to the indicated point inclusive, and \picvar{m} = -\textbar \picvar{m}\textbar\ if the indicated point is below \widvar{Center}. \picvar{Center}, \picvar{dX} and \picvar{dY} are the values of \widvar{Center}, \widvar{dX}, \widvar{dY} of the current activated grid, respectively.

For example, assume the current activated grid is defined as: \widvar{Center} \code{ = Box1.ne}, \widvar{dX} \code{= boxwid}, \widvar{dY} \code{= boxht}. The symbolic expression of the point marked ``+'' in Figure 3.10 is :
\begin{center}
\begin{verbatim}
Box1.ne + (2*boxwid, boxht).
\end{verbatim}
\end{center}

This expression is added to the IR at the CIP. 

\begin{figure}
\begin{center}
\epsfig{figure=gridgravity.eps}
\end{center}
\caption{Indicate points with grid \& gravity}
\end{figure}

 \item Arbitrary other (\emph{x}, \emph{y}) point: If the LMCed point is not any corner or grid point, the coordinates of the point are added to the IR at the CIP. 
 \end{itemize}

When gravity is off, the exact point the mouse is at is taken as the 
indicated point.  

\item Textually: Type \picvar{position}, where \picvar{position} is a \program{pic} expression for the position of the desired point. \picvar{position} is added to the IR at the CIP.
\end{itemize}

\subsection{Adding text}
In \program{pic}, text can be either an attribute of any \program{pic} primitive except \token{move}, or a standalone object. Each line of text is a separate quoted string. 

\begin{itemize}
\item Adding text as an attribute is the same as adjusting other attributes. 
Assume that you have just inserted an object, such as a \code{box}, into the IR at the CIP.
 \begin{itemize}
 \item With the palette: 
  \begin{enumerate}
  \item LMC the \widquote\ button. \codequote\ is added to the IR. 
  \item Type the text that you want to attach to the object, and end by typing \widquote. The typed text followed by \codequote\ is added to the IR at the CIP as you type. 
  \end{enumerate}

 \item With the keyboard:
  \begin{enumerate} 
  \item Type \widquote, and \codequote\ is added to the IR.
  \item Type the text you want to attach to the object, and end by typing \widquote. The typed text followed by \codequote\ is added to the IR at the CIP as you type.
  \end{enumerate}
 \end{itemize}

A way to get multiple text items associated with an object, each in a 
separate line centered inside the object is to repeat Steps 1 through 2 
for each text item.

\item Adding text as a standalone object is the same as adding text as an attribute, except that the quoted text is not following any other object.
\end{itemize}
