Favorite Management

Functions related to accessing and manipulating the Favorites. More...

Classes
struct	API_Favorite
	A container for Favorite entry settings. More...

Functions
GSErrCode	ACAPI_Favorite_Get (API_Favorite *favorite)
	Loads the parameters of the given favorite.
GSErrCode	ACAPI_Favorite_Create (const API_Favorite &favorite)
	Creates a new Favorites entry based on the given element.
GSErrCode	ACAPI_Favorite_Change (const API_Favorite &favorite, const API_Element *elementMask=nullptr, const UInt64 memoMask=0)
	Changes an existing Favorite (identifed by name).
GSErrCode	ACAPI_Favorite_Rename (const GS::UniString &oldName, const GS::UniString &newName)
	Renames an existing Favorite (identifed by name).
GSErrCode	ACAPI_Favorite_Delete (const GS::UniString &name)
	Deletes a Favorites entry.
GSErrCode	ACAPI_Favorite_GetNum (const API_ElemType &type, short *count, GS::Array< API_FavoriteFolderHierarchy > *folders, GS::Array< GS::UniString > *names)
	Returns the names and indexes of the contents of the Favorites list, along with the amount of entries, for a given type and variation.
GSErrCode	ACAPI_Favorite_GetPreviewImage (const GS::UniString &name, API_ImageViewID viewType, NewDisplay::NativeImage *nativeImagePtr)
	Returns the favorite preview image.
GSErrCode	ACAPI_Favorite_Import (const IO::Location &location, const API_FavoriteFolderHierarchy &targetFolder, bool importFolders, API_FavoriteNameConflictResolutionPolicy conflictPolicy, GS::UniString *firstConflictName=nullptr)
	Imports the contents of a Favorites file or folder into the plan.
GSErrCode	ACAPI_Favorite_Read (const IO::Location &location, GS::Array< API_Favorite > *favorites)
	Reads the contents of a Favorites file or folder.
GSErrCode	ACAPI_Favorite_Export (const IO::Location &location, const GS::Array< GS::UniString > *names=nullptr)
	Exports the Favorites in the plan into a Favorites file or folder.

Detailed Description

Functions related to accessing and manipulating the Favorites.

Function Documentation

ACAPI_Favorite_Change()

GSErrCode ACAPI_Favorite_Change	(	const API_Favorite &	favorite,
		const API_Element *	elementMask = nullptr,
		const UInt64	memoMask = 0
	)

Changes an existing Favorite (identifed by name).

Parameters

favorite	[in] The Favorite entry settings.
elementMask	[in] Optional parameter for masking the relevant fields of favorite.element.
memoMask	[in] Optional parameter for specifying the relevant parts of the favorite.memo parameter.

Returns

• NoError - The function has completed with success.
• APIERR_BADNAME - Invalid name given (there is no Favorite with the given favorite.name).
• APIERR_GENERAL - The Favorites list entry could not be changed.
• APIERR_BADPARS - Invalid element given (invalid library part ID), or a marker was given with an element that is not an object.
• APIERR_BADCLASSIFICATION - One of the specified classification items is not available for the given element.

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 \"%s\"", false, favorite.name.ToCStr ().Get ());
    }
 
    ACAPI_DisposeElemMemoHdls (&favorite.memo.Get ());
 
    return;
}       /* Do_ChangeFavorite */

ACAPI_Favorite_Create()

GSErrCode ACAPI_Favorite_Create

(

const API_Favorite &

favorite

)

Creates a new Favorites entry based on the given element.

Parameters

favorite

[in] The Favorite entry settings.

Returns

• NoError - The function has completed with success.
• APIERR_BADNAME - Invalid name given.
• APIERR_GENERAL - The new Favorites list entry could not be created.
• APIERR_BADPARS - Invalid element given (invalid library part ID), or a marker was given with an element that is not an object.
• APIERR_BADCLASSIFICATION - One of the specified classification items is not available for the given element.

ACAPI_Favorite_Delete()

GSErrCode ACAPI_Favorite_Delete

(

const GS::UniString &

name

)

Deletes a Favorites entry.

Parameters

name	[in] The name of the Favorites entry to delete.

Returns

• NoError - The function has completed with success.
• APIERR_BADNAME - Invalid name given.
• APIERR_NOTMINE - In Teamwork mode, the given Favorites entry is owned by someone else.

ACAPI_Favorite_Export()

GSErrCode ACAPI_Favorite_Export	(	const IO::Location &	location,
		const GS::Array< GS::UniString > *	names = nullptr
	)

Exports the Favorites in the plan into a Favorites file or folder.

Parameters

location	[in] The path to the file (if the location has the Favorite binary's extension) or folder (otherwise) to export to.
names	[in] The list of the Favorites to export.

Returns

• NoError - The function has completed with success.
• APIERR_NOACCESSRIGHT - The location file or folder couldn't be opened for write.

ACAPI_Favorite_Get()

GSErrCode ACAPI_Favorite_Get

(

API_Favorite *

favorite

)

Loads the parameters of the given favorite.

Parameters

favorite

[in/out] The Favorite entry settings. On input, it identifies the Favorite based on its name. On return, the other fields are filled.

Returns

• NoError - The function has completed with success.
• APIERR_GENERAL - The Favorites list could not be retrieved.
• APIERR_BADPARS - The favorite parameter is nullptr.
• APIERR_BADNAME - Invalid name given (there is no Favorite with the given favorite.name).

Remarks

This function does not create a new element into the database, you must use the ACAPI_Element_Create function to do so.

ACAPI_Favorite_GetNum()

GSErrCode ACAPI_Favorite_GetNum	(	const API_ElemType &	type,
		short *	count,
		GS::Array< API_FavoriteFolderHierarchy > *	folders,
		GS::Array< GS::UniString > *	names
	)

Returns the names and indexes of the contents of the Favorites list, along with the amount of entries, for a given type and variation.

Since

Archicad 26

Parameters

type	[in] The given type of elements.
count	[out] The amount of entries for that type and variation combination in the Favorites list.
folders	[out] The folders of the entries for that type and variation combination in the Favorites list.
names	[out] The names of the entries for that type and variation combination in the Favorites list.

Returns

• NoError - The function has completed with success.
• APIERR_GENERAL - The Favorites list could not be retrieved.

Remarks

The API_FavoriteFolderHierarchy type is a typedef of GS::Array<GS::UniString>. From version 26 the typeID and variationID parameters were merged into a single API_ElemType parameter.

ACAPI_Favorite_GetPreviewImage()

GSErrCode ACAPI_Favorite_GetPreviewImage	(	const GS::UniString &	name,
		API_ImageViewID	viewType,
		NewDisplay::NativeImage *	nativeImagePtr
	)

Returns the favorite preview image.

Parameters

name	[in] The name of the given favorite.
viewType	[in] The type of the view.
nativeImagePtr	[out] A pointer to the preview image.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - If the given nativeImagePtr is nullptr.
• APIERR_BADNAME - If there is no favorite with the given name.

ACAPI_Favorite_Import()

GSErrCode ACAPI_Favorite_Import	(	const IO::Location &	location,
		const API_FavoriteFolderHierarchy &	targetFolder,
		bool	importFolders,
		API_FavoriteNameConflictResolutionPolicy	conflictPolicy,
		GS::UniString *	firstConflictName = nullptr
	)

Imports the contents of a Favorites file or folder into the plan.

Parameters

location	[in] The path to the Favorite file or folder to import.
targetFolder	[in] The folder to import the Favorites to.
importFolders	[in] Specifies if the imported folders should be kept (all Favorites will be imported into the targetFolder otherwise).
conflictPolicy	[in] Specifies what to do when an imported Favorite already exists in the plan. API_FavoriteNameConflictResolutionPolicy Meaning API_FavoriteError If one of the imported Favorites already exists in the plan, return with APIERR_NAMEALREADYUSED and set the firstConflictName parameter to the conflicting name API_FavoriteSkip If an imported Favorite already exists in the plan, keep the old one in the plan, and ignore the imported one. API_FavoriteOverwrite If an imported Favorite already exists in the plan, keep the imported one and delete the old one in the plan. API_FavoriteAppend If an imported Favorite already exists in the plan, generate a new name for the imported one and keep both Favorites.
firstConflictName	[out] The name of the first Favorite that was imported and already existed in the plan. Only filled if the conflictPolicy parameter is API_FavoriteError.

Returns

• NoError - The function has completed with success.
• APIERR_NOACCESSRIGHT - The Favorites list is not editable in a teamwork project.
• APIERR_BADPARS - The location isn't a valid Favorite file or folder path.
• APIERR_NAMEALREADYUSED - The conflictPolicy parameter is API_FavoriteError, and there was a name conflict.

Remarks

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

ACAPI_Favorite_Read()

GSErrCode ACAPI_Favorite_Read	(	const IO::Location &	location,
		GS::Array< API_Favorite > *	favorites
	)

Reads the contents of a Favorites file or folder.

Parameters

location	[in] The path to the Favorite file or folder to read.
favorites	[out] The parameters of the favorites that have been read successfully.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The location isn't a valid Favorite file or folder path.

Remarks

Reads the contents of a Favorite file or folder and returns them without modifying the plan. ACAPI_Favorite_Read combined with ACAPI_Favorite_Create works much like ACAPI_Favorite_Import, however it gives more control, but it is less efficient.

ACAPI_Favorite_Rename()

GSErrCode ACAPI_Favorite_Rename	(	const GS::UniString &	oldName,
		const GS::UniString &	newName
	)

Renames an existing Favorite (identifed by name).

Parameters

oldName	[in] The name of the existing Favorite entry.
newName	[in] The new name.

Returns

• NoError - The function has completed with success.
• APIERR_BADNAME - Invalid name given (empty name is invalid, or there is no Favorite with the given oldName).
• APIERR_GENERAL - The Favorites list entry could not be changed.
• APIERR_NAMEALREADYUSED - newName is already used as a Favorite name.

Example

// -----------------------------------------------------------------------------
// Rename favorite named "Favorite_Test"
//  - appends "[Renamed]" to it's name
// -----------------------------------------------------------------------------
 
static void     Do_RenameFavorite (void)
{
    GSErrCode           err;
    GS::UniString       oldName = "Favorite_Test";
    GS::UniString       newName = oldName + " [Renamed]";
 
    ACAPI_WriteReport ("### Favorite_Test Do_RenameFavorite ###", false);
 
    err = ACAPI_Favorite_Rename (oldName, newName);
    if (err != NoError) {
        if (err == APIERR_BADNAME)
            ACAPI_WriteReport ("ACAPI_Favorite_Rename failed because bad name was given", false);
        if (err == APIERR_NAMEALREADYUSED)
            ACAPI_WriteReport ("ACAPI_Favorite_Rename failed because the new name is alerady in used", false);
        else if (err == APIERR_NOTMINE)
            ACAPI_WriteReport ("ACAPI_Favorite_Rename failed because the given favorite does not belong to the client", false);
        else
            ACAPI_WriteReport ("ACAPI_Favorite_Rename failed", false);
    } else {
        ACAPI_WriteReport ("ACAPI_Favorite_Rename successfully renamed favorite \"%s\" to \"%s\"", false, oldName.ToCStr ().Get (), newName.ToCStr ().Get ());
    }
 
    return;
}       /* Do_RenameFavorite */