Adding and using .NET forms, .NET controls, and WPF elements

The UI Toolkit .NET routines enable you to embed the following in a Toolkit application:

These routines do not work with Synergy .NET. For information on using Toolkit programs with Synergy .NET, see Using UI Toolkit with .NET.

Only .NET forms can be embedded directly into Toolkit windows, but you can embed .NET controls and WPF elements either by adding them to a .NET form and then embedding the form, or by instructing Toolkit to create a .NET form as you add a control or element.

With the Toolkit .NET routines, you can do the following:

The user sees the .NET form, .NET control, or WPF element as part of your Toolkit application. Input and menu entries work as they do with any other Toolkit window, and if a .NET form is part of a composite window, tabbing takes the user in and out of the form. Note, however, that unless the container window is part of a composite window, you won’t be able to use Tab or Shift+Tab to access buttons on the Toolkit container window (the Toolkit window that contains the form, control, or element). See the DOTNET_TKINPUT Discussion for more information on how keyboard input is handled.

When you embed a .NET form, .NET control, or WPF element, you associate it with a Toolkit container window. Because the container is a Toolkit window, you can perform all standard window-related Toolkit functions (place, remove, delete, resize, and so forth) by referencing the window ID for the container. Note, however, that resizing the Toolkit container window doesn’t automatically resize the form. If you resize the container, areas of the form can be cut off or portions of the Toolkit container window may be visible on the bottom or right of the form. (You can adjust this by querying and setting the width and height properties of the form.) The only time Toolkit automatically sizes a form is when it automatically creates a form (when the flags argument is passed as DN_MAKEFORM or DN_WPF in a call to %DOTNET_TKWIN).

Embedding a .NET form

This is the basic procedure for embedding a .NET form in a Toolkit application and using the form as part of the application. (You can also add a .NET form to a previously embedded form. See Embedding .NET forms, .NET controls, and WPF elements.)

1. Load the assembly that contains the type to be instantiated, and create an instance of a .NET form contained in the assembly.

The easiest way to do this is by using gennet40, dblproto, and the NEW keyword. For example, if you have a program named MyTkProg and you want to embed a form with a text editor named TextEditor that’s in a prebuilt assembly named MyTextEd.dll, you could do the following:

Run gennet40 to generate a wrapper class for TextEditor:

gennet40 -output Editor.dbl "c:\MyForms\MyTextEd.dll"

Run dblproto to generate prototypes for the class. The output will be Editor.dbp.

dblproto Editor.dbl

Create an instance of TextEditor:

Record
    txt    ,@TextEditor
Proc
    txt = new TextEditor()

Compile the .dbl file produced by gennet40 (Editor.dbl) and your Toolkit application (MyProg.dbl). Make sure the MyTkProg compile has access to the prototypes (Editor.dbp) generated by dblproto.

dbl -qrelaxed:interop Editor
dbl MyTkProg

Link your Toolkit application with the compiled Editor file:

dblink MyTkProg Editor

For more information, see

Note that you can also do this directly with the Synergy .NET API (see Synergy .NET Assembly API), but we recommend using gennet40, which simplifies the process.

2. Use %DOTNET_TKWIN to embed the .NET form in a Toolkit container window. If the .NET form will be part of a composite window, you’ll also need to use the DC_ADD subfunction for %C_CONTAINER to add the container window to the composite window.
3. Access properties, call methods, and register event handlers for the .NET form object as necessary. Note that registering an event handler involves adding a delegate to an event. See Synergy .NET Assembly API, and note that gennet40 creates a public variable for each event defined in a class. These variables contain event objects, and you can call an AddHandler method for these to add a delegate.
4. Do one of the following:
5. Respond to any new entries after the application exits from DOTNET_TKINPUT or C_PROCESS, and call methods or query properties for the .NET form to get the input results.
6. Delete the Toolkit container window, if it isn’t automatically deleted as a result of exiting the current environment (using E_EXIT). This releases Toolkit’s reference to the .NET form.

Embedding .NET forms, .NET controls, and WPF elements

To add a .NET control or a WPF element to a Toolkit application, the control or element must be on a .NET form. But what if you have a .NET control or a WPF element that you’d like to use on its own (e.g., a grid control), and you don’t have a form? Or what if you want to add a .NET form or control to a .NET form that’s already embedded in a Toolkit window? Except for the first three steps listed above in Embedding a .NET form, the procedure is the same.

1. Create an instance of the .NET form, .NET control, or WPF element. See step 1 in Embedding a .NET form, which discusses creating an instance of a .NET form. You can use the same procedure to create an instance of a .NET control or a WPF element.
2. Do one of the following:
3. Follow step 3 through step 6 above in Embedding a .NET form.