AX_INPUT

Perform input to an ActiveX control

xcall AX_INPUT(tk_container_id, [help_id], [wait_time][, menu_flag])

Arguments

tk_container_id

The ID of the Toolkit ActiveX container window. (n)

help_id

(optional) A help identifier that will be passed if the menu entry “O_HELP” is signaled or selected. (a)

wait_time

(optional) The time-out limit for I/O processing to be completed before returning to the calling routine. This setting overrides any AX_TIMEOUT setting. (n)

D_FOREVER or -1

Never time out.

D_GLOBAL or -2

Use the global value (see g_wait_time). (default)

D_IMMEDIATE or 0

Time out immediately.

Wait up to n seconds (where n is a positive value) for the user to press a key.

menu_flag

(optional) If passed and true, a flag that causes AX_INPUT to return utility menu entries (U_ and O_HELP) instead of processing them. (n)

Discussion

AX_INPUT should be used instead of UI Toolkit’s I_INPUT routine whenever you want to do input to an ActiveX control while Toolkit is running. AX_INPUT enables you to focus the component and allow the user to perform input on it, while at the same time allowing menu entries to be selected and returned from the Toolkit. (On UNIX, this subroutine calls M_PROCESS. On OpenVMS, it is ignored.)

The specified Toolkit ActiveX container window is activated and used to determine which keys get passed through to ActiveX controls. Before calling AX_INPUT, the client routine should establish focus on the correct control by setting the “Ext_Focus” property of the desired control.

AX_INPUT recognizes the following reserved menu entries, which are documented in Appendix B: Reserved Menu Entries:

E_CLEAR

E_COPY

E_CUT

E_MARK

E_PASTE

Unless menu_flag is passed as true, the help method for the current environment will be invoked if the “O_HELP” menu entry is signaled or selected, and if a “U_” menu entry is signaled or selected, EUTILS_METHOD for the current environment will be invoked. If menu_flag is passed as true, AX_INPUT returns these menu entries instead of processing them.

Note that when an ActiveX control is part of a composite window, tab and shift+tab may not move focus to the next or previous child if the ActiveX control consumes these as accelerators. If this is the case, you can work around this by signaling “C_NEXT” or “C_PREV”. For information, see Controlling tabbing, focus, and input context.

When AX_INPUT returns, g_select will be true and g_entnam will contain the selected menu entry. Note that an ActiveX event handler routine can use %M_SIGNAL to force a break from AX_INPUT.

If the operation times out, g_select is set to true and g_entnam is set to the entry name specified in g_time_entry, which is defined in tkctl.def. See g_time_entry.

See also

Examples

The following example uses this script file:

.script
.column c_general, "General"
.entry o_help, "Help", key(f1)
.entry o_exit, "Exit", key(esc), select(x)
.end

This example performs input to an ActiveX control.

main ToolkitActiveX             ;Toolkit ActiveX example
.include "DBLDIR:activex.def"    ;ActiveX definitions
.include "WND:tools.def"         ;Toolkit definitions
.include "WND:inpctl.def"        ;Toolkit input controls
.align
stack record
    colid    ,i4                 ;Column ID
    axwin    ,i4                 ;ActiveX Toolkit window ID
    axcntr   ,i4                 ;ActiveX Container ID
    axctrl   ,i4                 ;ActiveX Control ID
proc
    xcall u_start("ToolkitActiveX")
                                 ;Start Toolkit and open our window lib
    xcall m_ldcol(colid,, "c_general")  ;Load our general column
    axwin = %ax_tkwin("", 10, 40, axcntr)
                                 ;Create Toolkit ActiveX window and container
    axctrl = %ax_load(axcntr, "MSMask.MaskEdBox.1", 15, 15, 100, 20)
                                 ;Create a masked edit control at 15,15
                                 ; (pixels) within the container, sized
                                 ; at 100x20 (pixels)
    xcall u_window(D_PLACE, axwin, 5, 21)  ;Place the window
    xcall ax_wantskey(axwin, D_KEY_ALL, D_MAP_CONTROL, D_KEY_MENU, D_MAP_MENU)
                                 ;Tell the window that we want any key
                                 ; that is not a menu shortcut to be
                                 ; passed to the ActiveX controls
    xcall ax_set(axctrl, "Ext_Focus", TRUE)
                                 ;Focus the masked edit control
    repeat                       ;Here's our input loop
      begin
        xcall ax_input(axwin)    ;Allow input to anything available
        if (g_select)            ;Menu entry or shortcut?
          begin
            using g_entnam select  ;Which one?
            ("O_EXIT "), exitloop
            endusing
          end
      end
    xcall u_finish               ;Close Toolkit
endmain