Diamond Tutorial

        o Chapter 0 - Overview
        o Chapter 1 - From the beginning
        o Chapter 2 - Introducing edit toolbar and element properties
        o Chapter 3 - Some direct mouse manipulations
        o Chapter 4 - Direct Mouse manipulations with group of elements
        o Chapter 5 - Using text window
        o Chapter 6 - More
    

About the manual

Manual introduce you new Diamond-Draw program and intended to users having
basic knowledge of the Pic language. However reading the manual one can learn
more than using a dry interface only but capabialities of pic language itself.

In overview we'll talk about goals we tryed to achieve, consider what
points of previuos interface we want to improve and make some assumptions
on language we'll use and constrains we'll try to preserve.

First chapter intoduce new system ,new terms we will use and explains how
to build first example.

In chapter 2 we consider the Edit toolbar - a tool which makes use of
standart program options more convinient and simple.

Chapter 3 and 4 intended to direct mouse manipulations - the power of new
interface. In chapter 4 we concentrate how to manipulate with group of
elements and element insertions.

Chapter 5 returns us to the diagram creation typing text but using an
internal text window with its advantages such as history of commands,
autoappending commands and the most important the real time picture update
as earlier (using direct manipulations).

We assume the next thing : not every Pic function will be described in this
user manual. A user who want deal with some more sophisticated stuffs may
receive appropriate information from the existing Pic manuals.

What really will be discussed :

Operations that you can perform using the product functionality which is
specified by WYSIWYG approach ( by the way we cover almost everything that
defined in the Pic so we assume it will be enough)

  ------------------------------------------------------------------------

 0.Overview of the product

For many reasons in computer sciences we need simple diagrams containing
boxes , circles and other explaining documents we working with.

For creation such documents (in UNIX environment) we have a specially
designed tool - Pic , language which support mentioned diagrams and allows
to build sophisticated things . However working with it we are forced to
batch drawing. It has its own advantages and disadvantages. It makes it
possible to insert diagrams in a document, but it not answer to a modern
design approach.

Of course there are few programs that present WYSIWYG(what you see is what
you get) approach . Someone is compatible to Pic compiler (xfig WD-pic) but
they are not as flexible in drawing as Pic language allows and have a room
for improvement.

As main lacks of the previous solutions we may mention :

   * They are not flexible and not allow to do everything that the Pic does
   * There are too much dialogs in these products
   * Working with mouse is not supported
   * Current object position is very hard to be altered

Our purpose is to design a tool which will be able to present more features,
be more flexible reliable and simple to use.

Our goals during the design of this program are:

   * Preserve that internal representation looks like human-written Pic
     description
   * Implement multilevel undo and redo mechanism ( changes will not be so
     harmful )
   * Avoid dialog boxes and confirmation clicks as much as possible
   * Both attributes and arguments are changeable
   * As indicative names for buttons as possible

As been said in WD-Pic (one of the previous WYSIWYG approaches)
specification it allows to create simple schemes on the fly but any unusual
element requires too complex actions and it may be done in text editor with
less efforts. It's clear that to perform simple and powerful interface is a
very difficult stuff. Anyway we try to perform more direct mouse actions ,
mouse menu which will allow to edit current element ,more features for
editing element and group of elements. Besides of it , we do a special text
window and user will be able to make the same operation as in text editor,
but see the updated picture . Mix of direct manipulation and textual
changes will allow to create things using all Pic language power.

So using our product you will(as we hope) achieve both the regular Pic
power and comfortable interface.

Now let talk about the language we use for describing our product.

There are two basic ways to create a picture and its representation in the
product:

   * using the WYSIWYG graphic interface to draw the picture using one from
     follows:
        o direct command choosing from different menus
        o menu accelerators
        o direct mouse manipulation
   * writing a textual description of the picture in the Pic language

From the users point of view these two ways are equivalent in the final
result.

By those two ways you can:

  1. Insert in your document any graphical element that specified in the
     Pic language:
        o box , arrow , ellipse , circle, line, scale, spline , arc , text
  2. Specify directions , that influence the rest of the picture:
        o up , down , left , right
  3. Define element parameters:
        o size ( width , height , radius )
        o line style ( solid , dotted , dashed , invisible )
        o places ( at , with ... at )
        o adjustments (above , below , right , left )
        o arc directions ( clockwise)
  4. Use default parameters
        o scale , boxwid , boxht , linewid , lineht , circlerad , arcrad ,
          ellipsewid, ellipseht,
        o movewid , moveht
  5. If you want to insert in your document the same picture more than once
     the next operator is defined:
        o for ... to ... by ...


  ------------------------------------------------------------------------

1.From the beginning

All pic language diagrams are based on basic pic elements. There are: box,
ellipse, circle, line, arrow, arc, text and move. All elements have their
own attributes like position, line style or associated text.
Pic compiler uses those attributes to perform desired diagrams. Some of
these attributes are necessary other are optional.

To create some diagram  you can use your favorite text editor to write 
a Pic program after that compile it and see if your program produce 
a desired diagram. This so called BATCH approach .Of course it seems 
not so convenient to do changes and only after recompiling see the change.
Another option is to open Diamond-Draw program and do it there. 
What we see once opening Diamond-Draw?

On the left panel there is Pic token bar directions buttons ,properties bar,
drawing buttons and some checkboxes .
You can use drawing buttons for drawing basic Pic elements.
In order to change current drawing direction you can use directions buttons.
Properties bar shows you the current element properties.There are so called
Default attribute . In future we will see how they can be modifyed or added.
The other thing that you of course notice is that mouse location on the
screen always can be found in small window near the left bar. Further we
will use name Mouse location window for that.
For bounded elements such as box, circle or ellipse you can set if
program asks you for associated text automatically or not.
This option can be set using Text On/Off text checkbox which can be found
at the left panel. Nevertheless Text Off is the default.
Using this features you ca create not too sofisticated Pic diagrams.

After a diagram is done you can receive a text generated by the program .
To do this you open View menu and choose View source option.
Then separate window with  text generated by the program will be opened.

May be you want to save your diagram ? You can do it clicking File menu 
and then choosing Save As option. Save dialog ( and all file dialogs )
are the standard ones.

In the next chapters we will see how to build more complicated pictures.


2.Introducing edit toolbar and element properties

Edit toolbar has all standard edit options performed by clicking
appropriate icon.
Edit options available: Cut, Copy , Paste , Delete , Undo and Redo.
All editing operations are performed with the Current element.

It is time to clarify what the Current element is.
You should keep in mind that program always defines Current
element (even when you open new file current element is default insertion
position of first token).

By definition: Current is the element inserted or modified last.

Insertion of new element will be done after Current in specified direction.
All element manipulation via Edit toolbar, Edit menu or
mouse are related to current element if not specified otherwise .

You can perform any editing operation with the Current element
clicking an appropriate button at Edit toolbar.

After you change diagram (i.e. also change the Pic file containing this 
diagram) current element is also changed.
E.g. if a new element is inserted it becomes Current,
     if the Current element was deleted the one edited last becomes Current.	

Now let's talk about elements properties changing.
Clicking the right mouse button causes editing menu to appear.
Further we call this menu Current element menu. Current element menu has
all basic editing functions such as cut, copy, paste,delete and
properties(used for Properties dialog opening).
Clicking the item properties in this menu causes the Current element 
Properties dialog to appear. 

Properties dialog consists of 2 panels : for the Current element properties 
definition and for an added text edition.

In this dialog you can change properties of the current element:
element size, position, drawing style.
For each such attribute there is an appropriate window where you insert 
a desired value for that attribute.
For a bounded shape you can define if the element will be filled.

As we have said before you can add a a text to the element.
In order to perform this you insert a text you want to add to the
current element in the special window ( marked "text" ).
In order to place this text in a desired place you must choice one of the
optoins defined by radio button.




3. Some direct mouse manipulations


4.Direct Mouse manipulations with group of elements

For more convenient and efficient working the program allows you to make
manipulations with group of elements. 

Group selection done by mouse. In order to select a group of elements 
click left mouse button and without release it pick out rectangle
containing desired group of elements. Actions you can take with group are
Copy, Cut, Paste, Move and Delete. 

You should specify direction of copy as usual, this means where copy of
group will appear. The selected group will be drawn near the last element. 
If you need the new group to be at another location you can move it here.


5. Using text window

If you are familiar with Pic language and prefer writing code to mouse
manipulation you should use Text window for creating your picture.
You have two Text windows:

One small text window at the bottom of the main window - here you have only
few lines for inserting code

Second is just opened text editor invoked by clicking on Text Editor option
in the View popup menu.
Second option is a regular text editor and Diamond Draw doesn't support
any new operation in it.

In the bottom window you have number of useful functions( in addition to 
regular editor functions ) that you don't have in regular text editor.
For example you have an automatic line appending (if possible) by
clicking the End key and automatic spelling


6. More

To read about specific options you should use a full manual. Here we
provide some useful hints which save your time. 

Finally we say that in order to use all program power you should learn how
to work in text window. This of course forces you to learn PIC language
itself a little. Doing some things using a text window allows to save more
time but need more inteligent steps. What are you like more depends on
you only.

  
  ------------------------------------------------------------------------