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)
Set the current row and column:
Set the current cell as text:
Read it back as a number:
W.F1.number 23.2 1 + W.F1.number 24.2
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
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:
(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;
∇EVTCLICK;⎕IO  ⎕IO←1  'The user clicked in row ',(⍕⎕WARG),' column ',⍕⎕WARG ∇
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.
Copyright © 1996-2010 MicroAPL Ltd