API_Favorite |

A container for Favorite entry settings.

    typedef struct {
        GS::UniString                                            name;
        API_Element                                              element;
        GS::Optional<API_ElementMemo>                            memo;
        GS::Optional<API_Element>                                elementMarker;
        GS::Optional<API_ElementMemo>                            memoMarker;
        GS::Optional<GS::Array<API_Property>>                    properties;
        GS::Optional<GS::Array<GS::Pair<API_Guid, API_Guid>>>    classifications;
        GS::Optional<GS::Array<API_ElemCategoryValue>>           elemCategoryValues;
        GS::Optional<API_FavoriteFolderHierarchy>                folder;
        GS::Optional<GS::Array<API_SubElement>>         	 subElements;
    } API_Favorite;

Members

name: Unique name identifier of the Favorite.
element: The element settings of the Favorite.
memo: (Optional) The element memo settings of the Favorite.
elementMarker: (Optional) The marker element settings of the Favorite.
memoMarker: (Optional) The marker element’s memo settings of the Favorite.
properties: (Optional) The properties of the Favorite.
classifications: (Optional) The classification system and classification item pairs of the Favorite.
elemCategoryValues: (Optional) The element categories of the Favorite.
folder: (Optional) The folder of the Favorite.
subElements: (Optional) The subelements of the Favorite ().

Remarks

This structure is used by the Favorite API functions.

In case of ACAPI_Favorite_Get and ACAPI_Favorite_Change functions you just have to set the name field for identifying the Favorite and set which optional fields do you want to retrieve/change.

Do not forget to call ACAPI_DisposeElemMemoHdls for the memo and memoMarker fields if you set them and they are not needed any more.

The API_FavoriteFolderHierarchy type is a typedef of GS::Array<GS::UniString>.

In Archicad 25 the subElements member was introduced.

Example


// -----------------------------------------------------------------------------
// Change favorite named "Favorite_Test"
//  - set it's ID string to "[Changed]"
// -----------------------------------------------------------------------------

static void     Do_ChangeFavorite (void)
{
    GSErrCode           err;
    API_Favorite        favorite ("Favorite_Test");

    favorite.memo.New ();
    BNZeroMemory (&favorite.memo.Get (), sizeof (API_ElementMemo));
    favorite.memo->elemInfoString = new GS::UniString ("[Changed]");

    ACAPI_WriteReport ("### Favorite_Test Do_ChangeFavorite ###", false);

    err = ACAPI_Favorite_Change (favorite, nullptr, APIMemoMask_ElemInfoString);
    if (err != NoError) {
        if (err == APIERR_BADNAME)
            ACAPI_WriteReport ("ACAPI_Favorite_Change failed because bad name was given", false);
        else if (err == APIERR_NOTMINE)
            ACAPI_WriteReport ("ACAPI_Favorite_Change failed because the given favorite does not belong to the client", false);
        else
            ACAPI_WriteReport ("ACAPI_Favorite_Change failed", false);
    } else {
        ACAPI_WriteReport ("ACAPI_Favorite_Change successfully changed favorite named \"%T\"", false, favorite.name.ToPrintf ());
    }

    ACAPI_DisposeElemMemoHdls (&favorite.memo.Get ());

    return;
}       /* Do_ChangeFavorite */

For further informations and examples, please see the documentation of the related Favorite API functions or the Favorite_Test example Add-On.

Requirements

Version: API 23 or later

Header: APIdefs_Favorite.h

Members

Remarks

Example

Requirements

See Also