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 oldpictID
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