Window Management

Functions related to the Project Windows, such as creating, opening, switching and closing windows. More...

Classes
struct	API_WindowInfo
	Identification parameters of a project window. More...
struct	API_NewWindowPars
	Parameters to open a new window. More...

Typedefs
typedef GSErrCode	APICustomWindowHandlerProc(const API_Guid &userRefId, API_NotifyWindowEventID notifID)
	User supplied callback function for handling events in windows opened by the add-on.

Enumerations
enum	API_WindowTypeID {   API_ZombieWindowID , APIWind_FloorPlanID , APIWind_SectionID , APIWind_DetailID ,   APIWind_3DModelID , APIWind_LayoutID , APIWind_DrawingID , APIWind_MyTextID ,   APIWind_MyDrawID , APIWind_MasterLayoutID , APIWind_ElevationID , APIWind_InteriorElevationID ,   APIWind_WorksheetID , APIWind_ReportID , APIWind_DocumentFrom3DID , APIWind_External3DID ,   APIWind_Movie3DID , APIWind_MovieRenderingID , APIWind_RenderingID , APIWind_ModelCompareID ,   APIWind_IESCommonDrawingID = 0x00001000 , APIWind_AllModel2DID , APIWind_AllModelID , APIWind_AllIFCID ,   APIWind_AllWithoutMovieRenderingID , APIWind_AllID }
	Possible values of a window/database identifier , API_DatabaseTypeID. More...

Functions
GSErrCode	ACAPI_Window_ChangeWindow (const API_WindowInfo *windowInfo)
	Changes the current (active) window.
GSErrCode	ACAPI_Window_GetCurrentWindow (API_WindowInfo *windowInfo)
	Returns the identifier of the current (active) window.
GSErrCode	ACAPI_Window_ResetCurrentWindow ()
	Deletes the database elements of the current window and sets up a new, empty environment.
GSErrCode	ACAPI_Window_NewWindow (API_NewWindowPars *newWindowPars, APICustomWindowHandlerProc *handlerProc=nullptr)
	Opens a new window.
GSErrCode	ACAPI_Window_CloseWindow (API_WindowInfo *windowInfo)
	Closes a window.
GSErrCode	ACAPI_Window_GetOwnWindows (API_WindowTypeID *windowTypeID, GS::Array< API_Guid > *guid=nullptr)
	Returns the ids of the opened windows in an array.
GSErrCode	ACAPI_Window_GetGridSettings (API_GridType *gridPars)
	Returns the grid setting parameters of the current database.
GSErrCode	ACAPI_Window_ChangeGridSettings (API_GridType *gridPars)
	Changes the grid setting parameters of the current database.
GSErrCode	ACAPI_Window_SetWindowId (const API_Guid *pOldGuid, const API_Guid *pNewGuid)
	Changes the guid of a previously registered window. Useful when replacing already opened windows by reusing their window object.
GSErrCode	ACAPI_Window_Check (API_ActionCenterItemID item)
	Runs the selected checks of the Action Center.

Detailed Description

Functions related to the Project Windows, such as creating, opening, switching and closing windows.

Typedef Documentation

APICustomWindowHandlerProc

typedef GSErrCode APICustomWindowHandlerProc(const API_Guid &userRefId, API_NotifyWindowEventID notifID)

User supplied callback function for handling events in windows opened by the add-on.

Parameters

userRefId	[in] The reference GUID of the custom window, as supplied to ACAPI_Window_NewWindow.
notifID	[in] The type of the event for the custom window.

Returns

• NoError - The function has completed with success.

Remarks

This function will be called when installed with ACAPI_Window_NewWindow. The following types of events will come for your custom window:

Event type	Description
APINotifyWindow_Rebuild	The user chose Rebuild from the menu.
APINotifyWindow_Activate	Your window was activated.
APINotifyWindow_Close	The user closed your window.

Enumeration Type Documentation

API_WindowTypeID

enum API_WindowTypeID

Possible values of a window/database identifier , API_DatabaseTypeID.

Remarks

This structure holds the parameters of a window or database reference. It must be passed in the case of changing the current window/database (ACAPI_Database_ChangeCurrentDatabase), or just getting the identification of the active one.(ACAPI_Window_GetCurrentWindow /ACAPI_Database_GetCurrentDatabase) In API_PublishFormatData structure it defines the windows in which the publish format is available.

Function Documentation

ACAPI_Window_ChangeGridSettings()

GSErrCode ACAPI_Window_ChangeGridSettings

(

API_GridType *

gridPars

)

Changes the grid setting parameters of the current database.

Parameters

gridPars

[out] the grid parameters

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - gridPars is nullptr

Remarks

This function is used to change the parameters of the actual grid setting. It is database dependent, each database may have different grid parameters set. The actual setting parameters can be got with the ACAPI_Window_GetGridSettings function.

Example

API_GridType        gridPars;
GSErrCode           err;
 
BNZeroMemory (&gridPars, sizeof (API_GridType));
err = ACAPI_Database (APIDb_GetGridSettingsID, &gridPars, nullptr);
if (err == NoError) {
    gridPars.gridSwitch = !gridPars.gridSwitch;
    err = ACAPI_Database (APIDb_ChangeGridSettingsID, &gridPars, nullptr);
}

ACAPI_Window_ChangeWindow()

GSErrCode ACAPI_Window_ChangeWindow

(

const API_WindowInfo *

windowInfo

)

Changes the current (active) window.

Parameters

windowInfo

[in] The identification parameters of the requested front window

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - windowInfo is nullptr.
• APIERR_NOPLAN - There is no any project opened.
• APIERR_BADWINDOW - the requested front window is invalid

Remarks

This function is used to change the front window of the server application. It performs the same operation as you click the appropriate menu item in the Window menu. Generally the current window and the window of the current database are the same. However you must be careful; the database dependent functions work on the current database instead of the database of the current window. The interface functions work on the current window always. Note, that this function changes the current database also. This function is very useful to access the database of a section/elevation and detail window if the ACAPI_Database_ChangeCurrentDatabase function has been failed. It occurs when the section or detail window was not opened any time since the actual project has been opened; the database is not available since it is not regenerated. Once the user switch to the section or detail window, the database becomes available. This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.

Example

API_WindowInfo      windowInfo;
API_DatabaseInfo    origDB, planDB;
API_Element         element;
GS::Array<API_Guid> elemList;
GSErrCode           err;
 
BNZeroMemory (&planDB, sizeof (API_DatabaseInfo));
planDB.typeID = APIWind_FloorPlanID;
 
ACAPI_Database (APIDb_GetCurrentDatabaseID, &origDB, nullptr);
ACAPI_Database (APIDb_ChangeCurrentDatabaseID, &planDB, nullptr);
 
ACAPI_Element_GetElemList (API_CutPlaneID, &elemList);
for (GS::Array<API_Guid>::ConstIterator it = elemList.Enumerate (); it != nullptr; ++it) {
    ACAPI_Database (APIDb_ChangeCurrentDatabaseID, &planDB, nullptr);
    BNZeroMemory (&element, sizeof (API_Element));
    element.header.guid = *it;
    err =  ACAPI_Element_Get (&element);
    if (err == NoError) {
        BNZeroMemory (&windowInfo, sizeof (API_WindowInfo));
        windowInfo.typeID = APIWind_SectionID;
        windowInfo.databaseUnId = element.cutPlane.databaseID;
        err = ACAPI_Automate (APIDo_ChangeWindowID, &windowInfo, nullptr);
    }
}

ACAPI_Window_Check()

GSErrCode ACAPI_Window_Check

(

API_ActionCenterItemID

item

)

Runs the selected checks of the Action Center.

Since

Archicad 25

Parameters

item	[in] The checks that Action Center will preform.

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - There is no open project.
• APIERR_REFUSEDCMD - Refused to run check method because of opened modal dialog.

Remarks

This function runs the checks of the Action Center. The Action Center tab will appear if an issue was found.

ACAPI_Window_CloseWindow()

GSErrCode ACAPI_Window_CloseWindow

(

API_WindowInfo *

windowInfo

)

Closes a window.

Parameters

windowInfo

parameters of the window to be closed (type and reference index)

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - windowPars is nullptr.
• APIERR_REFUSEDCMD - the function is called from notification level.
• APIERR_REFUSEDPAR - not APIWind_MyTextID or APIWind_MyDrawID is requested.
• APIERR_WINDNOTEXIST - a window with the same type and reference index is not opened.
• APIERR_NOPLAN - no open project

Remarks

This function is used to close a previously opened custom window. It is the inverse function of ACAPI_Window_NewWindow, so it is limited to close simple text or drawing windows. Such a window can be closed from the same addon, which it was opened from.

Example

API_WindowInfo      windowInfo;
GSErrCode           err;
 
BNZeroMemory (&windowInfo, sizeof (API_WindowInfo));
windowInfo.typeID = APIWind_MyDrawID;
windowInfo.index  = 1;
 
err = ACAPI_Database (APIDb_CloseWindowID, &windowInfo, nullptr);

ACAPI_Window_GetCurrentWindow()

GSErrCode ACAPI_Window_GetCurrentWindow

(

API_WindowInfo *

windowInfo

)

Returns the identifier of the current (active) window.

Parameters

windowInfo

[out] The identification parameters of the front window

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - windowInfo is nullptr.
• APIERR_BADWINDOW - the type of the current front window is not known by the API

Remarks

This function is used to return the parameters of the front window of the server application. It can be used to identify which window your command was called on. Generally the current window and the window of the current database are the same. However you must be careful; the database dependent functions work on the current database not on the database of the current window. The interface functions work on the current window always. Note that this function fills out only the fields which are needed to identify the window type and the database behind the window. In order to retrieve the additional parameters of the database (title, name, ref, masterLayoutUnId) call the ACAPI_Window_GetDatabaseInfo function with the databaseUnId of the current window. Use the ACAPI_Window_ChangeWindow function to change the current window.

Example

API_WindowInfo windowInfo;
BNZeroMemory (&windowInfo, sizeof (API_WindowInfo));
GSErrCode err = ACAPI_Database (APIDb_GetCurrentWindowID, &windowInfo, nullptr);

ACAPI_Window_GetGridSettings()

GSErrCode ACAPI_Window_GetGridSettings

(

API_GridType *

gridPars

)

Returns the grid setting parameters of the current database.

Parameters

gridPars

[out] the grid parameters

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - gridPars is nullptr

Remarks

This function is used to get the parameters of the actual grid setting. It is database dependent, each database may have different grid parameters set. The setting parameters can be changed with the ACAPI_Window_ChangeGridSettings function.

Example

API_GridType        gridPars;
GSErrCode           err;
 
BNZeroMemory (&gridPars, sizeof (API_GridType));
err = ACAPI_Database (APIDb_GetGridSettingsID, &gridPars, nullptr);
if (err == NoError) {
    gridPars.gridSwitch = !gridPars.gridSwitch;
    err = ACAPI_Database (APIDb_ChangeGridSettingsID, &gridPars, nullptr);
}

ACAPI_Window_GetOwnWindows()

GSErrCode ACAPI_Window_GetOwnWindows	(	API_WindowTypeID *	windowTypeID,
		GS::Array< API_Guid > *	guid = nullptr
	)

Returns the ids of the opened windows in an array.

Parameters

windowTypeID	[in] TypeID of the opened windows.
guid	[out] An array of guids of the opened windows.

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - There is no open project. The operation cannot be executed without an open project.
• APIERR_BADPARS - Incorrect windowTypeID or guid was specified.

ACAPI_Window_NewWindow()

GSErrCode ACAPI_Window_NewWindow	(	API_NewWindowPars *	newWindowPars,
		APICustomWindowHandlerProc *	handlerProc = nullptr
	)

Opens a new window.

Parameters

newWindowPars	[in] parameters of the window to be created (type and reference index)
handlerProc	[in] Callback function to handle special (e.g. activate) events. Specify nullptr if you are not interested in these events.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - windowPars is nullptr.
• APIERR_REFUSEDCMD - the function is called from notification level.
• APIERR_REFUSEDPAR - not APIWind_MyTextID or APIWind_MyDrawID is requested.
• APIERR_WINDEXIST - a window with the same type and reference index already opened.
• APIERR_NOPLAN - no open project

Remarks

This function is used to open a new window. It is limited to opening simple text or drawing windows. The drawing window will have limited functionality and database beyond, compared to a normal 2D model window. It can have real 2D elements only (lines, arcs, etc.), construction elements like walls or beams cannot appear in this database. The database cannot be modified by the user, the input and edit functionality on these windows are disabled for the user. These type of windows are excellent to visualize the output of your algorithms, for example in case of listings. An add-on can open any number of drawing and text windows at the same time. Once an add-on opens such a window, it will be responsible for rebuilding its content when it is necessary. Archicad will post notifications for such an event. Upon receiving a notification Archicad will pass the windowPars->userRefCon parameter to the add-on to identify which window it should work on. Refer to the Notification Manager to get further details.

Example

API_NewWindowPars   windowPars;
GSErrCode           err;
 
BNZeroMemory (&windowPars, sizeof (API_NewWindowPars));
windowPars.typeID = APIWind_MyDrawID;  // create a drawing window
windowPars.userRefCon = 1;
GS::snuprintf (windowPars.wTitle, sizeof (windowPars.wTitle) / sizeof (GS::uchar_t), L("API window: %ld"), userRefCon);
 
err = ACAPI_Database (APIDb_NewWindowID, &windowPars, nullptr);

ACAPI_Window_ResetCurrentWindow()

GSErrCode ACAPI_Window_ResetCurrentWindow

(

)

Deletes the database elements of the current window and sets up a new, empty environment.

Returns

• NoError - The function has completed with success.
• APIERR_BADWINDOW - The current database is not a custom drawing or owned by an other addon.

Remarks

This function is used to delete all elements from the current window. It returns an error if the active window is not a custom window owned by the caller addon. You can use the ACAPI_Window_ResetCurrentDatabase function to reset the content of any window being in the background.

ACAPI_Window_SetWindowId()

GSErrCode ACAPI_Window_SetWindowId	(	const API_Guid *	pOldGuid,
		const API_Guid *	pNewGuid
	)

Changes the guid of a previously registered window. Useful when replacing already opened windows by reusing their window object.

Parameters

pOldGuid	Guid of an existing window to be replaced with the new one.
pNewGuid	Guid of a non-existing window to replace the old one.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - pOldGuid or pNewGuid is nullptr
• APIERR_WINDNOTEXIST - No window found with the given guid.
• APIERR_WINDEXIST - There is a window already registered with the new guid.
• APIERR_GENERAL - Any other unexpected error

Remarks

If there is a content validator associated with the old guid, this function will delete it. This function only works if the window's type is either APIWind_MyDrawID or APIWind_MyTextID.