View Handling

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

Classes
class	ACAPI::ModelViews::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 3x4 transformation matrix. More...
struct	API_StoryType
	Parameters of one story. More...
struct	API_AxonoPars
	Parallel projection parameters. 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. More...
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. More...
enum	API_3DCutSurfFills { API_3DDocumentVectorFilles = 1 , API_3DDocumentUniformMaterial = 2 , API_3DDocumentOwnMaterial = 3 , API_3DDocumentOwnShadedMaterial = 4 }
	How to display the cut surfaces. More...
enum	API_3DUncutSurfaceFillType { API_3DDocumentPenColor = 1 , API_3DDocumentMaterialColorShaded = 2 , API_3DDocumentMaterialColorNonShaded = 3 }
	How to display the uncut surfaces. More...
enum	API_3DHiddenEdgeVisibility { API_3DDocumentHideHiddenEdges , API_3DDocumentShowHiddenEdges }
	Show or hide hidden edges. More...
enum	API_3DOnCutPlaneVisibility { API_3DDocumentDontShowOnCutPlanes , API_3DDocumentShowOnCutPlanes }
	Show or hide hidden cut lines. More...
enum	API_DocumentSourceID { API_DDD = 1 , API_FloorPlan = 2 }
	3D Document source. More...
enum	API_ViewSourceID { API_Top = 1 , API_Bottom = 2 }
	Skeleton drawing 3D Document view source. More...

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

enum API_3DCutSurfFills

How to display the cut surfaces.

Enumerator
API_3DDocumentVectorFilles	Display the cut surfaces with the cut fill from the building materials.
API_3DDocumentUniformMaterial	Fill the cut surfaces with a custom color.
API_3DDocumentOwnMaterial	Display the cut surfaces based on the cut element's surface settings.
API_3DDocumentOwnShadedMaterial	Display the cut surfaces based on the cut element's surface settings, and shade.

API_3DFilterModeID

enum API_3DFilterModeID

The enumeration of the available 3D filter modes.

Remarks

Use this enum in API_3DFilterAndCutSettings structure.

Enumerator
API_FilterByRules	Show All by the given rules in API_3DFilterAndCutSettings structure.
API_FilterBySelection	Show Selection only.
API_FilterByMarqueeAndRules	Show Marquee by the given rules in API_3DFilterAndCutSettings structure.

API_3DHiddenEdgeVisibility

enum API_3DHiddenEdgeVisibility

Show or hide hidden edges.

Enumerator
API_3DDocumentHideHiddenEdges	Hide hidden edges.
API_3DDocumentShowHiddenEdges	Show hidden edges.

API_3DModelTypeID

enum API_3DModelTypeID

Model image type in the 3D window.

Remarks

The API_3DModelTypeID type is used in the API_3DWindowInfo structure.

Enumerator
API3DModel_Block	Block model
API3DModel_WireFrame	Wireframe model
API3DModel_Hiddenline	Hidden line model
API3DModel_Shading	Shaded model

API_3DOnCutPlaneVisibility

enum API_3DOnCutPlaneVisibility

Show or hide hidden cut lines.

Enumerator
API_3DDocumentDontShowOnCutPlanes	Hide hidden cut lines.
API_3DDocumentShowOnCutPlanes	Show hidden cut lines.

API_3DUncutSurfaceFillType

enum API_3DUncutSurfaceFillType

How to display the uncut surfaces.

Enumerator
API_3DDocumentPenColor	Fill the uncut surfaces with a custom color.
API_3DDocumentMaterialColorShaded	Display the uncut surfaces based on the element's surface settings.
API_3DDocumentMaterialColorNonShaded	Display the uncut surfaces based on the element's surface settings, and shade.

API_DocumentSourceID

enum API_DocumentSourceID

3D Document source.

Enumerator
API_DDD	3D Document is created from 3D source.
API_FloorPlan	3D Document is created from floorplan.

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.

Enumerator
APIShadContours_Draft	Rough contours are drawn in the shaded image
APIShadContours_Off	Contours are not visible in the shaded image
APIShadContours_Best	Fine contours are drawn in the shaded image

API_ShowGhostType

enum API_ShowGhostType

Represents the way of the ghost to be shown.

Enumerator
APIGhost_NoFloor	No floor to be shown (eg. Section or Detail database).
APIGhost_ShowOneFloor	Show one floor scpecified in API_GhostRecord.
APIGhost_ShowAboveFloor	Show above floor.
APIGhost_ShowBelowFloor	Show below floor.
APIGhost_ShowPreviousFloor	Show previous floor.
APIGhost_ShowAllStructure	Show all.

API_SpecFolderID

enum API_SpecFolderID

The selector of special folders.

Enumerator
API_ApplicationPrefsFolderID	The folder into which the application writes its preferences.
API_GraphisoftPrefsFolderID	The folder containing general preferences of Graphisoft applications.
API_GraphisoftHomeFolderID	The Graphisoft home folder.
API_CacheFolderID	The folder where the application may write data to speed up its operation.
API_DataFolderID	The location of the Data folder.
API_UserDocumentsFolderID	The folder where the application places the output files by default.
API_TemporaryFolderID	The folder where the application stores temporary data, and which will be emptied when you launch the application.
API_ApplicationFolderID	The folder containing the running application. It should be considered as read-only.
API_DefaultsFolderID	This folder contains the default preferences (e.g. default user profile settings, shortcuts, command layouts, etc.) that come with the program installation. Located in the application folder, and should be considered as read-only.
API_WebObjectsFolderID	This folder is the recommended place for storing objects and other files downloaded from the Web.
API_TemplatesFolderID	The default location of Archicad project templates.
API_HelpFolderID	The default location of the application's Help folder.
API_EmbeddedProjectLibraryFolderID	The location of the embedded project library.
API_EmbeddedProjectLibraryHotlinkFolderID	The location of the embedded project library of hotlinked modules.

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.

Enumerator
APIStory_GoTo	change the active story
APIStory_Delete	delete a story
APIStory_InsAbove	insert a new story above an existing one
APIStory_InsBelow	insert a new story below an existing one
APIStory_SetHeight	change the height of an existing story. It results that all of the above stories will have modified story level.
APIStory_Rename	change the name of an existing story
APIStory_SetElevation	change the elevation of an existing story
APIStory_SetDispOnSections	change the visibility of Story Level Lines in section window of an existing story

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.

Enumerator
APIVectShad_Off	Sun shadows are not generated
APIVectShad_ContOff_AllSurf	Sun shadows on all surfaces without contours
APIVectShad_ContOn_AllSurf	Sun shadows on all surfaces with contours
APIVectShad_ContOff_OneLevel	Sun shadows on a single level without contours
APIVectShad_ContOn_OneLevel	Sun shadows on a single level without contours

API_ViewSourceID

enum API_ViewSourceID

Skeleton drawing 3D Document view source.

Enumerator
API_Top	Floorplan skeleton drawing viewed from top.
API_Bottom	Floorplan skeleton drawing viewed from bottom.

Function Documentation

ACAPI_UserInput_ClearElementHighlight()

void 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
//------------------------------------------------------
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 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 {};
 
GSErrCode err = ACAPI_View_Get3DCuttingPlanes (&cutInfo);
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 = ACAPI_CreateAttributeIndex (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 = ACAPI_CreateAttributeIndex (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_View_Change3DCuttingPlanes (&cutInfo);
    if (err == NoError) {
        API_WindowInfo windowInfo {};
        windowInfo.typeID = APIWind_3DModelID;
        err = ACAPI_Window_ChangeWindow (&windowInfo);
    }
 
    BMKillHandle ((GSHandle *) &(cutInfo.shapes));
}

ACAPI_View_Change3DImageSets()

GSErrCode 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_View_Get3DImageSets (&filterAndCutSettings);
if (err == NoError) {
    filterAndCutSettings.elemTypeFilter.insert ({API_ZombieElemID, false}); // Hide everything in 3D
 
    ACAPI_View_Change3DImageSets (&filterAndCutSettings);
 
    filterAndCutSettings.elemTypeFilter.clear ();
    filterAndCutSettings.elemTypeFilter.insert ({API_WallID, true});
    filterAndCutSettings.elemTypeFilter.insert ({API_BeamID, true}); // show walls and beams only
    setMustConvert = true;
    ACAPI_View_Change3DImageSets (&filterAndCutSettings, &setMustConvert);
}

ACAPI_View_Change3DProjectionSets()

GSErrCode 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;
 
err = ACAPI_View_Get3DProjectionSets (&proj3DInfo);
if (err == NoError && proj3DInfo.isPersp && proj3DInfo.camGuid != APINULLGuid) {
    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_View_Change3DProjectionSets (&proj3DInfo, nullptr);
    }
}

ACAPI_View_Change3DStyle()

GSErrCode 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 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_View_Get3DWindowSets (&windowInfo);
if (err == NoError) {
    windowInfo.hSize *= 2;                              // grow 3D window size
    windowInfo.vSize *= 2;
    windowInfo.setWindowSize = true;
    ACAPI_View_Change3DWindowSets (&windowInfo);
}

ACAPI_View_ChangeAutoIntersect()

GSErrCode 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 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 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 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 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 ACAPI_View_CoordToPoint	(	API_Coord *	coord,
		API_Point *	point )

Converts a model coordinate to screen coordinate in the current database.

Parameters

coord	[in] The coordinate to convert.
point	[out] The associated screen coordinate.

Returns

• NoError - The function completed successfully.
• APIERR_BADPARS - Any of the parameters are nullptr.

Remarks

This function determines the pixel corresponding to a real coordinate. It is the inverse function of ACAPI_View_PointToCoord. Note that different coordinates may be assigned to the same pixel. The conversion mainly depends on the window size, 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;
 
c.x = 1.0;
c.y = 2.0;
ACAPI_View_CoordToPoint (&c, &p);
ACAPI_View_PointToCoord (&p, &c);

ACAPI_View_Create3DStyle()

GSErrCode 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 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).

API_GhostRecord apiGhostRecord;
GSErrCode err;
 
API_DatabaseInfo planDB;
BNZeroMemory (&planDB, sizeof (API_DatabaseInfo));
ACAPI_Database_GetCurrentDatabase (&planDB);
 
BNZeroMemory (&apiGhostRecord, sizeof (API_GhostRecord));
apiGhostRecord.parentDatabase = planDB.databaseUnId;
apiGhostRecord.floor = 0;
err = ACAPI_View_CreateGhostRecord (&apiGhostRecord);

ACAPI_View_DeleteGhostRecord()

GSErrCode 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 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

API_3DCutPlanesInfo cutInfo {};
 
GSErrCode err = ACAPI_View_Get3DCuttingPlanes (&cutInfo);
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 = ACAPI_CreateAttributeIndex (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 = ACAPI_CreateAttributeIndex (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_View_Change3DCuttingPlanes (&cutInfo);
    if (err == NoError) {
        API_WindowInfo windowInfo {};
        windowInfo.typeID = APIWind_3DModelID;
        err = ACAPI_Window_ChangeWindow (&windowInfo);
    }
 
    BMKillHandle ((GSHandle *) &(cutInfo.shapes));
}

ACAPI_View_Get3DImageSets()

GSErrCode 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 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 {};
 
return ACAPI_View_Get3DProjectionSets (&proj3DInfo);

ACAPI_View_Get3DStyle()

GSErrCode 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 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 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_GetCurrentImage()

GSErrCode ACAPI_View_GetCurrentImage	(	NewDisplay::NativeImage &	nativeImage,
		const API_ImageSource &	imageSource )

Gets an image of the current view (3D, or rendering).

Parameters

nativeImage	[in/out] contains the image data on output
imageSource	[in] describes the source of the image: 3D window or rendering window

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - No open project.
• APIERR_BADWINDOW - The current window is not valid for image export.

Remarks

This function retrieves an image of the current view, supporting both 3D and rendering windows.

ACAPI_View_GetDocumentFrom3DDefaults()

GSErrCode 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 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 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 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 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 ACAPI_View_GetZoom	(	API_Box *	zoomBox = nullptr,
		API_Tranmat *	tranmat = nullptr )

Returns the actual zoom parameters of the current database.

Parameters

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

Returns

• NoError - The function completed successfully.
• APIERR_BADDATABASE - The current database is not a 2D drawing type.
• APIERR_BADPARS - zoomBox is nullptr.

Remarks

This function retrieves the zoom box of the window of the current database if it is a 2D drawing type window. To change the current 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 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 completed successfully.
• 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 {};
 
    GSErrCode err = ACAPI_Drawing_GetDrawingLink (&drawingElem->drawing.head.guid, &drwLinkInfo);
    if (drwLinkInfo.linkPath != nullptr)
        delete drwLinkInfo.linkPath;
    if (drwLinkInfo.viewPath != nullptr)
        BMKillPtr (&drwLinkInfo.viewPath);
 
    if (err == NoError)
        err = ACAPI_View_GoToView (APIGuidToString (drwLinkInfo.linkGuid).ToCStr ().Get ());
 
    return err;
}

ACAPI_View_IsAutoGroupOn()

GSErrCode 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 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 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_ModelToScreen()

GSErrCode ACAPI_View_ModelToScreen	(	const API_Coord3D &	coord3D,
		API_Coord &	coord )

Projects a model coordinate to screen in the current view.

Parameters

coord3D	the coordinate to project to screen.
coord	the projected coordinate.

Returns

NoError - The function completed successfully.

Remarks

In 3D, coordinate projection happens. In other views, the z value of the 3D coordinate is simply disregarded.

Example code snippets from Notification Manager / Show notification bubble at local origo

 
    API_Coord3D localOrigo3D;
    if (auto getLocalOrigoResult = ACAPI_Database_GetLocOrigo (&localOrigo3D); getLocalOrigoResult != NoError) {
        ACAPI_WriteReport ("Failed to get Local Origo.", false);
        return;
    }
 
    API_Coord localOrigo;
    ACAPI_View_ModelToScreen (localOrigo3D, localOrigo);
 
    API_Point point;
    ACAPI_View_CoordToPoint (&localOrigo, &point);
 
    static constexpr const char* TestGuid = "255EACB7-197C-4176-B231-813D8F39AB29";
 
    auto notificationBubble = ACAPI::UI::Notification::CreateNotificationBubbleManager ().CreateNotificationBubble (APIGuidFromString (TestGuid));
 
    GS::UniString message = "This is a notification bubble at the local origo";
 
    notificationBubble.SetText (message);
    notificationBubble.SetIcon (DG::Icon (SysResModule, DG::Icon::Floppy));
    notificationBubble.SetTimeout (2000);
 
    notificationBubble.Show (point);
 

ACAPI_View_PointToCoord()

GSErrCode ACAPI_View_PointToCoord	(	API_Point *	point,
		API_Coord *	coord )

Converts a screen coordinate into a 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 completed successfully.
• APIERR_BADPARS - Any of the parameters are nullptr.

Remarks

This function determines the real (model space) coordinate of a screen pixel coordinate. It is the inverse function of ACAPI_View_CoordToPoint. Note that different coordinates may be assigned to the same pixel. The conversion mainly depends on the window size, 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;
 
c.x = 1.0;
c.y = 2.0;
ACAPI_View_CoordToPoint (&c, &p);
ACAPI_View_PointToCoord (&p, &c);

ACAPI_View_Rebuild()

GSErrCode 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 completed successfully.
• 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_View_Rebuild (&regenerate);

ACAPI_View_Redraw()

GSErrCode ACAPI_View_Redraw

(

)

Redraws the content of the current window.

Returns

• NoError - The function completed successfully.
• APIERR_NOPLAN - no open project
• APIERR_BADDATABASE - the current window and the active database are not in sync

Remarks

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

ACAPI_View_ResetZoom()

GSErrCode 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 completed successfully.
• APIERR_NOPLAN - No open project.
• APIERR_BADDATABASE - The current database does not match 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 restores one of the previous zooms. The database will not be rebuilt. If the numOfStepsBack parameter is nullptr, the initial zoom is restored, and all other stored zooms will be erased. To get the current zoom box, refer to the ACAPI_View_GetZoom function. To change the current 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;
 
zoomBox.xMin = -1.5;
zoomBox.yMin =  0.0;
zoomBox.xMax =  1.5;
zoomBox.yMax =  3.0;
err = ACAPI_View_Zoom (&zoomBox);
if (err == NoError) {
    printPars.printArea = PrintArea_CurrentView;
    err = ACAPI_ProjectOperation_Print (&printPars);
 
    numOfStepsBack = 1;
    ACAPI_View_ResetZoom (&numOfStepsBack);
    ACAPI_View_Rebuild ();
}

ACAPI_View_SetCurrent3DStyle()

GSErrCode 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 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 completed successfully
• 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 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 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 ACAPI_View_StoreViewSettings

(

bool

store

)

Stores or restores the current view settings.

Parameters

store

[in] Stores the settings if not 0, restores if 0.

Returns

• NoError - The function completed successfully.
• 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 element), and restores them afterwards. This function must be called in pairs and cannot be stacked. Use this sparingly; it may cause a rebuild.

ACAPI_View_Zoom()

GSErrCode 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 completed successfully.
• 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_View_Zoom ();  // fit in window

ACAPI_View_ZoomToElements()

GSErrCode 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 completed successfully, or you passed an empty element array.

Remarks

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

ACAPI_View_ZoomToSelected()

GSErrCode ACAPI_View_ZoomToSelected

(

)

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

Returns

• NoError - The function completed successfully.

FindViewByGuid()

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

inline

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

Parameters

guid	The guid of the view.

Returns

Returns the view wrapped in a Result.

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