Chapter 22: Tutorial - Adding an ActiveX Control

This chapter describes how to add an ActiveX Control to your screenset. You need to have read the chapter Programming Your Own Controls and the previous tutorials before looking at this one.

The following sections take you step by step through changing a screenset to use the supplied clock ActiveX control.

22.1 Screenset Alterations

The aim of this tutorial is to display the supplied ActiveX clock control when you double-click on the time on the status bar. You will be shown how to use an ActiveX control later, but for now we will open customer.gs in NetExpress and define the following objects in the screenset:

A dialog box to hold the ActiveX clock.
A dialog box that will allow the alarm time to be set.
A message box to display a message when the alarm goes off.

Make the dialog box to hold the ActiveX clock about a third of the size of the customer screenset, and place it anywhere.
Name this object CLOCK-DIALOG.
Leave all its properties as default.
Define the parent as being $WINDOW.
Create a message box to display a message when the alarm goes off.
Name this object ALARM-GONE-OFF-MBOX.
Leave all its properties as default.
Define the parent as being $WINDOW.
Add two PIC 9(2) data items, ALARM-HOURS and ALARM-MINUTES, to the Data Block for this screenset.
Make the dialog box that will allow the alarm time to be set about a third of the size of the customer screenset, and place it anywhere.
Name this object SET-ALARM-DIALOG.
Leave all its properties as default.
Define the parent as being $WINDOW.
On the CLOCK-DIALOG dialog box:
- Create a push button with its text set to "Set Alarm".
- Add the following dialog to the Set Alarm button:
```
 BUTTON-SELECTED
     MOVE " " IO-TEXT-BUFFER2(1)
     SET-FOCUS SET-ALARM-DIALOG
```
- Create a push button with its text set to "Close".
- Add the following dialog to the Close button so that it unshows the CLOCK-DIALOG dialog box when it is clicked.
```
 BUTTON-SELECTED
     UNSHOW-WINDOW CLOCK-DIALOG $NULL
```
  Do not delete the CLOCK-DIALOG dialog box, as this will cause the alarm not to function.
On the SET-ALARM-DIALOG:
- Create an entry field to hold the hour of the alarm time.
  Link this to the ALARM-HOURS master field.
- Create an entry field to hold the minutes of the alarm time.
  Link this to the ALARM-MINUTES master field.
- Create an entry field to hold the message to be displayed when the alarm is triggered.
  The master field for this entry field should be IO-TEXT-BUFFER2.
- Create a push button with its text set to "OK". The OK button should have the following dialog:
```
 BUTTON-SELECTED
     BRANCH-TO-PROCEDURE SET-ALARM
```
- Create a push button with its text set to "Cancel". The Cancel button should have the following dialog to enable the SET-ALARM-DIALOG dialog box to be deleted when the user clicks Cancel:
```
 BUTTON-SELECTED
     DELETE-WINDOW SET-ALARM-DIALOG $NULL
```
- Add the following dialog to the SET-ALARM-DIALOG dialog box itself:
```
 CR
     BRANCH-TO-PROCEDURE SET-ALARM

 ESC
     DELETE-WINDOW SET-ALARM-DIALOG $NULL

   SET-ALARM
* Dialog will be added here later.
```

Having completed these steps, you can add the dialog to use the left-mouse-button-double-click event that you added in the earlier tutorial to display the CLOCK-DIALOG dialog box. See the section Customizing the Status Bar Control Program in the chapter Tutorial - Adding and Customizing a Status Bar.

In the left-mouse-button-double-click event callback, you added code to send user event 34591 when the callback was triggered. The code you added also places the section number of the status bar on which the double-click event happened into the NUMERIC-VALUE(1) data item.

With this information, you can add the following to the MAIN-WINDOW dialog table to process the double-click user event:

 USER-EVENT
     XIF= $EVENT-DATA 34591 DOUBLE-CLICK-EVENT

   DOUBLE-CLICK-EVENT
     IF= NUMERIC-VALUE(1) 5 DOUBLE-CLICK-ON-CLOCK

   DOUBLE-CLICK-ON-CLOCK
     SET-FOCUS CLOCK-DIALOG

This dialog causes the CLOCK-DIALOG dialog box to be shown if the MAIN-WINDOW window receives user event number 34591, and NUMERIC-VALUE(1) is set to 5 (the 5th section of the status bar contains the clock).

22.2 Using the Dialog System Clock ActiveX Control

A separate demonstration of applying this functionality is provided in the clock.gs screenset and documented in the file clockds.txt

If you have followed the tutorial, you will have created a CLOCK-DIALOG dialog box in your screenset. You can now add the supplied Dialog System clock ActiveX control to this dialog box.

Add the following data definitions to your screenset:

CLOCK-DIALOG-ACTIVEX-OBJREF          OBJ-REF
ACTIVEX-PARAMETERS                         1              
  PARM-NAME                      X     30.0           
  P1                             C5     4.0           
  P2                             C5     4.0           
  P3                             OBJ-REF

You must make sure that the last four items are indented, to show they are group items.

The first data item listed is used to store the object reference of the ActiveX . The master field group specified is used as the second parameter when calling the ActiveX control program.

The next step is to position the ActiveX control on the CLOCK-DIALOG dialog box:

Select File, Import, ActiveX control....
Select Dialog System Clock.
The control is added to the ActiveX toolbar, from where you can select it and place it on the status bar of the customer screenset.

The ActiveX Control Properties dialog box opens when you position the ActiveX control.
Specify a name for the ActiveX control, set the master field to be CLOCK-DIALOG-ACTIVEX-OBJREF, and set the program name to be CLOCKCTRL.
Click Generate to generate the ActiveX control program.
Click OK.
You now need to set the properties for the ActiveX control. Each ActiveX control has tailorable properties which determine the run-time behavior of that control.
When the control has been painted, a Property List dialog box is displayed. This shows some (not always all) of the configurable properties that the control provides. You can change the values in either this list or use the Controls context menu to view the full list of properties via the ActiveX property page context menu choice.

In the case of the Dialog System clock ActiveX, the available properties are the background bitmap, and whether the clock displays as analog or digital.

Note: The export facility of Dialog System does not export ActiveX properties. This means that if you export and import an ActiveX user control, you will have to re-set the properties. This also applies to duplicating ActiveX user control objects by holding down the control key while dragging the object, and copying and pasting ActiveX user controls.

You need to add the dialog to handle the user event that indicates that the alarm time has been reached. Add the following to the CLOCK-DIALOG dialog box:

 USER-EVENT
     IF= $EVENT-DATA 34570 ALARMGONEOFF

   ALARMGONEOFF
     INVOKE-MESSAGE-BOX ALARM-GONE-OFF-MBOX IO-TEXT-BUFFER2(1) $REGISTER

Finally, you need to complete the SET-ALARM procedure that you added to the dialog for the SET-ALARM-DIALOG dialog box earlier. This procedure invokes the SetAlarm method in the ActiveX control to set the alarm. Add the following dialog below SET-ALARM:

     SET-MOUSE-SHAPE SET-ALARM-DIALOG "SYS-WAIT"
     MOVE ALARM-HOURS P1(1)
     MOVE ALARM-MINUTES P2(1)

     NULL-TERMINATE IO-TEXT-BUFFER2(1)
     CLEAR-CALLOUT-PARAMETERS $NULL
     CALLOUT-PARAMETER 1 IO-TEXT-BUFFER2(1) $null
     CALLOUT-PARAMETER 8 P3(1) $NULL
     INVOKE "chararry" "withValue" $PARMLIST

This dialog demonstrates the passing of the Message text (in IO-TEXT-BUFFER2(1)) as an object reference to a CharacterArray instance. Note the use of the functions NULL-TERMINATE and INVOKE for the P3(1) variable. These functions are described in detail in the Help. Add the following dialog:

 MOVE "INVOKE-ActiveX-METHOD" CALL-FUNCTION(1)
     SET OBJECT-REFERENCE(1) CLOCK-DIALOG-ActiveX-OBJREF
     MOVE "SetAlarm" PARM-NAME(1)

     CLEAR-CALLOUT-PARAMETERS $NULL
     CALLOUT-PARAMETER 1 FUNCTION-DATA $NULL
     CALLOUT-PARAMETER 2 ActiveX-PARAMETERS $NULL
     CALLOUT "ocxctrl" 0 $PARMLIST

     CLEAR-CALLOUT-PARAMETERS $NULL
     CALLOUT-PARAMETER 8 P3(1) $NULL
     INVOKE P3(1) "finalize" $PARMLIST

     DELETE-WINDOW SET-ALARM-DIALOG $NULL

You have now completed adding the Dialog System clock ActiveX control to your screenset. Save your screenset and run it to try out the changes you have made.