| Tutorial - Adding and Customizing a Status Bar | Tutorial - Adding an ActiveX Control | |
This tutorial takes you through adding the menu bar and toolbar control program to the sample Customer screenset supplied with Dialog System. You will notice that many of the steps for adding the menu bar are almost exactly the same as those for adding a status bar, as described in the previous tutorial.
You use the same steps to add a menu bar and toolbar to any window in any screenset. The same principles apply to adding any other control program to a screenset. You will find out how to:
Before starting this tutorial you should have:
The user control objects and control programs are also documented in:
The topic on user controls describes how to create a user control and set its properties.
The topics in this section give detailed information on the control programs and the functions available.
A separate demonstration of using a toolbar control program is provided in the screenset tbards.gs, and is documented in the file tbards.txt in your DialogSystem\demo\tbards subdirectory.
Dialog System starts up and the Customer Details window is displayed.
One of the most important features to note when using class library menus and toolbars is that each toolbar button has an associated menu item. When a toolbar button is selected, a menu event is generated by the class library for its associated menu item. Similarly, when a menu item is enabled, disabled, checked or unchecked, its associated toolbar button is also.
Before using any of the control programs, a common data area must be defined in the screenset Data Block. This is used to pass information between a screenset and the control programs at run time.
Each user control that you define in a screenset must have a Data
Block item (master field) associated with it. The data item must be
defined as OBJ-REF as it is used to hold the class library
object reference of the created control. The data item must be defined
before you add the user control. If you do not have any object references
defined in your screenset, then Dialog System will not let you define a
user control.
Include the following data item in the Data Block of the screenset, to hold the object reference of the menu bar and toolbar:
MYTOOLBAR OBJ-REF
If you have completed the previous chapter, Tutorial - Adding and Customizing a Status Bar, you will not need to include the following data definition for FUNCTION-DATA in the screenset Data Block:
FUNCTION-DATA 1 WINDOW-HANDLE C5 4.0 OBJECT-REFERENCE OBJ-REF CALL-FUNCTION X 30.0 NUMERIC-VALUE C5 4.0 NUMERIC-VALUE2 C5 4.0 SIZE-WIDTH C5 4.0 SIZE-HEIGHT C5 4.0 POSITION-X C5 4.0 POSITION-Y C5 4.0 IO-TEXT-BUFFER X 256.0 IO-TEXT-BUFFER2 X 256.0
because FUNCTION-DATA is common to all the control programs, so you need define it only once in each screenset that uses the control programs.
If you do need to include the FUNCTION-DATA definition, you can import it from the file funcdata.imp in the DialogSystem\source subdirectory. Select File, Import, Screenset and click OK to acknowledge the currently loaded screenset might be overwritten. Click the File button, double-click funcdata.imp, click the Import button and then OK and Close.
Next you need to import the following:
TBAR-PARMS 1
MENU-INDEX 9 2.0
CALLBACK-ENTRY-NAME X 32.0
ACCEL-FLAGS 9 3.0
ACCEL-KEY 9 3.0
MENU-TEXT X 256.0
MENU-HINT-TEXT X 256.0
RESOURCE-FILE X 256.0
RESOURCE-ID 9 5.0
TOOL-TIP-TEXT X 256.0
INSERT-BUTTON-BEFORE 9 2.0
MSG-BOX-TEXT X 256.0
from the file tbardata.imp in the DialogSystem\source subdirectory in the same way as described above.
| MYTOOLBAR | will be used to store the object reference of the created toolbar. This data item will be the masterfield for the toolbar user control defined in the steps below. |
| TBAR-PARMS | is a general purpose group used to pass information about menu items and toolbar buttons to the control program when using the toolbar functions. |
To enable the class library, define CONFIG-FLAG and CONFIG-VALUE as C5 4.0 items in your Data Block, and then add the following dialog to the beginning of the SCREENSET-INITIALIZED event in the global dialog of the screenset:
CLEAR-CALLOUT-PARAMETERS $NULL
CALLOUT-PARAMETER 1 CONFIG-FLAG $NULL
CALLOUT-PARAMETER 2 CONFIG-VALUE $NULL
MOVE 15 CONFIG-FLAG
MOVE 1 CONFIG-VALUE
CALLOUT "dsrtcfg" 3 $PARMLIST
This dialog must be placed before any other dialog in the SCREENSET-INITIALIZED event.
When you have defined the required data, define the user control:
A message box appears, asking you if you want to generate a class library menu structure. Click Yes.
A message box appears, reminding you that you need to include the necessary entries in the Data Block for use by the generated control program. You have done this in the earlier steps, so click OK to continue.
You can see the generated program being added to your Customer project in the background.
Once you have completed all these steps with your screenset, you can run it to see the User Control working.
At this stage, the menu bar and toolbar will not do anything useful.
You need to add dialog for the menu bar and toolbar to work correctly.
TBAR2 is the name of our customized version of the toolbar control program. This will be our controlling program for our menu.
To enable the customized version of the toolbar control to be called, add the following dialog at the end of the screenset's global dialog:
CALLOUT-TBAR CALLOUT "TBAR2" 0 $NULL
If you have not completed the previous chapter, you will need to add a WINDOW-CREATED event in Object Dialog. If you have completed the previous chapter, add the following dialog to the WINDOW-CREATED event:
INVOKE MYTOOLBAR "show" $NULL
Save the screenset.
Select Edit, Menu Bar or the Edit menu bar icon from the toolbar. The Menu Bar Definition dialog box appears.
Because we are going to to use the menu created by the control program, and not the one created by DSGRUN, select Options, and check Use Class Library. This ensures that DSGRUN does not itself create the menu.
As an example, we will add two new menu options, Edit and Options, either side of the existing Orders menu option. Edit will have one menu item, Select all. Options will have a menu item, Customize, which will open a submenu containing Fonts.
You can see that a new menu item, Edit, has been added, with a submenu choice of Edit.
You can see that a new menu item, Options, has been added, with a submenu choice of Options.
You can see that Customize now has a submenu choice of Customize.
A message box appears, asking you if you want to generate a class library menu structure. Click Yes.
A second message box appears, asking you if you want to overwrite the entire toolbar program. Click No so that only the menu definitions are generated, leaving any toolbar changes intact.
A message box appears, reminding you that you need to include the necessary entries in the Data Block for use by the generated control program. You have done this in the earlier steps, so click OK to continue.
You can see the generated program being added to your Customer project in the background.
At this stage, you can see the menu options you have added, but they will not do anything if you select them.
Look at the data structure defined in tbar2.cbl as an example of how to create your own toolbar. To do this, from within tbar2.cbl, select the Net Express Search, Locate Definition menu choice to locate the data item "bData".
The bData table structure defines an ordered list of buttons to be added to the toolbar. Buttons are added to the toolbar in the order in which they appear in the list.
An example of a single button record is shown below:
*>---------------------------------------------------------------- * Button object reference. 03 object reference. * Menu item index to associate button with or zero if this * button is to be a separator. This index refers to an index * within the mData table. 03 pic x comp-5 value 2. *> "Exit" menu item * Resource ID of button bitmap. 03 pic x(4) comp-5 value IDB-EXIT. * Tool tip to be displayed when mouse is over button. 03 pic x(bStringSize) value z"Quit this application". *>----------------------------------------------------------------
Each element of the table defines a button on the toolbar and is made up of four parts:
The default toolbar structure that has been generated contains a separator and a button associated with menu index 2. However, as we have generated a menu structure from the existing Dialog System menu, the index of the File, Exit menu item is in fact 7. Therefore, to associate the second button with the correct menu index, change it from 2 to 7.
As an example, we will add two new toolbar buttons for Select All and Fonts.
To change the toolbar defined in tbar2.cbl, use the existing button records as an example to change the button structure.
You can now see the two buttons you have just created displayed below the menu items in the toolbar.
Again, the toolbar buttons will not do anything if you select them.
In the previous section we added an existing bitmap button from the file tbresid.cpy. In this section, we will create a new button bitmap.
copy "tbresid.cpy"
add in the new bitmaps you have created by entering:
78 IDB-Button1 value 220. 78 IDB-Button2 value 221.
We are going to review the toolbar structure in tbar2.cbl which provides a menu item and associated toolbar button. This file contains data structures that define how the toolbar will look and respond to events.
We will look at how to define the toolbar.
Ensure that the button definition data record contains a reference to an IDB_ resource identifier you defined in the resource file earlier. That is, IDB-Button1 and IDB-Button2.
Save tbar2.cbl and close it.
USER-EVENT
XIF= $EVENT-DATA 37000 @EXISTING-DIALOG-MENU-PROCEDURE
Replace the executed procedure with your own menu dialog table. In this example, we will use TEST-MENU-CHOICE, so enter:
USER-EVENT XIF= $EVENT-DATA 37000 TEST-MENU-CHOICE
And add the following dialog immediately below the above lines:
TEST-MENU-CHOICE IF= NUMERIC-VALUE(1) 7 @EXIT IF= NUMERIC-VALUE(1) 9 SELECT-ALL IF= NUMERIC-VALUE(1) 14 FONTS
At the end of the dialog, add the following lines:
SELECT-ALL BEEP FONTS BEEP BEEP
If you are adding class library menu items to replace existing menu items, you can simply branch to the procedure name (prefixed with the @ symbol) that was previously used to handle the menu event. Alternatively, you could make a COBOL CALL to a subprogram from your toolbar callback code following the class library menu event.
USER-EVENT
XIF= $EVENT-DATA 37000 DIALOG-PROCEDURE
DIALOG-PROCEDURE
* Dialog function processing - perhaps show a message box
As an alternative to the use of dialog functions to handle the class library menu event, your toolbar callback code could simply make a COBOL CALL to an existing program to perform that menu function.
Save the screenset, switch to the Net Express IDE and rebuild the project.
You can now select Animate, Run, to test your screenset. When you select either Select All from the Edit menu, or the toolbar button, the dialog procedure that you coded will be executed. Try this for Fonts, from the Options, Customize menu too.
Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Tutorial - Adding and Customizing a Status Bar | Tutorial - Adding an ActiveX Control | |