		   3DE, the IPAS3 Resource Editor
		   Copyright 1993 Kyle S. Peacock
		       for Yost Group, Inc.

                          ****************

           3DE IS NOT SUPPORTED BY AUTODESK OR YOST GROUP.  

   Yost Group developed this tool for internal use -- to make complex
   custom user interface work easier to do within the IPAS context.  
   Any work you do with 3DE is at your own risk.  If you have questions
   about 3DE, you'll have to work them out among yourselves in Section 
   17 of Compuserve's ASOFT forum (reserved for registered Autodesk 
   Multimedia developers).

   This is untested software.  We recommend that you save your work
   often, and we do not assume any liability for lost data.

                          ****************



3DE is an IPAS3 Resource Editor that provides the IPAS programmer with 
dialog and icon editing tools.  With 3DE, an IPAS programmer can design all 
the dialog templates for an IPAS routine by visually placing interface 
elements such as buttons, edit fields, text, frames, and icons into a dialog 
box.  When a 3DE session is saved, 3DE writes out a C header file containing 
the variable declarations needed to create the dialogs using the dialog 
library (see the Dialog Library section of the IPAS3 SDK manual).

Compiler Support
This version of 3DE only natively supports Metaware HighC compilers.  It's
possible to edit the 3de files so that they'll work with Watcom compilers,
and the technique for doing that is illustrated at the end of this document.

About Resource Files
3DE reads and writes C header files that can be included in the IPAS program's 
client module.  These files contain declarations of variables that make up 
dialogs, icons, edit field objects, etc.  Because this file contains variable 
declarations, some simple guidelines must be followed when using this file.
The resource header file should be included in exactly one module.  If another 
module needs to reference the variables in this file, a new header file should 
be created with the variable declarations (minus the initializer) preceded by 
the extern keyword.  This header file can be included in any modules that need 
to reference the variables.

In order for 3DE to be able to read this file properly and make modifications 
to it, it should remain untouched by the IPAS programmer.  If the IPAS 
programmer modifies this file by adding new declarations that 3DE doesn't 
recognize, they will probably be lost after modifications by 3DE.

The variables that are declared in the 3DE file are named according to the 
identifier name given to the associated interface object when it was created 
in 3DE, or in some cases, a name derived from the identifier name.

3DE Screen Layout
This section provides descriptions of 3DE's menus, icons, dialogs and work 
areas. 3DE consists of two main work areas: 
1) The dialog overview work area displays an icon representing each dialog 
that is part of the current project.  Double-click on one of the icons to 
bring up that dialog for editing.

2) The dialog edit work area is used when editing a specific dialog.  The 
dialog is displayed in the upper-left corner of the work area as it would 
actually appear in 3D Studio.

In addition to the work area, a tool box on the left side of the screen 
contains several icons, and there is a menu bar at the top of the screen.


3DE Menus

The 3DE menu bar consists of three menu headings, Info, File, and Options.  To 
the right of the headings the x and y world coordinates of the mouse cursor 
are displayed whenever the mouse cursor is positioned over the work area.  
Inside a pop-up menu, next to menu items, the keyboard short cut for that item 
is displayed. For instance, next to "About 3DE" in the "Info" topic, a '!' 
character appears indicating that pressing the '!' key is equivalent to 
selecting that menu item.

Info:
This menu contains two items that provide information about the current 3DE 
session.

About:
Displays a dialog containing information about the author and current version 
of 3DE.

Status:
Displays the number of dialogs, elements, and icons in use and the number 
available.

File:
Items on this menu let you load and save 3DE files.

New:
Deletes all dialogs and associated elements from memory allowing a new project 
to be started.  A prompt appears to verify that you want to do.

Load:
Brings up a file selector letting the user choose a file to load into 3DE.

Merge:
Brings up a file selector letting the user load the contents of a file to the 
current project.  If the file being merged contains dialogs with conflicting 
identifiers, an error message is displayed and the merge is aborted.  If this 
happens, the only way to merge the files is to save the current project, load 
the file to be merged, rename the conflicting dialogs, and then merge with 
original project.

Save:
Brings up a file selector and lets you set the directory and file name under 
which to save the current project.

Delete:
Brings up a file selector and lets you choose a 3DE file to delete.

Quit:
Quits 3DE.  A prompt appears to verify that this is what you want to do.

Options:
This menu contains items that control editing defaults in 3DE.  When each 
item is active, a check mark appears beside it in the menu.

Frame Strings:
When Frame Strings is active, it causes strings in dialogs to be displayed 
with a dashed outline indicating the boundary of the object.  The text is 
always centered within this boundary.

Snap H:
When Snap H is active, objects moved horizontally within a dialog will snap 
to every nth pixel where n is defined by the current horizontal 'snap' value 
(see Set Snap menu item).

Snap V:
When Snap Vis active, objects moved vertically within a dialog will snap to 
every nth pixel where n is defined by the current vertical 'snap' value 
(see Set Snap menu item).

Snap H Size:
When Snap H Size is active, objects sized horizontally within a dialog will 
snap to every nth pixel where n is defined by the current horizontal 'snap' 
value (see Set Snap menu item).

Snap V Size:
When Snap V Size is active, objects sized vertically within a dialog will 
snap to every nth pixel where n is defined by the current vertical 'snap' 
value (see Set Snap menu item).

Snap All:
Selects all four snap items: Snap H, Snap V, Snap H Size, and Snap V Size.

Unsnap All:
Deselects all four snap items: Snap H, Snap V, Snap H Size, and Snap V Size.

Trash Multiples:
Used to delete one or more dialogs.  When it is selected, the work area 
changes to include the identifiers of all dialogs in the project.  Any 
number of these identifiers can be selected by clicking on them with the 
mouse, or de-selected by clicking again (they will appear turquoise when 
selected).  When you have selected all of the dialogs you want to delete, 
click on the trash icon in the tool box to delete them from memory.  You are 
prompted to confirm this action.

Sort X & Y:
This option sorts the dialog elements so that they are drawn top-down, 
left-right.

Center In Parent:
Centers all selected objects relative to their parent.

3DE Tool Box
On the left side of the screen, a tool box containing several icons, is 
displayed.  The tool box is divided into two sections.  The upper section 
does not change much, while the lower section contains different tools 
depending on which workspace you are currently working in.

The top section consists of:

Trash Can:
To delete an object from the workspace, drag it over this icon.  Make sure 
that the cursor is positioned within the icon before releasing the mouse 
button.  You are prompted to confirm any deletion.

Select All:
Click on this icon to select all objects within a dialog.  If 3DE is in Trash 
Multiples mode, this selects all dialogs.  See Trash Multiples menu item.

Select None:
Click on this icon to deselect all objects within a dialog.  If 3DE is in 
Trash Multiples mode, this deselects all dialogs.  See Trash Multiples menu 
item.

Clipboard:
Drag an object over the clipboard icon to save it temporarily in memory.  If 
multiple items are selected, you can save the set on the clipboard.  When 
there is something on the clipboard, its icon changes appearance to let you 
know.  If you there is already something on the clipboard, dragging a new 
object onto the clipboard erases the old one.  To place clipboard objects into 
a dialog, click on the clipboard icon and the object(s) can be dragged out 
back into the work area.

Exit:
This icon appears only after the Trash Multiples menu item is selected on the 
Options menu.  The exit icon replaces the clipboard icon when 3DE is in the 
Trash Multiples mode.  Click on this icon to terminate this mode and return to 
the dialog work space.


Icons in the lower section represent the types of objects that can be created.  
Drag one of these icons into the work area to create a new instance of that 
object type.

Dialog Icon:
This is the only icon in the lower section when the work area is in Create 
Dialog mode.  Drag this icon into the work area to create a new dialog.  A 
prompt appears asking for the name of the new dialog.  Enter the name of the 
dialog up to 7 characters, and press Enter.


Once you have created a new dialog to edit, the following buttons appear.

Button:
Drag this icon into the work space to create a new button object.

Edit:
Drag this icon into the work space to create a new edit field object.

String:
Drag this icon into the work space to create a new text object.

Box:
Drag this icon into the work space to create a new box object.

Frame:
Drag this icon into the work space to create a new frame object.

Icon:
Drag this icon into the work space to create a new icon object.

Boxed Character:
Drag this icon into the work space to create a new boxed character object.  
An example of this type of object is a drive button in the 3D Studio file 
selector.


Editing A Dialog:
You will probably spend most of your time in the Dialog Edit mode.  In this 
mode, interface elements can positioned and sized within the main dialog.

Parent/Child relationships:
IPAS dialogs maintain hierarchical, parent/child relationships between 
interface objects.  The parent dialog or root dialog is at the top of the 
hierarchy with its children and its children's children following.

The way relationships are determined within a dialog is by the position of the 
upper-left corner of an object relative to another object.  If an object's 
upper-left corner lies within another object's boundary, it is considered to 
be the child of that object.

When a parent object is re-positioned, its children move with it.  A parent 
object is restricted during re-sizing so that it can never be so small that 
one of its children's upper-left corners will fall outside of the parent's 
boundary.  A child object can however, be large enough to have part of its 
boundary lie outside of its parent's boundary.  Of course this makes for very 
strange and unstandard-looking dialogs.

Moving and Sizing Objects:
In general, use the mouse to move interface objects around within a dialog.  
If the object is moved so that its upper left corner lies over another object 
that it did not overlay previously, a warning message will appear to inform 
you that you are about to change the parent-child relationship.  This also 
occurs if an object is moved so that its upper-left corner is no longer 
positioned over its parent object.  At the prompt, you can either accept or 
cancel the move.  If you cancel it, the object is returned to its previous 
position.

To size an object, place the mouse cursor over its lower-right corner, and 
click.  Then, drag the mouse to define the new size.  If the object you are 
sizing has child objects, sizing is restricted so that the upper-left corners 
of the child objects do not extend past the boundaries of the parent.

Selecting/Deselecting Objects:
Some times you may want to apply an operation to one or more objects at the 
same time.  To do this, you can select a group of objects.  The Select All and 
Deselect All icons in the toolbox on the left side of the screen select or 
deselect, respectively, all of the objects in the current dialog.  If you want 
to select more than one, but fewer than all of the objects in a dialog, click 
and drag a rectangular region around a group of objects to select them.  
Selected objects appear with thicker white frames.  To deselect objects, click 
on the Deselect Objects icon in the toolbox.

Interface Elements:
Each of the interface elements that make up a dialog has a set of parameters 
that can be defined within the Resource Editor.  To bring up the dialog that 
lets you edit these parameters, double-click on the object you want to edit.
The seven interface element type are:

Button:                 A standard push button. 
Editable:               An edit field.
String:                 A static text label.
Box:                    A solid, shaded rectangle.
Frame:                  A shaded frame, not solid.
Icon:                   A single bit per pixel image.
Boxed Character:        Similar to a button, but with a single character 
label.

Most interface objects share a set of common fields, they are:

String, Text, or Button Text : This is the text that will appear on the 
object. For instance, in the case of a button object, this is the button's 
label.

Key : The keyboard accelerator to activate the object. If the object was a 
button, and this field was set to 'x', then the character 'x' would act as 
the keyboard counter-part to clicking on the button.

ASCII Key: Entering an ASCII value in this field and clicking on the Display 
button will cause the Key field to be updated with the character associated 
with the ASCII value. This makes it possible to assign non-printing characters 
like escape and enter to the key field.

Display : Causes the Key field to be updates according to the content of the 
ASCII field.

Default: [ENTER] : Sets the 'Key' field to the enter key.
Identifier : The name of an identifier to represent the object within the 
dialog. If this field is non-empty, a #define statement will be generated in 
the output resource file that will define this objects index within the 
dialog. This constant is used with many if the dialog library routines to 
refer to the control.

Editables don't share all these fields. Instead, Editables have the following 
extra fields:

Display Size : This is the number of characters that can be displayed in the 
edit object at once. This number can't be greater than the 'Edit Size' field.

Edit Size : This is the total number of characters that can be entered into 
the edit field. This number can be larger than the value in the 'Display Size' 
field.

Edit Type : The type of the field restricts the set of character strings that 
the user can enter into the edit field. The possible types are:

Any:            Any character can be entered.

Int:            A positive or negative integer value can be entered. 

Float:          A positive or negative floating point value can be entered.

Pos-Int:        A non-negative integer value can be entered.

Pos-Float:      A non-negative floating point value can be entered.

Univ:           These are universe units such as inches, meters, etc.

Pos-Univ:       A non-negative distance in 3D Studio universe units can be 
entered.

Pri-Fname:      An 8 character filename with no extension.

Dos-Fname:      An 8 character filename, plus . (period) and a 
three-character extension can be entered.

Uppercase:      Any character can be entered, but lower-case characters will 
automatically be converted to upper-case.

Other:          A custom type.  An integer value (10 or greater) can be 
entered in the field below to identify the type.

Icons have an additional button in their attribute edit dialog that brings 
up the icon editor.  The icon editor is described in the next section.

Creating and Editing Icons:
Icons are single bit/pixel images that can be placed in a dialog.  Icon 
definitions can also be used with the IPAS graphics functions to draw 
patterns directly on the display.  Icons can be up to 128 x 128 pixels in 
size.

The icon editor is made up of an edit window, an icon view window, and a 
series of buttons. 

The edit window is where the actual drawing takes place.  Click with the 
mouse in this window to set the color of a pixel to either white or black, or 
toggle the color depending on the drawing mode.  This window has scroll bars 
to allow scrolling of the work area if that the icon is larger than the 
viewing area.The icon view window displays the work in progress at a 1-to-1 
viewing ratio.  If the zoom ratio is set to 4X or greater, then a turquoise 
frame will be displayed in this window representing the region that is 
visible in the edit window.  Click in this window to move the center of the 
turquoise frame.  The edit window is then automatically scrolled to this 
region.

The buttons on the right side of the dialog set drawing modes, and icon size, 
etc. 
They are:

Pen:            This set of radio buttons sets the drawing mode to drawing, 
erasing, or toggling between the two.

Zoom:           Sets the zoom factor of the edit window.

Width & Height: These fields set the width and height of the icon. The 
buttons to the right of the fields labeled default, restore the icon to the 
default size. After entering new sizes in these fields, click on the re-size 
button to make the changes take effect.

Clear:          Clears the current icon to the background color.

Invert:         Inverts every pixel of the icon.

Flip X:         Flips the icon horizontally.

Flip Y:         Flips the icon vertically.



Scroll Bars and Other Interface Functionality:

The Resource Editor lets you design bare dialog templates visually.  However, 
the actual appearance and functionality of the dialog is determined by the C 
code that actually manipulates the interface elements.  This code is written 
by the IPAS programmer.

Sliders and scroll-boxes are typical examples of functions that are added to 
a dialog template.  A slider is made up of a box object and two button objects 
with each button at the opposite end of the box.  A scroll box is usually made 
from a vertical slider and another box.  Thus, to create a scroll box, a 
vertical slider (made from two buttons and a box object) and a box object are 
created in the Resource Editor.  The links that make this group of objects 
into a functioning scroll box are set up using the structures and functions 
provided by the dialog library (see the Dialog Library section of this manual 
for more info).In fact, any type of custom control can be created with the 
Resource Editor.  The programmer creates a box object that defines the 
position and size of the control, and then links in custom functions that 
draw the control and react to the user's actions.

Good luck!


** NOTE REGARDING USING THIS VERSION OF 3DE WITH THE WATCOM COMPILER.

Metaware compilers don't mind the use of constant strings in this version
of 3DE's structures, but Watcom compilers can't handle it.

The fourth element of an Editable structure created by 3DE, should be a char *
not a constant string.  This is very important for WATCOM because they assign
identical constant strings to the same location.

It's possible to edit the ascii file to get around this problem.  Here is
one example (out of many techniques) of how to do this:


output from 3DE:
       Editable mainedit[]=
        {
        { 5, 10, 0, "          ", 1, 0, 0, NULL, NULL },
        { 5, 10, 0, "          ", 1, 0, 0, NULL, NULL },
        };
change to:
        char editbuf0[11];  /* the size of the array = bcount + 1 */
        char editbuf1[11];

        Editable mainedit[]=
        {
        { 5, 10, 0, editbuf0, 1, 0, 0, NULL, NULL },
        { 5, 10, 0, editbuf1, 1, 0, 0, NULL, NULL },
        };


[end]

