ACAPI_Register_Subtype |

Registers a new library part subtype.

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

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

Return Values

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.

For other common API errors see the API Errors document.

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 16×16 and 30×21 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

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

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:


'FILE' 132    "Roof Opening.gsm" {
    "Roof Opening.gsm"
}

'STR#' 32611  "Skylight subtype" {
/* [  1] */     "Skylight"                          /* Subtype name */
/* [  2] */     "Skylight Selection Settings..."    /* Selection settings dialog title */
/* [  3] */     "Select All Skylights"              /* Select All menuitem string in Edit menu */
/* [  4] */     "Skylight Tool"                     /* Toolbox item name */
/* [  5] */     "The Skylight tool is used for placing skylight library items into roofs by clicking on the roof."
                                                    /* Toolbox item popup help text */
/* [  6] */     "Skylight Default Settings..."      /* Default settings dialog title */
/* [  7] */     "Enter First Point of Skylight."    /* Default prompt text */
}

'GICN' 32602  "Small toolbar icon for Skylight" {
}

'GICN' 32603  "Large toolbox icon for Skylight" {
}

'ACP0' 132    "Metric Defaults" {
/* [  1] VarName  */ "001_defObjName"
/* [  1] Value    */ "Skylight Pivot Hung"

/* [  2] VarName  */ "002_Symb_layer"
/* [  2] Value    */ "7"

/* [  3] VarName  */ "003_Symb_material"
/* [  3] Value    */ "47"

/* [  4] VarName  */ "004_Symb_info"
/* [  4] Value    */ "Sky-001"

/* [  5] VarName  */ "005_Symb_level"
/* [  5] Value    */ "0"

/* [  6] VarName  */ "006_Symb_pen"
/* [  6] Value    */ "2"

/* [  7] VarName  */ "007_Symb_onePen(0/1)"
/* [  7] Value    */ "0"

/* [  8] VarName  */ "008_Symb_showAlways"
/* [  8] Value    */ "0"

/* [  9] VarName  */ "009_Symb_showAbove"
/* [  9] Value    */ "0"

/* [ 10] VarName  */ "010_Symb_showBelow"
/* [ 10] Value    */ "0"

/* [ 11] VarName  */ "011_Symb_gravityPar"
/* [ 11] Value    */ "0"

/* [ 12] VarName  */ "012_Symb_contourPen"
/* [ 12] Value    */ "72"

/* [ 13] VarName  */ "013_Symb_fillPen"
/* [ 13] Value    */ "73"

/* [ 14] VarName  */ "014_Symb_bkgPen"
/* [ 14] Value    */ "80"

/* [ 15] VarName  */ "015_Symb_fill"
/* [ 15] Value    */ "65"

/* [ 16] VarName  */ "016_Symb_lineType"
/* [ 16] Value    */ "1"

/* [ 17] VarName  */ "017_Symb_useLineType"
/* [ 17] Value    */ "0"

/* [ 18] VarName  */ "018_Symb_useMaterial"
/* [ 18] Value    */ "1"

/* [ 19] VarName  */ "019_Symb_useSectAttrs"
/* [ 19] Value    */ "1"

/* [ 20] VarName  */ "020_Symb_LightIsOn"
/* [ 20] Value    */ "0"

/* [ 21] VarName  */ "021_Symb_IsAutoOnStoryVisibility"
/* [ 21] Value    */ "0"
}

In the RegisterInterface function:


//------------------------------------------------------
// Interface definitions
//------------------------------------------------------
GSErrCode __ACENV_CALL    RegisterInterface (void)

{
    GSErrCode   err = ACAPI_Register_Subtype ('SKLT', 132, true, 32611, 32602, 32603, TBoxGroup_Openings,
                                              API_TBoxEnabled_FloorPlan + API_TBoxEnabled_ModelSection + API_TBoxEnabled_3D, 132);
    return err;
}   // RegisterInterface

Requirements

Version: API 4.1 or later

Header: ACAPinc.h

Parameters

Return Values

Remarks

Example

Requirements

See Also