View Handling

Functions related to the View Settings, zoom and various other View-related functionality. More...

Classes
class	ACAPI::v1::View
	A class that represents an Archicad navigator view. More...
struct	API_Box
	Rectangular region of the model. More...
struct	API_RGBAColor
	RGB color reference with transparency. More...
struct	API_Rect
	Rectangle in pixel coordinates. More...
struct	API_Tranmat
	A 3*4 transformation matrix. More...
struct	API_AxonoPars
	Parallel projection parameters. More...
struct	API_StoryType
	Parameters of one story. More...
struct	API_GhostStoryType
	Ghost Story settings. More...
struct	API_GhostRecord
	Describes a tracing (ghost) database. More...
struct	API_StoryInfo
	Story information of the active project. More...
struct	API_StoryCmdType
	Parameters of the change story settings command. More...
struct	API_3DProjectionInfo
	3D projection setting parameters. More...
struct	API_3DFilterAndCutSettings
	Parameters of the 'Filter and Cut Elements in 3D' dialog. More...
struct	API_3DWindowInfo
	3D Window setting parameters. More...
struct	API_3DStyle
	3D Style parameters. More...
struct	API_3DCutShapeType
	Shape of the 3D cutting plane. More...
struct	API_3DCutPlanesInfo
	Data of the "3D Cutting Planes..." dialog. More...
struct	API_UniformAttributeOptions
	General representation of a Model Display in 3D Document. More...
struct	API_SkeletonOptions
	Skeleton drawing options. More...
struct	API_DocumentFrom3DDefaults
	Default settings of 3D document. More...
struct	API_DocumentFrom3DType
	Represents a 3D Document. More...

Enumerations
enum	API_ShowGhostType {   APIGhost_NoFloor = 0 , APIGhost_ShowOneFloor , APIGhost_ShowAboveFloor , APIGhost_ShowBelowFloor ,   APIGhost_ShowPreviousFloor , APIGhost_ShowAllStructure }
	Represents the way of the ghost to be shown.
enum	API_StoryCmdID {   APIStory_GoTo , APIStory_Delete , APIStory_InsAbove , APIStory_InsBelow ,   APIStory_SetHeight , APIStory_Rename , APIStory_SetElevation , APIStory_SetDispOnSections }
	Action codes for the story settings command. More...
enum	API_3DFilterModeID { API_FilterByRules , API_FilterBySelection , API_FilterByMarqueeAndRules }
	The enumeration of the available 3D filter modes. More...
enum	API_3DModelTypeID { API3DModel_Block = 0 , API3DModel_WireFrame , API3DModel_Hiddenline , API3DModel_Shading }
	Model image type in the 3D window. More...
enum	API_ShadingContoursID { APIShadContours_Draft = 0 , APIShadContours_Off , APIShadContours_Best }
	Contour visibility options for shaded image mode in the 3D window. More...
enum	API_VectorShadowID {   APIVectShad_Off = 0 , APIVectShad_ContOff_AllSurf , APIVectShad_ContOn_AllSurf , APIVectShad_ContOff_OneLevel ,   APIVectShad_ContOn_OneLevel }
	Options for vectorial sun shadow generation in the 3D window. More...
enum	API_SpecFolderID {   API_ApplicationPrefsFolderID = 1 , API_GraphisoftPrefsFolderID , API_GraphisoftHomeFolderID , API_CacheFolderID ,   API_DataFolderID , API_UserDocumentsFolderID , API_TemporaryFolderID , API_ApplicationFolderID ,   API_DefaultsFolderID , API_WebObjectsFolderID , API_TemplatesFolderID , API_HelpFolderID ,   API_EmbeddedProjectLibraryFolderID , API_EmbeddedProjectLibraryHotlinkFolderID }
	The selector of special folders.
enum	API_3DCutSurfFills { API_3DDocumentVectorFilles = 1 , API_3DDocumentUniformMaterial = 2 , API_3DDocumentOwnMaterial = 3 , API_3DDocumentOwnShadedMaterial = 4 }
	How to display the cut surfaces.
enum	API_3DUncutSurfaceFillType { API_3DDocumentPenColor = 1 , API_3DDocumentMaterialColorShaded = 2 , API_3DDocumentMaterialColorNonShaded = 3 }
	How to display the uncut surfaces.
enum	API_3DHiddenEdgeVisibility { API_3DDocumentHideHiddenEdges , API_3DDocumentShowHiddenEdges }
	Show or hide hidden edges.
enum	API_3DOnCutPlaneVisibility { API_3DDocumentDontShowOnCutPlanes , API_3DDocumentShowOnCutPlanes }
	Show or hide hidden cut lines.
enum	API_DocumentSourceID { API_DDD = 1 , API_FloorPlan = 2 }
	3D Document source.
enum	API_ViewSourceID { API_Top = 1 , API_Bottom = 2 }
	Skeleton drawing 3D Document view source.

Functions
Result< View >	ACAPI::FindViewByGuid (const API_Guid &guid)
	Constuct a view object referring to an existing Archicad view by guid.
GSErrCode __ACENV_CALL	ACAPI_View_Redraw ()
	Redraws the content of the current window.
GSErrCode __ACENV_CALL	ACAPI_View_Rebuild (bool *doRebuildAndRegenerate=nullptr)
	Rebuilds the content of the current window.
GSErrCode __ACENV_CALL	ACAPI_View_Zoom (API_Box *zoomBox=nullptr, API_Rect *zoomRect=nullptr, API_Tranmat *tranmat=nullptr)
	Performs a zoom operation.
GSErrCode __ACENV_CALL	ACAPI_View_ZoomToSelected ()
	Zooming to the actual selection. (Even in 3D.)
GSErrCode __ACENV_CALL	ACAPI_View_ZoomToElements (const GS::Array< API_Guid > *elemsToZoom)
	Zoom to the given elements.
GSErrCode __ACENV_CALL	ACAPI_View_GoToView (const char *viewGuidStr)
	Switches to the given navigator view.
GSErrCode __ACENV_CALL	ACAPI_View_CoordToPoint (API_Coord *coord, API_Point *point)
	Convert a model coordinate to screen in the current database.
GSErrCode __ACENV_CALL	ACAPI_View_PointToCoord (API_Point *point, API_Coord *coord)
	Convert a screen coordinate into model coordinate in the current database.
GSErrCode __ACENV_CALL	ACAPI_View_SetZoom (API_Box *zoomBox=nullptr, API_Tranmat *tranmat=nullptr)
	Sets the zoom box of the current database.
GSErrCode __ACENV_CALL	ACAPI_View_GetZoom (API_Box *zoomBox=nullptr, API_Tranmat *tranmat=nullptr)
	Returns the actual zoom parameters of the current database.
GSErrCode __ACENV_CALL	ACAPI_View_ResetZoom (short *numOfStepsBack)
	Restores the zoom parameters of the current database by a given number of steps.
GSErrCode __ACENV_CALL	ACAPI_View_StoreViewSettings (bool store)
	Stores/restores the actual view settings.
GSErrCode __ACENV_CALL	ACAPI_View_IsAutoGroupOn (bool *autoGrp)
	Returns the current state of the autogroup mode.
GSErrCode __ACENV_CALL	ACAPI_View_IsSuspendGroupOn (bool *suspGrp)
	Returns the current state of the Suspend Groups mode.
GSErrCode __ACENV_CALL	ACAPI_View_CreateGhostRecord (const API_GhostRecord *ghostRecord)
	Create a new Trace (ghost) database.
GSErrCode __ACENV_CALL	ACAPI_View_GetGhostRecord (const API_DatabaseUnId *databaseUnId, API_GhostRecord *ghostRecord)
	Retrieve a Trace record from the database.
GSErrCode __ACENV_CALL	ACAPI_View_DeleteGhostRecord (const API_GhostRecord *ghostRecord)
	Deletes a Virtual Trace (ghost) record.
GSErrCode __ACENV_CALL	ACAPI_View_ChangeGhostRecord (const API_GhostRecord *ghostRecord)
	Change the settings of a Virtual Trace (ghost) record.
GSErrCode __ACENV_CALL	ACAPI_View_GetGhostStorySettings (API_GhostStoryType *ghostStoryType)
	Retrieves the current ghost story settings.
GSErrCode __ACENV_CALL	ACAPI_View_Get3DProjectionSets (API_3DProjectionInfo *proj3DInfo)
	Returns information on the 3D projection settings.
GSErrCode __ACENV_CALL	ACAPI_View_Change3DProjectionSets (API_3DProjectionInfo *proj3DInfo, bool *switchOnlyAxonoOrPersp=nullptr)
	Changes the parameters of the 3D projection.
GSErrCode __ACENV_CALL	ACAPI_View_Get3DImageSets (API_3DFilterAndCutSettings *filterAndCutSettings)
	Returns the 3D image item settings.
GSErrCode __ACENV_CALL	ACAPI_View_Change3DImageSets (API_3DFilterAndCutSettings *filterAndCutSettings, bool *mustConvert=nullptr)
	Changes the 3D image item settings.
GSErrCode __ACENV_CALL	ACAPI_View_Get3DWindowSets (API_3DWindowInfo *windowInfo)
	Retrieves the 3D Window settings.
GSErrCode __ACENV_CALL	ACAPI_View_Change3DWindowSets (API_3DWindowInfo *windowInfo)
	Changes the 3D window settings.
GSErrCode __ACENV_CALL	ACAPI_View_Get3DStyle (API_3DStyle *style)
	Retrieves all parameters of a 3D style.
GSErrCode __ACENV_CALL	ACAPI_View_Change3DStyle (API_3DStyle *style)
	Modifies the parameters of an existing 3D style.
GSErrCode __ACENV_CALL	ACAPI_View_Create3DStyle (API_3DStyle *style)
	Creates a new 3D style.
GSErrCode __ACENV_CALL	ACAPI_View_Get3DStyleList (GS::Array< GS::UniString > *styles, GS::UniString *current=nullptr)
	Retrieves the names of all styles in the project and/or the name of the current style.
GSErrCode __ACENV_CALL	ACAPI_View_SetCurrent3DStyle (const GS::UniString *name)
	Sets an existing style as active.
GSErrCode __ACENV_CALL	ACAPI_View_Get3DCuttingPlanes (API_3DCutPlanesInfo *cutInfo)
	Retrieves the 3D cutting plane settings.
GSErrCode __ACENV_CALL	ACAPI_View_Change3DCuttingPlanes (API_3DCutPlanesInfo *cutInfo)
	Changes the 3D cutting planes.
GSErrCode __ACENV_CALL	ACAPI_View_GetShowHideState (bool *isShown)
	Returns the visibility of application.
GSErrCode __ACENV_CALL	ACAPI_View_ChangeShowHideState (bool *toShow)
	Changes the visibility of application.
GSErrCode __ACENV_CALL	ACAPI_View_IsAutoIntersectOn (bool *isOn)
	Returns the state of the automatic wall intersection flag.
GSErrCode __ACENV_CALL	ACAPI_View_ChangeAutoIntersect (bool *isOn)
	Modifies the automatic wall intersection flag.
GSErrCode __ACENV_CALL	ACAPI_View_GetDocumentFrom3DDefaults (API_DocumentFrom3DDefaults *documentFrom3DDefaults)
	Returns the 3D document setting default values.
GSErrCode __ACENV_CALL	ACAPI_View_ChangeDocumentFrom3DDefaults (API_DocumentFrom3DDefaults *documentFrom3DDefaults)
	Changes the 3D document setting default values.
GSErrCode __ACENV_CALL	ACAPI_View_GetDocumentFrom3DSettings (API_DatabaseUnId *databaseUnId, API_DocumentFrom3DType *documentFrom3DType)
	Returns the 3D document settings of the specified database.
GSErrCode __ACENV_CALL	ACAPI_View_ChangeDocumentFrom3DSettings (API_DatabaseUnId *databaseUnId, API_DocumentFrom3DType *documentFrom3DType)
	Changes the 3D document settings of the specified database.
GSErrCode __ACENV_CALL	ACAPI_View_ShowSelectionIn3D ()
	Activates the 3D window and shows the selected elements.
GSErrCode __ACENV_CALL	ACAPI_View_ShowAllIn3D ()
	Activates the 3D window and shows the whole model.
void __ACENV_CALL	ACAPI_UserInput_ClearElementHighlight ()
	Removes element highlights from 2D (floor plan and section) and 3D window.

Detailed Description

Functions related to the View Settings, zoom and various other View-related functionality.

Enumeration Type Documentation

API_3DFilterModeID

enum API_3DFilterModeID

The enumeration of the available 3D filter modes.

Remarks

Use this enum in API_3DFilterAndCutSettings structure.

API_3DModelTypeID

enum API_3DModelTypeID

Model image type in the 3D window.

Remarks

The API_3DModelTypeID type is used in the API_3DWindowInfo structure.

API_ShadingContoursID

enum API_ShadingContoursID

Contour visibility options for shaded image mode in the 3D window.

Remarks

The API_ShadingContoursID type is used in the API_3DWindowInfo structure.

API_StoryCmdID

enum API_StoryCmdID

Action codes for the story settings command.

Remarks

Refer to the API_StoryCmdType structure for further details on modifying the story structure of Archicad.

API_VectorShadowID

enum API_VectorShadowID

Options for vectorial sun shadow generation in the 3D window.

Remarks

The API_VectorShadowID type is used in the API_3DWindowInfo structure. The elevation of the horizontal plane for shadow generaion on a single level is given in the shadowElevation field of API_3DWindowInfo.

Function Documentation

ACAPI_UserInput_ClearElementHighlight()

void __ACENV_CALL ACAPI_UserInput_ClearElementHighlight

(

)

Removes element highlights from 2D (floor plan and section) and 3D window.

Since

Archicad 26

Remarks

This function removes element highlights set by ACAPI_UserInput_SetElementHighlight. After changing element highlights the model needs to be redrawn by calling ACAPI_Automate (ACAPI_View_Redraw).

Example

//------------------------------------------------------
// Highlight every mesh
//------------------------------------------------------
static void Do_HighlightElements (void)
{
    static bool hled = false;
 
    if (hled) {
        // remove the highlight
        ACAPI_UserInput_ClearElementHighlight ();
    } else {
        GS::Array<API_Guid> meshList;
        ACAPI_Element_GetElemList (API_MeshID, &meshList);
 
        if (meshList.GetSize () > 0) {
            GS::HashTable<API_Guid, API_RGBAColor>  hlElems;
            API_RGBAColor   hlColor = { 0.0, 0.5, 0.75, 0.5 };
            for (auto it = meshList.Enumerate (); it != nullptr; ++it) {
                hlElems.Add (*it, hlColor);
                hlColor.f_red += 0.1;
                if (hlColor.f_red > 1.0)
                    hlColor.f_red = 0.0;
            }
 
            bool wireframe3D = false;
            API_RGBAColor nonHighlightedElemsColor = {0.7, 0.7, 0.7, 0.95};
 
            ACAPI_UserInput_SetElementHighlight (hlElems, wireframe3D, nonHighlightedElemsColor);
        }
    }
 
    hled = !hled;
}

ACAPI_View_Change3DCuttingPlanes()

GSErrCode __ACENV_CALL ACAPI_View_Change3DCuttingPlanes

(

API_3DCutPlanesInfo *

cutInfo

)

Changes the 3D cutting planes.

Parameters

cutInfo

Data of the "3D Cutting Planes..." dialog

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - cutInfo is nullptr or contains invalid data
• APIERR_NOPLAN - No open project

Remarks

This function is used to change the 3D cutting plane parameters.

Example

API_3DCutPlanesInfo cutInfo;
BNZeroMemory (&cutInfo, sizeof (API_3DCutPlanesInfo));
 
GSErrCode err = ACAPI_Environment (APIEnv_Get3DCuttingPlanesID, &cutInfo, nullptr);
if (err == NoError) {
    if (cutInfo.shapes != nullptr)
        BMKillHandle ((GSHandle *) &(cutInfo.shapes));
 
    cutInfo.isCutPlanes = true;
    cutInfo.nShapes = 2;
    cutInfo.shapes = reinterpret_cast<API_3DCutShapeType**> (BMAllocateHandle (cutInfo.nShapes * sizeof (API_3DCutShapeType), ALLOCATE_CLEAR, 0));
    if (cutInfo.shapes != nullptr) {
        (*cutInfo.shapes)[0].cutStatus = 2;
        (*cutInfo.shapes)[0].cutPen = 3;
        (*cutInfo.shapes)[0].cutMater = 11;
        (*cutInfo.shapes)[0].pa = -3.0499805934954503;
        (*cutInfo.shapes)[0].pb = 0.43107875694662845;
        (*cutInfo.shapes)[0].pc = 3.5670423669734248;
        (*cutInfo.shapes)[0].pd = 2.4161856450872907;
        (*cutInfo.shapes)[1].cutStatus = 3;
        (*cutInfo.shapes)[1].cutPen = 4;
        (*cutInfo.shapes)[1].cutMater = 12;
        (*cutInfo.shapes)[1].pa = -2.9081872443425456;
        (*cutInfo.shapes)[1].pb = 0.37912781320386035;
        (*cutInfo.shapes)[1].pc = 3.4016167929617027;
        (*cutInfo.shapes)[1].pd = -1.1569668026192714;
    }
 
    err = ACAPI_Environment (APIEnv_Change3DCuttingPlanesID, &cutInfo, nullptr);
    if (err == NoError) {
        API_WindowInfo windowInfo;
        BNZeroMemory (&windowInfo, sizeof (API_WindowInfo));
        windowInfo.typeID = APIWind_3DModelID;
        err = ACAPI_Automate (APIDo_ChangeWindowID, &windowInfo, nullptr);
    }
 
    BMKillHandle ((GSHandle *) &(cutInfo.shapes));
}

ACAPI_View_Change3DImageSets()

GSErrCode __ACENV_CALL ACAPI_View_Change3DImageSets	(	API_3DFilterAndCutSettings *	filterAndCutSettings,
		bool *	mustConvert = nullptr
	)

Changes the 3D image item settings.

Since

Archicad 26

Parameters

filterAndCutSettings	[in] Parameters of the 'Filter and Cut Elements in 3D' dialog box
mustConvert	[in] Optional parameter; if it is not nullptr and its value is true then the function drops the partial conversion data, so that a full rebuild will be performed upon the next Rebuild operation

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - No open project

Remarks

This function is used to change the 3D image item settings which can be accessed via the 'Filter and Cut Elements in 3D' dialog box.

Example

API_3DFilterAndCutSettings     filterAndCutSettings = {};
bool                setMustConvert;
GSErrCode           err;
 
err = ACAPI_Environment (APIEnv_Get3DImageSetsID, &filterAndCutSettings);
if (err == NoError) {
    filterAndCutSettings.elemTypeFilter.insert ({API_ZombieElemID, false}); // Hide everything in 3D
 
    ACAPI_Environment (APIEnv_Change3DImageSetsID, &filterAndCutSettings);
 
    filterAndCutSettings.elemTypeFilter.clear ();
    filterAndCutSettings.elemTypeFilter.insert ({API_WallID, true});
    filterAndCutSettings.elemTypeFilter.insert ({API_BeamID, true}); // show walls and beams only
    setMustConvert = true;
    ACAPI_Environment (APIEnv_Change3DImageSetsID, &filterAndCutSettings, &setMustConvert);
}

ACAPI_View_Change3DProjectionSets()

GSErrCode __ACENV_CALL ACAPI_View_Change3DProjectionSets	(	API_3DProjectionInfo *	proj3DInfo,
		bool *	switchOnlyAxonoOrPersp = nullptr
	)

Changes the parameters of the 3D projection.

Parameters

proj3DInfo	[in] Parameters of the '3D Projection Settings...' dialog
switchOnlyAxonoOrPersp	[in] Optional parameter. If it is not nullptr and the value is true, only the isPersp field of proj3DInfo is considered

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - proj3DInfo is nullptr
• APIERR_NOPLAN - No open project

Remarks

This function is used to change the 3D projection. If you pass true in the switchOnlyAxoOrPersp parameter, the kind of the projection (parallel or perspective) will be changed only, all the other parameters will be ignored. If the value of camGuid or actCamSet field of API_3DProjectionInfo is non-zero, the perspective projection will be defined according to the camera identified by camGuid. If camGuid is invalid, the first camera of the camera set defined by the actCamSet field will be used. Otherwise the perspective settings will not be related to any floorplan camera element, and will be defined by the API_PerspPars data. These fields are irrelevant when changing the axonometric projection parameters.

Example

/* Change to the next perspective camera */
API_Element           element;
API_3DProjectionInfo  proj3DInfo;
GSErrCode             err;
 
BNZeroMemory (&proj3DInfo, sizeof (API_3DProjectionInfo));
err = ACAPI_Environment (APIEnv_Get3DProjectionSetsID, &proj3DInfo, nullptr, nullptr);
if (err == NoError && proj3DInfo.isPersp && proj3DInfo.camGuid != APINULLGuid) {
    BNZeroMemory (&element, sizeof (API_Element));
    element.header.guid = proj3DInfo.camGuid;
    err = ACAPI_Element_Get (&element);
    if (err == NoError && element.camera.perspCam.nextCam != APINULLGuid) {
        proj3DInfo.camGuid = element.camera.perspCam.nextCam;
        err = ACAPI_Environment (APIEnv_Change3DProjectionSetsID, &proj3DInfo, nullptr, nullptr);
    }
}

ACAPI_View_Change3DStyle()

GSErrCode __ACENV_CALL ACAPI_View_Change3DStyle

(

API_3DStyle *

style

)

Modifies the parameters of an existing 3D style.

Parameters

style

[in] New parameters of the existing 3D style

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - style is nullptr, or a some parameter of the style is invalid.
• APIERR_NOPLAN - No open project.
• APIERR_NOACCESSRIGHT - The user does not have Teamwork privilege to modify 3D styles.

Remarks

Renaming styles is not supported, do not edit the style->name field as it is used for the identification of the existing style.

Example

// Get the name of all styles.
GS::Array<GS::UniString> stylesNames;
GS::UniString currentName;
ACAPI_View_Get3DStyleList (&stylesNames, &currentName);
 
API_3DStyle apiStyle {};
// Get the details of the currently active style. The name field is used for identification.
GS::ucsncpy (apiStyle.name, currentName.ToUStr (), API_UniLongNameLen);
ACAPI_View_Get3DStyle (&apiStyle);
 
// Change ground color to green.
apiStyle.backGroundRGB = { 0.0, 1.0, 0.0 };
// Update the style.
ACAPI_View_Change3DStyle ( &apiStyle);
 
// Create a new style based on the current one, with a different sky color. Finally set it as the current style.
GS::UniString testStyleName ("testStyle");
if (!stylesNames.Contains (testStyleName)) {
    apiStyle.bkgSkyColor = { 0.2, 0.2, 1.0 };
    GS::ucsncpy (apiStyle.name, testStyleName.ToUStr (), API_UniLongNameLen);
    ACAPI_View_Create3DStyle (&apiStyle);
    ACAPI_View_SetCurrent3DStyle (&testStyleName);
}

ACAPI_View_Change3DWindowSets()

GSErrCode __ACENV_CALL ACAPI_View_Change3DWindowSets

(

API_3DWindowInfo *

windowInfo

)

Changes the 3D window settings.

Parameters

windowInfo

[in] Parameters of the 3D Window.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - windowInfo is nullptr
• APIERR_NOPLAN - No open project

Remarks

This function is used to modify the data of the '3D Window Settings' dialog box, and the size and zoom parameters of the 3D window. In order the changes to take effect you might need to call the ACAPI_Database_RebuildCurrentDatabase database function. You can also change the zoom of the 3D model window with the ACAPI_View_Zoom automation function.

Example

API_3DWindowInfo    windowInfo;
GSErrCode           err;
 
err = ACAPI_Environment (APIEnv_Get3DWindowSetsID, &windowInfo, nullptr, nullptr);
if (err == NoError) {
    windowInfo.model3D = API3DModel_Shading;                /* switch to shaded mode */
    windowInfo.vectSunShadow = APIVectShad_ContOn_AllSurf;  /* switch On shadow casting */
    windowInfo.hSize *= 1.5;                                /* grow 3D window size */
    windowInfo.vSize *= 1.5;
    windowInfo.setWindowSize = true;
    ACAPI_Environment (APIEnv_Change3DWindowSetsID, &windowInfo, nullptr, nullptr);
}

ACAPI_View_ChangeAutoIntersect()

GSErrCode __ACENV_CALL ACAPI_View_ChangeAutoIntersect

(

bool *

isOn

)

Modifies the automatic wall intersection flag.

Parameters

isOn	Turns on/off the automatic wall intersection.

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - No open project.
• APIERR_BADPARS - The isOn parameter is nullptr.

Remarks

This flag was part of the Display Options in previous (pre-10) API versions. From API 10, it has started its own 'life'. The current state of the flag can be queried with ACAPI_View_IsAutoIntersectOn.

ACAPI_View_ChangeDocumentFrom3DDefaults()

GSErrCode __ACENV_CALL ACAPI_View_ChangeDocumentFrom3DDefaults

(

API_DocumentFrom3DDefaults *

documentFrom3DDefaults

)

Changes the 3D document setting default values.

Parameters

documentFrom3DDefaults

[in] The new default values of the 3D document database.

Returns

• NoError - The function completed with success.
• APIERR_BADPARS - The documentFrom3DDefaults parameter is nullptr.

Remarks

You can use this function to change the 3D document setting default values. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

ACAPI_View_ChangeDocumentFrom3DSettings()

GSErrCode __ACENV_CALL ACAPI_View_ChangeDocumentFrom3DSettings	(	API_DatabaseUnId *	databaseUnId,
		API_DocumentFrom3DType *	documentFrom3DType
	)

Changes the 3D document settings of the specified database.

Parameters

databaseUnId	[in] The database unique ID of the 3D document database to change parameters for.
documentFrom3DType	[in] The new parameters.

Returns

• NoError - The function completed with success.
• APIERR_BADDATABASE - The referred database is not a 3D document.
• APIERR_BADPARS - The dbPars or documentFrom3DType parameter is nullptr, or the settings couldn't be obtained.

Remarks

You can use this function to change the 3D document settings of the specified database. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

ACAPI_View_ChangeGhostRecord()

GSErrCode __ACENV_CALL ACAPI_View_ChangeGhostRecord

(

const API_GhostRecord *

ghostRecord

)

Change the settings of a Virtual Trace (ghost) record.

Parameters

ghostRecord

The Trace database to change.

Returns

• NoError - The function has completed with success.
• APIERR_WINDNOTEXIST - The parent database does not exist.

Remarks

Change the settings of the trace record associated with the parent database. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

ACAPI_View_ChangeShowHideState()

GSErrCode __ACENV_CALL ACAPI_View_ChangeShowHideState

(

bool *

toShow

)

Changes the visibility of application.

Parameters

toShow

[in] Application is visible.

Returns

• NoError - The function has completed with success.

Remarks

This function is used to change visibility of application. The actual visibility can be retrieved with the ACAPI_View_GetShowHideState function. Supported on Windows only.

ACAPI_View_CoordToPoint()

GSErrCode __ACENV_CALL ACAPI_View_CoordToPoint	(	API_Coord *	coord,
		API_Point *	point
	)

Convert a model coordinate to screen in the current database.

Parameters

coord	the coordinate to convert
point	the associated screen coordinate

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - any of the parameters are nullptr.

Remarks

This function is used to determine the pixel of a real coordinate. It is the inverse function of ACAPI_View_PointToCoord function. Note that different coordinates may be assigned to the same pixel. The conversion mainly depends on the window size, on the actual drawing scale and zoom settings (ACAPI_Drawing_GetDrawingScale, ACAPI_View_GetZoom) which means the projection is database dependent.

Example

API_Coord    c;
API_Point    p
GSErrCode    err;
 
c.x = 1.0;
c.y = 2.0;
err = ACAPI_Database (APIDb_CoordToPointID, &c, &p);
err = ACAPI_Database (APIDb_PointToCoordID, &p, &c);

ACAPI_View_Create3DStyle()

GSErrCode __ACENV_CALL ACAPI_View_Create3DStyle

(

API_3DStyle *

style

)

Creates a new 3D style.

Parameters

style

[in] Parameters of a new 3D style

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - style is nullptr, or a some parameter of the style is invalid, or a style with the same name already exists.
• APIERR_NOPLAN - No open project.
• APIERR_NOACCESSRIGHT - The user does not have Teamwork privilege to create a 3D style.

Remarks

The newly created style is not applied upon creation. To set the new style as active use ACAPI_View_SetCurrent3DStyle.

Example

// Get the name of all styles.
GS::Array<GS::UniString> stylesNames;
GS::UniString currentName;
ACAPI_View_Get3DStyleList (&stylesNames, &currentName);
 
API_3DStyle apiStyle {};
// Get the details of the currently active style. The name field is used for identification.
GS::ucsncpy (apiStyle.name, currentName.ToUStr (), API_UniLongNameLen);
ACAPI_View_Get3DStyle (&apiStyle);
 
// Change ground color to green.
apiStyle.backGroundRGB = { 0.0, 1.0, 0.0 };
// Update the style.
ACAPI_View_Change3DStyle ( &apiStyle);
 
// Create a new style based on the current one, with a different sky color. Finally set it as the current style.
GS::UniString testStyleName ("testStyle");
if (!stylesNames.Contains (testStyleName)) {
    apiStyle.bkgSkyColor = { 0.2, 0.2, 1.0 };
    GS::ucsncpy (apiStyle.name, testStyleName.ToUStr (), API_UniLongNameLen);
    ACAPI_View_Create3DStyle (&apiStyle);
    ACAPI_View_SetCurrent3DStyle (&testStyleName);
}

ACAPI_View_CreateGhostRecord()

GSErrCode __ACENV_CALL ACAPI_View_CreateGhostRecord

(

const API_GhostRecord *

ghostRecord

)

Create a new Trace (ghost) database.

Parameters

ghostRecord

Information describing the new Trace database.

Returns

• NoError - The function has completed with success.

Remarks

This function creates a new Trace record (ghost database). This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

This example code creates a Trace record out of the ground floor plan (assuming that the floor plan window is in front).

ACAPI_View_DeleteGhostRecord()

GSErrCode __ACENV_CALL ACAPI_View_DeleteGhostRecord

(

const API_GhostRecord *

ghostRecord

)

Deletes a Virtual Trace (ghost) record.

Parameters

ghostRecord

The Trace database to delete (the parentDatabase and ghostDatabase should be set).

Returns

• NoError - The function has completed with success.

Remarks

Deletes the trace record associated with the parent database. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

ACAPI_View_Get3DCuttingPlanes()

GSErrCode __ACENV_CALL ACAPI_View_Get3DCuttingPlanes

(

API_3DCutPlanesInfo *

cutInfo

)

Retrieves the 3D cutting plane settings.

Parameters

cutInfo

[out] Data of the "3D Cutting Planes..." dialog

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - cutInfo is nullptr
• APIERR_NOPLAN - No open project
• APIERR_MEMFULL - Low memory condition

Remarks

This function is used to get information on 3D cutting planes.

Example

See the example of APIEnv_Change3DCuttingPlanesID
function.

ACAPI_View_Get3DImageSets()

GSErrCode __ACENV_CALL ACAPI_View_Get3DImageSets

(

API_3DFilterAndCutSettings *

filterAndCutSettings

)

Returns the 3D image item settings.

Since

Archicad 26

Parameters

filterAndCutSettings

[out] Parameters of the 'Filter and Cut Elements in 3D' dialog box

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - filterAndCutSettings is nullptr
• APIERR_NOPLAN - No open project

Remarks

This function is used to retrieve the 3D image item settings which can be accessed via the 'Filter and Cut Elements in 3D' dialog box. See an example at the description of ACAPI_View_Change3DImageSets.

ACAPI_View_Get3DProjectionSets()

GSErrCode __ACENV_CALL ACAPI_View_Get3DProjectionSets

(

API_3DProjectionInfo *

proj3DInfo

)

Returns information on the 3D projection settings.

Parameters

proj3DInfo

[out] Parameters of the '3D Projection Settings...' dialog

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - proj3DInfo is nullptr
• APIERR_NOPLAN - No open project

Remarks

This function is used to get the parameters can be set in the '3D Projection Settings...' dialog of Archicad. Refer to the API_3DProjectionInfo structure to get further details.

Example

API_3DProjectionInfo  proj3DInfo;
GSErrCode             err;
 
BNZeroMemory (&proj3DInfo, sizeof (API_3DProjectionInfo));
err = ACAPI_Environment (APIEnv_Get3DProjectionSetsID, &proj3DInfo, nullptr);

ACAPI_View_Get3DStyle()

GSErrCode __ACENV_CALL ACAPI_View_Get3DStyle

(

API_3DStyle *

style

)

Retrieves all parameters of a 3D style.

Parameters

style

[in/out] Parameters of the 3D Style

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - style is nullptr, or style->name is invalid.
• APIERR_NOPLAN - No open project.

Remarks

Set the style->name field to the name of a valid style in the project, and call ACAPI_View_Get3DStyle to get the details of that style. Leaving the style->name field empty is equivalent to setting it to the name of the current style.

Example

// Get the name of all styles.
GS::Array<GS::UniString> stylesNames;
GS::UniString currentName;
ACAPI_View_Get3DStyleList (&stylesNames, &currentName);
 
API_3DStyle apiStyle {};
// Get the details of the currently active style. The name field is used for identification.
GS::ucsncpy (apiStyle.name, currentName.ToUStr (), API_UniLongNameLen);
ACAPI_View_Get3DStyle (&apiStyle);
 
// Change ground color to green.
apiStyle.backGroundRGB = { 0.0, 1.0, 0.0 };
// Update the style.
ACAPI_View_Change3DStyle ( &apiStyle);
 
// Create a new style based on the current one, with a different sky color. Finally set it as the current style.
GS::UniString testStyleName ("testStyle");
if (!stylesNames.Contains (testStyleName)) {
    apiStyle.bkgSkyColor = { 0.2, 0.2, 1.0 };
    GS::ucsncpy (apiStyle.name, testStyleName.ToUStr (), API_UniLongNameLen);
    ACAPI_View_Create3DStyle (&apiStyle);
    ACAPI_View_SetCurrent3DStyle (&testStyleName);
}

ACAPI_View_Get3DStyleList()

GSErrCode __ACENV_CALL ACAPI_View_Get3DStyleList	(	GS::Array< GS::UniString > *	styles,
		GS::UniString *	current = nullptr
	)

Retrieves the names of all styles in the project and/or the name of the current style.

Parameters

styles	[out] List of the names of all styles in the project.
current	[out] The name of the currently active style.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - Both parameter pointers are nullptr.

Remarks

This function is used to retrieve the list of 3D styles which can be accessed via the '3D Styles' dialog box. Any of the parameters can be set to nullptr if that information is to be ignored, but doing so with both at the same time returns no information.

Example

// Get the name of all styles.
GS::Array<GS::UniString> stylesNames;
GS::UniString currentName;
ACAPI_View_Get3DStyleList (&stylesNames, &currentName);
 
API_3DStyle apiStyle {};
// Get the details of the currently active style. The name field is used for identification.
GS::ucsncpy (apiStyle.name, currentName.ToUStr (), API_UniLongNameLen);
ACAPI_View_Get3DStyle (&apiStyle);
 
// Change ground color to green.
apiStyle.backGroundRGB = { 0.0, 1.0, 0.0 };
// Update the style.
ACAPI_View_Change3DStyle ( &apiStyle);
 
// Create a new style based on the current one, with a different sky color. Finally set it as the current style.
GS::UniString testStyleName ("testStyle");
if (!stylesNames.Contains (testStyleName)) {
    apiStyle.bkgSkyColor = { 0.2, 0.2, 1.0 };
    GS::ucsncpy (apiStyle.name, testStyleName.ToUStr (), API_UniLongNameLen);
    ACAPI_View_Create3DStyle (&apiStyle);
    ACAPI_View_SetCurrent3DStyle (&testStyleName);
}

ACAPI_View_Get3DWindowSets()

GSErrCode __ACENV_CALL ACAPI_View_Get3DWindowSets

(

API_3DWindowInfo *

windowInfo

)

Retrieves the 3D Window settings.

Parameters

windowInfo

[out] Parameters of the 3D Window

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - windowInfo is nullptr
• APIERR_NOPLAN - No open project

Remarks

This function is used to get the data of the '3D Window Settings' dialog box, and the size and zoom parameters of the 3D window.

ACAPI_View_GetDocumentFrom3DDefaults()

GSErrCode __ACENV_CALL ACAPI_View_GetDocumentFrom3DDefaults

(

API_DocumentFrom3DDefaults *

documentFrom3DDefaults

)

Returns the 3D document setting default values.

Parameters

documentFrom3DDefaults

[out] The default settings of 3D document database.

Returns

• NoError - The function completed with success.
• APIERR_BADPARS - The documentFrom3DDefaults parameter is nullptr.

Remarks

You can use this function to obtain the 3D document setting defaults.

ACAPI_View_GetDocumentFrom3DSettings()

GSErrCode __ACENV_CALL ACAPI_View_GetDocumentFrom3DSettings	(	API_DatabaseUnId *	databaseUnId,
		API_DocumentFrom3DType *	documentFrom3DType
	)

Returns the 3D document settings of the specified database.

Parameters

databaseUnId	[in] The database unique ID of the 3D document database to get the parameters for.
documentFrom3DType	[out] The parameters.

Returns

• NoError - The function completed with success.
• APIERR_BADDATABASE - The referred database is not a 3D document.
• APIERR_BADPARS - The dbPars or documentFrom3DType parameter is nullptr, or the settings couldn't be obtained.

Remarks

You can use this function to obtain the 3D document settings of the specified database.

ACAPI_View_GetGhostRecord()

GSErrCode __ACENV_CALL ACAPI_View_GetGhostRecord	(	const API_DatabaseUnId *	databaseUnId,
		API_GhostRecord *	ghostRecord
	)

Retrieve a Trace record from the database.

Parameters

databaseUnId	[in] Retrieve the trace record for this database (the parent database unid is given here).
ghostRecord	[out] The ghost record for that database.

Returns

• NoError - The function has completed with success.

Remarks

Use this function to retrieve an existing trace (ghost) record. You should pass the parent database unid here (the same database the trace record was created for).

ACAPI_View_GetGhostStorySettings()

GSErrCode __ACENV_CALL ACAPI_View_GetGhostStorySettings

(

API_GhostStoryType *

ghostStoryType

)

Retrieves the current ghost story settings.

Parameters

ghostStoryType

The ghost story settings

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - ghostStory is nullptr
• APIERR_NOPLAN - There is no floor plan window opened

Remarks

Use this function to retrieve the ghost story settings. The same data can also be required with the ACAPI_ProjectSetting_GetStorySettings environment function.

ACAPI_View_GetShowHideState()

GSErrCode __ACENV_CALL ACAPI_View_GetShowHideState

(

bool *

isShown

)

Returns the visibility of application.

Parameters

isShown

[out] Application is visible.

Returns

• NoError - The function has completed with success.

Remarks

This function is used to used to get visibility of application. The actual visibility can be changed with the ACAPI_View_ChangeShowHideState function. Supported on Windows only.

ACAPI_View_GetZoom()

GSErrCode __ACENV_CALL ACAPI_View_GetZoom	(	API_Box *	zoomBox = nullptr,
		API_Tranmat *	tranmat = nullptr
	)

Returns the actual zoom parameters of the current database.

Parameters

zoomBox	[out] The actual zoom parameters
tranmat	[out] Contains the floor plan grid rotation.

Returns

• NoError - The function has completed with success
• APIERR_BADDATABASE - The current database is not 2D drawing type
• APIERR_BADPARS - zoomBox is nullptr

Remarks

This function is used to retrieve the zoom box of the window of the current database if it is 2D drawing type window. To change the actual zoom box refer to the ACAPI_View_SetZoom function. To restore one of the previous zooms use the ACAPI_View_ResetZoom function.

ACAPI_View_GoToView()

GSErrCode __ACENV_CALL ACAPI_View_GoToView

(

const char *

viewGuidStr

)

Switches to the given navigator view.

Parameters

viewGuidStr

[in] string representation of the GUID of the navigator view to be generated

Returns

• NoError - the function has completed with success
• APIERR_BADPARS - viewGuidStr is nullptr, or not a valid GUID
• APIERR_BADID - no view found with the specified GUID
• APIERR_GENERAL - failed to generate the view

Remarks

This function simulates the action when you open a view from the Project Navigator. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

GSErrCode GoToLinkedDrawingView (const API_Element* drawingElem)
{
    API_DrawingLinkInfo drwLinkInfo;
    BNZeroMemory (&drwLinkInfo, sizeof (API_DrawingLinkInfo));
 
    GSErrCode err = ACAPI_Database (APIDb_GetDrawingLinkID, (void*) drawingElem->drawing.linkUId, &drwLinkInfo);
    if (drwLinkInfo.linkPath != nullptr)
        delete drwLinkInfo.linkPath;
    if (drwLinkInfo.viewPath != nullptr)
        BMKillPtr (&drwLinkInfo.viewPath);
 
    if (err == NoError)
        err = ACAPI_Automate (APIDo_GoToViewID, drwLinkInfo.linkGuid, nullptr);
 
    return err;
}

ACAPI_View_IsAutoGroupOn()

GSErrCode __ACENV_CALL ACAPI_View_IsAutoGroupOn

(

bool *

autoGrp

)

Returns the current state of the autogroup mode.

Parameters

autoGrp

[out] Autogroup mode is ON or OFF.

Returns

• NoError - The function completed with success.
• APIERR_NOPLAN - There is no plan window currently opened
• APIERR_BADPARS - autoGrp is nullptr

Remarks

This function is used to get the current autogroup mode.

ACAPI_View_IsAutoIntersectOn()

GSErrCode __ACENV_CALL ACAPI_View_IsAutoIntersectOn

(

bool *

isOn

)

Returns the state of the automatic wall intersection flag.

Parameters

isOn	Tells whether the automatic intersection of walls is turned on.

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - No open project.
• APIERR_BADPARS - The isOn parameter is nullptr.

Remarks

This flag was part of the Display Options in previous (pre-10) API versions. With the separation of the Display Options from Display and Output Options, automatic intersection has started its own 'life'. Its value can be modified with ACAPI_View_ChangeAutoIntersect.

ACAPI_View_IsSuspendGroupOn()

GSErrCode __ACENV_CALL ACAPI_View_IsSuspendGroupOn

(

bool *

suspGrp

)

Returns the current state of the Suspend Groups mode.

Parameters

suspGrp

[out] Suspend Groups mode is ON or OFF.

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - There is no plan window currently opened
• APIERR_BADPARS - suspGrp is nullptr

Remarks

This function is used to get the current suspendgroup mode. For changing the suspension state of groups use the ACAPI_Grouping_Tool function.

ACAPI_View_PointToCoord()

GSErrCode __ACENV_CALL ACAPI_View_PointToCoord	(	API_Point *	point,
		API_Coord *	coord
	)

Convert a screen coordinate into model coordinate in the current database.

Parameters

point	[in] the pixel screen coordinate to convert
coord	[out] the associated model space coordinate

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - any of the parameters are nullptr

Remarks

This function is used to determine the real (model space) coordinate of a screen pixel coordinate. It is the inverse function of ACAPI_View_CoordToPoint function. Note that different coordinates may be assigned to the same pixel. The conversion mainly depends on the window size, on the actual drawing scale and zoom settings (ACAPI_Drawing_GetDrawingScale, ACAPI_View_GetZoom) which means the projection is database dependent.

Example

API_Coord    c;
API_Point    p
GSErrCode    err;
 
c.x = 1.0;
c.y = 2.0;
err = ACAPI_Database (APIDb_CoordToPointID, &c, &p);
err = ACAPI_Database (APIDb_PointToCoordID, &p, &c);

ACAPI_View_Rebuild()

GSErrCode __ACENV_CALL ACAPI_View_Rebuild

(

bool *

doRebuildAndRegenerate = nullptr

)

Rebuilds the content of the current window.

Parameters

doRebuildAndRegenerate

[in] Performs a rebuild and regenerate operation instead of a simple rebuild. Optional; considered false (i.e. rebuild only) if omitted.

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - no open project
• APIERR_BADDATABASE - the current window and the active database don't match

Remarks

This function is used to rebuild the content of the current (front) window. The effect is the same as if the user chose the Rebuild menu command with or without holding the Option (Alt) key. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

GSErrCode   err;
bool        regenerate = true;      /* do rebuild & regenerate */
 
err = ACAPI_Automate (APIDo_RebuildID, &regenerate, nullptr);

ACAPI_View_Redraw()

GSErrCode __ACENV_CALL ACAPI_View_Redraw

(

)

Redraws the content of the current window.

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - no open project
• APIERR_BADDATABASE - the current window and the active database are not in synchrony

Remarks

This function is used to redraw the content of the current (front) window.

Example

GSErrCode    err;
err = ACAPI_Automate (APIDo_RedrawID, nullptr, nullptr);

ACAPI_View_ResetZoom()

GSErrCode __ACENV_CALL ACAPI_View_ResetZoom

(

short *

numOfStepsBack

)

Restores the zoom parameters of the current database by a given number of steps.

Parameters

numOfStepsBack

[in] Number of steps to go back among the previous zoom boxes

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - No open project.
• APIERR_BADDATABASE - The current database does not match to the current window. (This function works only in this case.)
• APIERR_BADPARS - The step number is less than 1 or greater than the number of currently stored zooms.

Remarks

This function is used to restore one of the previous zooms. The database will not be rebuilt. If the numOfStepsBack parameter is nullptr, the initial zoom is restored, and all the other stored zooms will be erased. To get the actual zoom box refer to the ACAPI_View_GetZoom function. To change the actual zoom box refer to the ACAPI_View_SetZoom and the ACAPI_View_Zoom functions.

Example

GSErrCode       err;
API_Box         zoomBox;
API_PrintPars   printPars;
short           numOfStepsBack;
 
BNZeroMemory (&zoomBox, sizeof (API_Box));
zoomBox.xMin = -1.5;
zoomBox.yMin =  0.0;
zoomBox.xMax =  1.5;
zoomBox.yMax =  3.0;
err = ACAPI_Automate (APIDo_ZoomID, &zoomBox, nullptr);
if (err == NoError) {
    BNZeroMemory (&printPars, sizeof (API_PrintPars));
    printPars.printArea = PrintArea_CurrentView;
    err = ACAPI_Automate (APIDo_PrintID, &printPars, nullptr);
 
    numOfStepsBack = 1;
    ACAPI_Database (APIDb_ReSetZoomID, &numOfStepsBack, nullptr);
    ACAPI_Automate (APIDo_RebuildID, nullptr, nullptr);
}

ACAPI_View_SetCurrent3DStyle()

GSErrCode __ACENV_CALL ACAPI_View_SetCurrent3DStyle

(

const GS::UniString *

name

)

Sets an existing style as active.

Parameters

name	[in] Name of an existing style

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - name is nullptr, or the specified style does not exist.
• APIERR_NOPLAN - No open project.

Remarks

See an example at the description of ACAPI_View_Get3DStyleList.

Example

// Get the name of all styles.
GS::Array<GS::UniString> stylesNames;
GS::UniString currentName;
ACAPI_View_Get3DStyleList (&stylesNames, &currentName);
 
API_3DStyle apiStyle {};
// Get the details of the currently active style. The name field is used for identification.
GS::ucsncpy (apiStyle.name, currentName.ToUStr (), API_UniLongNameLen);
ACAPI_View_Get3DStyle (&apiStyle);
 
// Change ground color to green.
apiStyle.backGroundRGB = { 0.0, 1.0, 0.0 };
// Update the style.
ACAPI_View_Change3DStyle ( &apiStyle);
 
// Create a new style based on the current one, with a different sky color. Finally set it as the current style.
GS::UniString testStyleName ("testStyle");
if (!stylesNames.Contains (testStyleName)) {
    apiStyle.bkgSkyColor = { 0.2, 0.2, 1.0 };
    GS::ucsncpy (apiStyle.name, testStyleName.ToUStr (), API_UniLongNameLen);
    ACAPI_View_Create3DStyle (&apiStyle);
    ACAPI_View_SetCurrent3DStyle (&testStyleName);
}

ACAPI_View_SetZoom()

GSErrCode __ACENV_CALL ACAPI_View_SetZoom	(	API_Box *	zoomBox = nullptr,
		API_Tranmat *	tranmat = nullptr
	)

Sets the zoom box of the current database.

Parameters

zoomBox	[in] The zoom parameters to set; pass nullptr to set the zoom factor according to the drawing extent.
tranmat	[in] Transformation matrix (optional parameter).

Returns

• NoError - The function has completed with success
• APIERR_NOPLAN - There is no any project opened
• APIERR_BADDATABASE - The current database is not 2D drawing type
• APIERR_BADPARS - The passed zoomBox is incorrect (empty box)

Remarks

This function is used to set the zoom box of the current 2D drawing type database. The database will not be rebuilt unless the transformation matrix is set. To get the actual zoom box refer to the ACAPI_View_GetZoom function. To restore one of the previous zooms use the ACAPI_View_ResetZoom function. You can modify the zoom of the 3D model window with the ACAPI_View_Change3DWindowSets environment function. In order to set the zoom of the top window, use the ACAPI_View_Zoom automation function instead.

ACAPI_View_ShowAllIn3D()

GSErrCode __ACENV_CALL ACAPI_View_ShowAllIn3D

(

)

Activates the 3D window and shows the whole model.

Returns

• NoError - The function has completed with success.
• APIERR_BADWINDOW - The command cannot be executed on the topmost window.

Remarks

Activates the 3D window and shows the whole model. To switch to the 3D window showing the selected elements only, use the ACAPI_View_ShowSelectionIn3D function.

ACAPI_View_ShowSelectionIn3D()

GSErrCode __ACENV_CALL ACAPI_View_ShowSelectionIn3D

(

)

Activates the 3D window and shows the selected elements.

Returns

• NoError - The function has completed with success.
• APIERR_BADWINDOW - The command cannot be executed on the topmost window.

Remarks

Activates the 3D window and shows the selected elements. To switch to the 3D window showing the all the elements, use the ACAPI_View_ShowAllIn3D function.

ACAPI_View_StoreViewSettings()

GSErrCode __ACENV_CALL ACAPI_View_StoreViewSettings

(

bool

store

)

Stores/restores the actual view settings.

Parameters

store

[in] stores the settings if not 0 , restore if 0

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The function cannot be stacked.

Remarks

Stores general view settings for a view before longer operations (e.g. saving the contents of a drawing elment), and restores them afterwards. This function has to be called in pairs, and cannot be stacked. Use this sparingly; may cause a rebuild.

ACAPI_View_Zoom()

GSErrCode __ACENV_CALL ACAPI_View_Zoom	(	API_Box *	zoomBox = nullptr,
		API_Rect *	zoomRect = nullptr,
		API_Tranmat *	tranmat = nullptr
	)

Performs a zoom operation.

Parameters

zoomBox	[in] The box to zoom in (optional parameter, can be nullptr)
zoomRect	[in] Zoom rectangle (optional parameter, alternative of zoomBox, can be nullptr)
tranmat	[in] Transformation matrix (optional parameter)

Returns

• NoError - The function has completed with success
• APIERR_NOPLAN - There is no open project
• APIERR_BADDATABASE - The active database is not the top window
• APIERR_BADPARS - The passed zoomBox is incorrect (empty box) or zoomRect is too small

Remarks

This function performs a zoom or a fit in window operation on the front window, and rebuilds it. If the zoomBox parameter is passed, the given zoom factor will be set up. Alternatively you can pass a rectangle to define the zoom in pixel coordinates. If both parameters are nullptr, a Fit In Window command will be executed. To set the zoom box of a 2D drawing type window without rebuilding the database, use the ACAPI_View_SetZoom database function. You can retrieve the current zoom box of a 2D drawing type window with ACAPI_View_GetZoom. If the top window is the 3D model window, only the zoomRect parameter is considered. You can retrieve the current window size with the ACAPI_View_Get3DWindowSets environment function. You can also modify the zoom of the 3D model window with the ACAPI_View_Change3DWindowSets environment function.

Example

ACAPI_Automate (APIDo_ZoomID, nullptr, nullptr);  // fit in window

ACAPI_View_ZoomToElements()

GSErrCode __ACENV_CALL ACAPI_View_ZoomToElements

(

const GS::Array< API_Guid > *

elemsToZoom

)

Zoom to the given elements.

Parameters

elemsToZoom

[in] Zoom to these elements (cannot be nullptr.

Returns

• APIERR_BADPARS - The elementsToZoom parameter is nullptr.
• NoError - The function has completed with success, or you passed an empty element array.

Remarks

The function works both in the 2D and 3D window.

ACAPI_View_ZoomToSelected()

GSErrCode __ACENV_CALL ACAPI_View_ZoomToSelected

(

)

Zooming to the actual selection. (Even in 3D.)

Returns

• NoError - The function has completed with success.

FindViewByGuid()

Result< View > ACAPI::v1::FindViewByGuid ( const API_Guid &  guid )

inline

Constuct a view object referring to an existing Archicad view by guid.

It is compatible with the guid member of the API_NavigatorItem struct.

Parameters

guid	The guid of the view.