Project Info

Functions for managing Project Info groups and fields. More...

Functions
GSErrCode	ACAPI_ProjectInfo_GetGroups (std::vector< API_Guid > &groupGuids)
	Retrieves the GUIDs of all ProjectInfo groups.
GSErrCode	ACAPI_ProjectInfo_GetGroupName (const API_Guid &groupGuid, GS::UniString &name)
	Retrieves the name of a ProjectInfo group.
GSErrCode	ACAPI_ProjectInfo_CreateGroup (const GS::UniString &name, API_Guid &createdGroupGuid)
	Creates a new ProjectInfo group.
GSErrCode	ACAPI_ProjectInfo_RenameGroup (const API_Guid &groupGuid, const GS::UniString &newName)
	Renames a ProjectInfo group.
GSErrCode	ACAPI_ProjectInfo_DeleteGroup (const API_Guid &groupGuid)
	Deletes a ProjectInfo group.
GSErrCode	ACAPI_ProjectInfo_MoveGroup (const API_Guid &groupGuid, const std::optional< API_Guid > &beforeGroupGuid=std::nullopt)
	Moves a ProjectInfo group to a new position.
GSErrCode	ACAPI_ProjectInfo_GetFields (const API_Guid &groupGuid, std::vector< API_Guid > &fieldGuids)
	Retrieves the GUIDs of all fields in a ProjectInfo group, including subfields.
GSErrCode	ACAPI_ProjectInfo_GetField (const API_Guid &fieldGuid, GS::UniString &name, GS::UniString &value)
	Retrieves the name and value of a ProjectInfo field.
GSErrCode	ACAPI_ProjectInfo_CreateField (const API_Guid &groupGuid, const GS::UniString &name, API_Guid &createdFieldGuid)
	Creates a new custom ProjectInfo field in the specified group.
GSErrCode	ACAPI_ProjectInfo_RenameField (const API_Guid &fieldGuid, const GS::UniString &newName)
	Renames a custom ProjectInfo field.
GSErrCode	ACAPI_ProjectInfo_SetFieldValue (const API_Guid &fieldGuid, const GS::UniString &value)
	Sets the value of a ProjectInfo field.
GSErrCode	ACAPI_ProjectInfo_DeleteField (const API_Guid &fieldGuid)
	Deletes a custom ProjectInfo field.
GSErrCode	ACAPI_ProjectInfo_MoveField (const API_Guid &fieldGuid, const API_Guid &toGroupGuid, const std::optional< API_Guid > &beforeFieldGuid=std::nullopt)
	Moves a ProjectInfo field to a new position, possibly in a different group.

Detailed Description

Functions for managing Project Info groups and fields.

Function Documentation

ACAPI_ProjectInfo_CreateField()

GSErrCode ACAPI_ProjectInfo_CreateField	(	const API_Guid &	groupGuid,
		const GS::UniString &	name,
		API_Guid &	createdFieldGuid )

Creates a new custom ProjectInfo field in the specified group.

Since

Archicad 30

Parameters

groupGuid	[in] The GUID of the group to create the field in.
name	[in] The name for the new field.
createdFieldGuid	[out] The GUID of the created field.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The given group GUID does not exist.
• APIERR_NAMEALREADYUSED - A field with the given name already exists.
• APIERR_NOACCESSRIGHT - The user does not have the Teamwork permission to modify Project Info.

Example

GSErrCode CreateCustomField (const API_Guid& groupGuid)
{
    API_Guid createdFieldGuid;
    GSErrCode err = ACAPI_ProjectInfo_CreateField (groupGuid, "My Custom Field", createdFieldGuid);
    if (err == NoError) {
        err = ACAPI_ProjectInfo_SetFieldValue (createdFieldGuid, "Initial Value");
    }
    return err;
}

ACAPI_ProjectInfo_CreateGroup()

GSErrCode ACAPI_ProjectInfo_CreateGroup	(	const GS::UniString &	name,
		API_Guid &	createdGroupGuid )

Creates a new ProjectInfo group.

Since

Archicad 30

Parameters

name	[in] The name for the new group.
createdGroupGuid	[out] The GUID of the created group.

Returns

• NoError - The function has completed with success.
• APIERR_NAMEALREADYUSED - A group with the given name already exists.
• APIERR_NOACCESSRIGHT - The user does not have the Teamwork permission to modify Project Info.

Example

GSErrCode CreateNewGroup ()
{
    API_Guid createdGroupGuid;
    GSErrCode err = ACAPI_ProjectInfo_CreateGroup ("My Custom Group", createdGroupGuid);
    if (err == NoError) {
        ACAPI_WriteReport ("Created group: %s", false, APIGuidToString (createdGroupGuid).ToCStr ().Get ());
    }
    return err;
}

ACAPI_ProjectInfo_DeleteField()

GSErrCode ACAPI_ProjectInfo_DeleteField

(

const API_Guid &

fieldGuid

)

Deletes a custom ProjectInfo field.

Since

Archicad 30

Parameters

fieldGuid

[in] The GUID of the field to delete. Must be a custom (non-fixed) field.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The given field GUID does not exist.
• APIERR_REFUSEDPAR - The field is a fixed (built-in) field and cannot be deleted.
• APIERR_NOACCESSRIGHT - The user does not have the Teamwork permission to modify Project Info.

Example

GSErrCode DeleteCustomField (const API_Guid& fieldGuid)
{
    GSErrCode err = ACAPI_ProjectInfo_DeleteField (fieldGuid);
    if (err == APIERR_REFUSEDPAR) {
        ACAPI_WriteReport ("Cannot delete a fixed (built-in) field", true);
    }
    return err;
}

ACAPI_ProjectInfo_DeleteGroup()

GSErrCode ACAPI_ProjectInfo_DeleteGroup

(

const API_Guid &

groupGuid

)

Deletes a ProjectInfo group.

Since

Archicad 30

Parameters

groupGuid

[in] The GUID of the group to delete.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The given group GUID does not exist.
• APIERR_REFUSEDPAR - The group contains fixed fields and cannot be deleted.
• APIERR_NOACCESSRIGHT - The user does not have the Teamwork permission to modify Project Info.

Example

GSErrCode DeleteGroup (const API_Guid& groupGuid)
{
    GSErrCode err = ACAPI_ProjectInfo_DeleteGroup (groupGuid);
    if (err == APIERR_REFUSEDPAR) {
        ACAPI_WriteReport ("Cannot delete group: it contains fixed fields", true);
    }
    return err;
}

ACAPI_ProjectInfo_GetField()

GSErrCode ACAPI_ProjectInfo_GetField	(	const API_Guid &	fieldGuid,
		GS::UniString &	name,
		GS::UniString &	value )

Retrieves the name and value of a ProjectInfo field.

Since

Archicad 30

Parameters

fieldGuid	[in] The GUID of the field.
name	[out] The name of the field.
value	[out] The value of the field.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The given field GUID does not exist.

Example

GSErrCode GetFieldNameAndValue (const API_Guid& fieldGuid)
{
    GS::UniString name, value;
    GSErrCode err = ACAPI_ProjectInfo_GetField (fieldGuid, name, value);
    if (err == NoError) {
        ACAPI_WriteReport ("Field '%s' = '%s'", false, name.ToCStr ().Get (), value.ToCStr ().Get ());
    }
    return err;
}

ACAPI_ProjectInfo_GetFields()

GSErrCode ACAPI_ProjectInfo_GetFields	(	const API_Guid &	groupGuid,
		std::vector< API_Guid > &	fieldGuids )

Retrieves the GUIDs of all fields in a ProjectInfo group, including subfields.

Since

Archicad 30

Parameters

groupGuid	[in] The GUID of the group.
fieldGuids	[out] Array to be filled with the GUIDs of all fields in the group (including subfields), in order.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The given group GUID does not exist.

Remarks

Subfields of fields are also returned. Subfields are fields whose values contribute to a parent field's calculated value (e.g., address components of a full address field).

Example

GSErrCode ListFieldsInGroup (const API_Guid& groupGuid)
{
    std::vector<API_Guid> fieldGuids;
    GSErrCode err = ACAPI_ProjectInfo_GetFields (groupGuid, fieldGuids);
    if (err == NoError) {
        for (const API_Guid& fieldGuid : fieldGuids) {
            GS::UniString name, value;
            if (ACAPI_ProjectInfo_GetField (fieldGuid, name, value) == NoError) {
                ACAPI_WriteReport ("  %s = %s", false, name.ToCStr ().Get (), value.ToCStr ().Get ());
            }
        }
    }
    return err;
}

ACAPI_ProjectInfo_GetGroupName()

GSErrCode ACAPI_ProjectInfo_GetGroupName	(	const API_Guid &	groupGuid,
		GS::UniString &	name )

Retrieves the name of a ProjectInfo group.

Since

Archicad 30

Parameters

groupGuid	[in] The GUID of the group.
name	[out] The name of the group.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The given group GUID does not exist.

Example

GSErrCode GetGroupName (const API_Guid& groupGuid)
{
    GS::UniString name;
    GSErrCode err = ACAPI_ProjectInfo_GetGroupName (groupGuid, name);
    if (err == NoError) {
        ACAPI_WriteReport ("Group name: %s", false, name.ToCStr ().Get ());
    }
    return err;
}

ACAPI_ProjectInfo_GetGroups()

GSErrCode ACAPI_ProjectInfo_GetGroups

(

std::vector< API_Guid > &

groupGuids

)

Retrieves the GUIDs of all ProjectInfo groups.

Since

Archicad 30

Parameters

groupGuids

[out] Array to be filled with the GUIDs of all groups, in order.

Returns

• NoError - The function has completed with success.

Example

GSErrCode ListProjectInfoGroups ()
{
    std::vector<API_Guid> groupGuids;
    GSErrCode err = ACAPI_ProjectInfo_GetGroups (groupGuids);
    if (err == NoError) {
        for (const API_Guid& groupGuid : groupGuids) {
            GS::UniString name;
            if (ACAPI_ProjectInfo_GetGroupName (groupGuid, name) == NoError) {
                ACAPI_WriteReport ("Group: %s", false, name.ToCStr ().Get ());
            }
        }
    }
    return err;
}

ACAPI_ProjectInfo_MoveField()

GSErrCode ACAPI_ProjectInfo_MoveField	(	const API_Guid &	fieldGuid,
		const API_Guid &	toGroupGuid,
		const std::optional< API_Guid > &	beforeFieldGuid = std::nullopt )

Moves a ProjectInfo field to a new position, possibly in a different group.

Since

Archicad 30

Parameters

fieldGuid	[in] The GUID of the field to move. Must not be a subfield.
toGroupGuid	[in] The GUID of the destination group.
beforeFieldGuid	[in] The GUID of the field before which to move. Pass std::nullopt to move to the end.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - Any of the given GUIDs does not exist.
• APIERR_REFUSEDPAR - The field is a subfield; subfields move automatically with their parent field and cannot be reordered.
• APIERR_NOACCESSRIGHT - The user does not have the Teamwork permission to modify Project Info.

Example

GSErrCode MoveFieldToGroup (const API_Guid& fieldGuid, const API_Guid& toGroupGuid)
{
    return ACAPI_ProjectInfo_MoveField (fieldGuid, toGroupGuid);
}
 
GSErrCode MoveFieldBefore (const API_Guid& fieldGuid, const API_Guid& toGroupGuid, const API_Guid& beforeFieldGuid)
{
    return ACAPI_ProjectInfo_MoveField (fieldGuid, toGroupGuid, beforeFieldGuid);
}

ACAPI_ProjectInfo_MoveGroup()

GSErrCode ACAPI_ProjectInfo_MoveGroup	(	const API_Guid &	groupGuid,
		const std::optional< API_Guid > &	beforeGroupGuid = std::nullopt )

Moves a ProjectInfo group to a new position.

Since

Archicad 30

Parameters

groupGuid	[in] The GUID of the group to move.
beforeGroupGuid	[in] The GUID of the group before which to move. Pass std::nullopt to move to the end.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The given group GUID or beforeGroupGuid does not exist.
• APIERR_NOACCESSRIGHT - The user does not have the Teamwork permission to modify Project Info.

Example

GSErrCode MoveGroupToEnd (const API_Guid& groupGuid)
{
    return ACAPI_ProjectInfo_MoveGroup (groupGuid);
}
 
GSErrCode MoveGroupBefore (const API_Guid& groupGuid, const API_Guid& beforeGroupGuid)
{
    return ACAPI_ProjectInfo_MoveGroup (groupGuid, beforeGroupGuid);
}

ACAPI_ProjectInfo_RenameField()

GSErrCode ACAPI_ProjectInfo_RenameField	(	const API_Guid &	fieldGuid,
		const GS::UniString &	newName )

Renames a custom ProjectInfo field.

Since

Archicad 30

Parameters

fieldGuid	[in] The GUID of the field to rename. Must be a custom (non-fixed) field.
newName	[in] The new name for the field.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The given field GUID does not exist.
• APIERR_REFUSEDPAR - The field is a fixed (built-in) field and cannot be renamed.
• APIERR_NAMEALREADYUSED - A field with the given name already exists.
• APIERR_NOACCESSRIGHT - The user does not have the Teamwork permission to modify Project Info.

Example

GSErrCode RenameField (const API_Guid& fieldGuid)
{
    GSErrCode err = ACAPI_ProjectInfo_RenameField (fieldGuid, "New Field Name");
    if (err == APIERR_REFUSEDPAR) {
        ACAPI_WriteReport ("Cannot rename a fixed (built-in) field", true);
    }
    return err;
}

ACAPI_ProjectInfo_RenameGroup()

GSErrCode ACAPI_ProjectInfo_RenameGroup	(	const API_Guid &	groupGuid,
		const GS::UniString &	newName )

Renames a ProjectInfo group.

Since

Archicad 30

Parameters

groupGuid	[in] The GUID of the group to rename.
newName	[in] The new name for the group.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The given group GUID does not exist.
• APIERR_NAMEALREADYUSED - A group with the given name already exists.
• APIERR_NOACCESSRIGHT - The user does not have the Teamwork permission to modify Project Info.

Example

GSErrCode RenameGroup (const API_Guid& groupGuid)
{
    GSErrCode err = ACAPI_ProjectInfo_RenameGroup (groupGuid, "Renamed Group");
    if (err != NoError) {
        ACAPI_WriteReport ("Failed to rename group", true);
    }
    return err;
}

ACAPI_ProjectInfo_SetFieldValue()

GSErrCode ACAPI_ProjectInfo_SetFieldValue	(	const API_Guid &	fieldGuid,
		const GS::UniString &	value )

Sets the value of a ProjectInfo field.

Since

Archicad 30

Parameters

fieldGuid	[in] The GUID of the field. Must not be a field that has subfields.
value	[in] The new value for the field.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - The given field GUID does not exist.
• APIERR_REFUSEDPAR - The field has subfields; its value is calculated automatically from them.
• APIERR_NOACCESSRIGHT - The user does not have the Teamwork permission to modify Project Info.

Example

GSErrCode SetFieldValue (const API_Guid& fieldGuid)
{
    GSErrCode err = ACAPI_ProjectInfo_SetFieldValue (fieldGuid, "New Value");
    if (err == APIERR_REFUSEDPAR) {
        ACAPI_WriteReport ("Cannot set value: field has subfields", true);
    }
    return err;
}