PreviousData Access Multiple ScreensetsNext

Chapter 10: Programming Your Own Controls

In this chapter you see how to tailor User and ActiveX Controls to use with your Dialog System application. The topics covered are:

10.1 Control Programs

Using a control program, any object can be manipulated using programmed functions appropriate to that object. You can perform actions on that control such as refreshing, deleting or updating data associated with the control:

Dialog System provides programs that enable you to include the following controls in your application:

The source code for each control is designed to be as generic as possible. You can tailor and re-use the code with the minimum of changes. The extent to which this is possible, however, varies according to the control itself.

The control programs are implemented using calls to the Net Express class libraries.

10.1.1 Control Implementation Architecture

The following diagram illustrates the architecture used to implement controls using Dialog System and the class libraries.

User control process

Figure 10-1: Controls Implementation Architecture

When you create an ActiveX or user control:

  1. You paint a control on a window in your screenset and associate a master field and program name with that control.

  2. An application program calls dsgrun and supplies a screenset in the normal manner.

  3. When Dialog System creates a window on which an ActiveX or user control is defined, an entry point in the program associated with the user control is called.

  4. The entry point code performs all the tasks necessary to enable the class library to create the window object.

    As part of the control creation process, code exists in the generated control programs to enable the registration of callbacks for events in which the program is interested. This associates program entry points with the occurrence of defined system events.

  5. When the defined system event occurs, it causes the specified entry point code to be executed.

  6. The entry point code performs all the required processing, including updating the Data Block.

  7. The entry point code passes a message back to the Panels V2 program. This is received as a USER-EVENT in the Dialog System screenset, so that any additional dialog processing can be performed.

  8. The control can be manipulated through a CALLOUT to the user control program or directly by the class library through the Dialog System INVOKE function.

10.2 ActiveX Controls

As you saw in the chapter Control Objects, ActiveX Controls are supplied by third-party vendors and can be integrated into Dialog System. When you use an ActiveX Control in your interface, you need to customize it to suit your own requirements.

10.2.1 ActiveX Control Properties

There are three types of ActiveX design-time properties:

In many cases, the default properties will not suit your application. For example, the default properties for a spreadsheet ActiveX Control may only have two columns and two rows. On the other hand, some ActiveX Controls, such as the Dialog System clock ActiveX Control, has mainly acceptable defaults.

You should refer to the documentation for the ActiveX Control to determine the properties that you need to set. The changed property data is stored in your screenset.

10.2.2 Tailoring Your ActiveX Control

The steps that you need to take to tailor your ActiveX Control are:

10.2.2.1 Selecting an ActiveX Control

To specify the ActiveX Control directly from Dialog System's menu:

  1. Select Import on the File menu.

  2. Select ActiveX Control on the sub-pulldown menu.

  3. Select your required ActiveX Control from the list box showing the ActiveX Controls which are registered on your system.

    An icon representing this control appears on the ActiveX toolbar. You can select this ActiveX Control directly from the ActiveX toolbar whenever you need to re-use it.

  4. Ensure that your Data Block has an item defined as OBJ-REF with which the ActiveX Control is to be associated.

  5. Position and size the ActiveX Control.

    The ActiveX Control Properties dialog box is automatically shown as in Figure  10-2.

    ActiveX Properties

    Figure 10-2: ActiveX Control Properties Dialog Box

10.2.2.2 Defining the ActiveX Control Properties

In the ActiveX Control Properties dialog box:

  1. Specify the Data Block Master Field OBJ-REF name for this control.

  2. Specify the name for the control program.

  3. Ensure your Net Express project is open and available in the Net Express IDE.

  4. Select Add program to current project.

  5. Click Generate to generate a COBOL source program which is automatically tailored to the control you are using and added to the open project.

    This will be the controlling program for the ActiveX control in your screenset.

  6. Click OK.

10.2.2.3 Customizing the ActiveX Control Program with the Programming Assistant

An example of a customized ActiveX Control program is located in the folder Net Express\DialogSystem\Demo\Activex\Custgrid. The file custgrid.txt describes how to run the demonstration.

Customizing a control program to work with your ActiveX Control involves:

To tailor your ActiveX Control you need to explore the methods, properties and events that your ActiveX Control supports. The Programming Assistant simplifies this task by providing a visual environment from which you can extract the pre-defined functions that your program requires. It provides you with code to:

10.2.2.4 Starting the Programming Assistant

To access the Programming Assistant:

  1. Right-click in the ActiveX control.

  2. Select Programming Assistant... on the context menu.

    The ActiveX Programming Assistant dialog box is shown in Figure 10-3.

Prog Assist dialog

Figure 10-3: ActiveX Programming Assistant Dialog Box

There are two tab pages available in this dialog box, enabling you to insert the code relating to methods and properties or events directly into your open COBOL program.

10.2.2.4.1 Methods and Properties

Selecting the Methods/Properties tab displays the screen shown above in Figure 10-3.

The left-hand pane displays the ActiveX control and exposes its run-time object hierarchy. The right-hand pane displays the methods and properties that this control provides.

When you select a Method or Property in the right-hand pane, the associated COBOL code appears in the pane in the lower part of the dialog box.

To insert this code into the program which creates the ActiveX at run time:

  1. Open the program in the Net Express IDE.

  2. Place the cursor at the required position in this program for the new code.

    There is no clearly commented place to insert this code, as methods and properties insertions depend entirely on your program logic. The code can be used in the context of control initialization, event callback or simple run-time manipulation.

  3. Return to the Programming Assistant window.

  4. Click on Insert Code.

    The created code contains all required parameters and return values needed for the function you selected.

10.2.2.4.2 Sub-objects

ActiveX Controls can have associated sub-objects, each of which has its own methods and properties which can be viewed or edited. To see these, click on the + sign connected with the ActiveX Control in the left-hand pane.

Sub-objects generally do not have related events. These are globally handled in the ActiveX Control.

10.2.2.4.3 Events

Selecting the Events tab displays the screen in Figure 10-4.

Prog Assist dialog - events

Figure 10-4: ActiveX Programming Assistant Dialog Box - Events

The upper part of the dialog box shows a list of event names. Next to each event name there may be parameters which are passed by the event to the ActiveX controlling program.

As with the methods and properties view, the lower pane displays the code associated with the event selected in the upper pane. The radio buttons' functions are described below.

10.2.2.4.4 Variables

When the Variable Definitions button is selected, you can see the variables connected with the event selected in the upper pane. These variables:

10.2.2.4.5 Event Registration

Selecting the Register button displays the code which your controlling program needs in order to register a callback for the selected event. Registering an event callback performs two tasks:

The generated name of the entry point is Program ID+On+event name. For example, if the event name is BeforeDeleteRow the generated entry point name would be Program IDOnBeforeDeleteRow.


Note: The generated entry point name is prefixed by the program ID to ensure the uniqueness of the entry point across different control programs. For example, you may have the same event name in different ActiveX controls. Without the program ID attached to the entry point, the OLE class library would not know which control program to call.


You need to insert this code in the Register-Callbacks section of your controlling program which is executed on creation of the control.

10.2.2.4.6 Event Handler

When you select the Handler Code button:

You insert the event handling code at the comment

*Add your event handler code here.

Sample code is available in the generated control program.

To insert this code:

  1. Open the program in the Net Express IDE.

  2. Click on the insertion position in this program for the new code.

    There is a clearly commented place to insert this code. The code can be used in the context of control initialization, event callback or simple run-time manipulation.

  3. Return to the Programming Assistant window.

  4. Click on Insert Code.

    The created code contains all required parameters and return values needed for the function you selected.

10.2.2.5 Summary

The Programming Assistant for ActiveX controls significantly reduces the ActiveX control familiarisation process, as well as the time taken to produce the code you need.

10.3 User Controls

When you use a User Control in your interface, you need to customize it to suit your own requirements. The steps that you need to take to tailor your User Control are:

10.3.1 Specify the User Control

The User Control object allows you to add a Net Express Class Library GUI object to your screenset.

To create the User Control:

  1. Define a Data Block entry of type OBJ-REF with which the control will be associated.

  2. Select the window where you want to add the User Control.

  3. Select User control on the Object menu, or click User Control on the Objects toolbar.

  4. Position and size the user control.

    The User Control dialog box is shown as in Figure 10-5.

    User control Properties

    Figure 10-5: User Control Dialog System Properties Dialog Box

  5. Complete the following items on the User Control Properties dialog box:

    1. Choose an appropriate name for the user control. Make this as descriptive as possible, for example MAIN-WINDOW-STATUS-BAR.

    2. Specify the relevant OBJ-REF data item as the master field name.

    3. Specify a name for your user control program.

      You should choose a name which is different from any of the Class Programs defined in the Net Express class library. Once you have chosen a new name for the tailored control program, you can start to modify it to provide the functionality that you require.

    4. Select the type of control you require from those available in the drop down list.

    5. Ensure your Net Express project is open and available in the Net Express IDE.

    6. Select Add program to current project.

    7. Click Generate to generate a COBOL source program which is automatically tailored to the control you are using and added to the open project.

      This will be the controlling program for the user control in your screenset.

    8. Click OK.

10.3.2 User Control Types

In all circumstances you will need to import the Data Block definitions listed in the funcdata.imp file found in your DialogSystem\Source directory. Select the Dialog System File/Import/Screenset menu choice and select funcdata.imp for import on the resulting dialog box.

The following sections detail the changes you need to make to successfully use the generated programs with your screenset.

10.3.2.1 Spin Button

No COBOL code changes are required. Simply implement a USER-EVENT dialog event on the parent window of your spin button, to respond to the event posted by the generated program. Your dialog code can then ensure your Data Block master field is updated to the new value passed by the control program.

Example:
USER-EVENT
     XIF=$EVENT-DATA 34580 UPDATE-MASTER
     UPDATE-MASTER
     * The User control program updates the NUMERIC-VALUE
     * field. This code updates the field I want
     MOVE NUMERIC-VALUE(1) MY-NUMERIC-FIELD

10.3.2.2 Status Bar

No COBOL code changes are required. You simply need to implement the following points, which are covered in more detail in the Tutorial chapters later in this book.

This procedure is covered in detail in the chapter Tutorial - Adding and Customizing a Status Bar.

10.3.2.3 Tree View

When using the generated TreeView control program, first import the tviewdata.imp file, to populate the required entries in your screenset Data Block.

To use the TreeView control program, simply populate the ATVIEW-PARMS Data Block group with the data you want to insert into the Created Tree control. See your Help for details.

Callback registration and event handler examples are provided in the generated program. You can adapt them to meet your own needs.

10.3.2.4 Toolbar

When using the generated Toolbar control program, first import the tbardata.imp file, to populate the required entries in your screenset Data Block.

To use the Toolbar control program, adapt the menu and toolbar button definition used by the program: do this by editing one WORKING-STORAGE copyfile that defines the structure to be used.

Next simply write code to respond to menu/ button choice selection by the user, and take whatever action you require, including execution of existing menu choice dialog which is already defined in your screensets.

10.3.2.5 User Defined

When creating the User control object, you can generate a generic skeleton control program, which provides the structure for you to create any control you choose.

10.3.3 Summary

The generated programs you produce will compile and run successfully without change. You can now change the code to perform any additional functions you require in your application, or, as you have seen, you can use the generated code unchanged.

The intention is to produce a full suite of control programs which provide access to all class library controls via the same procedural COBOL interface. This process will be completed in future releases of Dialog System in Net Express.


Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousData Access Multiple ScreensetsNext