%AX_TKSINGLE

Create a Toolkit container and load a single ActiveX control

window_id = %AX_TKSINGLE(tk_container_name, rows, columns, control_name, [ocx_file], 
&          [license_string][, prefix])

Return value

window_id

On Windows, %AX_TKSINGLE returns the ID of the created Toolkit container window. On UNIX, this routine always returns false. On OpenVMS, this routine always returns true. (^VAL)

Arguments

tk_container_name

The name of the Toolkit container window to create. (a)

rows

The number of rows to initially size the window. (n)

columns

The number of columns to initially size the window. (n)

control_name

The name of the ActiveX control you want to load. (a)

ocx_file

(optional) The name of the OCX file that contains the control. (a)

license_string

(optional) The optional license string for the control. (a)

prefix

(optional) The optional prefix for binding extension routines to the automatically registered %UWNDEVENTS_METHOD set and for auto-binding control events. (See the documentation for the autobind_prefix argument for %AX_LOAD.) If you pass prefix to %AX_TKSINGLE, it is used in two places: for the %UWNDEVENTS_METHOD set that is registered for the Toolkit container window and for binding (AX_BIND) routines to each of the control events. (a)

Discussion

%AX_TKSINGLE does the following:

Creates a Toolkit container window.
Creates an ActiveX container window.
Loads the ActiveX control.
Registers a %UWNDEVENTS_METHOD set. (This includes a routine for each event.)
Optionally saves the addresses of extension routines so they can be used later within the registered method set. (Use the prefix argument to do this.)

%AX_TKSINGLE loads only one ActiveX control per Toolkit container. (To use more than one ActiveX control in a single Toolkit container, you must use %AX_TKWIN.) You maintain only one ID: the window ID returned by %AX_TKSINGLE. The resulting Toolkit container window is part of the current environment, but can be promoted to global.

%AX_TKSINGLE automatically registers a default method set that includes an entry for each event. For example, for D_EVENT_LEFT_CLICK, there’s an %AX_TKEVENT_LEFT_CLICK entry. (The names for these routines all begin with AX_TKEVENT_.) This method set also includes %AX_TKEVENT_SIZE (for the D_EVENT_SIZE event), which automatically resizes the ActiveX control when the user or the program resizes the Toolkit container window.

If you want to create your own routines for these events, there are three ways to replace these methods: by creating extensions, by creating your own routines with the same name and linking them in at runtime, or by registering your own method set. We recommend extensions, which are routines you write whose names have a common prefix, but otherwise are modeled after the event names for the AX_TKEVENT_* supplied methods (documented in Supplied methods). For example, if the common prefix is GRID_ and you create an extension for the left click event, your extension would need to be named GRID_TKEVENT_LEFT_CLICK. You then pass the prefix (“GRID_”, in this case) as the prefix argument to %AX_TKSINGLE.

Note the following:

Only %AX_TKEVENT_SIZE contains code that affects the ActiveX control. The other automatically registered methods do nothing unless you pass prefix or you have created your own routines with the same names as the automatically registered set.
Only those routines available at runtime with the correct naming convention are registered as extensions.
You don’t have to supply an extension for every event.

If you pass a null string (“”) for tk_container_name, Toolkit assigns a unique window name in the form _W_nnn, where nnn is the window ID.

If the ActiveX control cannot be loaded and the ocx_file argument

is passed and non-blank, %AX_TKSINGLE attempts to automatically register the OCX file specified by ocx_file and then attempts to load the control a second time. If either fails, %AX_TKSINGLE resignals the error trapped on the load failure.
is not passed or is blank, %AX_TKSINGLE resignals the error trapped on the load failure.

See also

Examples

The following example creates a Toolkit container window, creates an ActiveX container, and loads the MSCAL.Calendar ActiveX control. When the CAL_SELECT menu entry is signaled, a message box is displayed indicating the currently selected date in the calendar control.

proc
    xcall u_start
    wndid = %ax_tksingle("", 10, 40, "MSCAL.Calendar", "mscal.ocx",, "calendar_")
    xcall b_button(wndid, "CAL_SELECT", DSB_TEXT, "OK")
    xcall b_button(wndid, "O_EXIT", DSB_TEXT, "Cancel")
    xcall u_window(D_PLACE, wndid, 5, 21)
    repeat
      begin
        xcall ax_input(wndid)
        if (g_select)
          using g_entnam select
("CAL_SELECT"), begin
          xcall u_message("Selected date (MM/DD/YYYY): " +
          &          %string(%ax_tkgetint(wndid, "Month")) + "/" +
          &          %string(%ax_tkgetint(wndid, "Day"), "XX") + "/" +
          &          %string(%ax_tkgetint(wndid, "Year"), "XXXX"))
        end
(),            exitloop
          endusing
      end
    xcall u_finish
.end