Custom panels in settings dialogs

Custom panels in settings dialogs

From Archicad 8 you have possibility to add user interface components integrated into the standard settings dialogs to handle your custom element and attribute data. You can append your additional panels into the

• element settings dialogs
• attribute settings dialogs
• info box

Registration of panels

First in the RegisterInterface function you should let the server application know that the add-on wants to add a custom panel into one of the settings dialogs. The dialog is specified with element ID and variation in case of element settings, or the attribute ID in case of attribute settings. You must also pass the resource IDs of the relevant interface resources, such as the icon and the title string of the panel and the tabpage dialog itself.

From Archicad 11 an optional visibleByDefault parameter is added to control the default appearance of the panel. If you pass true, the panel will be visible on the specified settings dialog or info box, unless the effective Work Environment settings override the actual visibility of the panel.

In Archicad 12 an optional growType parameter is added to control the grow type (none/horizontal/vertical/both) of the element and attribute settings panel.

The details can be found at the description of the functions:

• ACAPI_AddOnIntegration_RegisterSettingsPanel
• ACAPI_AddOnIntegration_RegisterAttributePanel
• ACAPI_AddOnIntegration_RegisterInfoBoxPanel

Installing the panel handlers

After registering the custom panels the add-on should initialize the handlers in its Initialize function. In order to be called in the program starting phase the add-on must be preloaded type, that is the return value of the CheckEnvironment must be APIAddon_Preload.

The element or attribute settings panel is represented by an object derived from the TBUI::APIToolUIPanel or VBAD::APIAttrUIPanel classes respectively. These classes contain an observer to the tabpage including the element or attribute data, and a reference to the dialog item itself. The observers are supposed to handle the corresponding database and dialog user action events.

In order to utilize these classes the add-on must include the **_UCLib_**, **_UDLib_** and **_VBElemDialogs_** modules. _(The interface of these modules are not documented.)_

When the panel objects are successfully constructed, the panel creation and destruction handler functions should be passed to the API with ACAPI_AddOnIntegration_InstallPanelHandler.

Creating and destroying the tabpages

It is important to know that the tab pages as dialog items are constructed only on demand, that is when the user chooses to open a settings dialog, in which your add-on has registered a custom panel, the Dialog Manager builds up the dialog panel-by-panel. When the dialog construction process arrives to your panel, it calls the installed APIPanelCreateProc, where the add-on can create the dialog items themselves and attach an observer to the tabpage. After closing the settings dialog all panels are destroyed; the APIPanelDestroyProc is called to detach the observer and destruct the tabpage object.

In case of info box panels the create-destroy events happen when the info box switches to and from the corresponding toolbox mode.

You can get more experience regarding this topic by studying the **_Panel_Test_** example add-on.