Using the OS/2 Tutorial Framework

by Mike Kaply

Provided on Volume 8 of The Developer Connection for OS/2 is the Tutorial Framework, which helps you create a tutorial that looks very similar to the highly-acclaimed OS/2 Warp tutorial. You'll find several Framework files on your Developer Connection CD-ROMs, as well as a number of bitmaps you can use for your push buttons. This article provides an overview of how to use the Framework.

Note: The Framework is provided "as is," so all interfaces described in this article are subject to change. You must use C Set++ with this Framework; a precompiled version is not provided. (Other versions will be available in the future.) To assemble the tutorial, run NMAKE. The tutorial will be built for you.

Panel Identifiers
In order to identify the panels, each is assigned a three-digit identifier, XYY, where X is the section and YY is the panel number within that section. For instance, 203 identifies panel 3 in section 2. Note that these numbers are used in all files to identify panels.

Resource File - TUTORIAL.RC
The resource file contains entries for all text and artwork in the tutorial, as well as the accelerator table. Modifications must be made to most of these items. If you have trouble keeping track of what to do in each section of the resource file, there are comments in the file to help you.

BITMAP 203     s2p3.bmp If you had a version of this bitmap that was 16-color, you would also provide the following: BITMAP 1203    16s2p3.bmp Notice that the title "bitmap" has an ID of 1 for the 256-color version and 1001 for the 16-color version.
 * The first section in the resource file is the artwork section. Once you have created artwork that conforms to the specifications in the artwork section, reference the artwork in the resource file by providing entries for each panel. For example, if the artwork for panel 3 in section 2 is S2P3.BMP, the entry in the resource file would be as follows:

The artwork section also contains bitmaps for all the push buttons in the tutorial. You should not need to modify this section. The first part of the strings section contains all the information for each panel, including its title, multi-line entry (MLE) text, and "Do It!" and "Practice" text. You can identify pieces of the panels by adding constants to the panel identifier. Be aware that all entries are limited to 255 characters. PANEL          Title of panel TEXT           Initial text of MLE PRACTICETB     MANDATORY: Title bar of practice window index entry PRACTICE1      Practice step 1 PRACTICE2      Practice step 2 PRACTICE3      Practice step 3 PRACTICE4      Practice step 4 PRACTICE5      Practice step 5 PRACTICE6      Practice step 6 PRACTICE7      Practice step 7 PRACTICE8      Practice step 8 PRACTICE9      Practice step 9 DOITTB         Title bar of Do It! window DOITTEXT       Text of Do It! ''Figure 1. Constants used in the resource file''
 * The second section in the resource file is the strings section. This section contains strings for the panels, the buttons, the error messages, and all the "hover" text. It also contains the name of the shared memory segment that is used by the tutorial. This must be customized for your tutorial.

For TEXT and DOITTEXT, you can add the identifier LINE2 if you run over 255 characters. For example: 301+TEXT         "This is line 1" 301+TEXT+LINE2   "This is line 2" The next part of the strings section contains the button information. All push buttons have an identifier. To produce two-line buttons, add 1 to the identifier. Adding 2 to that button identifies the hover text. For example: IDB_SECTION1    "~Introduction" IDB_SECTION1+1  "to the tutorial" IDB_SECTION1+2  "This is the hover text" You can have up to nine sections in the tutorial.

Other push buttons contained in this section are the action buttons and the Return and Quit buttons.

The next part contains the error messages, which should not need to be customized.

The last part of the strings section contains the shared memory identifier. You should customize the shared memory identifier to be unique for your application. If a user starts the tutorial twice, the tutorial uses the shared memory identifier to redisplay the first instance of the tutorial. You only need to change the word TUTOR, not SHAREMEM.


 * Next in the resource file is the accelerator table. If you use tildes (~) to indicate where you want accelerators on your buttons, you must identify them in the accelerator table. There should be an entry for each section button.
 * The last part of the resource file is the dialog template for the index dialog. This should not be modified.

Artwork
All artwork in the tutorial is produced as OS/2 bitmaps, and can be 256 or 16 colors. The default is 256, but if a 16-color bitmap is provided, and the user has a 16-color system, the 16-color bitmap will be displayed. To specify the 16-color artwork, add 1000 to the panel number in the resource file.

Artwork should be a very specific size - 285 x 312 with a three-pixel border at the top and bottom. The title screen is the exception; it should be 632 x 312 with a three-pixel white border around the entire image. We have also introduced a one-pixel gray border inside of the white border of all images.

IPF File - TUTORIAL.IPF
The IPF file provides the text for the right-hand window in the tutorial. To specify which tutorial panel an IPF panel is associated with, use the res= attribute and specify the panel identifier. In general, this panel uses standard IPF tagging. There are only a few exceptions to this: :link reftype=inform res=201.Link to Section 2 Panel 1:elink.
 * Links in IPF panels should not be listed as reftype=hdref. They should be reftype=inform so the tutorial can update the rest of the screen. For example:
 * Reset the margin to 1 at the beginning of each panel (to overcome a formatting problem in IPF).

Also, notice that there are very specific dimensions for all the IPF pages. These should not be changed.

You can also provide a help panel that is displayed when the user presses the F1 key. This panel can be identified to the Framework using the API tutQueryDefaultHelp. More information on this is provided below in the section on the C file.

C File - TUTUSER.C
The Tutorial Framework provides one C file that contains all the code you will need to modify. You must make some changes to this file, particularly to identify the help file and the default help panel. The following APIs are provided: tutOpenObject("");
 * VOID _tutBeginDoIt(USHORT usCurPanel) provides the ability to perform a function when the user clicks on the "Do It!" button. For instance, you might open an object. You should provide an entry in the switch statement for each panel for which you provide a "Do It!" option.
 * VOID _tutEndDoIt(USHORT usCurPanel) provides the ability to perform a function when the user returns from the "Do It!" function. This is where you can provide cleanup, such as closing objects or applications. Note that it is not necessary to provide this function for every panel. To implement this, you should provide an entry in the switch statement for each panel for which you want to close an application or object after returning from a "Do It!" option.
 * VOID _tutBeginPractice(USHORT usCurPanel) provides the ability to perform a function when the user clicks on the "Practice" button. For instance, you might open an object. You do not have to provide an entry in the switch statement for each panel for which you provide a "Practice" option if the item that is needed to practice is already available.
 * VOID _tutEndPractice(USHORT usCurPanel) provides the ability to perform a function when the user returns from the "Practice" function. This is where you can provide cleanup, such as closing objects or applications. Note that it is not necessary to provide this function for every panel. To implement this, you should provide an entry in the switch statement for each panel for which you want to close an application or object after returning from a "Practice" option.
 * BOOL _tutDoIt(VOID) lets you remove the "Do It!" option from the tutorial. If you don't want to provide a "Do It!" option, return FALSE from this function. Otherwise return TRUE.
 * BOOL _tutPractice(VOID) lets you remove the "Practice" option from the tutorial. If you don't want to provide a "Practice" option, return FALSE from this function. Otherwise return TRUE.
 * ULONG _tutQueryIntroPanel(ULONG ulSecondPanel) lets you specify which panel is the introduction to the tutorial. This panel will not be indented in the Index. If you don't want to have an introduction panel, return 0. If you are going to have multiple introduction panels, return 0 and specify a section name in your .RC file for "Introduction." The default is to return the panel that is passed in (that is, the second panel).
 * ULONG _tutQueryCongratPanel(ULONG ulLastPanel) lets you specify which panel is the "Congratulations" panel. This panel will not be indented in the Index. If you don't want to have a "Congratulations" panel, return 0. The default is to return the panel that is passed in (that is, the last panel).
 * ULONG _tutQueryTitlePanel(ULONG ulFirstPanel) lets you specify which panel is the title panel. It is not recommended that you change this, as unexpected results can occur.
 * ULONG _tutQueryMouseOverPanel(ULONG ulSecondPanel) identifies which panel you want to have the ability to display help for items when the mouse is passed over them. This is generally the same as the introduction panel. If you don't want to provide this feature, return 0. The default is to use the second panel.
 * ULONG _tutQuerySectionButtonHeight(ULONG ulDefaultHeight) lets you change the height of the section buttons. This is particularly useful if you need to provide two-line buttons. Just return a new value you want to be the height. The default height is 23.
 * ULONG _tutQuerySpacing(ULONG ulDefaultSpacing) lets you change the spacing between items in the tutorial. The default is 3. To change this, return a different value. However, changing to a large value can have unexpected results. Also, if you change this value, you should change the margins in your artwork accordingly.
 * ULONG _tutQueryDefaultHelp(VOID) provides a default help panel in the tutorial, which is displayed when the user presses the F1 key. Return the resid of the panel in your .HLP file.
 * PSZ _tutQueryHelpFile(VOID) identifies the help file for your application. Return a string that is the name of the help file.
 * VOID tutOpenObject(PSZ pszObjectID) is provided as a service for you. You can call it with an object ID and it will open that object for you. For example, to open the OS/2 System folder, use the following:

Conclusion
Using the Tutorial Framework allows you to create tutorials consistent with the OS/2 Warp tutorial, and lets you take advantage of the new look and feel with very little programming effort.