## Using OCX/ActiveX Controls

An OCX or ActiveX control is an external control which you can place on one of your APLX windows. There are many such controls available from Microsoft and from third-party software vendors. Examples include controls for drawing graphs, spreadsheet controls, document viewers, calendar controls, etc.

The use of an ActiveX/OCX control is best illustrated by an example. Suppose you want to use the Formula One spreadsheet control from Visual Components, Inc. You must first create a window, and then place the control on it. The class name of the control is one of the names returned by the `xclasses` property (or you can use the Control Browser window). For Formula One, we can use the programmatic ID `'VCF1.VCF1Ctrl.1'`:

          W„'Ś' ŚNEW 'Window'
          W.F1.New 'VCF1.VCF1Ctrl.1' Ş W.F1.align„ Ż1

At this point, we have created a window and the control, ready for use but currently without any data:

Now we can see what properties and methods the external control exposes:

          W.F1.properties
     align anchors autodraw caption children class color data doublebuffered dragsou
          rce droptarget enabled events handle methods name opened order pointer pro
          perties scale self size sourceformats tabstop targetformats tie verbs visi
          ble where winptr xAllowArrows xAllowAutoFill xAllowDelete xAllowDesigner x
          AllowEditHeaders xAllowFillRange xAllowFormulas xAllowInCellEditing xAllow
          MoveRange xAllowObjSelections xAllowResize xAllowSelections ... etc etc

          W.F1.methods
     Click Close Delete Doverb Draw Focus Hide New Open Paint Resize Send Set Show S
          howaboutbox Showproperties Trigger XAboutBox XAddColPageBreak XAddPageBrea
          k XAddRowPageBreak XAddSelection XAttach XAttachToSS XAutoFillItemsCount X
          CalculationDlg XCancelEdit XCheckRecalc XClearClipboard XClearRange XColor
          PaletteDlg XColWidthDlg XCopyAll XCopyRange XCopyRangeEx ... etc etc

There are many more which we have not shown for brevity. The first few are standard APLX properties/methods, and then those beginning with 'x' are defined by the Formula One control. The APLX Control Browser gives you more details:

You can also look at the Formula One help file for full documentation.

### Using external Properties and Methods

You can use the properties, and call methods, just as you would for built-in APLX controls:

Read the current row (Note: You can use 'row' or 'xrow' as the property name)

          W.F1.row
    1

Set the current row and column:

          W.F1.row„2
          W.F1.col„3

Set the current cell as text:

          W.F1.text„'23.2'

Read it back as a number:

          W.F1.number
    23.2
         1 + W.F1.number
    24.2

### Array properties

Some external controls use 'Array Properties', which are collections of properties indexed by one or more parameters (usually but not always integers). APLX uses a special syntax for these. See the separate description of Array Properties for details.

### Responding to external Events

Many ActiveX/OCX controls trigger events, just like those associated with APLX built-in controls. You can cause APLX functions to be called when an event occurs, by setting the associated 'on..' property of the control. The names of the events are those defined by the control, with a leading 'X'. Thus, if the OCX control has an event called 'Recalculate', you assign your event handling function to the property `onXRecalculate`. (You can omit the 'X' if the name does not clash with an APLX built-in name). You can find out the names of the events in the usual way:

          W.F1.events
     onClick onClose onDblClick onDestroy onDragDrop onDragEnd onDragEnter onDragLea
          ve onDragOver onDragStart onFocus onHide onKeyDown onKeyPress onKeyUp onMo
          useDown onMouseMove onMouseUp onOpen onSend onShow onUnFocus onXCancelEdit
           onXClick onXDblClick onXEndEdit onXEndRecalc onXKeyDown onXKeyPress onXKe
          yUp onXModified onXMouseDown onXMouseMove onXMouseUp onXObjClick onXObjDbl
          Click onXObjGotFocus onXObjLostFocus onXObjValueChanged onXRClick onXRDblC
          lick onXSelChange onXStartEdit onXStartRecalc onXTopLeftChanged onXValidat
          ionFailed

(Again the first few of these are the standard APLX events; the external control events begin with 'onX'). The Control Browser gives more information on parameters and data types.

Any parameters to the callback function can be retrieved using the ŚWARG system function.

For example, the Formula One spreadsheet-control allows you to specify a callback, to be triggered when the user clicks in a cell. The event name is `onXClick`, and the parameters are defined as:

`void Click (long nRow, long nCol);`

This means that it passes two integer parameters, which are the row and column of the cell in which the user has clicked.

You can associate an APL function with this event as follows:

          W.F1.onXClick„'EVTCLICK'

(Note that in this case we must use the full name `onXClick`, because there is also an APLX built-in event called `onClick`).

In your APLX callback function you can retrieve the event parameters; ŚWARG will return a two-element vector with the row and column values:

          ’EVTCLICK;ŚIO
    [1]   ŚIO„1
    [2]   'The user clicked in row ',(•ŚWARG[1]),' column ',•ŚWARG[2]
          ’

### Additional methods for OCX/ActiveX controls

There are some specific built-in APLX methods which apply to OCX controls. These are:

`Showproperties`: (No arguments). Displays the control's properties dialog, if there is one, allowing the user to set specific properties (for example, a charting control may allow the user to select the type of chart). It returns a boolean scalar 1 if the user pressed OK, or 0 if the user pressed Cancel.

`Showaboutbox`: (No arguments). Displays the control's About Box, typically giving copyright and version information.

See also the `verbs` property and the `Doverb` method.

Topic: APLX Help : System Classes : OCX/ActiveX Controls and OLE Automation : Using OCX/ActiveX Controls

[ Previous | Next | Contents | Index ]