OS/2 Shareware BBS: 10 Tools/10-Tools.zip/pdlite.zip/using.INF

OS/2 Help File | 1995-07-11 | 216KB | 529 lines

ΓòÉΓòÉΓòÉ 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.