


        
                        DOCUMENTATION FOR DLGED

                         Author: M. A. Sridhar
                         Date:   Dec 13th, 1995


This is a rudimentary, no-frills dialog editor for YACL. It is missing lots
of bells and whistles, but it works, and (IMHO) is usable. I used it for
creating some of its own dialogs.

To begin editing a dialog, you either use the 'New' menu item under File, or
you use the 'Open' item. More about 'Open' later.


Creating objects:
-----------------
To create a SimpleVObject, you pull down the Create menu and pick an object
in it. The cursor changes to cross-hairs, and when you click on the main
window, an instance of the object you chose is placed there. The dialog
editor chooses a default size for the newly-created object. It automatically
chooses the next unused id for the object, and displays the id in the box.


Selection:
----------
Immediately after an object is created, it is selected; this is indicated by
the handles around it. You can select any object by clicking on it. You can
select multiple objects in either of two ways: drawing a large rubber-banded
rectangle around them while holding the mouse down, or by clicking on the
first one and then holding the shift key down while clicking on additional
ones.


Editing:
--------
You can move the selected objects by dragging them. You can move a whole
group of selected objects at a time. You can also resize, but when resizing,
you should have selected just one object. When you move the cursor over the
boundary of a selected object, you can see the cursor shape change,
indicating that you can resize it. The cursor shows an up-arrow if you're
positioned at a corner, and bidirectional arrows when you're positioned on a
side of the object to be resized.

You can also cut, copy and paste objects. And you can replicate, align and
resize them; look in the corresponding menu items under the Edit menu.
You can look at an object's properties by either double-clicking on
it or selecting it and choosing the Edit|Properties menu item. If you modify
any of the properties in the resulting dialog (e.g., position or size) the
change is reflected in the object and displayed.

Each object has a view id, as stipulated by YACL, and can have a symbolic
name you can use as a synonym for the view id in your program. By default,
there is no symbolic name, but you can assign one in the properties dialog.
Each object also has a title, which is the same as the title attribute of the
VisualObject. If you set a title for an object, the title is displayed in the
box for the object; if no title is set, the kind and id of the object are
displayed in the box.


Testing:
--------
You can test the dialog you've built via the File|Test menu option. The size
of the dialog will be the same as the size of your main window, so you can
grow or shrink the latter to resize your dialog.


Saving and restoration:
-----------------------
You can save the current dialog in a file via the File|Save menu item. The
dialog is saved as an array of view descriptors in the format required by
the CompositeVObject's constructor. (I recommend using the extension `.cxx'
for this save file name, so that you can compile it separately and link it
into your application.) If you assigned any symbolic names to your objects,
they will be saved as elements of an enumeration in another file, with the
same base name as the view descriptor file but with extension `.ids'.  This
allows you to compile the saved .cxx file separately and link it into your
program. You can #include the .ids file into parts of your application that
need access to the symbolic names.

Thus each dialog is represented by two files, with the same base name but
with extensions .cxx and .ids respectively. Note that each dialog must have
a separate file pair; the dialog editor is not capable of handling multiple
dialog descriptions in the same .cxx file. Of course, you can work around
this by creating a master .ids file that #include's all your individual
dialog .ids files, and a master .cxx file that #include's all the individual
dialog .cxx files.

You can restore a saved dialog via the File|Open menu item. Bear in mind that
the restoration code does not do any fancy parsing. It looks for sections of
the file delimited by line pairs that have the strings "YACLDlgEditorBegin"
and "YACLDlgEditorEnd" and extracts the structures between these pairs. You
can therefore edit these files if you want, and even change the sizes,
positions and symbolic names in them. But be warned that the restoration code
does just the bare minimal amount of error checking.



Implementation notes:
--------------------
Here are a few notes that might be of interest.

1.  The Properties dialog is created once and made invisible. Each time the
user brings up the properties dialog, it is made visible explicitly and
executed modally. This has the advantage that if you (as user) drag the
properties dialog to a place on the screen that's convenient for you, then
every subsequent time you want the properties of an object, the properties
dialog reappears at the same place.

2. I have set the fonts of  the Size and Alignment dialogs to helvetica. This
tests the font setting mechanism.


