Bind a callback subroutine to an ActiveX event
|
WSupported on Windows
|
|
|
|
xcall AX_BIND(id, callback_event[, function])
or
return = %AX_BIND(id, callback_event[, function])
Return value
return
Always returns 1. (i)
Arguments
id
The ActiveX control ID returned by an %AX_LOAD call or the ActiveX container ID returned by an %AX_CREATE call. (D_HANDLE)
callback_event
A string that contains the name of a callback event for the ActiveX control if id is a control ID. If id is a container ID, one of the following events: (a)
The window has focus; keyboard events go to the window. (Note that a container rarely receives focus.)
The window lost focus.
The window was clicked.
The window was double-clicked.
The window was resized.
The window’s visible flag was set so the window is no longer hidden.
The window was hidden.
The window was closed.
The window was rendered useless and is no longer available.
A component of the window has focus, which has activated the window.
No component of the window has focus.
The origin (upper-left cell) of an ActiveX list was changed.
function
(optional) A string that contains the name of the function to call when the event occurs. (a)
Discussion
Once a callback routine has been bound to an ActiveX event, that routine is called whenever the associated event occurs within the control. In other words, %AX_BIND establishes a Synergy DBL routine as the supporting method for an ActiveX event. A callback routine should not perform any extended processing or processing that requires user input. Doing so may cause the application to lock up. For instance, rather than calling a Toolkit input routine within the callback, you should use M_SIGNAL to transfer the event to the outer input loop.
Be aware that when an OnFocus event is triggered while you’re debugging an OnFocus event method, the debug window receives focus.
|
If you’re familiar with Windows programming, don’t confuse a Windows event with an ActiveX event. A Windows event is directly associated with low-level windows “message traffic,” whereas an ActiveX event is entirely defined by a control’s designer. Confusion can arise because ActiveX events that are driven by and have the same name as Windows events are often created. (OnClick and OnClose are common examples.) |
The OnClick and OnDblClick events pass a VT_I4 bit flag argument that indicates which mouse button and what other keys are present. The OnResize event passes a VT_I4 flag that indicates what kind of resizing occurred. The activex.def file contains definitions for these button and resize flags.
The OnClose and OnDestroy events always occur as a pair. OnClose always occurs first.
The OnOriginChange event is for ActiveX lists only. See List Routines for details.
Whether or not the return value for the specified function is used depends on what return value (if any) is expected by the ActiveX control. If the function argument is not passed, the bind is cleared.
We recommend that you XCALL AX_BIND instead of accessing it as a function.
Note that you can also bind a routine automatically by specifying the autobind_prefix argument to %AX_CREATE or %AX_LOAD.
Examples
See Sample program.
