Dialog and Palette integration

Dialog and Palette managent, and Integration to existing dialogs. More...

Classes
struct	API_PolygonExt
	Representation of a 2D polygon and the 3D transformation plane. More...
class	API_AttributeIndex
	Index reference to an attribute. More...
struct	API_RGBColor
	RGB color reference. More...
struct	API_Polygon
	Representation of a two dimensional polygon. More...
struct	API_Plane3D
	Desribes a 3D plane. More...
struct	API_SunAngleSettings
	Sun angle settings. More...
struct	API_PerspPars
	Perspective projection parameters. More...
struct	API_StairType
	Represents a Stair element. More...
struct	API_PetPaletteType
	Parameters for performing user input with pet palette. More...
struct	API_UCCallbackType
	Describes the attribute set to be used in a user control dialog item. More...
struct	API_ObjectSettingsPars
	Defines the parameters of the Object Settings dialog. More...
class	API_AttributePickerParams
	Describes the type and the push check for creating an attribute picker in ACAPI_Dialog_CreateAttributePicker. More...
class	API_AttributePicker
	Describes an attribute picker created in ACAPI_Dialog_CreateAttributePicker, with getter and setter for the selected attribute and the hanlder of push check click event. More...
struct	API_AttributeFolderPickerParams
	Describes the type and the push check for creating an attribute folder picker in ACAPI_Attribute_CreateAttributeFolderPicker. More...
struct	API_AddParType
	Describes a parameter of a Library Part. More...

Typedefs
typedef GSErrCode	APIPetPaletteCallBackProc(short actValue)
	User supplied callback procedure during pet palette input.

Enumerations
enum	API_RenovationStatusType {   API_UndefinedStatus = -1 , API_DefaultStatus = 0 , API_ExistingStatus = 1 , API_NewStatus = 2 ,   API_DemolishedStatus = 3 }
	Renovation status of the (primitive) element.
enum	API_ColorDepthID {   APIColorDepth_FromSourceImage = -1 , APIColorDepth_BW = 0 , APIColorDepth_16C , APIColorDepth_256C ,   APIColorDepth_16G , APIColorDepth_256G }
enum	API_BoundaryDisplay { APIBound_UncutContours = 1 , APIBound_NoContours = 2 , APIBound_OverrideContours = 3 }
	Boundary display options.
enum	API_CutPlanePlanConn { APICutPl_Online = 0 , APICutPl_Offline = 1 , APICutPl_Drawing = 2 }
	Define the status of the link between the Section/Elevation and the Floor Plan. More...
enum	API_SunAngleSettings_SunPositionOption { API_SunPosition_GivenByAngles = 0 , API_SunPosition_GivenByDate = 1 }
	Sun position options for calculating Sun's angles. More...
enum	API_UserControlType {   APIUserControlType_Pen , APIUserControlType_PenWithNull , APIUserControlType_PolyFill , APIUserControlType_WallFill ,   APIUserControlType_WallCompFill , APIUserControlType_AllFill , APIUserControlType_AllFillGradNoComp , APIUserControlType_WallSetsFill ,   APIUserControlType_WallComposites , APIUserControlType_SlabSetsFill , APIUserControlType_SlabComposites , APIUserControlType_RoofSetsFill ,   APIUserControlType_RoofComposites , APIUserControlType_ShellSetsFill , APIUserControlType_ShellComposites , APIUserControlType_OnlyCompFill ,   APIUserControlType_Material , APIUserControlType_MaterialWithGeneral , APIUserControlType_Layer , APIUserControlType_ZoneCategory ,   APIUserControlType_DashedLine , APIUserControlType_SymbolLine , APIUserControlType_CoverFill , APIUserControlType_WallProfile ,   APIUserControlType_BeamProfile , APIUserControlType_ColumnProfile , APIUserControlType_AllProfile , APIUserControlType_PolyFillWithGradient ,   APIUserControlType_BuildingMaterial , APIUserControlType_HandrailProfile , APIUserControlType_OtherGDLObjectProfile , APIUserControlType_BeamAndColumnProfile }
	Describes the different types of user controls. More...
enum	API_AddParID : Int32 {   API_ZombieParT = 0 , APIParT_Integer , APIParT_Length , APIParT_Angle ,   APIParT_RealNum , APIParT_LightSw , APIParT_ColRGB , APIParT_Intens ,   APIParT_LineTyp , APIParT_Mater , APIParT_FillPat , APIParT_PenCol ,   APIParT_CString , APIParT_Boolean , APIParT_Separator , APIParT_Title ,   APIParT_BuildingMaterial , APIParT_Profile , APIParT_Dictionary }
	Possible types of a Library Part additive parameter. More...

Functions
GSErrCode	ACAPI_LibraryManagement_OpenLibraryPart (const API_OpenLibPartInfo *libPartToOpen)
	Opens the given library part in the Library Part Editor window.
GSErrCode	ACAPI_LibraryManagement_ResetLibraries ()
	Resets the loaded libraries.
GSErrCode	ACAPI_Dialog_ActivateSessionReport ()
	Activates the session report window.
GSErrCode	ACAPI_Dialog_PetPalette (API_PetPaletteType *petPaletteInfo, APIPetPaletteCallBackProc *petPaletteProc)
	Opens a pet palette for performing user input from the add-on.
GSErrCode	ACAPI_Dialog_SetUserControlCallback (API_UCCallbackType *callbackType)
	Helper function to set the proper attribute callback for a user control.
GSErrCode	ACAPI_Dialog_ObjectSettings (API_ObjectSettingsPars *objectSettingsPars)
	Opens the Object/Lamp(/Window/Door) Settings dialog.
GSErrCode	ACAPI_Dialog_SettingsDialog (API_ToolBoxItem *toolBoxItem, const API_Guid *guid=nullptr, const UShort *indexOfSubTool=nullptr)
	Opens a tool settings dialog.
GSErrCode	ACAPI_Dialog_SettingsDialog (const API_Guid *dialogTestID=nullptr, const UShort *indexOfSubTool=nullptr)
	Opens the settings dialog of the current tool or current selection.
GSErrCode	ACAPI_Dialog_SaveLibPartFileDialog (bool *retCode, IO::Location *location, bool *browseForFolder=nullptr, GS::UniString *dialogTitle=nullptr, GS::UniString *dialogTypeStr=nullptr)
	Opens the Save Library Part dialog and returns the selected location.
GSErrCode	ACAPI_Dialog_OpenLibPartFileDialog (bool *retCode, IO::Location *location, bool *isGSM, bool *wasExternalEditorInvoked)
	Invokes the "Open Library Part" dialog.
GSErrCode	ACAPI_Dialog_OpenPictureDialog (bool *retCode, IO::Location *location)
	Opens an "Open Picture" dialog (same dialog as on Material Settings, Texture tabpage).
GSErrCode	ACAPI_Dialog_OpenOtherObjectDialog (bool *retCode, IO::Location *location, bool *isRoom)
	Invokes the "Open Library" dialog.
GSErrCode	ACAPI_UnregisterModelessWindow (Int32 referenceID)
	Ends the registration of an add-on's modeless palette with the API.
void	ACAPI_WriteReport (const GS::UniString &format, bool withDial,...)
	Writes a report string into the Report Windowot into a custom alert window.
GSErrCode	ACAPI_Dialog_CreateAttributePicker (const API_AttributePickerParams &attributePickerParams, GS::Owner< API_AttributePicker > &attributePicker)
	Enables the attribute picker functionality for a push check, if the user clicks the push check, the picker will open. Attributes pickers can be used to choose an attribute. On these new pickers, the folder structure and searching functionality is enabled.
GSErrCode	ACAPI_RegisterTeamworkReserveInterface (const API_Guid &objectId, short dialogId, short tabId, short tabResId, GSResModule resModule, GSResModule dialogIconResModule, APIReservationTeamWorkPanelParentUIRefreshNeededProc *teamworkPanelParentUIRefreshNeeded, APIReservationTeamWorkPanelParentDataSaveNeededProc *teamworkPanelParentDataSaveNeeded, const GS::UniString &requestMessage, API_TWAccessRights createRight=APINoPermission, API_TWAccessRights deleteModifyRight=APINoPermission)
	Registers an interface supporting reserve/release in teamwork operations.
GSErrCode	ACAPI_UnregisterTeamworkReserveInterface (const API_Guid &objectId, short dialogId=0)
	Unregisters a previously registered interface.
GSErrCode	ACAPI_RefreshTeamworkReserveInterface (const API_Guid &objectId, short dialogId, bool isTeamWorkPanelParentUIRefreshNeeded=false)
	Refreshes the registered teamwork interface.
GSErrCode	ACAPI_Teamwork_SendReleaseCommentMail (const API_Guid &objectId, short dialogId)
	Sends the release comment mail.

Detailed Description

Dialog and Palette managent, and Integration to existing dialogs.

Typedef Documentation

APIPetPaletteCallBackProc

typedef GSErrCode APIPetPaletteCallBackProc(short actValue)

User supplied callback procedure during pet palette input.

Parameters

actValue

[in] The current value of the pet palette control.

Returns

• NoError - The function has completed with success.

Remarks

When you open a pet palette with the ACAPI_Dialog_PetPalette ACAPI_Interface function, this callback procedure will be called whenever the user chooses a new item on the pet palette.

Enumeration Type Documentation

API_AddParID

enum API_AddParID : Int32

Possible types of a Library Part additive parameter.

Remarks

This identifier is mainly referenced from the API_AddParType structure.

API_ColorDepthID

enum API_ColorDepthID

Various options for color depth.

API_CutPlanePlanConn

enum API_CutPlanePlanConn

Define the status of the link between the Section/Elevation and the Floor Plan.

Remarks

From Archicad 9 it's possible to set the status of the link between the Section/Elevation and the Floor Plan (see API_CutPlaneType).

API_SunAngleSettings_SunPositionOption

enum API_SunAngleSettings_SunPositionOption

Sun position options for calculating Sun's angles.

Remarks

The options correspond to the different Sun position setting choices in the "3D Projection Settings..." dialog of Archicad.

API_UserControlType

enum API_UserControlType

Describes the different types of user controls.

Remarks

These are the special constants used in ACAPI_Dialog_SetUserControlCallback (...) function. They define the attribute set used in the user control.

Function Documentation

ACAPI_Dialog_ActivateSessionReport()

GSErrCode ACAPI_Dialog_ActivateSessionReport

(

)

Activates the session report window.

Since

Archicad 26

Returns

• NoError - The function has completed with success.

Remarks

This function is used to open the session report window after important informations were written in it. See also ACAPI_WriteReport.

ACAPI_Dialog_CreateAttributePicker()

GSErrCode ACAPI_Dialog_CreateAttributePicker	(	const API_AttributePickerParams &	attributePickerParams,
		GS::Owner< API_AttributePicker > &	attributePicker
	)

Enables the attribute picker functionality for a push check, if the user clicks the push check, the picker will open. Attributes pickers can be used to choose an attribute. On these new pickers, the folder structure and searching functionality is enabled.

Since

Archicad 26

Parameters

attributePickerParams	[in] Parameters of attribute picker (type of the attribute, the parameters of push check).
attributePicker	[out] The constructed picker.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - Incorrect attributePickerParams was specified.

ACAPI_Dialog_ObjectSettings()

GSErrCode ACAPI_Dialog_ObjectSettings

(

API_ObjectSettingsPars *

objectSettingsPars

)

Opens the Object/Lamp(/Window/Door) Settings dialog.

Parameters

objectSettingsPars

[in/out] The parameters to open the dialog with. Also contains the selected object on return.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - objectSettingsPars is nullptr.
• APIERR_BADID - objectSettingsPars contains invalid data.

Remarks

The Settings dialog may show only library parts with a given subtype. The default library part's library index can also be passed onto this function. It returns the parameters set in the Settings dialog, and also the additional parameters of the selected library part. If subtypeID is an empty string, then the passed typeID and variationID will be used to identify the tool whose subtype will serve as a filter. If libIndex is 0 (i.e. you haven't used ACAPI_LibraryPart_Search to find an appropriate library item), then the function tried to find the first item in the loaded libraries, whose subtype matches the passed subTypeID (or typeID and variationID). The linked properties information specified on the Listing and Labeling page returns in the propIndivLibInd and propCriteria fields. These properties should be linked to the element you would create after calling the Object Settings dialog (see ACAPI_ElementLink_SetLinkedPropertyObjects).

Example

GSErrCode SelectObject (void)
{
    GSErrCode    err = NoError;
    API_ObjectSettingsPars api_objSetPars;
 
    BNZeroMemory (&api_objSetPars, sizeof (API_ObjectSettingsPars));
 
    api_objSetPars.elemDef.object.head.type = API_ObjectID;    // this tells the API which dialog it should bring up
    CHCopyC ("{D65FA25D-A6D4-48A4-BD9B-2DFE16D58297}-{0D053320-4961-4B12-A2C3-BEA101B0E56F}", api_objSetPars.subtypeID);
    // GUID of Gas Supply Terminal subtype                       // the appropriate subtype should be copied here; it'll be used for filtering
 
    err = ACAPI_Interface (APIIo_ObjectSettingsID
, &api_objSetPars, nullptr);
    if (err == NoError) {
        char msgStr[256];
        sprintf (msgStr, "Object #%d was selected!", api_objSetPars.elemDef.object.libInd);
        ACAPI_WriteReport (msgStr, true);
 
        // Create an object element:
        {
            API_Element     element;
            API_ElementMemo memo;
            BNZeroMemory (&element, sizeof (API_Element));
            BNZeroMemory (&memo, sizeof (API_ElementMemo));
 
            element.object = api_objSetPars.elemDef.object;
            element.object.pos.x = ...x...;
            element.object.pos.y = ...y...;
            element.header.floorInd = ...story...;
            memo.params = api_objSetPars.addPars;
 
            err = ACAPI_CallUndoableCommand ("...",
                [&] () -> GSErrCode {
                    GSErrCode err1 = ACAPI_Element_Create (&element, &memo);
                    if (err1 == NoError)
                        err1 = ACAPI_ElementLink_SetLinkedPropertyObjects (&element.header, api_objSetPars.propCriteria, api_objSetPars.propIndivLibInd);
                    return err1;
                });
        }
    }
 
    if (api_objSetPars.addPars != nullptr)
        ACAPI_DisposeAddParHdl (&api_objSetPars.addPars);    // do not forget to dispose the handle
 
    return err;
}

ACAPI_Dialog_OpenLibPartFileDialog()

GSErrCode ACAPI_Dialog_OpenLibPartFileDialog	(	bool *	retCode,
		IO::Location *	location,
		bool *	isGSM,
		bool *	wasExternalEditorInvoked
	)

Invokes the "Open Library Part" dialog.

Since

Archicad 26

Parameters

retCode	Return code is true when a valid gsm file is successfully opened in the "Open Library Part" dialog.
location	Location of the selected library part.
isGSM	[in] Optional parameter. If it is set to true, the file filter in the open dialog is set to "General GDL Objects".
wasExternalEditorInvoked	[out] Optional parameter. If it is set to true, the file was opened using an external editor.

Returns

• NoError - The function has completed with success.

Remarks

This function invokes the "Open Library Part" dialog, and returns the chosen library part's location.

ACAPI_Dialog_OpenOtherObjectDialog()

GSErrCode ACAPI_Dialog_OpenOtherObjectDialog	(	bool *	retCode,
		IO::Location *	location,
		bool *	isRoom
	)

Invokes the "Open Library" dialog.

Since

Archicad 26

Parameters

retCode	[out] Return code. True if the zone stamp or label object file selected in the file open dialog was opened successfully.
location	The location of the library part.
isRoom	[in] Optional parameter. Defines the type of the file in the file open dialog (true - the file type is Zone, nullptr or false - the file type is Label)

Returns

• NoError - The function has completed with success.

Remarks

This function is used to let the user open a file of type Zone Stamp or Label, using the Open File Dialog. The location is set only if a valid Zone Stamp or Label file was selected in the "Open File" dialog.

ACAPI_Dialog_OpenPictureDialog()

GSErrCode ACAPI_Dialog_OpenPictureDialog	(	bool *	retCode,
		IO::Location *	location
	)

Opens an "Open Picture" dialog (same dialog as on Material Settings, Texture tabpage).

Since

Archicad 26

Parameters

retCode	[out] True if a valid picture format file is selected in the "Open Picture" dialog.
location	[out] The location of the selected Picture format file.

Returns

• NoError - The function has completed with success.

Remarks

Invokes the Open Picture (Load Image from Library) dialog, and returns the chosen picture's location. Also adds the chosen picture to the Embedded Library if it was not part of that previously.

ACAPI_Dialog_PetPalette()

GSErrCode ACAPI_Dialog_PetPalette	(	API_PetPaletteType *	petPaletteInfo,
		APIPetPaletteCallBackProc *	petPaletteProc
	)

Opens a pet palette for performing user input from the add-on.

Parameters

petPaletteInfo	[in] identifies the pet palette.
petPaletteProc	[in] callback procedure for the palette.

Returns

• 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, thanindicated by nCols * nRows. The supplied petPaletteID collides with abuilt-in Archicad petpalette identifier. Choosing the old pictID for identifier is a good idea. The supplied petPaletteIDcollides withanother petpalette, which differs from the actual one: it hasmore or less items, or it has the same number of items, butat 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).

ACAPI_Dialog_SaveLibPartFileDialog()

GSErrCode ACAPI_Dialog_SaveLibPartFileDialog	(	bool *	retCode,
		IO::Location *	location,
		bool *	browseForFolder = nullptr,
		GS::UniString *	dialogTitle = nullptr,
		GS::UniString *	dialogTypeStr = nullptr
	)

Opens the Save Library Part dialog and returns the selected location.

Parameters

retCode	[out] returns whether the dialog was closed with confirmation (OK, Save, etc.)
location	[in/out] sets the default library and filename to open the dialog with, and returns the location of the chosen file
browseForFolder	[in] enables the dialog to save Library Parts outside the Embedded Library (optional; the default value is false)
dialogTitle	[in] defines the title of the dialog (optional)
dialogTypeStr	[in] defines the library part type of the dialog (optional); applicable identifiers are: "ExportObjectDialog" (default), "ExportDoorDialog", "ExportWindowDialog"

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - retCode or location is nullptr.

Remarks

Use this function to let the user choose a file location for saving a library part in the loaded libraries. The function needs a valid location to open the dialog from. The location is set only if the dialog was closed with confirmation button (OK, Save, etc.).

Example

bool         done = false;
bool         retIsOk = false;
IO::Location location ("Untitled");
do {
    GSErrCode err = ACAPI_Interface (APIIo_SaveLibPartFileDialogID
, &retIsOk, &location);
    if (err == NoError && retIsOk) {
        API_LibPart libPart;
        BNZeroMemory (&libPart, sizeof (API_LibPart));
 
        IO::Name name;
        location.GetLastLocalName (&name);
 
        CHTruncate (name.ToString ().ToCStr (), libPart.file_Name, sizeof (libPart.file_Name));
        if (ACAPI_LibraryPart_Search (&libPart, false) == NoError) {
            ACAPI_WriteReport ("Library part with this name already exists, please choose different name.", true);
            done = false;
        } else {
            done = true;
        }
        if (libPart.location != nullptr)
            delete libPart.location;
    } else {
        done = true;
    }
} while (!done);

ACAPI_Dialog_SettingsDialog() [1/2]

GSErrCode ACAPI_Dialog_SettingsDialog	(	API_ToolBoxItem *	toolBoxItem,
		const API_Guid *	guid = nullptr,
		const UShort *	indexOfSubTool = nullptr
	)

Opens a tool settings dialog.

Parameters

toolBoxItem	[in] The parameters to open the dialog with.
guid	[in] Special unique identifier of the dialog, used in automated testing.
indexOfSubTool	[in] Index of sub tool to open the dialog at. If the dialog belongs to a hierarchical tool, this parameter can help to open the dialog with the desired sub tool in focus. Indexing starts from 0, which belongs to the first sub tool on the UI. If you do not want to customize this behavior, leave it empty.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - toolBoxItem->type is invalid.
• APIERR_CANCEL - CANCEL was hit.

Remarks

The Settings dialog is identified with toolBoxItem->type.

Example

GSErrCode SettingsDialog (void)
{
    const API_Guid mySettingsDlgGuid = APIGuidFromString ("2A92ACAC-1E8C-40EC-9FAF-3171A07E1729");
 
    API_ToolBoxItem tbi = {};
    tbi.type = API_StairID;
 
    UShort indexOfSubTool = 3;
 
    return ACAPI_Interface (APIIo_SettingsDialogID
, &tbi, &mySettingsDlgGuid, &indexOfSubTool);
}

ACAPI_Dialog_SettingsDialog() [2/2]

GSErrCode ACAPI_Dialog_SettingsDialog	(	const API_Guid *	dialogTestID = nullptr,
		const UShort *	indexOfSubTool = nullptr
	)

Opens the settings dialog of the current tool or current selection.

Parameters

dialogTestID	[in] Special unique identifier of the dialog, used in automated testing.
indexOfSubTool	[in] Index of sub tool to open the dialog at. If the dialog belongs to a hierarchical tool, this parameter can help to open the dialog with the desired sub tool in focus. Indexing starts from 0, which belongs to the first sub tool on the UI. If you do not want to customize this behavior, leave it empty.

Returns

• NoError - The function has completed with success.
• APIERR_CANCEL - CANCEL was hit.

Remarks

Opens the Settings Dialog for the last selected element. If no element is selected, the Settings Dialog of the current tool will be opened.

Example

GSErrCode SettingsDialog (void)
{
    const API_Guid mySettingsDlgGuid = APIGuidFromString ("2A92ACAC-1E8C-40EC-9FAF-3171A07E1729");
 
    API_ToolBoxItem tbi = {};
    tbi.type = API_StairID;
 
    UShort indexOfSubTool = 3;
 
    return ACAPI_Interface (APIIo_SettingsDialogID
, &tbi, &mySettingsDlgGuid, &indexOfSubTool);
}

ACAPI_Dialog_SetUserControlCallback()

GSErrCode ACAPI_Dialog_SetUserControlCallback

(

API_UCCallbackType *

callbackType

)

Helper function to set the proper attribute callback for a user control.

Parameters

callbackType

[in] identifies the control to set the callback for.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - callbackType is nullptr, or the supplied dialogID is invalid.
• APIERR_BADID - the given dialog is closed, or the supplied callback type is invalid.

Remarks

This function provides an easy way for your user control items to use the default attribute set in the server application. By settings this callback, you don't have to write your own.

Example

API_UCCallbackType   ucb;
GSErrCode            err;
 
// initialize user controls
BNZeroMemory (&ucb, sizeof (ucb));
ucb.dialogID = TAB_ATTRIBUTE;            // dialog or tab page ID
ucb.type     = APIUserControlType_Pen;   // control type
ucb.itemID   = IDC_PENSET;               // user control's item ID
err = ACAPI_Interface (APIIo_SetUserControlCallbackID
, &ucb);

ACAPI_LibraryManagement_OpenLibraryPart()

GSErrCode ACAPI_LibraryManagement_OpenLibraryPart

(

const API_OpenLibPartInfo *

libPartToOpen

)

Opens the given library part in the Library Part Editor window.

Parameters

libPartToOpen

[in] Identifies the library part to open.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed library part information is incorrect.

Remarks

First it tries to open by the document name, then the file name (which may come from the location).

ACAPI_LibraryManagement_ResetLibraries()

GSErrCode ACAPI_LibraryManagement_ResetLibraries

(

)

Resets the loaded libraries.

Returns

• NoError - The function completed with success.
• APIERR_NOTMINE - The project library list is not editable in Teamwork. You need to reserve it first.

Remarks

All the currently selected libraries will go away. You can use this command to prepare for defining your own set of libraries. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Warning

Legacy function - to be deleted in future versions, use ACAPI::Library::LibraryManager::RemoveLibrary instead

ACAPI_RefreshTeamworkReserveInterface()

GSErrCode ACAPI_RefreshTeamworkReserveInterface	(	const API_Guid &	objectId,
		short	dialogId,
		bool	isTeamWorkPanelParentUIRefreshNeeded = false
	)

Refreshes the registered teamwork interface.

Parameters

objectId	[in] The unique identifier of this interface (that you passed during registration).
dialogId	[in] The dialog ID you registered the interface for.
isTeamWorkPanelParentUIRefreshNeeded	[in] Update the parent UI as well?

Returns

• NoError - The function completed with success.

ACAPI_RegisterTeamworkReserveInterface()

GSErrCode ACAPI_RegisterTeamworkReserveInterface	(	const API_Guid &	objectId,
		short	dialogId,
		short	tabId,
		short	tabResId,
		GSResModule	resModule,
		GSResModule	dialogIconResModule,
		APIReservationTeamWorkPanelParentUIRefreshNeededProc *	teamworkPanelParentUIRefreshNeeded,
		APIReservationTeamWorkPanelParentDataSaveNeededProc *	teamworkPanelParentDataSaveNeeded,
		const GS::UniString &	requestMessage,
		API_TWAccessRights	createRight = APINoPermission,
		API_TWAccessRights	deleteModifyRight = APINoPermission
	)

Registers an interface supporting reserve/release in teamwork operations.

Parameters

objectId	[in] The unique identifier of this interface.
dialogId	[in] The dialog ID you register the interface for.
tabId	[in] The tab page ID you register the interface for.
tabResId	[in] The resource describing the tab page interface elements.
resModule	[in] The resource module identifier that identifies the module containing the tab page interface elements.
dialogIconResModule	[in] The resource module identifier that identifies the module containing the tab page icons.
teamworkPanelParentUIRefreshNeeded	[in] The callback function which is called when you have to refresh the items on the registered interface.
teamworkPanelParentDataSaveNeeded	[in] The callback function which is called before your panel is closed. You can use this function to set an internal state in your add-on which you can use later to perform teamwork-related operations (e.g., reserve or release AddOnObjects).
requestMessage	[in] The request message.
createRight	[in] The teamwork create right you assign to this interface.
deleteModifyRight	[in] The teamwork delete and modify right you assign to this interface.

Returns

• NoError - The function completed with success.
• APIERR_BADPARS - objectId is APINULLGuid or dialogId is 0 or tabId is 0.
• APIERR_NOPLAN - No project is open.
• APIERR_NOTEAMWORKPROJECT - The open project is not a teamwork project.
• APIERR_BADID - objectId is APINULLGuid.

ACAPI_Teamwork_SendReleaseCommentMail()

GSErrCode ACAPI_Teamwork_SendReleaseCommentMail	(	const API_Guid &	objectId,
		short	dialogId
	)

Sends the release comment mail.

Parameters

objectId	[in] The unique identifier of this interface (that you passed during registration).
dialogId	[in] The dialog ID you registered the interface for.

Returns

• NoError - The function completed with success.

ACAPI_UnregisterModelessWindow()

GSErrCode ACAPI_UnregisterModelessWindow

(

Int32

referenceID

)

Ends the registration of an add-on's modeless palette with the API.

Parameters

referenceID

[in] The number to uniquely identify your modeless palette. Use the same ID that was supplied to ACAPI_RegisterModelessWindow.

Returns

• NoError - The function has completed with success.

Remarks

When you close the modeless palette the registration should be ended with this function; call it in the FreeData function.

ACAPI_UnregisterTeamworkReserveInterface()

GSErrCode ACAPI_UnregisterTeamworkReserveInterface	(	const API_Guid &	objectId,
		short	dialogId = 0
	)

Unregisters a previously registered interface.

Parameters

objectId	[in] The unique identifier of this interface (that you passed during registration).
dialogId	[out] The dialog ID you registered the interface for.

Returns

• NoError - The function completed with success.
• APIERR_BADID - objectId is not registered.

ACAPI_WriteReport()

void ACAPI_WriteReport	(	const GS::UniString &	format,
		bool	withDial,
			...
	)

Writes a report string into the Report Windowot into a custom alert window.

Parameters

format	A pointer to the message/format string.
withDial	If true an alert window displaying the report string comes up, otherwise it writes to the Report window.
...	This a variadic argument which supplies the parameters to the format string