The lpwdoprArgs parameter of wdCommandDispatch is a pointer to an array of Word operator (WDOPR) data structures. The WDOPR structure lets you pass one of several types of data, and even lets you pass entire arrays of strings or double-precision floating-point values.
For efficiency, several types of data can be passed in the same memory location through the union part of the WDOPR structure; the Type field determines how the data is to be interpreted. Other bit fields in the WDOPR data structure convey to and from the Word API function important information about the argument.
Here is the Windows WDOPR and LPWDOPR type definition, which is found in WDCAPI.H:
typedef struct
{
union
{
short Short;
long Long;
double Double;
LPUCHAR String;
struct
{
ARRAY_DEF far * ArrayDef;
union
{
double far * DoubleArray;
LPUCHAR far * StringArray;
};
};
};
ushort BufferSize;
ushort Type :4;
ushort IsArray :1;
ushort ForInput :1;
ushort ForOutput :1;
ushort BufferTooSmall :1;
ushort :8;
ushort FieldId;
} WDOPR, far * LPWDOPR;
Note
On the Macintosh, the corresponding type definition has named unions, Macintosh-specific types (for example, StringPtr instead of LPUCHAR), and a different bit-field order. Otherwise, the information for the Macintosh is the same as the information given for Windows in the following sections. For the complete Macintosh WDOPR data structure, see WDCAPI.H on the Microsoft Word Developer's Kit disk (Macintosh).
The following paragraphs describe in detail each part of the WDOPR data structure.
The WDOPR structure starts with a union of several data types. Each WDOPR argument is set up to pass one of these data types at a time. In addition to passing a single short, long, double, or string value, you can also pass arrays of doubles or strings. If an array is passed, the WDOPR structure contains a pointer to the array and to a data structure that defines the dimensions of the array. For complete information about arrays in the Word operator, see "Specifics on Arrays" later in this section.
This field specifies the length of a string handled for input or output. If the argument is set for input, the BufferSize field can be set to one of two ways:
If the argument is set for output, the BufferSize field indicates the size of
the buffer allocated for the returned string. If the allocated buffer is not large
enough, or if you deliberately set BufferSize to 0 (zero), an error occurs, the BufferTooSmall bit field is set to 1, and BufferSize is set to the required size. For information about handling returned strings, see "Techniques for Successful Calling" later in this appendix.
The following bit fields in the WDOPR data structure convey important information about the argument.
These 4 bits indicate the type of the WDOPR's data. The constants TypeVoid, TypeShort, TypeLong, TypeDouble, and TypeString are defined in WDCAPI.H for use in this field.
In Part 2, "WordBasic Reference," statement and function arguments and return types are specified as "number" (TypeShort, TypeLong, TypeDouble) or "text" (TypeString). To determine the appropriate WDOPR type for a "number" argument or return type, cross-reference the WordBasic topic with WBTYPE.TXT (Windows) or WBTYPE (Macintosh), a text file included in the CAPI folder on the Microsoft Word Developer's Kit disk; if the statement or function does not appear in the list of those that use TypeDouble or TypeLong, then the WDOPR type should be TypeShort.
This bit should be set to 1 if the WDOPR is passing an array of the indicated data type. Note that it is the responsibility of the calling function to handle the allocation of memory for WDOPR arrays. For more information, see "Specifics on Arrays" later in this section.
ForInput indicates that the contents of the WDOPR argument are intended as input to a dialog box's field settings. This bit is ignored if the command does not correspond to a dialog box.
ForOutput indicates that the WDOPR has been set up to return the value of one field of a dialog box. Set this bit if you are using the CommandDefaults constant for DlgOptions in your wdCommandDispatch function. This bit is ignored if the command does not correspond to a dialog box.
If the allocated buffer space is too small to hold the field's data, wdCommandDispatch generates an error that sets BufferTooSmall to 1 (true) upon return from calling the command. It is important to clear this bit when making any call. The calling routine is responsible for checking this bit field and taking corrective action. Note that you can check this flag, reallocate the buffer (using the required size returned in BufferSize), and try the call again. If this occurs after calling a command that corresponds to a dialog box where the ForOutput bit was set before the call, this bit should be checked in all WDOPRs to determine which buffer was too small.
FieldID is an identifier for the named field parameters passed in each WDOPR. Constants are provided in WDFID.H for this field, and they correspond closely to the parameters that can be passed in WordBasic, as described in Part 2, "WordBasic Reference." For example, in WordBasic the FormatFont statement takes the .Bold argument. The corresponding FieldID constant used to pass a short value of 1 in a WDOPR argument is fidBold. This WDOPR would, of course, be constructed and passed as part of a wdFormatFont command to the wdCommandDispatch function.
The WDOPR data structure is set up to facilitate the passing of either arrays of strings or arrays of doubles. These arrays can have one or more dimensions.
One of the data types in the union part of the WDOPR is a nested set of structures for passing arrays. Several pieces of information about each array are passed in the appropriate variables. The ARRAY_DEF structure passes information on the number of dimensions in the array and the size of each of those dimensions. Like the WDOPR structure, the ARRAY_DEF structure is also defined in WDCAPI.H, and is listed here for reference.
typedef struct
{
short cArrayDimensions;
short ArrayDimensions[];
} ARRAY_DEF;
The remaining part of the WDOPR's array-passing structure is a union of two pointers. In the first case, the pointer is to the first value in an array of double-precision floating-point values. In the second case, the pointer is to an area of memory containing a list of pointers to null-terminated strings.
Keep the following points in mind when building WDOPR arguments to pass arrays:
Note
There is a subtle difference in the way WordBasic and C arrays are dimensioned. In WordBasic, an array has elements 0 (zero) through n, whereas
in C, an array has elements 0 (zero) through n–1, where n is the value given in the array's declaration. The following two arrays, for example, will be allocated the same amount of memory, with elements 0 (zero) through 5 in both cases:
' WordBasic array definition Dim Array (5) // C array definition double Array[6];
Keep this in mind when working with WordBasic arrays in your Word API code.