AX_BIND

Bind a callback subroutine to an ActiveX event

WTSupported in traditional Synergy 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)

OnFocus

The window has focus; keyboard events go to the window. (Note that a container rarely receives focus.)

OnUnfocus

The window lost focus.

OnClick

The window was clicked.

OnDblClick

The window was double‑clicked.

OnResize

The window was resized.

OnShow

The window’s visible flag was set so the window is no longer hidden.

OnHide

The window was hidden.

OnClose

The window was closed.

OnDestroy

The window was rendered useless and is no longer available.

OnActivate

A component of the window has focus, which has activated the window.

OnDeactivate

No component of the window has focus.

OnOriginChange

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.

Note

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. See %AX_CREATE or %AX_LOAD.

Examples

See Sample program.