%GRID_CREATE

Create a Toolkit container for the Spread control

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

Return value

window_id

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

Arguments

rows

The number of rows for the initial container window size. (n)

columns

The number of columns for the initial container window size. (n)

license_string

Your developer license string for the Spread COM 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 %GRID_CREATE, 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)

control_name

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

ocx_file

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

Discussion

To use the full functionality of MESCIUS’s Spread COM control (which is used in a limited way behind the scenes for ActiveX Toolkit lists), use %GRID_CREATE, which does the following:

creates a Toolkit container window.
creates an ActiveX container window.
loads the Spread control.
registers a %UWNDEVENTS_METHOD set. (This includes a routine for each element.)
optionally saves the address of extension routines so they can be used later within the registered method set. (Use the prefix argument to do this.)

You maintain only one ID: the window ID returned by %GRID_CREATE. The resulting Toolkit container window is part of the current environment, but can be promoted to global. See Creating a container for the Spread control for information on other routines you can use with the Spread control in a Toolkit container.

To obtain your developer license string for the license_string argument, use the ActiveX Diagnostic Utility (axutl.exe). You must have installed a licensed copy of the Spread COM control (purchased from MESCIUS.) to get this string.

For information on the prefix argument and on causing the routines in the automatically registered method set to call routines (extensions) you’ve created, see the %AX_TKSINGLE Discussion.

By default %GRID_CREATE loads the Spread control distributed with Toolkit. If you want to use a different version of Spread COM, you can use the control_name argument to pass a different control name, and you can use the ocx_file argument to pass the name (and path, if necessary) of a different OCX file and automatically register it.

If the Spread control cannot be loaded and the ocx_file argument

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

The UI Toolkit distribution includes grid.def, a file that provides definitions for constants used by the Spread control. See Examples below.

See the Spread control documentation for information on the methods, properties, and events supported by this control.

See also

Examples

The following example creates a Toolkit container, creates an ActiveX container, and loads the Spread control.

.include "WND:tools.def"
.include "DBLDIR:activex.def"
.include "WND:grid.def"
.define  D_SPREAD_LICENSE, 1234567
proc
    xcall u_start
    wndid = %grid_create(10, 40, D_SPREAD_LICENSE, "tgrid_")
    xcall u_window(D_PLACE, wndid, 10, 21)
    ctlid = %ax_tkctlid(wndid)
    xcall ax_set(ctlid, "Col", 1)
    xcall ax_set(ctlid, "Col2", 5)
    xcall ax_set(ctlid, "Row", 10)
    xcall ax_set(ctlid, "Row2", 10)
    xcall ax_set(ctlid, "BlockMode", TRUE)
    xcall ax_set(ctlid, "BackColor", RGB_VALUE(0,0,255))
    xcall ax_set(ctlid, "BlockMode", FALSE)
    xcall ax_set(ctlid, "Row", 2)
    xcall ax_set(ctlid, "Col", 3)
    xcall ax_set(ctlid, "ForeColor", RGB_VALUE(255,0,0))
    xcall ax_set(ctlid, "Text", "Hello world!")
    xcall ax_set(ctlid, "Action", SS_ACTION_ACTIVE_CELL)
    repeat
      begin
        xcall ax_input(wndid)
        if (g_select)
          exitloop
      end
    xcall u_finish
.end