AX_WANTSKEY
Register keys to an ActiveX control
WTSupported in traditional Synergy on Windows
|
|
|
|
xcall AX_WANTSKEY(tk_container_id, key_code, mapping_flag[, key_code, & mapping_flag, ...])
Arguments
tk_container_id
The ID of the UI Toolkit ActiveX container window. (n)
key_code
The Toolkit key code for the desired key (defined in inpctl.def) or one of the following: (n)
All key codes (CTRL_A_KEY through CTL_SHFTTAB)
All keys that are currently mapped to shortcuts
mapping_flag
One of the following values (defined in tools.def): (n)
Map as a control accelerator, then menu accelerator, then keystroke. (default)
Map only as a keystroke.
Map as a control accelerator, then keystroke.
Map only as a menu accelerator (shortcut).
Discussion
AX_WANTSKEY allows function and control keys to be passed to the ActiveX control instead of being interpreted by Toolkit. (On UNIX and OpenVMS, this routine is ignored.)
The special key_code values enable you to allow only certain keys to be processed as shortcuts.
When a function or control key is pressed while in AX_INPUT, the default processing of that keystroke is as follows:
- If the key is mapped as an accelerator by the focused control or any of its containers, the key will be mapped accordingly.
- Otherwise, if the key is available to Toolkit as a shortcut, it will be mapped accordingly, whether or not that shortcut is currently active.
- Finally, if the key is neither an accelerator for the control nor an available Toolkit shortcut key, it is translated as a keystroke and passed to the focused control.
AX_WANTSKEY allows this behavior to be overridden in one of three ways for any control or function key when processing a specific ActiveX container window. (The mapping flag D_MAP_DEFAULT specifies the default processing and is only needed to reset a previously specified mapping flag for that key.)
- If a key is designated with a D_MAP_KEY mapping flag, neither the control’s accelerators nor UI Toolkit’s shortcuts will be mapped from this key. Rather, the key will immediately be interpreted as a keystroke and passed to the focused control. This option is useful with Delphi controls that typically respond to keystrokes using an OnKeyDown or OnKeyPress event.
- If a key is designated with a D_MAP_CONTROL mapping flag, the processing is the same as D_MAP_DEFAULT except that UI Toolkit’s shortcut mapping is skipped. The key will only be used by the control as either an accelerator (if the control defines it as such) or as a keystroke. This option is useful when you know that the control needs to see the key, but you do not know whether it defines it as an accelerator or a keystroke. Visual Basic controls often fall into this category.
- If a key is designated with a D_MAP_MENU mapping flag, the control will not see the keystroke at all, and the key will be mapped as a UI Toolkit shortcut. This option is useful if you want to override a key that is used by the control to signal a menu entry instead.
The following table illustrates the types of key mapping that may occur for each option. Where more than one type of mapping is shown, the leftmost marked column has priority.
Option |
Control |
UI Toolkit shortcut |
Keystroke to control |
---|---|---|---|
D_MAP_DEFAULT |
|
|
|
D_MAP_KEY |
|
|
|
D_MAP_CONTROL |
|
|
|
D_MAP_MENU |
|
|
|
Because all key codes that can be passed to AX_WANTSKEY are available to Toolkit as shortcuts, a key will never be seen as a keystroke to the control when shortcut mapping is enabled for the key.
The application used to create the ActiveX control can affect whether or not you need to use AX_WANTSKEY. For instance, controls written using Visual Basic rarely need to use AX_WANTSKEY, because keystrokes like tab, shift+tab, and esc are already mapped as accelerators. However, controls written using Delphi usually require you to use AX_WANTSKEY, because Delphi doesn’t automatically translate keystrokes. Unless you developed the control, you won’t know if it is handling the keystrokes or not. Therefore, we recommend that at first you try not using AX_WANTSKEY. If a keystroke doesn’t get through to the control, you can add the key using AX_WANTSKEY. |
See also
Examples
The default mapping works for most controls, but a more robust setting can be established by calling the following statement after you have placed and enabled all desired menu shortcuts:
xcall ax_wantskey(tk_container_id, D_KEY_ALL, D_MAP_CONTROL, D_KEY_MENU, D_MAP_MENU)
This statement first designates that all keys belong to the control (either as an accelerator or as a keystroke), and then it maps all enabled menu shortcuts to Toolkit. Therefore, if the key corresponds to an enabled menu shortcut it will be interpreted as such. Otherwise, it is left to the control to interpret.
Also see the Examples for AX_INPUT.