API_AddParType |

Describes a parameter of a Library Part.

    typedef struct {
      API_AddParID       typeID;
      short              index;
      short              typeMod;
      char               name[API_NameLen];
      GS::uchar_t        uDescname [API_UAddParDescLen];
      GS::uchar_t        valueDescription [API_UAddParNumDescLen];
      Int32              dim1;
      Int32              dim2;
      unsigned short     flags;
      short              filler_1;
      Int32              filler_2;
      GSHandle           arrayDescriptions;
      union {
             double      real;
             GS::uchar_t uStr [API_UAddParStrLen];
             GSHandle    array;
      } value;
    } API_AddParType;

Members

typeID

The type of the additional parameter.

index

The index of the additional parameter inside the additional parameter list.

typeMod

Type modifier; the variable is a simple instance or an array with the type typeID.

name[API_NameLen]

The name of the additional parameter.

uDescname[API_UAddParDescLen]

The Unicode description of the additional parameter.

valueDescription[API_UAddParNumDescLen]

The Unicode parameter value description string in UTF-16 encoding.

dim1

The first dimension of the array; in case of array modifier

dim2

The second dimension of the array; in case of array modifier

flags

Modifier flags.

Value	Description
`API_ParFlg_Child`	This parameter is a child of the preceding title.
`API_ParFlg_BoldName`	Show the name of the parameter in bold.
`API_ParFlg_Open`	Show the child parameters of this parameter.
`API_ParFlg_Disabled`	Disable this parameter; mainly used for separator lines
`API_ParFlg_Hidden`	Hidden parameter; does not appear in the Settings dialogs.
`API_ParFlg_SHidden`	Hidden parameter from scripts.

arrayDescriptions

Unicode description string values of an array parameter in UTF-16 encoding. Values are stored immediately after each other to conserve space.

value:: real

contains the value of the parameter; in the case the typeID is not APIParT_CString

value:: uStr[API_UAddParStrLen]

contains the Unicode value of a string type parameter; when the typeID is APIParT_CString

value:: array

Values of an array parameter. For string type arrays the values are stored immediately after each other to conserve space (e.g.: “alpha\0beta\0gamma\0”)

Remarks

This structure describes the additional parameters for a Library Part. It is also used for Library Part-based element (objects, windows, doors, etc.) and attribute types (zone category).

For parameters with array modifier, you can change the dimensions of the array on the fly when you create or modify an element. This enables you to put just a placeholder for an array into the library part parameter, and adjust that when you actually place the library part.

The value list type modifier (which was present in API 1.3) disappeared, as the value list script has dead; a new approach introduced in API 2.1 based on the parameter script of the Library Part.

It is strongly advised to use the APIAny_OpenParametersID, APIAny_ChangeAParameterID, APIAny_GetActParametersID, APIAny_CloseParametersID functions to modify a parameter in the parameter list.

Dictionary parameters are currently inaccessible with this structure.

Example


static void   DumpOneParam (API_AddParID      typeID,
                            const char        *varname,
                            unsigned short    flags,
                            double            value,
                            const GS::uchar_t *valueStr,
                            Int32             dim1,
                            Int32             dim2)

{
    char        head[256], val[256];

    if (dim1 == 0 && dim2 == 0)
        sprintf (head, "    %s 0x%02X", varname, flags);
    else {
        if (dim1 < 0) {
            sprintf (head, "    %s: [%d][%d] 0x%02X", varname, -dim1, -dim2, flags);
            ACAPI_WriteReport (head, false);
            return;
        }
        sprintf (head, "       [%d][%d]", dim1, dim2);
    }

    switch (typeID) {
        case APIParT_Integer:
        case APIParT_LightSw:
        case APIParT_Intens:
        case APIParT_LineTyp:
        case APIParT_Mater:
        case APIParT_FillPat:
        case APIParT_PenCol:
        case APIParT_Boolean:
        case APIParT_BuildingMaterial:
        case APIParT_Profile:
                    sprintf (val, "%d", (Int32) value);
                    break;

        case APIParT_Length:
        case APIParT_Angle:
        case APIParT_RealNum:
        case APIParT_ColRGB:
                    sprintf (val, "%f", value);
                    break;

        case APIParT_CString:
        case APIParT_Title:
                    sprintf (val, "\"%s\"", (const char *) GS::UniString (valueStr).ToCStr ());
                    break;

        case APIParT_Separator:
                    CHCopyC ("-------------------", val);
                    break;

        default:
                    CHCopyC ("???????", val);
                    break;
    }

    GiveMessage_Str (head, val, false);

    return;
}

See to example of the ACAPI_LibPart_GetParams function to get the control frame for this example.

Requirements

Version: API 1.3 or later

Header: APIdefs_LibraryParts.h

Members

Remarks

Example

Requirements

See Also