| 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, 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 CLEAR-CALLOUT-PARAMETERS $NULL CALLOUT-PARAMETER 1 FUNCTION-DATA $NULL CALLOUT-PARAMETER 2 TBAR-PARMS $NULL CALLOUT "TBAR2" 0 $PARMLIST
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 and close the screenset.
Look at the data structure defined in tbar2defn.cpy as an example of how to create your own menu. To do this, right-click tbar2.cbl in the left-hand pane, and select Edit. Select the NetExpress Search, Locate Definition menu choice to locate the data item "mData".
The mData table structure defines the content and structure (hierachy) of the menu. An example of a single menu record, File, is shown below:
01 mData.
78 mDataStart value NEXT.
***>>> Start USER MENU DATA <<<***
*>----------------------------------------------------------------
* Menu item object reference.
03 object reference.
* Type of menu item.
03 pic x comp-5 value typeHasChildren.
* Accelerator key definition (see keys.cpy for details).
03 pic x(4) comp-5 value noAcceleratorKeyDefined.
* Name of callback to be invoked when menu item selected.
03 pic x(mCallbackSize) value SPACES.
* Null terminated menu text followed by optional null
* terminated menu hint text.
* The whole string must also be terminated by a further null.
03 pic x(mStringSize) value z"&File" & x"00".
*>----------------------------------------------------------------
03 object reference.
03 pic x comp-5 value typeLastSibling.
03 pic x comp-5 value KS-Virtual-Key.
03 pic x comp-5 value OVK-F3.
03 pic xx.
*> The entry point called when menu/toolbutton selected. Keep this
*> the same for all choices - see the On-Item-Selected SECTION of this program
03 pic x(mCallbackSize) value '"'&ProgramID & 'OnItemSelected"'.
03 pic x(mStringSize) value z"E&xit" &
z"Quit this application" & x"00".
*>----------------------------------------------------------------
Each element of the table defines an item in the menu structure and is made up of five parts:
The first menu record details the first menu item to be added to the window. The first menu item must be one of the following:
Each time a sub menu is added, all the subsequent menu item records are added to that sub menu until one of the following types of item is encountered:
In the case of the first two types listed above, subsequent items are added to the parent sub menu or window. In the case of the last two types listed above, subsequent items are added to a new sub menu.
This can be explained briefly as follows:
As an example, we will add two new menu options, Edit and Options. Edit will have one menu item, Select all. Options will have a menu item, Customize, which will open a submenu containing Fonts.
To change the menu defined in tbar2defn.cpy, use the existing menu records as an example to change the menu structure.
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 tbar2defn.cpy as an example of how to create your own toolbar. To do this, from within tbar2.cbl, select the NetExpress Search, Locate Definition menu choice to locate the data item "mData".
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:
01 bData. 78 bDataStart value NEXT. *>---------------------------------------------------------------- * 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:
As an example, we will add two new toolbar buttons for Select All and Fonts.
To change the toolbar defined in tbar2defn.cpy, 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 menu and toolbar structure in tbar2defn.cpy which provides a menu item and associated toolbar button. This file contains data structures that define how the menu and toolbar will look and respond to events.
The first half of the copyfile defines the menu. Each toolbar button has an associated menu item, so we will look at how to define the menu first.
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) 2 @EXIT IF= NUMERIC-VALUE(1) 4 SELECT-ALL IF= NUMERIC-VALUE(1) 7 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.
Note: The example uses only part of the datablock (the FUNCTION-DATA and TBAR-PARMS group records) to call the toolbar controlling program. If you need additional data in the callback processing, you should adapt the callout and the toolbar program to use the whole data block. The use of the groups mentioned above can then continue unchanged.
Save the screenset, switch to the NetExpress 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 © 1998 Micro Focus 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 | |