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.