═══ 1. Trademarks ═══ The following are trademarks of the Prominare Inc. Prominare Prominare Designer The following are trademarks of the IBM Corporation. CUA Common User Access IBM Operating System/2 OS/2 Presentation Manager Workplace Shell ═══ 2. Copyright ═══ Copyright ╕ 1989-1994 Prominare Inc. All Rights Reserved. ═══ 3. Introduction ═══ This section is a step-by-step explanation of how to use Prominare Designer to design applications. Process Outline The process of designing and building an application is fairly straightforward. It follows the following steps: Step Process 1 Design application interface and generate resource script file. 2 Add backing code for interface design and build application. 3 Execute initial prototype. 4 Add new elements to application. 5 Add additional backing code for interface design. 6 Rebuild application. 7 Execute new version of application. Steps 4 through 7 become the general process while the application is under further development. You can perform steps 4 and 5 at any point, when you add new functionality to the application through new modules. Starting the Process Double click on the Prominare Designer entry in the Prominare Designer folder. This gets Prominare Designer started on creating the interface for your application. ═══ 4. Step 1: Designing the Application ═══ To begin your design, select the Start new design option in the Prominare Designer Startup dialogue. Prominare Designer will not allow you to create dialogues or windows until a design has been defined. Prominare Designer Startup dialogue The New Design dialogue appears, containing preset initial options along with those for you to complete. In the Basename entry field, enter the basename for the application, Example. Notice that when you change the focus from the entry field in the dialogue, Example.H appears in the Include entry field. Make sure that the OS/2 2.x target environment appears in the Environment group box; this ensures that the correct script and resource conventions are selected. Also make sure that the options in the Save group box are selected. The Include header files and Source code files check boxes are automatically selected when you create a new design. For deletion control, you can select one of three types: None, Don't verify, and Verify on save. These options control how deleted controls and other elements in the resource script file are handled. For example, the None option prevents Prominare Designer from removing any deleted resource type references from your resource script file. Don't verify allows Prominare Designer to delete the references from your resource script files, whereas Verify on save displays a list of deleted controls before the design is saved, allowing you to delete items that could cause resource script file references to be updated for the deleted control or controls. By default, the None option is selected. This tells Prominare Designer that you will remove any dead resource types caused by controls removed from the design. The options for the App type group box pertain only to the OS/2 2.x environment (the OS/2 Workplace is only present in OS/2 2.x). Since you are creating an application and not a Workplace object, make sure that the Presentation Manager radio button is selected. New Design dialogue Prominare Designer can save resource information in two formats, .RES and .RC. The former is the final resource format that is bound to the application or DLL. The latter is in script format, which must be processed by the Resource Compiler (which in turn creates the .RES file). .RES is inherently faster than .RC; depending on the size of your design and the number of resources you have to deal with, using this format can significantly reduce the time it takes to build the application. For this example, select the .RC option. Click the mouse pointer on the Set push button, informing Prominare Designer that you are finished defining the project. Prominare Designer then automatically sets up predefined information, such as program variables, that will be used within the application. Now you are ready to begin designing the application. To use Prominare Designer most effectively, it is best to create the dialogues before the main program window. This makes it easy to associate the dialogues with their respective menus. Of course, you can create the main window first, then the dialogues and then go back and edit the menu items to add the associated dialogues. But if you know the dialogues already, it is easier to create them first. Creating the Dialogues The first dialogue is the Example Dialogue. Select the Edit menu and then the New menu item, displaying the New Dialogue/Window dialogue. Select the dialogue type you wish to create. In this case, select the first item of the second row and then click on the Create push button. This displays the Window/Dialogue Styles dialogue, throughwhich you define the title bar text, ID symbol, and value, window, or dialogue styles. Make sure that the Type combination box shows Dialogue. In the Relative combination box, select Window to make the dialogue you are creating relative to its parent window. The remaining combination boxes can be ignored, as they are not relevant to the dialogue you are creating. Click in the Text multi-line entry field and then select the text there by pointing to the first character, clicking, and dragging the mouse to the right. Once all the text is selected, press the delete key (as there is no title bar within the dialogue). New Dialogue/Window dialogue Next, click in the ID field and enter DLG_EXAMPLE. Select the value and change it to 100. Set the style of the dialogue with the Style group check boxes so that only the Visible and Dialogue frame check boxes are selected. Finally, click on the Enter push button to create the dialogue frame in the lower left corner of Prominare Designer above the status window. You can now move and size the dialogue frame. The suggested size is 145 dialogue units wide (cx) and 80 dialogue units high (cy). To do this, place the mouse pointer on the top right-hand corner of the dialogue sizing frame and, when the mouse pointer changes from an arrow shape to the 45 double-headed arrow shape, press button 1 on the mouse. While keeping the mouse button depressed, drag the sizing frame to the top right of the Prominare Designer window until you achieve the desired size. Select the Control menu, then the Icon item in the middle column of the menu. Notice that the mouse pointer changes from an arrow to a positioning pointer shape. As you move the mouse around, the [x,y] position at the bottom right in the status window changes, indicating the position of the crosshair relative to the lower left corner of the dialogue frame. Window/Dialogue Styles dialogue Move the mouse to relative position 58,50 and click mouse button 1. This tells Prominare Designer where you want to place the icon. A stylized icon and then a dialogue appears. In this dialogue, enter ID_WINDOW in the ID field. For the value, enter 1. This symbol and value will be used for both the icon and the main application window ID. Make sure that the Visible option is selected in the Base styles group. If you do not select this option, the icon will not be displayed in the dialogue when used by the application. Finally, click on the Enter push button to exit the dialogue. Before you exit, Prominare Designer checks to see if you have previously defined an icon resource for the icon control just created. When no icon is found, you are asked if you wish to define the icon resource. Select the Yes push button to display the Bitmap, Font, Icon, and Pointer Resources dialogue, through which you can define the icon resource to be used by the application. Unless you define the icon, the dialogue will not appear in the actual application. The Bitmap, Font, Icon, and Pointer Resources dialogue is used for five resource types. Select the Icon radio button and enter the ID symbol and value for the Icon. (As mentioned previously, the symbol for the icon is ID_WINDOW, also the symbol for the main application window.) Select the ID symbol and value using the ID field drop-down. Bitmap, Font, Icon and Pointer Resources dialogue All that remains for the icon is the name of the file containing the icon, which could have been created in the Icon Editor. In this case, enter Example.Ico before clicking on the Add button. You will be asked if you want to create the default icon, since the icon does not exist. Select the Yes button. This icon can be edited at a later point to become the final application icon. Now click on the Save button to exit the dialogue and save the definition. Select the Control menu again and notice that a check mark has appeared beside the Icon menu item. Prominare Designer always places a check mark beside the menu item in the Control menu of the currently selected control. You now want to place text in the dialogue; select the Text menu item in the second column of the menu. As with the icon you just created, the mouse pointer changes to the positioning pointer . This time, move the mouse pointer to relative position 10,30. When you press button 1 on the mouse, a dialogue is displayed, this time allowing you to set the text styles. Static Styles dialogue In this dialogue, replace the default text with Example Dialogue Box. No ID symbol is required; change the default ID value to -1 if you wish. In the Text options group, select the Horz. centered style and click on the Enter button. Static Styles dialogue A message box is displayed regarding CUA Non-Compliance. This message alerts you that secondary words in the entered text are capitalized. In this situation, ignore the warning since you are using the text as a title. CUA Non-compliance message box Notice that the text that you entered is not completely visible. To correct this, move the mouse pointer to the right side of the text sizing frame until it changes to the double-headed horizontal arrow. Press button 1 of the mouse and drag with the mouse button still depressed to the right of the dialogue, while watching the [cx,cy] value in the status window. Continue dragging the frame edge to the right until the [cx,cy] value is 125,8. Release the mouse button. The text is now centered in the dialogue. Finally, you need to create a push button to exit the dialogue. Instead of using the Control menu to create the next control, use the Tools window. Display it by selecting the Tools window button in the Tool Bar; the Tools window will appear in the top right hand corner of the Prominare Designer window. Notice the grid of control representations; you can click on the control you wish to create instead of using the Control menu. Select the Push Button control representation (top left button) in the Tools window and place the push button starting at location 45,5. When the dialogue is displayed, change the default text to OK. Now you need only add the ID symbol and value. This time, you will do it differently from the way you created the previous two controls. Button Styles dialogue You will probably have noticed the drop-down button in the ID field click on the button that displays the drop-down list like that of a combination box. This list contains all currently defined symbols; in it, notice the two symbols you entered previously: DLG_EXAMPLE and ID_WINDOW. There are also additional ID values, DID_OK and DID_CANCEL among others. These two symbols are predefined by OS/2 Presentation Manager for use with push buttons. As the symbols are labeled, one is usually associated with an OK push button and the other with a Cancel push button. In this case, you want to use the DID_OK symbol. To select the symbol, click once on the DID_OK symbol entry in the list. Also, notice a combination box labeled Dialogue. This combination box allows you to associate the push button with a dialogue displayed when the push button is selected by the user. This is useful when you are prototyping an application and want to demonstrate to others how the user would interact with it. Again, since the push button is used only to exit the dialogue, you do not need to use the combination box. Before you click on the Enter push button, click the Default check box in the Options group. This draws a heavy border around the button, which indicates the default action when the user presses the ENTER key. You have now created the first dialogue box. Completed dialogue Creating Application Windows Now that you've completed the dialogue, you need only to create the main application window. As with the dialogue, use the New... item in the Edit menu. Again, the New Dialogue/Window dialogue is displayed. Instead of selecting one of the dialogue types, select the window type--the bottom right image in the dialogue. This time, when the Window/Dialogue Styles dialogue is displayed, select Parent window in the Type combination box and the styles Title bar, System menu, Visible, Size border, Menu, Min button, Max button, Accelerators, and Shell position. For the text, type Example Window; for the ID symbol and value, use the ID field drop-down to select the ID_WINDOW. You do this because the icon used in the dialogue is the same icon to be used for the main window. Usually, the main window uses the ID of the icon. Enter Example Window in the entry field labeled Description. New Dialogue/Window dialogue Notice that the main parent window fills most of the Prominare Designer window but has no action bar; it will be displayed once you add an action bar menu item. Window/Dialogue Styles dialogue Creating the Menus Select the Menu button in the Tools window. A message box appears indicating that no menus exist for the window. It also asks if you want to select menus from the standard menus. Click on the Yes push button to display the Standard Menus dialogue. No menu message box This dialogue contains eight notebook pages, with each page signifying different action bar menus. Selecting the check box for the action bar item indicates that you wish to include that item in the action bar. The menu items generally associated with that item then become selectable. Select those that apply to the window you are creating. Standard Menus dialogue For this window, you want to include the File action bar item but none of the standard menu items. Select the File tab of the notebook, then click on the File action bar menu check box. The sub-menu items associated with the File action bar menu become selectable. It is impossible to have sub-menu items with no action bar items. Next, click on the Create button, creating the action bar menu item. The Menu Styles dialogue is then displayed, showing in the list boxes the File action bar item you selected in the Standard Menus dialogue. To add a formal ID symbol, select the item in the top list box and enter IDM_FILE in the ID field. Menu Styles dialogue Click on the Change button to update the item and add it to the list boxes. Next, you could enter a new item or change the current one. An * is displayed to the left of the text denoting the item as an action bar menu item; it is coloured dark red, distinguishing it from the regular menu items. Select the Menu item radio button to add the first menu item of the File menu. Enter ~Example dialogue... for the menu item text, IDM_EXAMPLE for the ID symbol, and 10 for the value. Since you previously created a dialogue (Example Dialogue), associate the menu item you are creating with the dialogue. Click on the Dialogue combination box arrow to display the dialogue list. Select the DLG_EXAMPLE symbol and the combination box entry field will be completed for you. From the Menu styles group, select the Text radio button. Before you can add the menu item to the list, you must associate the sub-menu item you are entering with the action bar menu by clicking on the File entry in the list box. This allows Prominare Designer to place the sub-menu into the correct action bar menu. When more than one action bar menu has been defined, this simplifies the process and prevents unnecessary arranging of menus later on. Now click on the Add button to add it to the sub-menu list. Menu Styles dialogue For the next menu item, select the Separator style and enter -1 in the ID entry field. This time, you do not have to associate the separator to the File menu, since it is already selected. Only when the sub-menu item that you are creating has a different parent do you need to select the parent menu item in the list box. The final menu item to be added to the File menu is the exit command. The exit command text should be E~xit\tF3; enter it in the Text field. Notice that an accelerator is now associated with the menu item; it will be automatically added to the accelerator table. The ID symbol and value for the menu item should be IDM_EXIT and 11. Associate the menu item with the File menu, select the Text style from the Menu styles group, click on the Add button and then on the Save button to exit and save the menu information. This also places the menu items within the window you are designing. You can see this be clicking on the File menu item in the window you are designing. Saving and Generating the Resource Script files The design of the application is now complete; all you need to do is save the project files with the Save item in the File menu. Prominare Designer prompts you to Save the include (.H) file? Two push buttons appear, Yes and No. Since you will need the header file to properly compile the source files, click Yes. Prominare Designer then saves the design file (.PDF) and header include files before generating the resource script (.RC) file for the application. The application interface is now complete and almost ready for you to add the backing code. Exit Prominare Designer by double clicking on the system menu; you are returned to the Workplace desktop. ═══ 5. Step 2: Adding Backing Code ═══ Once the interface for the application is complete, you can create the necessary C or C++ source files to handle the user's interaction requests. ═══ 6. Step 3: Execute Initial Prototype ═══ Now that you've completed the backing code and successfully built the new application, you can test its interface by actually running the application. ═══ 7. Step 4: Adding New Elements ═══ In this step, you learn to add new elements by adding a new dialogue to the application's design. Restart Prominare Designer and click on the Last opened radio button in the Prominare Designer Startup dialogue. This enables the Last opened drop-down, from which you can select the entry for the Example.PDF file from the files list box, to read in the design file for the application. Now you'll create the Another Example Dialogue, which will eventually be associated with the Another dialogue... item in the File menu. First, select the Edit menu, then the New... item. Again, select the dialogue type from the first item of the second row in the dialogue. New Dialogue/Window dialogue Make sure that Dialogue is selected in the Type combination box in the Window/Dialogue Styles dialogue. Delete the default text in the multi-line entry field (since the dialogue will not have a title bar) and click in the ID entry field. Enter DLG_ANOTHER and then click in the Value entry field and enter 110. Click on the Style group check boxes so that only the Visible and Dialogue frame check boxes are selected. For the description, enter Another Example Dialogue. Finally, click on the Enter push button to create the dialogue frame in the lower left corner of Prominare Designer, above the status window. You can now move and size the dialogue frame. The suggested size is 145 dialogue units wide (cx) and 80 dialogue units high (cy). Place the mouse pointer on the top right hand corner of the dialogue sizing frame. When the pointer changes to the 45 double-headed arrow, press mouse button 1 and drag the sizing frame to the top right of the Prominare Designer window until you achieve the desired size. Window/Dialogue Styles dialogue Now, select the Control menu and System icon item. Notice that the mouse pointer changes from an arrow to a positioning pointer shape. Move the mouse to relative position 58,50 and click mouse button 1. This tells Prominare Designer that you want to place the icon in this location. First a system icon, the actual mouse pointer arrow, and then the Static Styles dialogue is displayed. Click on the Icon list... push button to display the System Icon ID List dialogue. In this dialogue, move to the combination box and click on the drop down button to display the drop down list. Select SPTR_ICONINFORMATION ID in the drop down list. Click on the Select push button, placing the SPTR_ICONINFORMATION ID symbol in the ID field. Now click on the Enter push button to exit the dialogue. System Icon ID List dialogue In the Tools window, select the Text button. As with the System icon you previously created, the mouse pointer will change to the positioning pointer shape. This time, move the pointer to relative position 10,30. When you press button 1 on the mouse, a dialogue appears allowing you to set the text styles. In the Static Styles dialogue, replace the default text with Another Example Dialogue. No ID symbol is required; you can change the default ID value to -1 if you wish. In the Text options group, select Horz. centered before clicking on the Enter button. Notice that the text that you entered is not completely visible. To correct this, move the mouse pointer to the right side of the text sizing frame until it changes to the double-headed horizontal arrow. Press button 1 of the mouse and drag with the mouse button still depressed to the right of the dialogue, while watching the [cx,cy] value in the status window. Continue dragging the frame edge to the right until the [cx,cy] value is 125,8. Release the mouse button. The text is now centered in the dialogue. Finally, you need to create a push button to allow the dialogue to be exited. Select the Push Button icon in the Tools window and place the push button starting at location 45,5. When the Button Styles dialogue is displayed, change the default text to OK. Now you need to add only the ID symbol and value. Select the ID drop-down, then select the DID_OK symbol from the drop-down list. Before clicking on the Enter button, click the Default check box. With this done, the dialogue is complete. Now you need to create a new menu item in the File action bar menu, so you can display the dialogue from within the application. In the Window/dialogue combo box in the Tool Bar, select the ID_WINDOW item; Prominare Designer displays the Example Window. Completed dialogue Now select the Menu button in the Tools window so you can add the new menu item. In the dialogue, note the File entry with an * displayed to the left of the text, denoting that the item is an action bar menu item. Enter ~Another example dialogue... for the menu item text, IDM_ANOTHER for the ID symbol, and 12 for the value. Select Text in the Menu styles area. Menu Styles dialogue Since you have a previously-created dialogue, (Another Example Dialogue), you can associate the menu item you are creating with that dialogue. To do so, select the dialogue ID from the Dialogues drop down list. Before clicking on the Add button, click on the File entry in the list box. You must do this to associate the sub-menu item you are entering with the action bar menu. This allows Prominare Designer to place the sub-menu into the correct action bar menu. When more than one action bar menu item has been defined, this simplifies the process, preventing unnecessary arranging of menus later on. Notice that the new menu item was added below the Exit menu item. Since Exit should be the last item in the menu, you need to rearrange the items. Click on the Arrange... button to display the Arrange Menus dialogue. This is a convenient way to access the Menu Styles dialogue. Alternately, when you are not in the Menu Styles dialogue, access it by selecting Arrange menus... in the Options action bar menu. Arrange Menus dialogue Select Another example dialogue... in the list box, then move the mouse pointer to just above the Separator item. When the pointer changes from an arrow to a bar over the entry, click mouse button 1 to move the selected menu item to this location. Now that you've rearranged the order of the menus, click on the Accept button. You can double check that the menu is correct by simply clicking on the File menu of the Example window. Now click on the Save button to exit the dialogue. The second phase of the process is now complete and you can save the file. Since you want to rebuild the application, double click on the Prominare Designer system menu. You will be asked if you want to save the Example.Pdf file; click on the Yes button. You will also be prompted to save the include header file; again click Yes. ═══ 8. Step 5: Add Additional Backing Code ═══ Once you have exited Prominare Designer, you can add additional backing code to the source files. The code will handle the additional interface elements. ═══ 9. Step 6: Rebuild the Application ═══ After adding the new code, you can rebuild the application for further testing. ═══ 10. Step 7: Execute New Version of Application ═══ Finally, having rebuilt the application, you can test it.