AutoTexts

Functions for manipulating and accessing AutoTexts. More...

Enumerations
enum class	API_NoteAutotextID {   MeasuredValue , MeasuredValueToPZ , MeasuredValueToFirstRL , MeasuredValueToSecondRL ,   MeasuredValueToAltitude , MeasuredValueToSO , StoredOriginToPZ , TopElevToPZ ,   TopElevToFirstRL , TopElevToSecondRL , TopElevToAltitude , CoreTopElevToPZ ,   CoreTopElevToFirstRL , CoreTopElevToSecondRL , CoreTopElevToAltitude , CoreBottomElevToPZ ,   CoreBottomElevToFirstRL , CoreBottomElevToSecondRL , CoreBottomElevToAltitude , BottomElevToPZ ,   BottomElevToFirstRL , BottomElevToSecondRL , BottomElevToAltitude , ProjectZeroName ,   FirstReferenceLevelName , SecondReferenceLevelName , AltitudeName , StoredOriginName }
	Identifies the autotexts of the note. More...
enum	API_AppearID { APIApp_Normal , APIApp_Cumu , APIApp_CumuSv , APIApp_Elev }
	Describes the various options for the appearance of the dimensions.
enum	API_AutotextType { APIAutoText_Fixed = 0x00000001 , APIAutoText_Custom = 0x00000002 , APIAutoText_Other = 0x00000004 , APIAutoText_All = APIAutoText_Fixed + APIAutoText_Custom + APIAutoText_Other }
	Type of autotexts used in text and textual label elements. More...

Functions
GSErrCode __ACENV_CALL	ACAPI_AutoText_GetAutoTextFlag (bool *showAutoText)
	Returns the mode flag currently set for autotext replacing in retrieved texts.
GSErrCode __ACENV_CALL	ACAPI_AutoText_ChangeAutoTextFlag (bool *showAutoText)
	Switches autotexts to be replaced with their current values or kept as autotext keys in retrieved texts.
GSErrCode __ACENV_CALL	ACAPI_AutoText_GetAutoTextKeys (char ***keys, char ***values)
	Retrieves all autotext keys and their values.
GSErrCode __ACENV_CALL	ACAPI_AutoText_GetPropertyAutoTextKeyTable (API_Guid *guid, GS::HashTable< GS::UniString, GS::UniString > *keyGuidTable)
	Retrieves the context dependent autotexts keys.
GSErrCode __ACENV_CALL	ACAPI_AutoText_InterpretAutoText (const GS::UniString *autotext, const API_Guid *guid, GS::UniString *value)
	Retrieves the context dependent autotext's value.
GSErrCode __ACENV_CALL	ACAPI_AutoText_GetAutoTexts (GS::Array< GS::ArrayFB< GS::UniString, 3 > > *autotexts, API_AutotextType autotextType)
	Retrieves the key, description and value of the currently available autotexts.
GSErrCode __ACENV_CALL	ACAPI_AutoText_SetAnAutoText (const GS::UniString *autotextDbKey=nullptr, const GS::UniString *autotextValue=nullptr)
	Sets the value of an autotext.
GSErrCode __ACENV_CALL	ACAPI_AutoText_CreateAnAutoText (const API_Guid *guid, const char *uiKey)
	Creates a new entry in the Project Info.
GSErrCode __ACENV_CALL	ACAPI_AutoText_DeleteAnAutoText (const char *dbKey)
	Deletes a custom entry from the Project Info.
GSErrCode __ACENV_CALL	ACAPI_AutoText_GetNoteAutotexts (const API_ElemType &noteOwnerType, std::unordered_map< API_NoteAutotextID, std::unordered_set< API_ElemType > > &elemTypesForAutotextIDs, const GS::Optional< API_AppearID > &dimAppear=GS::NoValue)
	Returns a map that contains an element type set for every available autotext regards to the note owner's type.
GSErrCode __ACENV_CALL	ACAPI_AutoText_GetNoteKeywordForAutotextID (API_NoteAutotextID autotextID, GS::UniString &keyword)
	Returns the unistring keyword for note autotext id.

Detailed Description

Functions for manipulating and accessing AutoTexts.

Enumeration Type Documentation

API_AutotextType

enum API_AutotextType

Type of autotexts used in text and textual label elements.

Remarks

The API_AutotextType values are used for filtering autotext types to be retrieved with the ACAPI_AutoText_GetAutoTexts function.

API_NoteAutotextID

enum class API_NoteAutotextID

strong

Identifies the autotexts of the note.

Since

Archicad 26

Remarks

API_NoteAutotextID helps to identify the note autotexts. The evaluable autotexts depends on the note owner's type.

Function Documentation

ACAPI_AutoText_ChangeAutoTextFlag()

GSErrCode __ACENV_CALL ACAPI_AutoText_ChangeAutoTextFlag

(

bool *

showAutoText

)

Switches autotexts to be replaced with their current values or kept as autotext keys in retrieved texts.

Parameters

showAutoText

[in] The value of the autotext flag to be set.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed showAutoText parameter is nullptr.

Remarks

This function is used to set the flag which determines whether ACAPI_Element_GetMemo function retrieves the original content of the text or textual label element [false] (the database representation), or the interpreted one [true] (what you see on the user interface). You can retrieve this flag with the ACAPI_AutoText_GetAutoTextFlag function.

Example

bool currAutoTextFlag;
ACAPI_Goodies (APIAny_GetAutoTextFlagID, &currAutoTextFlag, nullptr);
bool setAutoTextFlag = false;
ACAPI_Goodies (APIAny_ChangeAutoTextFlagID, &setAutoTextFlag, nullptr);
 
// autotexts now are kept as keys in the retrieved text content
// when calling ACAPI_Element_GetMemo for textual elements
 
ACAPI_Goodies (APIAny_ChangeAutoTextFlagID, &currAutoTextFlag, nullptr);

ACAPI_AutoText_CreateAnAutoText()

GSErrCode __ACENV_CALL ACAPI_AutoText_CreateAnAutoText	(	const API_Guid *	guid,
		const char *	uiKey
	)

Creates a new entry in the Project Info.

Parameters

guid	[in] The guid of the autotext (stored in the database).
uiKey	[in] The string appear in the GUI (Project Info, Insert Autotext dialog).

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The guid or the uiKey parameter is nullptr or uiKey already exists.

Remarks

This function is used to create a new entry in the Project Info. It will apear in the Insert Autotext dialog also. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

bool    InsertAutotext (void)
{
    char* uiKey = {"Created Via API"};
    GS::Guid guid;
    guid.Generate ();
    API_Guid dbKey = GSGuid2APIGuid (guid);
 
    GSErrCode err = ACAPI_Goodies (APIAny_CreateAnAutoTextID, &dbKey, uiKey);
    if (err != NoError)
        DBPrintf ("APIAny_CreateAnAutoTextID function failed.");
 
    if (err == NoError) {
        GS::UniString dbKey ("autotext-");
        dbKey.Append (guid.ToUniString ());
        GS::UniString value ("custom text");
        err = ACAPI_Goodies (APIAny_SetAnAutoTextID, &dbKey, &value);
        if (err != NoError)
            DBPrintf ("APIAny_SetAnAutoTextID function failed.");
    }
}

ACAPI_AutoText_DeleteAnAutoText()

GSErrCode __ACENV_CALL ACAPI_AutoText_DeleteAnAutoText

(

const char *

dbKey

)

Deletes a custom entry from the Project Info.

Parameters

dbKey

[in] The identifier of the autotext (stored in the database).

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The dbKey parameter is nullptr or uiKey already exists.
• APIERR_BADID - The given autotext doesn't exist.

Remarks

This function is used to delete a custom entry from the Project Info. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

bool    DeleteLastAutotext (void)
{
    GS::Array<GS::ArrayFB<GS::UniString, 3> >       autoTexts;
    API_AutotextType    type = APIAutoText_Custom;
 
    GSErrCode err = ACAPI_Goodies (APIAny_GetAutoTextsID, &autoTexts, (void *) (Int32) type);
 
    if (err == NoError && !autoTexts.IsEmpty ()) {
        // delete last custom entry
        const GS::UniString& dbKey = autoTexts[autoTexts.GetSize () - 1][1];
        err = ACAPI_Goodies (APIAny_DeleteAnAutoTextID, (void*)((const char*) dbKey.ToCStr ()), nullptr);
        if (err != NoError)
            DBPrintf ("APIAny_DeleteAnAutoTextID function failed.");
    }
}

ACAPI_AutoText_GetAutoTextFlag()

GSErrCode __ACENV_CALL ACAPI_AutoText_GetAutoTextFlag

(

bool *

showAutoText

)

Returns the mode flag currently set for autotext replacing in retrieved texts.

Parameters

showAutoText

[out] The current value of the autotext flag.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed showAutoText parameter is nullptr.

Remarks

This function is used to get the current mode which determines whether ACAPI_Element_GetMemo function retrieves the original content of the text and textual label element [false] (the database representation), or the interpreted one [true] (what you see on the user interface). Use the ACAPI_AutoText_ChangeAutoTextFlag function to change this flag.

ACAPI_AutoText_GetAutoTextKeys()

GSErrCode __ACENV_CALL ACAPI_AutoText_GetAutoTextKeys	(	char ***	keys,
		char ***	values
	)

Retrieves all autotext keys and their values.

Parameters

keys	[out] Pointer to an array of C strings to be filled with the available autotext keys
values	[out] Pointer to an array of C strings to be filled with the corresponding interpreted values (optional, can be nullptr)

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed keys parameter is nullptr.

Remarks

This function and ACAPI_AutoText_GetAutoTexts can only resolve non-context dependent autotexts like "PROJECTNAME", "PROJECTNUMBER", "COMPANY", "SHORTDATE". For context dependent autotexts please use ACAPI_AutoText_GetPropertyAutoTextKeyTable with ACAPI_AutoText_InterpretAutoText The function allocates memory for the string arrays and for each strings dynamically. Do not forget to dispose the retrieved pointers when you do not need them any more. For the same purpose you can also use the ACAPI_AutoText_GetAutoTexts function. You can modify the value of an autotext with ACAPI_AutoText_SetAnAutoText.

Example

char** keys;
char** values;
 
GSErrCode err = ACAPI_Goodies (APIAny_GetAutoTextKeysID, &keys, &values);
if (err == NoError) {
    Int32 count = BMGetPtrSize (reinterpret_cast<GSPtr> (keys)) / sizeof (char*);
    for (Int32 i = 0; i < count; i++) {
        if (keys[i] == nullptr) {
            BMKillPtr (&values[i]);
            continue;
        }
 
        DBPrintf ("AutoText[%03d] \"%s\" = \"%s\"\n", i, keys[i], values[i]);
 
        BMKillPtr (&keys[i]);
        BMKillPtr (&values[i]);
    }
}
 
BMKillPtr (reinterpret_cast<GSPtr*>(&keys));
BMKillPtr (reinterpret_cast<GSPtr*>(&values));

ACAPI_AutoText_GetAutoTexts()

GSErrCode __ACENV_CALL ACAPI_AutoText_GetAutoTexts	(	GS::Array< GS::ArrayFB< GS::UniString, 3 > > *	autotexts,
		API_AutotextType	autotextType
	)

Retrieves the key, description and value of the currently available autotexts.

Parameters

autotexts	[out] Array of UniString triplets containing description, key and value of an autotext
autotextType	[in] Filter for collecting only the given type of autotexts

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed autotexts parameter is nullptr.

Remarks

This function and ACAPI_AutoText_GetAutoTextKeys can only resolve non-context dependent autotexts like "PROJECTNAME", "PROJECTNUMBER", "COMPANY", "SHORTDATE". For context dependent autotexts please use ACAPI_AutoText_GetPropertyAutoTextKeyTable with ACAPI_AutoText_InterpretAutoText Use this function to get the key, the description (as it is referenced in the user interface of Archicad), and the current value of the autotexts. The autotext data is retrieved in an array of array of UniStrings, so you do not need to free the allocated memory, as it is disposed automatically in the destructor. The UniString triplets contain the autotext data in the following order: description text, database key, value. You can control the range of the autotexts to be retrieved with the API_AutotextType parameter. You can modify the value of an autotext with ACAPI_AutoText_SetAnAutoText.

Example

#include "UniString.hpp"
#include "Array.hpp"
 
GS::Array<GS::ArrayFB<GS::UniString, 3> > autotexts;
API_AutotextType type = APIAutoText_Fixed;
 
GSErrCode err = ACAPI_Goodies (APIAny_GetAutoTextsID, &autotexts, (void *) (Int32) type);
if (err == NoError) {
    for (ULong i = 0; i < autotexts.GetSize (); i++) {
        DBPrintf ("AutoText[%03d] \"%s\" (\"%s\") = \"%s\"\n", i,
            (const char *) autotexts[i][0].ToCStr (), (const char *) autotexts[i][1].ToCStr (), (const char *) autotexts[i][2].ToCStr ());
    }
}

ACAPI_AutoText_GetNoteAutotexts()

GSErrCode __ACENV_CALL ACAPI_AutoText_GetNoteAutotexts	(	const API_ElemType &	noteOwnerType,
		std::unordered_map< API_NoteAutotextID, std::unordered_set< API_ElemType > > &	elemTypesForAutotextIDs,
		const GS::Optional< API_AppearID > &	dimAppear = GS::NoValue
	)

Returns a map that contains an element type set for every available autotext regards to the note owner's type.

Since

Archicad 26

Parameters

noteOwnerType	[in] The note owner's type.
elemTypesForAutotextIDs	[out] The result map for the note owner's type. The autotext is evaluable for the note if the parent element type is contained by the set. The empty set means the autotext is generally evaluable.
dimAppear	[in] The dimAppear is an optional parameter. It is only needed when the note owner's type is API_DimensionID.

Returns

• APIERR_BADID - The given element type is not a note owner type or if it is API_DimensionID then the given dimAppear is nullptr.

Remarks

This function is used to get a map for the note owner that contains every available autotexts and on which elements are they evaluable. The empty element type set means the autotext is generally evaluable.

Example

void    Do_LevelDimension_Edit ()
{
    API_Element element = {}, mask;
 
    if (!ClickAnElem ("Click a dimension to modify", API_LevelDimensionID, nullptr, &element.header.type, &element.header.guid)) {
        WriteReport_Alert ("No level dimension was clicked");
        return;
    }
 
    GSErrCode err = ACAPI_Element_Get (&element);
    if (err != NoError) {
        return;
    }
 
    ACAPI_ELEMENT_MASK_CLEAR (mask);
    ACAPI_ELEMENT_MASK_SET (mask, API_LevelDimensionType, note1.contentType);
    ACAPI_ELEMENT_MASK_SET (mask, API_LevelDimensionType, note1.contentUStr);
 
    element.levelDimension.note1.contentType = API_NoteContent_Custom;
 
    auto buildContentWithAllAvailableAutotexts = [&element] () -> GS::UniString {
        std::unordered_map<API_NoteAutotextID, std::unordered_set<API_ElemType>> autotextMap;
        const GSErrCode err = ACAPI_AutoText_GetNoteAutotexts (API_LevelDimensionID, autotextMap);
        if (err != NoError) {
            return "Custom";
        }
 
        GS::UniString content;
        for (auto& pairItem : autotextMap) {
            const API_NoteAutotextID autotextID = pairItem.first;
            const std::unordered_set<API_ElemType>& currentSet = pairItem.second;
 
            const bool isGeneralOrParentElemTypeSpecificAutotext =
                currentSet.empty () ||
                currentSet.find (element.levelDimension.parentType) != currentSet.end ();
            if (!isGeneralOrParentElemTypeSpecificAutotext) {
                continue;
            }
            GS::UniString keyword;
            ACAPI_AutoText_GetNoteKeywordForAutotextID (autotextID, keyword);
 
            if (!content.IsEmpty ()) {
                const GS::UniString separator = " ";
                content += separator;
            }
            content += keyword;
        }
        return content;
    };
 
    GS::UniString content = buildContentWithAllAvailableAutotexts ();
    element.levelDimension.note1.contentUStr = &content;
 
    err = ACAPI_Element_Change (&element, &mask, nullptr, 0, true);
}       // Do_LevelDimension_Edit

ACAPI_AutoText_GetNoteKeywordForAutotextID()

GSErrCode __ACENV_CALL ACAPI_AutoText_GetNoteKeywordForAutotextID	(	API_NoteAutotextID	autotextID,
		GS::UniString &	keyword
	)

Returns the unistring keyword for note autotext id.

Since

Archicad 26

Parameters

autotextID	[in] The note autotext identifier.
keyword	[out] The result keyword for the note autotext.

Returns

• NoError - This function always return NoError.

Remarks

This function is used to get the keyword for the note autotext.

Example

void    Do_LevelDimension_Edit ()
{
    API_Element element = {}, mask;
 
    if (!ClickAnElem ("Click a dimension to modify", API_LevelDimensionID, nullptr, &element.header.type, &element.header.guid)) {
        WriteReport_Alert ("No level dimension was clicked");
        return;
    }
 
    GSErrCode err = ACAPI_Element_Get (&element);
    if (err != NoError) {
        return;
    }
 
    ACAPI_ELEMENT_MASK_CLEAR (mask);
    ACAPI_ELEMENT_MASK_SET (mask, API_LevelDimensionType, note1.contentType);
    ACAPI_ELEMENT_MASK_SET (mask, API_LevelDimensionType, note1.contentUStr);
 
    element.levelDimension.note1.contentType = API_NoteContent_Custom;
 
    auto buildContentWithAllAvailableAutotexts = [&element] () -> GS::UniString {
        std::unordered_map<API_NoteAutotextID, std::unordered_set<API_ElemType>> autotextMap;
        const GSErrCode err = ACAPI_AutoText_GetNoteAutotexts (API_LevelDimensionID, autotextMap);
        if (err != NoError) {
            return "Custom";
        }
 
        GS::UniString content;
        for (auto& pairItem : autotextMap) {
            const API_NoteAutotextID autotextID = pairItem.first;
            const std::unordered_set<API_ElemType>& currentSet = pairItem.second;
 
            const bool isGeneralOrParentElemTypeSpecificAutotext =
                currentSet.empty () ||
                currentSet.find (element.levelDimension.parentType) != currentSet.end ();
            if (!isGeneralOrParentElemTypeSpecificAutotext) {
                continue;
            }
            GS::UniString keyword;
            ACAPI_AutoText_GetNoteKeywordForAutotextID (autotextID, keyword);
 
            if (!content.IsEmpty ()) {
                const GS::UniString separator = " ";
                content += separator;
            }
            content += keyword;
        }
        return content;
    };
 
    GS::UniString content = buildContentWithAllAvailableAutotexts ();
    element.levelDimension.note1.contentUStr = &content;
 
    err = ACAPI_Element_Change (&element, &mask, nullptr, 0, true);
}       // Do_LevelDimension_Edit

ACAPI_AutoText_GetPropertyAutoTextKeyTable()

GSErrCode __ACENV_CALL ACAPI_AutoText_GetPropertyAutoTextKeyTable	(	API_Guid *	guid,
		GS::HashTable< GS::UniString, GS::UniString > *	keyGuidTable
	)

Retrieves the context dependent autotexts keys.

Parameters

guid	[in] A pointer to a API_Guid that represents an object like a wall or slab. It can be APINULLGuid, but then only the general autotexts can be received like "Area", "Element ID" (which are common in all element types), and not the element specific ones like "Thickness of the wall".
keyGuidTable	[out] Pointer to a hash table where the resulting autotext names and keys will be stored for a given guid.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed parameters are invalid.

Remarks

This function will fill the passed hast table with the autotexts' name and key for any given an element like a wall. The names are the same as they can be seen in Archicad while inserting an autotext into a text field, for example "Area". The function allows for an APINULLGuid input. But keep in mind that in this case only the general autotexts will be returned. The resulting autotext keys can be used to create autotexts or to access the value of certain parameters associated with an object using the function ACAPI_AutoText_InterpretAutoText. These property keys usually look like PROPERTY-69A58F6F-DD3B-478D-B5EF-09A16BD0C548. To create an embeddable autotext from its key surround the key with inequality signs: <PROPERTY-69A58F6F-DD3B-478D-B5EF-09A16BD0C548>, then insert this text into the chosen text field.

Example

API_Guid guid;
 
if (!ClickAnElem ("Click on a slab to acquire its area.", API_SlabID, nullptr, nullptr, &guid)) {
    WriteReport_Alert ("No slab was clicked!");
    return;
}
else {
    WriteReport ("Slab clicked!");
    GS::HashTable<GS::UniString, GS::UniString> properties{ GS::HashTable<GS::UniString, GS::UniString>() };
    GSErrCode err = ACAPI_Goodies (APIAny_GetPropertyAutoTextKeyTableID, &guid, &properties);
    if (err == NoError) {
        if (properties.ContainsKey (GS::UniString ("Area"))) {
            GS::UniString area = properties.Get (GS::UniString ("Area"));
            GS::UniString value;
            err = ACAPI_Goodies(APIAny_InterpretAutoTextID, &area, &guid, &value);
            if (err == NoError) {
                WriteReport ("Area is: %T", value.ToPrintf ());
            } else {
                WriteReport ("Autotext for Area could not be resolved.");
            }
        } else {
            WriteReport ("Autotext key for Area could not be found.");
        }
    } else {
        WriteReport ("Error while retrieving the property autotext key table.");
    }
}

ACAPI_AutoText_InterpretAutoText()

GSErrCode __ACENV_CALL ACAPI_AutoText_InterpretAutoText	(	const GS::UniString *	autotext,
		const API_Guid *	guid,
		GS::UniString *	value
	)

Retrieves the context dependent autotext's value.

Parameters

autotext	[in] A pointer to a GS::UniString containing the key for the context dependent autotexts key, without the '<' and '>' signs. For example the "<The autotext key>" should look like "The autotext key".
guid	[in] Pointer to a API_Guid element for context dependency resolution. This can be the guid of any object which can contain an autotext. For example a label's guid is sufficient to resolve the autotext's value present on that label.
value	[out] A GS::UniString pointer that is either empty or contains the autotext's value.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - Either the autotext or the value was nullptr.
• APIERR_GENERAL - The passed autotext could not be resolved or it is has invalid formatting.

Remarks

Use this function to find the value of context dependent autotext keys. In this context, context dependency means that the value of a given autotext is determined by the object that it is bound to. For example a label with an autotext < Element Id > will show the object's Element Id that the label is bound to. These autotexts have a format similar to: <PROPERTY-69A58F6F-DD3B-478D-B5EF-09A16BD0C548> Remember to dispose of the '<' and '>' signs before passing the function an autotext key. So the previous example should look similar to PROPERTY-69A58F6F-DD3B-478D-B5EF-09A16BD0C548.

Example

API_Guid guid;
 
if (!ClickAnElem ("Click on a slab to acquire all of its available properties.", API_SlabID, nullptr, nullptr, &guid)) {
    WriteReport_Alert ("No slab was clicked!");
    return;
} else {
    WriteReport ("Slab clicked!");
    GS::HashTable<GS::UniString, GS::UniString> properties;
    ACAPI_Goodies (APIAny_GetPropertyAutoTextKeyTableID, (API_Guid *) &APINULLGuid, &properties);
    GSErrCode err = ACAPI_Goodies (APIAny_GetPropertyAutoTextKeyTableID, &guid, &properties);
    if (err == NoError) {
        properties.EnumeratePairs (
            [&err, &guid] (const GS::UniString& propertyName, GS::UniString& propertyKey) -> void {
                GS::UniString value;
                err = ACAPI_Goodies (APIAny_InterpretAutoTextID, &propertyKey, &guid, &value);
                if (err == NoError) {
                    WriteReport ("%T is: %T", propertyName.ToPrintf (), value.ToPrintf ());
                } else {
                    WriteReport ("Autotext for %T could not be resolved.", propertyName.ToPrintf ());
                }
            });
    } else {
        WriteReport ("Error while retrieving the property autotext key table.");
    }
}

ACAPI_AutoText_SetAnAutoText()

GSErrCode __ACENV_CALL ACAPI_AutoText_SetAnAutoText	(	const GS::UniString *	autotextDbKey = nullptr,
		const GS::UniString *	autotextValue = nullptr
	)

Sets the value of an autotext.

Parameters

autotextDbKey	[in] The database key of autotext to be changed
autotextValue	[in] The new autotext value for the specified key (optional, can be nullptr)

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The passed autotextDbKey parameter is nullptr.
• APIERR_BADVALUE - The passed autotext value is not valid.

Remarks

Use this function to set the value of an existing autotext defined by the given autotext key. You can set the autotext value empty by passing nullptr in the autotextValue parameter. You can get the list of currently available autotexts with the ACAPI_AutoText_GetAutoTexts and ACAPI_AutoText_GetAutoTextKeys functions. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

GS::UniString dbKey ("COMPANY");
GS::UniString value ("GRAPHISOFT SE");
 
GSErrCode err = ACAPI_Goodies (APIAny_SetAnAutoTextID, &dbKey, &value);