Opens a pet palette for performing user input from the add-on.

    GSErrCode ACAPI_Interface (
        APIIo_PetPaletteID,
        API_PetPaletteType*            petPaletteInfo,
        APIPetPaletteCallBackProc*     petPaletteProc
    );

 

Parameters

petPaletteInfo

[in] identifies the pet palette.

petPaletteProc

[in] callback procedure for the palette.

 

Return Values

NoError

The function has completed with success.

APIERR_BADPARS

One or both of the parameters are nullptr.

APIERR_NESTING

Pet palettes cannot be opened when the input has already begun.

APIERR_BADWINDOW

Pet palettes can be opened only above drawing windows.

APIERR_BADID

One of the following errors occured:

• The petIconIDsHdl is nullptr.
• The petIconIDsHdl contain more or less IDs, than indicated by nCols * nRows.
• The supplied petPaletteID collides with a built-in Archicad petpalette identifier. Choosing the old pictID for identifier is a good idea.
• The supplied petPaletteID collides with another petpalette, which differs from the actual one: it has more or less items, or it has the same number of items, but at least one of them has different icon resource identifier.
• The Add-On is using the old API_PetPaletteType structure.

For other common API errors see the API Errors document.

 

Remarks

The pet palette consists of individual ‘GICN’ icon resources (pet items). Each pet item in the palette assumed to be 22 pixels wide and 22 pixels high. Larger icons will appear truncated. The iconIDs should be passed to the Archicad in a GSHandle consisting of short numbers. The Archicad builds up the palette from these icons. Besides this, each different pet palette should have a unique identifier. Choosing the old pictID for identifier is a good idea.

  The pet palette can have tooltip (yellow bar) strings and help anchors (the help mechanism is loaded with it). The strings should be placed as pairs into a ‘DHLP’ resource. In the ‘DHLP’ resource, every tooltip and help anchor pair belongs to the corresponding pet item on the palette. This resource should be compiled into the API resource module, and their identifier can be passed to the API_PetPaletteType structure.

The API will search for only this resource, and will index this with the pet palette item’s relative index to get the help object and take an action: it will display the tooltip string, or will pass the anchor as a parameter to the help engine configured by the add-on.
If the add-on wants to take these opportunities, then it should set the Location of its own help engine by the DGRegisterAdditionalHelpLocation function of the Dialog Manager module. This can be done during the Initialize phase, and you should unregister the help location by calling DGUnregisterAdditionalHelpLocation during the FreeData phase. The developerId and localId is the MDID stored in your 32500 ‘MDID’ resource.

The palette callback procedure is called with the actual value of the pet palette (see APIPetPaletteCallBackProc).

 

Example

static GSErrCode __ACENV_CALL   PetPaletteCallBack (short actValue)
{
    GSErrCode err = NoError;

    short inputMode = actValue + 1;

    switch (inputMode) {
        case 1:     err = Do_InputAPoint ();
                    break;
        case 2:     err = Do_InputALine ();
                    break;
        case 3:     err = Do_InputAnArc ();
                    break;
        default:    err = APIERR_GENERAL;
                    break;
    }

    return err;
}


static GSErrCode   Do_InputWithPetPalette (void)
{
    GSErrCode           err;
    API_PetPaletteType  petPaletteInfo;
    short**             petItemIdsHdl;
    short               petItemIds[5] = { 32201, 32202, 32203, 32204, 32205 };

    BNZeroMemory (&petPaletteInfo, sizeof (API_PetPaletteType));

    // Constructing the handle, which contains the pet item icons' resource IDs
    short nIcons = sizeof (petItemIds) / sizeof (short);
    petItemIdsHdl = (short**) BMhAll (nIcons * sizeof (short));
    for (short i = 0; i < nIcons; i++)
        (*petItemIdsHdl)[i] = petItemIds[i];

    // Filling petPaletteInfo
    petPaletteInfo.petPaletteID = 32200;
    petPaletteInfo.nCols = 5;
    petPaletteInfo.nRows = 1;
    petPaletteInfo.value = 0;
    petPaletteInfo.grayBits = 0;
    petPaletteInfo.petIconIDsHdl = petItemIdsHdl;
    petPaletteInfo.dhlpResourceID = 32200;

    err = ACAPI_Interface (APIIo_PetPaletteID, &petPaletteInfo, PetPaletteCallBack);

    BMhKill ((GSHandle *) &petItemIdsHdl);

    return;
}


GSErrCode   __ACENV_CALL    Initialize (void)
{
    IO::Location helpLocation;
    ACAPI_GetOwnLocation (&helpLocation);
    helpLocation.DeleteLastLocalName ();
    IO::Path helpPath;
    helpLoc.ToDisplayText (&helpPath);
    DGRegisterAdditionalHelpLocation (developerId, localId, (const char*) helpPath);

    return;
}


GSErrCode   __ACENV_CALL    FreeData (void)
{
    DGUnregisterAdditionalHelpLocation (developerId, localId);

    return;
}

Please also study the Interface Functions example add-on.

 

Requirements

Version: API 5.1 or later

Header: APIdefs_Interface.h

 

See Also

API_PetPaletteType, APIPetPaletteCallBackProc
ACAPI_Interface, API Functions