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.