Opens a new window.

    GSErrCode ACAPI_Database (
        APIDb_NewWindowID,
        API_NewWindowPars*              newWindowPars,
        APICustomWindowHandlerProc*     handlerProc
    );

 

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.

 

Return Values

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

For other common API errors see the API Errors document.

 

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);

 

Requirements

Version: API 4.1 or later

Header: APIdefs_Database.h

 

See Also

API_NewWindowPars, APICustomWindowHandlerProc,
APIDb_NewDatabaseID, APIDb_CloseWindowID,
ACAPI_Database, API Functions