Appends a custom panel to an element settings dialog.

    GSErrCode  ACAPI_Register_SettingsPanel (
        Int32                   refCon,
        const API_ElemType&     tool,
        short                   iconId,
        short                   stringId,
        short                   pageId,
        short                   growType,
        bool                    visibleByDefault
    );

 

Parameters

refCon

[in] Unique reference number chosen for this panel

tool

[in] The element type that identifies the settings dialog

iconId

[in] Panel icon resource ID

stringId

[in] Title text to appear in the handler area of the panel

pageId

[in] Dialog resource ID of the tabpage

growType 

[in] Grow type of the tab page: can be DG_DLG_NOGROW, DG_DLG_HGROW, DG_DLG_VGROW, or DG_DLG_HGROW | DG_DLG_VGROW. This parameter is optional, the default is DG_DLG_NOGROW.

visibleByDefault 

[in] Show or hide the panel by default (optional parameter, false if omitted)

 

Return Values

APIERR_BADPARS

The passed element type is invalid.

APIERR_BADID

The passed tool / variation parameter pair does not identify a valid toolbox item (including invisible tools).

NoError

The function has completed with success.

For other common API errors see the API Errors document.

 

Remarks

This function appends a new panel into an element settings dialog specified by tool and variation. In order to get panel create/destroy events you must install the panel handler callback functions with ACAPI_Install_PanelHandler.

For more details refer to the general description of Custom Panels in Settings Dialogs.

From version 26 the tool and variation parameters were merged into a single API_ElemType parameter.

 

Example

Resources in the GRC file:

'STR#' 32550 "Panel test settings page" {
/* [  1] */         "Panel test settings page"
}

'GDLG' 32701  TabPage           0    0  444   50  "Panel test settings page" {
/* [  1] */ LeftText            0    3   80   18  LargePlain  vCenter  "Alternate Name:"
/* [  2] */ TextEdit           84    4  136   16  LargePlain  15
/* [  3] */ LeftText            0   28   50   18  LargePlain  vCenter  "U-Value:"
/* [  4] */ RealEdit           84   29   40   16  LargePlain  "0.0" "10.0"
/* [  5] */ LeftText          224   28   50   18  LargePlain  vCenter  "Height:"
/* [  6] */ LengthEdit        278   29   70   16  LargePlain  "0.0" "1000000"
}

'GICN' 32650  "Settings page icon" {
        "Panel_Icon"
}

Registration in the RegisterInterface function:

// -----------------------------------------------------------------------------
// Interface definitions
// -----------------------------------------------------------------------------
GSErrCode    __ACENV_CALL   RegisterInterface (void)
{
    GSErrCode err = ACAPI_Register_SettingsPanel (1, API_WallID, 32650, 32550, 32701);
    if (err != NoError) {
        DBPRINTF ("Panel_Test add-on: Cannot register element settings panel\n");
    }

    return NoError;
}

 

Requirements

Version: API 4.1 or later

Header: ACAPinc.h

 

See Also

API_ElemType
ACAPI_Install_PanelHandler
ACAPI_Register_InfoBoxPanel
ACAPI_Register_AttributePanel
Custom Panels in Settings Dialogs
API Functions