________________

THE OPENDOC DEMO
________________

In the BIN directory is a demonstration Document Shell.  This program
demonstrates some of OpenDoc's capabilities.  You can start the demo
by changing to the BIN directory and invoking DOCSHELL.EXE.

After starting the program, there are five things you can do:
    1) Activate and select parts
    2) Embed a part into a Container Part
    3) Change the background color for the Container Part
    4) Freeze and defrost the frame of a Container Part
    5) Move and resize the parts
    6) Use drag and drop to move parts into and out of Container Parts
    7) Rearrange the z-ordering of the parts
    8) Delete parts


WALKING THROUGH THE DEMO
------------------------
This section attempts to be a mini-tutorial, taking you through a
series of steps that demonstrate what you can do in the demo, and how
you go about doing it.

Before we start, be sure you install the OpenDoc package before you
run the demo.  The Document Shell must be running from a writable
disk.

To start the Document Shell double-click on the OpenDoc for OS/2 icon in
The Developer Connection for OS/2 folder.  Alternatively from the command
line, change to the DEVTOOLS\OPENDOC\BIN directory and type "DOCSHELL" or
"START DOCSHELL."

When you first start the DOCSHELL, what you will see is a standard
Presentation Manager (PM) frame window with a grid in the client area.
The grid you see is produced by the default root part provided with
this package.  The default root part is a Container Part.  You will
also see a menu bar across the top of the window with selections such
as Document, Edit, Embed, Background, and Help.  You will use the
Embed menu choice embed OpenDoc parts into Container Parts.

Once the Document Shell has started, select the Background menu choice
from the menu across the top of the window.  A pull-down menu will
display the available choices for the background color.  Select a
color.  The background color can be changed for Container Parts.

Next, select the Embed menu choice.  A pull-down menu will display the
names of the parts available to embed.  For this demonstration, the
following parts are available for embedding:

  - Clock Part     -- Displays a clock.
  - Container Part -- A part that can contain other parts.
  - Globe Part     -- Displays an animated, spinning globe.
  - Simple Part    -- This part beeps when you press a key.
  - Text Part      -- A simple, single-line text editing part.

Choose the Simple Part menu item and a Simple Part is embedded into
the root Container Part.

Activate the Simple Part (move the mouse pointer inside the part and
click the left mouse button once).  A white border with tiny, diagonal
black lines will be drawn around the part.  This activation border
indicates that the part is active.  When a part is active, it receives
keystrokes and mouse clicks.

Notice that when you activate the Simple Part, the menu across the top
of the window changes.  The Simple Part does not support the Embed or
Background menu choices, so these are removed from the menu by the part.

Place the tip of the mouse pointer (the hot spot) over the activation
border and click the left mouse button once.  The activation border
will be replaced by a gray frame with white areas.  At this point, the
embedded Simple Part is said to be "selected."  When a part is
selected, it can be moved, resized, and deleted.  The white areas on
the selection frame (there is one in each corner, and one in the
middle of each side) are called sizing handles and are used for
resizing the part.  The gray areas between the sizing handles are used
to move the part.

To change the size of the part, move the mouse pointer over one of the
white sizing handles on the selection frame, press and hold the left
mouse button, move the mouse pointer to a new location, then release
the mouse button.  Once the resizing operation has begun, and until
you release the mouse button, a light gray, "rubber-band" frame will
move with the mouse pointer to indicate the new size of the part.

To move the part, move the mouse pointer over one of the gray areas
between the sizing handles, press and hold the left mouse button, move
the mouse pointer to a new location, then release the mouse button.
Once the move operation has begun, and until you release the mouse
button, a light gray frame will move with the mouse pointer to
indicate the new location of the part.

Next move the mouse pointer over an area that is not in the Simple
Part and click the left mouse button once (the root part is already
the active part, we are simply deselecting the Simple Part).  Select
the Embed menu choice, and select Container Part from the pull-down
menu.  A Container Part will be embedded into your document.

Activate the newly embedded Container Part.  Notice that the menu did
not change when you activated the Container Part.  This is because the
root part and the newly embedded part are both Container Parts.  Now
select the part (single click with the mouse over the activation
border).  Select the Frame choice from the Edit menu, then select the
Freeze choice from the pop-out menu.  What you have done is to
"freeze" the Container Part's frame in the selected state.  Click the
mouse elsewhere in the Document Shell to deactivate the Container
Part, then click inside the Container Part again.  Notice that the
selection frame is drawn instead of the activation border; you cannot
activate the part while it is in the frozen state.  In addition, you
cannot access parts inside the Container Part.  Now select the Frame
choice from the Edit menu, and choose Defrost from the pop-out menu.
The Container Part's frame will now behave in its normal manner.

Activate the embedded Container Part again.  Select the Embed menu
choice and select the Clock Part from the pull-down menu.  Notice that
the Clock Part is embedded inside the Container Part.  If you move the
Container Part, the Clock Part is moved as well.  The Clock Part can
be activated and selected while it is inside the Container Part.

You can use drag and drop to move parts into other parts and out of
parts in which they are embedded.  To try this, select the Clock Part
inside the Container Part.  Place the mouse pointer over one of the
gray areas on the selection frame, and press and hold the right mouse
button.  Move the mouse pointer to a new location that is outside the
Container Part and release the right mouse button.  Notice that the
Clock Part is now outside the Container Part.  Next select the Simple
Part and use the same technique to drag it over the Container Part and
drop it.  Notice that when you move the Container Part, the Simple
Part moves with it.  Remember, you use the RIGHT mouse button for drag
and drop, the left mouse button for simple movement.

Next, move the parts so that the Simple Part is partially covered by
one of the other parts.  Select the Simple Part, then go to the menu
and choose the Arrange menu-item from the Edit menu.  Choose Move
Front from the pop-out.  The Simple Part will be raised from the
bottom of the z-order to the top and is now on top of the other parts.

Last, select the Container Part.  Press the Del key.  Notice that not
only is the Container Part deleted, but the Clock Part inside it is
deleted as well.  You could have used the Clear menu-item on the Edit
menu to achieve the same action.

We have covered the basic functionality of the Document Shell
demonstration.  Now you can take what you have learned and try your
own experiments to see what OpenDoc can do.


HOW-TO GUIDE
------------
  - To start the Document Shell
        To start the Document Shell (DOCSHELL.EXE), open an OS/2
        Window and, on the command line, change to the BIN directory
        and type "DOCSHELL" or "START DOCSHELL."  To start the
        Document Shell with a previously saved file, type
        "DOCSHELL <filename>" where <filename> is the name of the
        file to open. A sample OpenDoc document is given in SAMPLE.DOC.

  - To activate a part
        Single-click the left mouse button while the mouse pointer
        is within the part.  When a part is active, it receives
        keystrokes and messages.

  - To select a part
        Activate the part, then single-click the left mouse button
        while the mouse pointer (the hot spot) is on the activation
        border.  When a part is selected, it can be moved, resized,
        and deleted.

  - To select a part without activating it first
        First hold down the Ctrl key, then single-click the left mouse
        button while the mouse pointer is inside an inactive part.

  - To embed a part
        Activate the Container Part that you want to embed another
        part into (be sure the activation border is visible).
        Select Embed from the menu, then select the part you want
        to embed from the pull-down menu.

  - To resize a part
        Select the part.  Move the mouse pointer over one of the
        sizing handles on the selection frame (there is one in each
        corner and one in the middle of each side).  Press and hold
        the left mouse button.  Move the mouse pointer to a new
        location.  Release the left mouse button.  A part must be
        selected before it can be resized.

  - To move a part
        Select the part.  Move the mouse pointer over one of the gray
        area between the sizing handles on the selection frame.  Press
        and hold the left mouse button.  Move the mouse pointer to a
        new location.  Release the mouse button.  A part must be
        selected before it can be moved.

  - To drag and drop a part
        Select the part.  Move the mouse pointer over one of the gray
        area between the sizing handles on the selection frame.  Press
        and hold the RIGHT mouse button.  Move the mouse pointer to a
        new location.  Release the mouse button.  You can use drag and
        drop to move parts into and out of other parts.  A part must
        be selected before it can be dragged.

  - To change the z-ordering of the parts
        Select the part and use the Arrange menu-item from the Edit
        menu.  Use these menu-items to raise and lower a part above
        or below other parts.  A part must be selected before you can
        rearrange its z-order.

  - To delete a part
        Select the part and press the Del key.  This deletes the part
        and, if it is a Container Part, all the parts contained inside
        the part.  A part must be selected before it can be deleted.


MENU OPTIONS
------------
    Document   - Contains a single menu choice:
                     Close - Closes the document (exits).

    Edit       - Contains these menu choices:
                     Clear   - Deletes a selected part.

                     Arrange - Used to move parts forward and backward
                               in the z-order.  Displays a pop-out
                               menu with four choices:  Move Front,
                               Move Back, Move Forward, and Move
                               Backward.  These choices are used to
                               change the z-ordering of the parts--that
                               is, to change which part is on top (or
                               at the bottom) of the other parts.
                               Move Front raises a part to the top of
                               all the other parts.  Move Back lowers
                               a part at the bottom of all the other
                               parts.  Move Forward raises a part
                               by one level and Move Backward lowers
                               a part by one level.

                     Frame   - Available only while the Document
                               Shell or a Container Part is active.
                               Displays a pop-out menu which
                               contains two choices:  Freeze and
                               Defrost.  Selecting Freeze while
                               the active Container Part's frame is
                               in the selection state freezes the
                               part's frame in that state.  At this
                               point, you can activate other parts,
                               but you can only select the Container
                               Part.  Whenever you click the mouse
                               inside this part, the selection frame
                               will appear, not the activation border.
                               Selecting Defrost restores the part's
                               frame to its normal behavior.

    Embed      - Available only while a Container Part is active.
                 Displays a pull-down menu which lists the parts
                 available for embedding.  Selecting one of these
                 parts embeds the selected part into the active
                 Container Part.

    BackGround - Available only while a Container Part is active.
                 Displays a pull-down menu which contains a list
                 of available colors.  Selecting one of the colors
                 changes the background color for the active
                 Container Part.

    Help       - Displays a pull-down menu which contains a single
                 choice:  "About OpenDoc", which displays the About
                 OpenDoc Alpha dialog box.


SOME THINGS TO NOTICE
---------------------
When a part is the active part, a white border with thin black
diagonal lines is drawn around the perimeter of the part.  This is
called the activation border.  The root part of the Document Shell is
an exception to this rule.  When a part is selected for moving or
resizing a thicker, gray border, with white sizing handles is drawn
around the part.

As you change which part is active, the menu across the top of the
window will change.  This reflects the fact that different parts do
not have to have the same capabilities.

Not all parts can contain other parts.  In the sample, the Container
Part is the only part that can have other parts embedded in it.

When you move a part that contains other parts, the embedded parts are
moved along with the containing part.


NOTES ON THE DEMO
-----------------
Unless you give a filename when you start the Document Shell, parts
are automatically saved to a file named UNTITLED.nnn, where 'nnn' is a
number.  To bring up a previously saved part, run "DOCSHELL UNTITLED.nnn"
from the command line in an OS/2 Window, or, if you have renamed the
file, run "DOCSHELL <filename>".

__________________________________________________________________________

END OF DEMO.TXT
__________________________________________________________________________
