                       Using Dialog Boxes in Actor
                       ---------------------------

By Dan Walker
Copyright (c) 1990 the Whitewater Group, Inc.


This is the first in a number of articles that will be appearing on 
the BBS.  They are directed towards Actor(R) programmers who are not 
that familiar with Windows.  If  you have a topic you would like 
discussed in this space, please send a message describing your
idea to the sysop.

This article is about  using dialog boxes in Actor.  It describes 
what a dialog box is, how you create a dialog box,  and  how you 
incorporate and use dialog boxes with Actor.

What is a Dialog Box?
A dialog box is a specialized window that you can use to prompt the 
user for input.  Windows (tm) provides a number of items, called 
controls, that are used as components of a dialog box.  The basic 
control types are:

        Static
        Static controls are used to put labels and other informative
        text within the dialog box.

        Edit
        Edit controls are used as data entry fields.  These may be no
        bigger than a single character or big enough to enter whole 
        pages of text.

        Buttons
        Buttons are used to solicit multiple choice information.  
        Buttons come in a number of different styles:
             
           Push Buttons  
           used to initiate some action, e.g., most dialog boxes 
           have an "OK" button and a "CANCEL" button for ending the
           dialog.

           Check Boxes
           used to prompt the user to select all that apply.

           Radio Buttons
           used to select one from a group of mutually exclusive
           options.

           Group Boxes
           used to visually group items in a dialog.  A group box is
           frequently used in conjunction with a group of radio
           buttons.
            
  
        List boxes
        List boxes are used to present the user with variable-length
        lists of choices.  A good example of this is the file dialog
        box used by an Actor FileWindow.  One of its controls is a 
        list box of available files to edit.  Push buttons are 
        frequently used with list boxes to ask the user to confirm 
        his/her choice.

        Scroll bars
        Scroll bars are used to ask the user to specify a value
        within a certain range.  When you set up a scroll bar you 
        specify a beginning and ending range.  When the user slides 
        the thumb of the scroll bar, Windows computes a value that is
        the relative distance from the beginning value given the 
        ending value.  For example, if the beginning and ending 
        values are 1 and  50, sliding the thumb to the middle of the
        bar returns the value 25.

Most of the time your dialog boxes will be resources that you 
describe using one of the tools mentioned below and incorporate 
into the .EXE portion of your application.  Actor 2.0 also provides 
the means of dynamically creating dialog boxes.

How do I create a dialog box?
There are several ways to create a dialog box.  Some methods for 
creating dialog boxes, as well as sources of additional information 
on using these methods, are listed below:

        Use the Whitewater Resource Toolkit.
        This is the easiest way to edit dialog boxes and other 
        Windows resources.  With the Whitewater Resource Toolkit you 
        can design and compile your dialog in one step without 
        leaving Windows and without having to deal with the Microsoft resource
        compiler.  For more information on the Whitewater Resource Toolkit,
        see the Whitewater Resource Toolkit user's manual.

        Use DIALOG.EXE, the dialog editor that comes with the Windows
        Software Development Kit.  For more information on how to
        use this tool,  see chapter 10 of the Microsoft Windows Software
        Development Kit Programming Tools Manual.

        Use a text editor.  This is the hardest method to use but it
        can be done.  To do this, you need to edit a copy of ACTOR.RC
        and add to it a description of your dialog.  Dialog 
        descriptions or templates are written in the following form:

        dialogName DIALOG x, y, width, height
            STYLE style1 | style2 | ...
            BEGIN
               cntrl-type text ID, x, y, width, height, style
               .
               .
            END

        for example:

        MY_BOX DIALOG 20, 20, 150, 100
          STYLE WS_POPUP | WS_DLGFRAME
          BEGIN
             CTEXT "Test box 1" -1, 0, 10, 150, 8
             DEFPUSHBUTTON "OK" IDOK,50, 50, 32, 14, WS_GROUP
             PUSHBUTTON "CANCEL" IDCANCEL,100,50,32,14,WS_GROUP
          END

        This template will produce a dialog box with the text "Test 
        box 1" centered at the top and two buttons, one labeled "OK"
        and the other labeled "CANCEL".  The buttons will have the 
        control IDs of IDOK and IDCANCEL  respectively, which are
        defined in ACTOR.H.  Literal numeric values can also be used.

        For more information on creating dialog boxes in this manner,
        see "Programming Windows", Microsoft Press, by Charles 
        Petzold.


        Use the DialogDesign class to make dynamic dialog boxes.  
        This is a new feature in Actor 2.0.  With this class, you 
        can build a dialog box directly in memory and run it
        immediately.  This type of dialog is not a resource and 
        therefore the following section does not apply.  For more 
        information on DialogDesign objects, see the Actor 2.0 
        Addendum Manual.


How do I use my dialog box in Actor?
To use your dialog box, it must become part of the .EXE portion of 
Actor.  It is a good policy to keep an untouched copy of ACTOR.EXE,
ACTOR.H, and ACTOR.RC in a safe place.  Start each new application by
making copies of these backup copies.

There are several ways to append your dialog box to ACTOR.EXE.  The 
easiest way is to use the Whitewater Resource Toolkit which allows 
you to read and write dialog boxes and other resources directly to 
and from an .EXE file.  If you do not have the Whitewater Resource 
Toolkit, you must use the resource compiler, RC, a Microsoft tool 
that is included with Actor.

There are a couple of ways to include your dialog as one of the 
resources available to Actor.  Here is one way:

        1. Make your default directory ACTOR\RES.
        2. Edit ACTOR.RC to include texts that are part of your 
           dialog.  If you produced a header file with your dialog
           template, add a line near the top of ACTOR.RC that looks
           like this:

                #include mydialog.h

           where "mydialog" is replaced by the name of your header 
           file.  Use the "rinclude" directive to include your dialog
           template:

                rcinclude mydialog.dlg

        3. Type: RC ACTOR.RC 
           This will recompile all of the Actor resources, including
           your new dialog, and append them to ACTOR.EXE.


To use your dialog box in an Actor application, run the copy of Actor
that your dialog box is stored in.  Next design a descendent of the 
Dialog class to work with your dialog.  Your new class should 
minimally implement new versions of the methods "initDialog" and 
"command".  The "initDialog" method can be used to do any startup 
processing that might be necessary such as placing new values in 
edit controls.  The "command" method is the mechanism that allows 
you to respond to events occurring while your dialog box is active.
Typically, your dialog box will have a button or two that, when 
pressed, indicate that the dialog should end.  The "command" usually
uses a select statement to scan for the control Ids of the controls 
in your dialog.  This method is an appropriate place to retrieve 
information from the dialog box.  An example of this is the 
"command" method in InputDialog.  This method tests to see whether the 
"OK" button was pressed and if so, saves the text from the dialog, 
then ends the dialog.

Once you have set up these methods you can run your dialog by 
creating an instance of your new dialog class and sending it a 
"runModal" or "runModeless" message:

        Sam := new( MyDialog );
        runModal( Sam, "MY_BOX", ThePort );

In this example, MyDialog is a descendant of Dialog, MY_BOX is the
name of the dialog described above, and ThePort is a global variable
that is handy to use as the parent for your dialog box.  You do not 
send the "initDialog" and "command" messages; Windows and Actor do 
this for you.  Two good examples of using dialog boxes are built into
Actor.  These are the InputDialog and FileDialog classes.
     
In conclusion, let's review the steps for creating and using a dialog
box:

        1. Describe the dialog box.
        2. Compile the dialog box into ACTOR.EXE ( this step isn't
           necessary when using the Whitewater Resource Toolkit ).
        3. Design a descendent of the Dialog class to work with
           instances of your new dialog.
        4. Run your dialog using the "runModal" or "runModeless" 
           message.
                             