DOTNET_TKINPUT

Process an embedded form

WTSupported in traditional Synergy on Windows

 

 

 

xcall DOTNET_TKINPUT(window_id, [help_id], [wait_time], [menu_flag][, focus])

Arguments

window_id

The ID of a window created by %DOTNET_TKWIN. (Otherwise Toolkit throws an exception.) (n)

help_id

(optional) A help identifier to 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. (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.

n

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 DOTNET_TKINPUT to return utility menu entries (U_ and O_HELP) instead of processing them. (n)

focus

(optional) Indicates which component control (which .NET control or WPF form within the .NET form) to move focus to: D_FIRST (focus on the first control) or D_LAST (focus on the last control). If any other value is passed as focus, or if focus is not passed, the form determines where to move focus. And if no suitable component control can be found, the form itself receives focus. (n)

Discussion

DOTNET_TKINPUT processes a .NET form embedded in a Toolkit container window. This subroutine moves focus to the specified form (contained in window_id) and enables your program to accept input for the form. At the same time, it allows menu entries to be selected and returned to Toolkit. (On UNIX and OpenVMS, this subroutine merely returns.)

When focus is on a .NET form, most keystrokes are sent first to the form as input. The form’s PreProcessMessage method returns true if the form will consume the keyboard input, which prevents the Synergy runtime from processing the input. The PreProcessMessage method returns false if the form won’t consume the keyboard input, which allows the Synergy runtime to process the input.

The exceptions are tab and shift+tab. Toolkit sends tab directly to the Toolkit container, rather than the form (enabling the Synergy runtime to process it) if the .NET form is part of a composite window and tab is pressed when the last control in the form has focus. The same is true of shift+tab if pressed when the first control in the form has focus. tab and shift+tab are otherwise sent to the form and used by the form to navigate among its controls.

Tip

If you have a .NET control that needs to consume a keystroke that is used by the form (e.g., shift+tab, escape, or an accelerator key), you will need to override the control’s ProcessCmdKey or IsInputKey method or the form’s PreProcessMessage method. See Synergex KnowledgeBase article 100001973 for information.

If a keystroke can be mapped to a menu entry and isn’t consumed by the .NET form, the menu entry is signaled. DOTNET_TKINPUT recognizes the following:

DOTNET_TKINPUT returns only when a menu entry is signaled (g_select is true and g_entnam contains the name of the menu entry), an exception has been thrown (@DotNetException), or the operation times out. 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.

If, while the form is active, focus is diverted to another application, when focus returns to your Toolkit application, it is established on the form, and the form reestablishes focus among its component controls.

.NET forms in composite windows

If the Toolkit container window is part of a composite window, DOTNET_TKINPUT must be called from the processing method for the child window (which is C_METHNET by default), and tab and shift+tab are processed by the Synergy runtime if pressed when the first or last control in a .NET form has focus (as described above). tab moves forward through the following tabbing order, and shift+tab moves backward through the following.

1. Previous windows (or buttons if wrapping to the end) in the composite window’s tabbing order
2. The .NET form
3. Buttons on the .NET form’s Toolkit container window (in order)
4. Subsequent windows or buttons in the composite window’s tabbing order

See Controlling tabbing, focus, and input context for more information.

Examples

The following example embeds a .NET form in a Toolkit window and then processes it with DOTNET_TKINPUT. The container window created below is not part of a composite window, so DOTNET_TKINPUT is called directly. (If it was part of a composite window, the processing method for the child window, which is C_METHNET by default, would call DOTNET_TKINPUT.) Note that the first line uses .INCLUDE to include the .inc file generated by gennet40. See step 1 of Embedding a .NET form.

.include "MyForm.inc"       ;Include the .inc file generated by gennet40.
main
.include "WND:tools.def"
record
    form     ,@MyForm
    wndid    ,i4
    ctrid    ,i4
proc
    xcall u_start
    form = new MyForm()       ;Instantiate a MyForm object.
    wndid = %dotnet_tkwin("", 18, 78, form) ;Create container window and embed form (MyForm object)
    xcall b_button(wndid, "OK")
    xcall u_window(D_PLACE, wndid, 1, 1)    ;Place container window. 
        begin
          xcall dotnet_tkinput(wndid,,,, D_LAST);Process container window
        end
.
.
.
    xcall u_finish
endmain