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

Classes
class	ACAPI::Favorite::Favorite
	Favorite class represents a favorite element in the Archicad Favorite Manager. More...

class	ACAPI::Favorite::FavoriteFolder
	FavoriteFolder class represents a favorite folder in the Archicad Favorite Manager. More...

class	ACAPI::Favorite::FavoriteManager
	FavoriteManager class is the manager class for the Archicad Favorite Manager. More...

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

Enumerations
enum class	ACAPI::Favorite::FavoriteManager::ConflictPolicy { ACAPI::Favorite::FavoriteManager::ConflictPolicy::Error , ACAPI::Favorite::FavoriteManager::ConflictPolicy::Skip , ACAPI::Favorite::FavoriteManager::ConflictPolicy::OverwriteExisting , ACAPI::Favorite::FavoriteManager::ConflictPolicy::RenameNew }
	Options for handling conflicts while creating and importing favorites. More...

Functions
FavoriteManager	ACAPI::Favorite::GetFavoriteManager ()
	Creates a Favorite Manager instance.

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.

Enumeration Type Documentation

◆ ConflictPolicy

enum class ACAPI::Favorite::FavoriteManager::ConflictPolicy

strong

Options for handling conflicts while creating and importing favorites.

Enumerator
Error	The create/import process will fail if a conflict is detected.
Skip	The create/import process will skip the conflicting favorites.
OverwriteExisting	The create/import process will overwrite the conflicting favorites.
RenameNew	The create/import process will create a unique name for the new conflicting 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]"

// -----------------------------------------------------------------------------

void Do_ChangeFavorite (void)

{

GSErrCode err;

API_Favorite favorite ("Favorite_Test");

favorite.memo.New ();

favorite.memo.Get () = {};

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;

}

◆ 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

// -----------------------------------------------------------------------------

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;

}

Classes

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ ConflictPolicy

Function Documentation

◆ ACAPI_Favorite_Change()

◆ ACAPI_Favorite_Create()

◆ ACAPI_Favorite_Delete()

◆ ACAPI_Favorite_Export()

◆ ACAPI_Favorite_Get()

◆ ACAPI_Favorite_GetNum()

◆ ACAPI_Favorite_GetPreviewImage()

◆ ACAPI_Favorite_Import()

◆ ACAPI_Favorite_Read()

◆ ACAPI_Favorite_Rename()

◆ GetFavoriteManager()