Toolbox

Functions related to the manipulation of, and integrating into the Toolbox. More...

Classes
struct	API_ToolBoxInfo
	Contains information on the current state of the toolbox. More...

Functions
GSErrCode __ACENV_CALL	ACAPI_Toolbox_GetToolBoxMode (API_ToolBoxItem *toolBoxItem)
	Returns the actual toolbox mode.
GSErrCode __ACENV_CALL	ACAPI_Toolbox_SetToolBoxMode (API_ToolBoxItem *toolBoxItem)
	Sets the actual toolbox mode.
GSErrCode __ACENV_CALL	ACAPI_Toolbox_GetToolBoxInfo (API_ToolBoxInfo *toolBoxInfo, bool enableHidden=false)
	Returns information on the current state of the toolbox.
GSErrCode __ACENV_CALL	ACAPI_LibraryPart_RegisterSubtype (GSType signature, short templateFileResID, bool transparentNode, short stringResID, short smallIconResID, short largeIconResID, API_TBoxGroup toolGroupId, API_TBoxEnabled enableFlags, short defaultsResID)
	Registers a new library part subtype.

Detailed Description

Functions related to the manipulation of, and integrating into the Toolbox.

Function Documentation

ACAPI_LibraryPart_RegisterSubtype()

GSErrCode __ACENV_CALL ACAPI_LibraryPart_RegisterSubtype	(	GSType	signature,
		short	templateFileResID,
		bool	transparentNode,
		short	stringResID,
		short	smallIconResID,
		short	largeIconResID,
		API_TBoxGroup	toolGroupId,
		API_TBoxEnabled	enableFlags,
		short	defaultsResID
	)

Registers a new library part subtype.

Parameters

signature	[in] A four-character identifier of this library part subtype
templateFileResID	[in] 'FILE' resource ID of the subtype template library part compiled into the add-on
transparentNode	[in] Objects of this subtype can be shown on higher ancestry levels as well
stringResID	[in] Resource ID of the library part subtype description string
smallIconResID	[in] Resource ID of the small-sized toolbox (toolbar) item icon
largeIconResID	[in] Resource ID of the large-sized toolbox item icon
toolGroupId	[in] Toolbox item position
enableFlags	[in] Enable or disable the subtype tool depending on the active window
defaultsResID	[in] ID of the 'ACP0' resource that contains the element default values for this subtype

Returns

• APIERR_BADPARS - templateFileResID refers to an invalid 'FILE' resource or the built-in library part cannot be accepted as subtype template.
• NoError - The function has completed with success.

Remarks

This function registers a new library part subtype. In order to have an own element subtype the add-on must contain a built-in library part in its reource module. This library part will be loaded into the active libraries, and become a new node in the ancestry tree. The new element type will be identified with the signature identifier chosen by the add-on's writer. The signature should be unique in order to avoid collisions. You may pass 0 in the signature parameter if you do not need a new element type but a single subtype node. The subtype can appear in the toolbox as an external tool, and also on the Windows toolbar. In this case you must pass two valid icon resource IDs in the smallIconResID and the largeIconResID parameters. The size of the icons should be 16x16 and 30x21 pixels respectively. You can specify the position of the subtype item inserted into the toolbox with the toolGroupId parameter as follows:

API_TBoxGroup	Meaning
TBoxGroup_Root	The subtype tool item will be appended to the group of model element tools
TBoxGroup_Objects	The subtype tool item will be added to the object tools
TBoxGroup_Openings	The subtype tool item will be added to the window/door tools

You can control the availability of the subtype tool in the toolbox by setting the enableFlags bits:

API_TBoxEnabled	The subtype tool is enabled
API_TBoxEnabled_FloorPlan	on floor plan window
API_TBoxEnabled_ModelSection	on model type section and elevation windows
API_TBoxEnabled_DrawingSection	on drawing type section and elevation windows
API_TBoxEnabled_3D	on 3D model window
API_TBoxEnabled_Detail	on detail window
API_TBoxEnabled_Layout	on layout and master layout windows
API_TBoxEnabled_Worksheet	on worksheet window
API_TBoxEnabled_ModelInteriorElevation	on model type interior elevation windows
API_TBoxEnabled_DrawingInteriorElevation	on drawing type interior elevation windows

If you want to register your subtype tool without appearing in the toolbox, pass 0 for both the smallIconResID and the largeIconResID parameters. If you register a subtype tool you should define the factory default values for this element type in an 'ACP0' resource. The element default will be initialized with these parameters when no preferences data is stored. The structure of this resource is shown at the example below. The resource ID should be passed in the defaultsResID parameter. Learn more about this topic at the general description of Library Part Subtypes.

Example

Resources in the .GRC file:

ACAPI_Toolbox_GetToolBoxInfo()

GSErrCode __ACENV_CALL ACAPI_Toolbox_GetToolBoxInfo	(	API_ToolBoxInfo *	toolBoxInfo,
		bool	enableHidden = false
	)

Returns information on the current state of the toolbox.

Parameters

toolBoxInfo	[out] Miscellaneous information on the toolbox.
enableHidden	[in] Include hidden tools from the toolbox as well. This parameter is optional; if you pass nullptr in the second parameter, it defaults to false.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - tboxInfo is nullptr.
• APIERR_MEMFULL - Low memory condition.

Remarks

You can query the current state of the toolbox with this function. It returns information on the different installed items (external tools, too), and the active toolbox item (the active tool). The enableHidden flag tells Archicad to include hidden toolbox items as well. These are the tools which don't have any icon in the toolbox, though using them puts Archicad into a state which works as if you chose one of the 'real' tools. A good example of this is the Slab Accessory.

Example

ACAPI_Environment (APIEnv_GetToolBoxInfoID, &toolBoxInfo, (void *) (GS::UIntPtr) true);

ACAPI_Toolbox_GetToolBoxMode()

GSErrCode __ACENV_CALL ACAPI_Toolbox_GetToolBoxMode

(

API_ToolBoxItem *

toolBoxItem

)

Returns the actual toolbox mode.

Parameters

toolBoxItem

[out] Current toolbox mode data.

Returns

• NoError - The function completed with success.
• APIERR_BADPARS - toolBoxItem is nullptr

Remarks

This function is used to get the current toolbox mode. The mode is returned in the type field. For those types which can have more toolbox modes (ID_Wind, ID_Door, ID_Symb, ID_Light), the owner ID of the tool is returned, too. If the current toolbox mode has no element type associated with (e.g. arrow mode and marquee mode), the typeID will be API_ZombieElemID. To change the active toolbox item use the ACAPI_Toolbox_SetToolBoxMode function.

Example

API_ToolBoxItem tboxInfo;
BNZeroMemory (&tboxInfo, sizeof (API_ToolBoxItem));
 
GSErrCode err = ACAPI_Environment (APIEnv_GetToolBoxModeID, &tboxInfo, nullptr);
if (err == NoError) {
    GS::UniString elemName = "unknown";
    ACAPI_Element_GetElemTypeName (tboxInfo.type, amp;elemName);
 
    char buffer[256];
    if (tboxInfo.type == API_ZombieElemID) {
        sprintf (buffer, "Previous toolbox mode: Arrow or Marquee");
    } else if (tboxInfo.type.variationID == APIVarId_Generic) {
        sprintf (buffer, "Previous toolbox mode: %s", (const char*) elemName.ToCStr ());
    } else {
        char *p = (char *) &tboxInfo.type.variationID;
        sprintf (buffer, "Previous toolbox mode: %s  variation \"%c%c%c%c\"",
                    (const char*) elemName.ToCStr (), p[0], p[1], p[2], p[3]);
    }
 
    ACAPI_WriteReport (buffer, false);
}

ACAPI_Toolbox_SetToolBoxMode()

GSErrCode __ACENV_CALL ACAPI_Toolbox_SetToolBoxMode

(

API_ToolBoxItem *

toolBoxItem

)

Sets the actual toolbox mode.

Parameters

toolBoxItem

[in] Toolbox mode to be set.

Returns

• NoError - The function completed with success.
• APIERR_BADPARS - The variationID of the library part type does not match to the toolbox mode type
• APIERR_BADID - toolBoxItem->type contains invalid data

Remarks

This function is used to change the current toolbox mode. The mode is specified by the element type ID. For those types which can have more toolbox modes (ID_Wind, ID_Door, ID_Symb, ID_Light), the variationID of the tool should also be supplied. For API_ZombieElemID or an invalid element type ID specification the arrow mode will be set. Note that the function does not switch the toolbox immediately, but posts an event into the application queue. The command will be executed only when the application events are processed. To get the active toolbox mode use the ACAPI_Toolbox_GetToolBoxMode function.

Example

API_Guid        guid;
API_Element     element;
API_ToolBoxItem tboxInfo;
GSErrCode       err;
 
BNZeroMemory (&tboxInfo, sizeof (API_ToolBoxItem));
tboxInfo.type = API_ZombieElemID;
if (ClickAnElem ("Click an element to set toolbox mode", API_ZombieElemID, nullptr, &tboxInfo.type, &guid, nullptr)) {
    if (tboxInfo.type == API_ObjectID || tboxInfo.type == API_LampID ||
        tboxInfo.type == API_WindowID || tboxInfo.type == API_DoorID)
    {
        BNZeroMemory (&element, sizeof (API_Element));
        element.header.type.typeID   = tboxInfo.type.typeID;
        element.header.guid          = guid;
        err = ACAPI_Element_Get (&element);
        if (err == NoError)
            tboxInfo.type.variationID = element.header.type.variationID;
    }
}
 
err = ACAPI_Environment (APIEnv_SetToolBoxModeID, &tboxInfo, nullptr, nullptr);
if (err == NoError) {
    if (tboxInfo.type == API_ZombieElemID)
        WriteReport ("Current toolbox mode: Arrow");
    else {
        if (tboxInfo.type.variationID == APIVarId_Generic) {
            WriteReport ("Current toolbox mode: %s", ElemID_To_Name (tboxInfo.type));
        } else {
            char *p = (char *) &tboxInfo.type.variationID;
            WriteReport ("Current toolbox mode: %s  External \"%c%c%c%c\"", ElemID_To_Name (tboxInfo.type), p[0], p[1], p[2], p[3]);
        }
    }
}