User input management

Functions providing a way to access existing user input methods or creating custom user input and feedback. More...

Classes
class	ACAPI::v1::InputHandler
	A class to handle input related operations, like manipulating the input position and starting an input. More...
struct	API_PolyArc
	Representation of an arc segment of a two dimensional polygon. More...
struct	API_Neig
	Describes a neig point of an element. More...
struct	API_MagicWandInfo
	Curve tracing parameters. More...
struct	API_CursorSet
	Cursor set definition for a user input. More...
struct	API_RubberLineType
	Rubber line definition. More...
struct	API_RubberArcType
	Rubber line definition. More...
struct	API_RubberLineInfo
	Parameters of the rubber line callback function. More...
struct	API_GetPointType
	Parameters of the point input operation. More...
struct	API_Get3DComponentType
	Parameters of the get component type in 3D operation. More...
struct	API_GetLineType
	Parameters of the line input operation. More...
struct	API_GetArcType
	Parameters of the arc input operation. More...
struct	API_RubberPolyCallbacks
	Parameters of the polygon input operation. More...
struct	API_GetPolyType
	Parameters of the polygon input operation. More...
struct	API_ConstraintPars
	Parameters of the drawing constraint. More...

Typedefs
typedef void	RubberLineInfoProc(const API_RubberLineInfo *info)
	Callback function for custom feedback drawing.
typedef void	Get3DComponentProc(const API_Get3DComponentType *info)
	Callback function for getting elem informations online (realtime).
typedef char	API_NeigFilter[API_NeigFilterSize]
	Structure for filtering neigs during user input.

Enumerations
enum	API_CursorFormID {   APICursor_UserDefined , APICursor_Default , APICursor_Spin , APICursor_SystemArrow ,   APICursor_SystemClock , APICursor_IBeam , APICursor_Drag , APICursor_Trident ,   APICursor_ZoomIn , APICursor_ZoomOut , APICursor_Hand , APICursor_MiniHand ,   APICursor_Cross , APICursor_Check , APICursor_CheckRef , APICursor_Branch ,   APICursor_BranchRef , APICursor_XPoint , APICursor_Normal , APICursor_Tangent ,   APICursor_Arrow , APICursor_ArrowCheck , APICursor_ArrowCheckRef , APICursor_ArrowBranch ,   APICursor_ArrowBranchRef , APICursor_ArrowXPoint , APICursor_ArrowNormal , APICursor_ArrowTangent ,   APICursor_Pencil , APICursor_PencilCheck , APICursor_PencilCheckRef , APICursor_PencilBranch ,   APICursor_PencilBranchRef , APICursor_PencilXPoint , APICursor_PencilNormal , APICursor_PencilTangent ,   APICursor_Eye , APICursor_DoubleEye , APICursor_Hammer , APICursor_MagicWand ,   APICursor_Trimmer , APICursor_TrimmerFull , APICursor_Picker , APICursor_PickerFull ,   APICursor_Injection , APICursor_InjectionFull }
	Predefined cursor forms for customizing the user input. More...
enum	API_InitNeigFilterID { APIInitNeigFilter_Full , APIInitNeigFilter_Empty , APIInitNeigFilter_On , APIInitNeigFilter_Node }
	Type of the neig filter initialization. More...
enum	API_ConstraintType {   APIConst_X = 1 , APIConst_Y = 2 , APIConst_Z = 3 , APIConst_A = 4 ,   APIConst_R = 5 }
	Type of the drawing constraint. More...

Functions
Result< InputHandler >	ACAPI::v1::CreateInputHandler ()
	A function to create an InputHandler instance, that lets you handle input related operations.
GSErrCode	ACAPI_UserInput_GetMagicWandSets (API_MagicWandInfo *magicWandInfo)
	Returns information on curve tracing parameters.
GSErrCode	ACAPI_UserInput_InitNeigFilter (API_NeigFilter *neigFilter, API_InitNeigFilterID initNeigFilterID)
	Initializes the neig filter for an input.
GSErrCode	ACAPI_UserInput_SetNeigFilter (API_NeigFilter *neigFilter, API_NeigID neigID)
	Sets one of the neig types in the neig filter to be filtered.
GSErrCode	ACAPI_UserInput_ClearNeigFilter (API_NeigFilter *neigFilter, API_NeigID neigID)
	Sets one of the neig types in the neig filter not to be filtered.
GSErrCode	ACAPI_UserInput_GetPoint (API_GetPointType *pointInfo, RubberLineInfoProc *rubberLineInfoProc=nullptr, Get3DComponentProc *get3DComponentProc=nullptr)
	Performs a point input.
GSErrCode	ACAPI_UserInput_GetLine (API_GetLineType *lineInfo, RubberLineInfoProc *rubberLineInfoProc=nullptr)
	Performs a line input.
GSErrCode	ACAPI_UserInput_GetArc (API_GetArcType *arcInfo, RubberLineInfoProc *rubberLineInfoProc=nullptr)
	Performs an arc input.
GSErrCode	ACAPI_UserInput_GetPoly (API_GetPolyType *polyInfo, API_RubberPolyCallbacks *rubberPolyCallbacks=nullptr)
	Performs polygon input.
GSErrCode	ACAPI_UserInput_DrawRubberLine (API_RubberLineType *rubberLine)
	Draws graphical feedback during an input process.
GSErrCode	ACAPI_UserInput_DrawRubberArc (API_RubberArcType *rubberArc)
	Draws graphical feedback during an input process.
GSErrCode	ACAPI_UserInput_CompleteUserInput ()
	Finishes the user input.
GSErrCode	ACAPI_UserInput_CancelUserInput ()
	Cancels the user input.
GSErrCode	ACAPI_UserInput_SetConstraint (API_ConstraintPars *constraintPars)
	Set the drawing constraint for graphical user input.
GSErrCode	ACAPI_UserInput_ResetConstraint ()
	Dissolve the drawing constraint.
void	ACAPI_UserInput_SetElementHighlight (const GS::HashTable< API_Guid, API_RGBAColor > &highlightedElems, const GS::Optional< bool > &wireframe3D=GS::NoValue, const GS::Optional< API_RGBAColor > &nonHighlightedElemsColor=GS::NoValue)
	Highlight elements in the 2D (floor plan and section) and 3D window.

Detailed Description

Functions providing a way to access existing user input methods or creating custom user input and feedback.

Typedef Documentation

API_NeigFilter

API_NeigFilter

Structure for filtering neigs during user input.

See also

ACAPI_UserInput_InitNeigFilter, ACAPI_UserInput_ClearNeigFilter, ACAPI_UserInput_SetNeigFilter

Get3DComponentProc

typedef void Get3DComponentProc(const API_Get3DComponentType *info)

Callback function for getting elem informations online (realtime).

Parameters

info	Information on the actual input state.

Remarks

None.

RubberLineInfoProc

typedef void RubberLineInfoProc(const API_RubberLineInfo *info)

Callback function for custom feedback drawing.

Parameters

info	Information on the actual input state.

Remarks

You should implement this function if you have to give graphical feedback for the input operation invoked from your API tool add-on. This callback routine should be passed as a parameter when calling the ACAPI_UserInput_GetPoint, ACAPI_UserInput_GetLine and ACAPI_UserInput_GetArc interface functions. During the input process your procedure is called repeatedly as the mouse moves. In the info parameter you get the actual mouse coordinate and the current drawing phase. Call the ACAPI_UserInput_DrawRubberLine interface function to draw your rubber lines. The lines are drawn in XOR mode, therefore you can use the same code for both the drawing and erasing phases when calling back. From Archicad 9 the z coordinates are retrieved even when the input plane has not been defined. The height value can be non-zero if the cursor is on one of the neigs of a three-dimensional element, or gravity method is switched on for the element type the cursor is currently cruising above.

Enumeration Type Documentation

API_ConstraintType

enum API_ConstraintType

Type of the drawing constraint.

Remarks

For the utilization of API_ConstraintType see the ACAPI_UserInput_SetConstraint function. When fixing the input angle (APIConst_A), constValue is defined in radian

API_CursorFormID

enum API_CursorFormID

Predefined cursor forms for customizing the user input.

Remarks

The API_CursorFormID values are used to specify the cursor set for a user input process invoked from the API tool add-on.

Form	Icon	Description
APICursor_UserDefined		Cursor defined by resource ID (NOT USED)
APICursor_Default		Default cursor shape
APICursor_Spin		Spin cursor (rotating beach balls)
APICursor_SystemArrow		System arrow cursor
APICursor_SystemClock		System clock cursor
APICursor_IBeam		I beam cursor for text editing
APICursor_Drag		Cursor for dragging windows
APICursor_Trident		Trident cursor for dragging rollrect
APICursor_ZoomIn		Zoom in cursor
APICursor_ZoomOut		Zoom out cursor
APICursor_Hand		Hand cursor
APICursor_MiniHand		Small hand cursor
APICursor_Cross		Cross cursor
APICursor_Check		Check cursor (indicates ...Neig)
APICursor_CheckRef		Check cursor (thick)
APICursor_Branch		Branch cursor (indicates ...OnNeig)
APICursor_BranchRef		Branch cursor (thick)
APICursor_XPoint		Cross point cursor
APICursor_Normal		Normal (perpendicular) cursor
APICursor_Tangent		Tangent (osculation) cursor
APICursor_Arrow		Arrow cursor (selection mode)
APICursor_ArrowCheck		Check cursor in arrow mode
APICursor_ArrowCheckRef		Check cursor in arrow mode (thick)
APICursor_ArrowBranch		Branch cursor in arrow mode
APICursor_ArrowBranchRef		Branch cursor in arrow mode (thick)
APICursor_ArrowXPoint		Cross point cursor in arrow mode
APICursor_ArrowNormal		Normal cursor in arrow mode
APICursor_ArrowTangent		Tangent cursor in arrow mode
APICursor_Pencil		Pencil shaped cursor during input
APICursor_PencilCheck		Check cursor during input
APICursor_PencilCheckRef		Check cursor during input (thick)
APICursor_PencilBranch		Branch cursor during input
APICursor_PencilBranchRef		Branch cursor during input (thick)
APICursor_PencilXPoint		Cross point cursor during input
APICursor_PencilNormal		Normal cursor during input
APICursor_PencilTangent		Tangent cursor during input
APICursor_Eye		Eye cursor for window/door opening
APICursor_DoubleEye		Double eye for window/door position
APICursor_Hammer		Hammer cursor for completing input
APICursor_MagicWand		Magic wand cursor
APICursor_Trimmer		Scissors shaped cursor
APICursor_TrimmerFull		Scissors shaped cursor (thick)
APICursor_Picker		Dropper shaped cursor
APICursor_PickerFull		Dropper shaped cursor (thick)
APICursor_Injection		Injection shaped cursor
APICursor_InjectionFull		Injection shaped cursor (thick)

For example of using custom cursor sets see ACAPI_UserInput_GetArc.

API_InitNeigFilterID

enum API_InitNeigFilterID

Type of the neig filter initialization.

Remarks

For the utilization of API_InitNeigFilterID see the ACAPI_UserInput_InitNeigFilter function.

Function Documentation

ACAPI_UserInput_CancelUserInput()

GSErrCode ACAPI_UserInput_CancelUserInput

(

)

Cancels the user input.

Returns

• NoError - The function has completed with success.

Remarks

It works as if the user clicked the Cancel button on the control box during input.

ACAPI_UserInput_ClearNeigFilter()

GSErrCode ACAPI_UserInput_ClearNeigFilter	(	API_NeigFilter *	neigFilter,
		API_NeigID	neigID
	)

Sets one of the neig types in the neig filter not to be filtered.

Parameters

neigFilter	[in] The neig filter.
neigID	[in] Neig type to clear out from filtering.

Returns

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

Remarks

This function is used to set one of the neig types not to be filtered during a user input. More information about neig filtering can be found at the remarks section of the ACAPI_UserInput_InitNeigFilter function. To set a new filter use the ACAPI_UserInput_SetNeigFilter function.

Example

See APIIo_DrawRubberLineID
for example of using input neig filters.

ACAPI_UserInput_CompleteUserInput()

GSErrCode ACAPI_UserInput_CompleteUserInput

(

)

Finishes the user input.

Returns

• NoError - The function has completed with success.

Remarks

It works as if the user clicked the OK button on the control box during input.

ACAPI_UserInput_DrawRubberArc()

GSErrCode ACAPI_UserInput_DrawRubberArc

(

API_RubberArcType *

rubberArc

)

Draws graphical feedback during an input process.

Parameters

rubberArc

[in] Definition of the arc (circle or elliptic) to be drawn.

Returns

• NoError - The function has completed with success.
• APIERR_GENERAL - no rubber line callback function has been defined
• APIERR_BADPARS - rubberArc->arcType is neither APIRubberArc_OrigoAngles nor APIRubberArc_ThreePoint

Remarks

This function is used to draw rubber arcs while a user input. The function can be called only from the RubberLineInfoProc passed to the given input function; ACAPI_UserInput_GetPoint or ACAPI_UserInput_GetLine or ACAPI_UserInput_GetArc or ACAPI_UserInput_GetPoly. The arc is defined with the coordinate of the center point, the radius (or 'a' if ellipse), the beginning angle of the arc and the ending angle of the arc or with the coordinate of the center point, the beginning point of the arc, the ending point of the arc and the sign of the arc's angle (see API_RubberArcType).

Example

#define         PI                      3.141592653589793
 
/*------------------------------------------------------**
** Callback function to draw the rubber lines           **
**------------------------------------------------------*/
static void RubberLineCallBack (const API_RubberLineInfo *info)
 
{
    API_RubberArcType  rubberArc;
 
    BNZeroMemory (&rubberArc, sizeof (API_RubberArcType));
 
    rubberArc.lineThick = APIRubberLine_Simple;
    /* draws a unit circle around the actual cursor position */
 
    rubberArc.arcType = APIRubberArc_OrigoAngles;
    rubberArc.arc2D.r = crossWidth;
    rubberArc.arc2D.angle = 0.0;
    rubberArc.arc2D.ratio = 1.0;
    rubberArc.arc2D.begAng = 0;
    rubberArc.arc2D.endAng = 2 * PI;
    rubberArc.origC = info->actCoord;
    ACAPI_Interface (APIIo_DrawRubberArcID, &rubberArc, nullptr);
    return;
}
 
/*------------------------------------------------------**
** Filtered point input with rubberline feedback        **
**------------------------------------------------------*/
void    PutColumnOnAHotspot (void)
 
{
    GSErrCode           err;
    API_GetPointType    pointInfo;
    API_Element         elem;
 
    BNZeroMemory (&pointInfo, sizeof (API_GetPointType));
    CHCopyC ("Click onto a hotspot to create column", pointInfo.prompt);
 
    pointInfo.changeFilter = true;        /* let the cursor gravitate to hotspot neigs only */
    ACAPI_Interface (APIIo_InitNeigFilterID, pointInfo.filter, (void *) APIInitNeigFilter_Empty);
    ACAPI_Interface (APIIo_SetNeigFilterID, pointInfo.filter, (void *) APINeig_Hot);
 
    err = ACAPI_Interface (APIIo_GetPointID, &pointInfo, (void *) RubberLineCallBack);
 
    if (err) {
        if (err == APIERR_CANCEL)
            ACAPI_WriteReport ("Input was interrupted", true);
        else
            ACAPI_WriteReport ("Error in GetPoint", true);
    } else {
        if (pointInfo.neig.neigID != APINeig_Hot) {
            ACAPI_WriteReport ("There is no hotspot at the clicked position", true);
        } else {
            BNZeroMemory (&elem, sizeof (API_Element));
            elem.header.type = API_ColumnID;
            err = ACAPI_Element_GetDefaults (&elem, nullptr);
            if (err == NoError) {
                elem.column.origoPos.x = pointInfo.pos.x;
                elem.column.origoPos.y = pointInfo.pos.y;
                err = ACAPI_Element_Create (&elem, nullptr);
            }
        }
    }
 
    return;
}

ACAPI_UserInput_DrawRubberLine()

GSErrCode ACAPI_UserInput_DrawRubberLine

(

API_RubberLineType *

rubberLine

)

Draws graphical feedback during an input process.

Parameters

rubberLine

[in] Definition of the line to be drawn.

Returns

• NoError - The function has completed with success.
• APIERR_GENERAL - no rubber line callback function has been defined

Remarks

This function is used to draw rubber lines while a user input. The function can be called only from the RubberLineInfoProc passed to the given input function; ACAPI_UserInput_GetPoint or ACAPI_UserInput_GetLine or ACAPI_UserInput_GetArc or ACAPI_UserInput_GetPoly. The line is defined with the two endpoint coordinates. Note that during an input in the 3D model window the z coordinate can also be used to draw the feedback.

Example

/*------------------------------------------------------**
** Callback function to draw the rubber lines           **
**------------------------------------------------------*/
static void RubberLineCallBack (const API_RubberLineInfo *info)
 
{
    API_RubberLineType  rubberLine;
 
    BNZeroMemory (&rubberLine, sizeof (API_RubberLineType));
 
    rubberLine.lineThick = APIRubberLine_Simple;
    /* draws a unit square around the actual cursor position */
 
    rubberLine.c2.x = info->actCoord.x - 0.5;
    rubberLine.c2.y = info->actCoord.y - 0.5;
    rubberLine.c2.z = info->actCoord.z;
    rubberLine.c1 = rubberLine.c2;
    rubberLine.c2.y += 1.0;
    ACAPI_Interface (APIIo_DrawRubberLineID, &rubberLine, nullptr);
 
    rubberLine.c1 = rubberLine.c2;
    rubberLine.c2.x += 1.0;
    ACAPI_Interface (APIIo_DrawRubberLineID, &rubberLine, nullptr);
 
    rubberLine.c1 = rubberLine.c2;
    rubberLine.c2.y -= 1.0;
    ACAPI_Interface (APIIo_DrawRubberLineID, &rubberLine, nullptr);
 
    rubberLine.c1 = rubberLine.c2;
    rubberLine.c2.x -= 1.0;
    ACAPI_Interface (APIIo_DrawRubberLineID, &rubberLine, nullptr);
 
    return;
}
 
/*------------------------------------------------------**
** Filtered point input with rubberline feedback        **
**------------------------------------------------------*/
void    PutColumnOnAHotspot (void)
 
{
    GSErrCode           err;
    API_GetPointType    pointInfo;
    API_Element         elem;
 
    BNZeroMemory (&pointInfo, sizeof (API_GetPointType));
    CHCopyC ("Click onto a hotspot to create column", pointInfo.prompt);
 
    pointInfo.changeFilter = true;        /* let the cursor gravitate to hotspot neigs only */
    ACAPI_Interface (APIIo_InitNeigFilterID, pointInfo.filter, (void *) APIInitNeigFilter_Empty);
    ACAPI_Interface (APIIo_SetNeigFilterID, pointInfo.filter, (void *) APINeig_Hot);
 
    err = ACAPI_Interface (APIIo_GetPointID, &pointInfo, (void *) RubberLineCallBack);
 
    if (err) {
        if (err == APIERR_CANCEL)
            ACAPI_WriteReport ("Input was interrupted", true);
        else
            ACAPI_WriteReport ("Error in GetPoint", true);
    } else {
        if (pointInfo.neig.neigID != APINeig_Hot) {
            ACAPI_WriteReport ("There is no hotspot at the clicked position", true);
        } else {
            BNZeroMemory (&elem, sizeof (API_Element));
            elem.header.type = API_ColumnID;
            err = ACAPI_Element_GetDefaults (&elem, nullptr);
            if (err == NoError) {
                elem.column.origoPos.x = pointInfo.pos.x;
                elem.column.origoPos.y = pointInfo.pos.y;
                err = ACAPI_Element_Create (&elem, nullptr);
            }
        }
    }
 
    return;
}

ACAPI_UserInput_GetArc()

GSErrCode ACAPI_UserInput_GetArc	(	API_GetArcType *	arcInfo,
		RubberLineInfoProc *	rubberLineInfoProc = nullptr
	)

Performs an arc input.

Parameters

arcInfo	[in/out] Parameters of the arc input operation.
rubberLineInfoProc	[in] Callback function for custom feedback drawing.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - arcInfo is nullptr
• APIERR_BADPLANE - invalid plane definition in arcInfo
• APIERR_BADWINDOW - the operation cannot be performed in the current front window of the application
• APIERR_CANCEL - the input was canceled by the user

Remarks

This function is used to let the user input an arc graphically. If the input process has failed, the function returns APIERR_CANCEL. Otherwise the result is returned in the startCoord (if the start coordinate has not been given before the arc input), negArc, pos and neig fields of arcInfo. The center point and the start point of the arc can be defined directly, or entered graphically with the ACAPI_UserInput_GetPoint and ACAPI_UserInput_GetLine interface functions. The prompt string displayed in the control box which can contain instructions about the action. You can control the cursor gravity above neigs and the cursor shapes, and set the input plane. There is a possibility of drawing own graphical feedback during the input with passing a pointer to your rubber line callback function. For more details on the utilization refer to the documentation of the API_GetArcType structure. Do not invoke any input operation while there are modal dialogs open.

Example

API_GetPointType    pointInfo;
API_GetLineType     lineInfo;
API_GetArcType      arcInfo;
char                buffer [256];
GSErrCode           err;
 
BNZeroMemory (&pointInfo, sizeof (API_GetPointType));
BNZeroMemory (&lineInfo, sizeof (API_GetLineType));
BNZeroMemory (&arcInfo, sizeof (API_GetArcType));
 
CHCopyC ("Click the arc center point", pointInfo.prompt);
pointInfo.changeCursorSet = true;
 
/* show cross cursors suggesting the center point */
pointInfo.cursorSet.nothingOnCursor     = APICursor_XPoint;
pointInfo.cursorSet.pointOnCursor       = APICursor_ArrowXPoint;
pointInfo.cursorSet.lineOnCursor        = APICursor_PencilXPoint;
pointInfo.cursorSet.refPointOnCursor    = APICursor_ArrowXPoint;
pointInfo.cursorSet.refLineOnCursor     = APICursor_PencilXPoint;
pointInfo.cursorSet.crossOnCursor       = APICursor_ArrowXPoint;
pointInfo.cursorSet.normalOnCursor      = APICursor_PencilXPoint;
pointInfo.cursorSet.tangentOnCursor     = APICursor_ArrowXPoint;
 
err = ACAPI_Interface (APIIo_GetPointID, &pointInfo, nullptr);
 
if (!err) {
    CHCopyC ("Enter the arc start point", lineInfo.prompt);
    lineInfo.startCoord = pointInfo.pos;
    lineInfo.changeCursorSet = true;
 
    /* use hand cursors for drawing the radius of the arc */
    lineInfo.cursorSet.nothingOnCursor  = APICursor_Hand;
    lineInfo.cursorSet.pointOnCursor    = APICursor_MiniHand;
    lineInfo.cursorSet.lineOnCursor     = APICursor_MiniHand;
    lineInfo.cursorSet.refPointOnCursor = APICursor_MiniHand;
    lineInfo.cursorSet.refLineOnCursor  = APICursor_MiniHand;
    lineInfo.cursorSet.crossOnCursor    = APICursor_MiniHand;
    lineInfo.cursorSet.normalOnCursor   = APICursor_MiniHand;
    lineInfo.cursorSet.tangentOnCursor  = APICursor_MiniHand;
 
    err = ACAPI_Interface (APIIo_GetLineID, &lineInfo, nullptr);
}
 
if (!err) {
    CHCopyC ("Enter the arc end point", arcInfo.prompt);
    arcInfo.origo = lineInfo.startCoord;
    arcInfo.startCoord = lineInfo.pos;
    arcInfo.startCoordGiven = true;
    arcInfo.changeCursorSet = true;
 
    /* use eye cursors for getting the arc */
    arcInfo.cursorSet.nothingOnCursor   = APICursor_Eye;
    arcInfo.cursorSet.pointOnCursor     = APICursor_DoubleEye;
    arcInfo.cursorSet.lineOnCursor      = APICursor_DoubleEye;
    arcInfo.cursorSet.refPointOnCursor  = APICursor_DoubleEye;
    arcInfo.cursorSet.refLineOnCursor   = APICursor_DoubleEye;
    arcInfo.cursorSet.crossOnCursor     = APICursor_DoubleEye;
    arcInfo.cursorSet.normalOnCursor    = APICursor_DoubleEye;
    arcInfo.cursorSet.tangentOnCursor   = APICursor_DoubleEye;
 
    err = ACAPI_Interface (APIIo_GetArcID, &arcInfo, nullptr);
}
 
if (!err) {
    sprintf (buffer, "Origo coordinates:  (%Lf, %Lf)", arcInfo.origo.x, arcInfo.origo.y);
    ACAPI_WriteReport (buffer, false);
    if (arcInfo.negArc)
        sprintf (buffer, "Arc begins:  (%Lf, %Lf)\nArc ends:    (%Lf, %Lf)",
                arcInfo.pos.x, arcInfo.pos.y, arcInfo.startCoord.x, arcInfo.startCoord.y);
    else
        sprintf (buffer, "Arc begins:  (%Lf, %Lf)\nArc ends:    (%Lf, %Lf)",
                arcInfo.startCoord.x, arcInfo.startCoord.y, arcInfo.pos.x, arcInfo.pos.y);
    ACAPI_WriteReport (buffer, false);
} else if (err == APIERR_CANCEL)
    ACAPI_WriteReport ("Input was interrupted", true);

ACAPI_UserInput_GetLine()

GSErrCode ACAPI_UserInput_GetLine	(	API_GetLineType *	lineInfo,
		RubberLineInfoProc *	rubberLineInfoProc = nullptr
	)

Performs a line input.

Parameters

lineInfo	[in/out] Parameters of the line input operation.
rubberLineInfoProc	[in] Callback function for custom feedback drawing.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - lineInfo is nullptr
• APIERR_BADPLANE - invalid plane definition in lineInfo
• APIERR_BADWINDOW - the operation cannot be performed in the current front window of the application
• APIERR_CANCEL - the input was canceled by the user

Remarks

This function is used to let the user input a line graphically. If the input process has failed, the function returns APIERR_CANCEL. Otherwise the result is returned in the pos and neig fields of lineInfo. The start point of the line can be defined directly, or entered graphically with the ACAPI_UserInput_GetPoint interface function. The prompt string displayed in the control box which can contain instructions about the action. You can control the cursor gravity above neigs and the cursor shapes, and set the input plane. There is a possibility of drawing own graphical feedback during the input with passing a pointer to your rubber line callback function. For more details on the utilization refer to the documentation of the API_GetLineType structure. Do not invoke any input operation while there are modal dialogs open.

Example

See the examples of the APIIo_GetArcID
and APIIo_DrawRubberLineID
functions.

ACAPI_UserInput_GetMagicWandSets()

GSErrCode ACAPI_UserInput_GetMagicWandSets

(

API_MagicWandInfo *

magicWandInfo

)

Returns information on curve tracing parameters.

Parameters

magicWandInfo

[out] Parameters of the 'Magic Wand Settings...' dialog.

Returns

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

Remarks

This function is used to get the parameters can be set in the 'Magic Wand Settings...' dialog. Refer to the API_MagicWandInfo structure to get further details.

Example

API_MagicWandInfo  magicInfo;
GSErrCode          err;
 
BNZeroMemory (&magicInfo, sizeof (API_MagicWandInfo));
err = ACAPI_Environment (GetMagicWandSetsID, &magicInfo, nullptr);

ACAPI_UserInput_GetPoint()

GSErrCode ACAPI_UserInput_GetPoint	(	API_GetPointType *	pointInfo,
		RubberLineInfoProc *	rubberLineInfoProc = nullptr,
		Get3DComponentProc *	get3DComponentProc = nullptr
	)

Performs a point input.

Parameters

pointInfo	[in/out] Parameters of the point input operation.
rubberLineInfoProc	[in] Callback function for custom feedback drawing.
get3DComponentProc	[in] Callback function for getting elem informations online (realtime).

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - pointInfo is nullptr
• APIERR_BADPLANE - invalid plane definition in pointInfo
• APIERR_BADWINDOW - the operation cannot be performed in the current front window of the application
• APIERR_CANCEL - the input was canceled by the user

Remarks

This function is used to let the user input a point graphically. If the input process has failed, the function returns APIERR_CANCEL. Otherwise the result is returned in the pos and neig fields of pointInfo. The prompt string displayed in the control box which can contain instructions about the action. You can control the cursor gravity above neigs and the cursor shapes, and set the input plane. There is a possibility of drawing own graphical feedback during the input with passing a pointer to your rubber line callback function. For more details on the utilization refer to the documentation of the API_GetPointType structure. Do not invoke any input operation while there are modal dialogs open.

Example

See the examples of the APIIo_GetArcID
and APIIo_DrawRubberLineID
functions.

ACAPI_UserInput_GetPoly()

GSErrCode ACAPI_UserInput_GetPoly	(	API_GetPolyType *	polyInfo,
		API_RubberPolyCallbacks *	rubberPolyCallbacks = nullptr
	)

Performs polygon input.

Parameters

polyInfo	[in/out] Parameters of the polygon input operation.
rubberPolyCallbacks	[in] Callback functions for custom feedback drawing. Optional, can be nullptr.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - polyInfo is nullptr or one of the rubber callback function pointers in rubberProcs is nullptr
• APIERR_BADPLANE - Invalid plane definition in polyInfo
• APIERR_BADWINDOW - The operation cannot be performed in the current front window of the application
• APIERR_CANCEL - The input was canceled by the user

Remarks

This function is used to let the user input a polygon graphically. If the input process has failed, the function returns APIERR_CANCEL. Otherwise the result is returned in the coords, parcs, nCoords, nArcs and polylineWas fields of polyInfo. The returned polygon consists of at least 2 points. The polygon's coordinates start from index 1, and the polygon is closed if polyInfo->polylineWas is false, meaning that the last point is equal to the first. Do not forget to dispose the coords and parcs handle with BMKillHandle. If changePlane has not been set for the input, the z coordinates of the polygon nodes can be also retrieved in the zCoords handle by passing true in the getZCoords member of API_GetPolyType. In this case the add-on should dispose this handle when it is not needed any more. The start point of the polyline can be defined directly, or entered graphically with the ACAPI_UserInput_GetPoint interface function. The prompt string displayed in the control box can contain instructions about the action. You can control the cursor shapes, set the input plane and the specify the polygon input method. From API v3.1 it is possible to draw your own graphical feedback during the input, as it is provided in the ACAPI_UserInput_GetPoint, ACAPI_UserInput_GetLine, ACAPI_UserInput_GetArc functions. For more details on the utilization refer to the documentation of the API_GetPolyType structure. Do not invoke any input operation while there are modal dialogs open.

Example

API_GetPointType    pointInfo;
API_GetPolyType     polyInfo;
Int32               ind;
char                buffer [256];
GSErrCode           err;
 
BNZeroMemory (&pointInfo, sizeof (API_GetPointType));
BNZeroMemory (&polyInfo, sizeof (API_GetPolyType));
 
CHCopyC ("Click the first node of the polygon", pointInfo.prompt);
 
err = ACAPI_Interface (APIIo_GetPointID, &pointInfo, nullptr);
 
if (err == NoError) {
    CHCopyC ("Enter the polygon nodes", polyInfo.prompt);
    polyInfo.startCoord = pointInfo.pos;                  /* polygon starts with the clicked point */
    polyInfo.method = APIPolyGetMethod_General;
 
    err = ACAPI_Interface (APIIo_GetPolyID, &polyInfo, nullptr);
}
 
if (err == NoError) {
    ACAPI_WriteReport ("Polygon Coordinates:", false);
    for (ind = 1; ind <= polyInfo.nCoords; ind++) {
        sprintf (buffer, "[%2d]  (%Lf, %Lf)", ind, (*polyInfo.pos) [ind].x, (*polyInfo.pos) [ind].y);
        ACAPI_WriteReport (buffer, false, false);
    }
} else if (err == APIERR_CANCEL)
    ACAPI_WriteReport ("Input was interrupted", true);

ACAPI_UserInput_InitNeigFilter()

GSErrCode ACAPI_UserInput_InitNeigFilter	(	API_NeigFilter *	neigFilter,
		API_InitNeigFilterID	initNeigFilterID
	)

Initializes the neig filter for an input.

Parameters

neigFilter	[in] The neig filter.
initNeigFilterID	[in] Type of the filter initialization. The possible values: Filter value Meaning APIInitNeigFilter_Full Filter all neig types APIInitNeigFilter_Empty Filter nothing APIInitNeigFilter_On Filter line type neigs only APIInitNeigFilter_Node Filter node type neigs only

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - neigFilter is nullptr or initNeigFilterID is not a valid API_InitNeigFilterID value

Remarks

This function is used to initialize the neig filter for an input process. Use neig filtering if you want to control the default behavior of the cursor sensitivity above a certain set of neig types. During a filtered input the cursor gravity works only for those neig types that are set in the neig filter, all the other neigs will be ignored. To change certain filters in the API_NeigFilter structure use the the ACAPI_UserInput_SetNeigFilter and ACAPI_UserInput_ClearNeigFilter functions. Note that the changeFilter field of the API_NeigFilter structure must be set to true, in order to have the neig filter effect.

Example

See APIIo_DrawRubberLineID
for example of using input neig filters.

ACAPI_UserInput_ResetConstraint()

GSErrCode ACAPI_UserInput_ResetConstraint

(

)

Dissolve the drawing constraint.

Returns

• NoError - The function has completed with success.

Remarks

This function is used to dissolve drawing constraint. Do not forget to call it after ACAPI_UserInput_SetConstraint.

Example

See the example of the APIIo_SetConstraintID
function.

ACAPI_UserInput_SetConstraint()

GSErrCode ACAPI_UserInput_SetConstraint

(

API_ConstraintPars *

constraintPars

)

Set the drawing constraint for graphical user input.

Parameters

constraintPars

[in] Parameters of the drawing constraint.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - constraintPars is nullptr
• APIERR_BADID - Invalid type of drawing constraint in constraintPars

Remarks

This function is used to set drawing constraint before the user input. It could be called just before ACAPI_UserInput_GetPoint, ACAPI_UserInput_GetLine, ACAPI_UserInput_GetArc, ACAPI_UserInput_GetPoly or in the addPolyNodeProc, delPolyNodeProc callback functions. After finishing the input do not forget to call ACAPI_UserInput_ResetConstraint function.

Example

API_GetPointType    pointInfo;
API_GetLineType     lineInfo;
API_ConstraintPars  constPars;
Int32               ind;
char                buffer [256];
GSErrCode           err;
 
BNZeroMemory (&pointInfo, sizeof (API_GetPointType));
BNZeroMemory (&lineInfo, sizeof (API_GetLineType));
BNZeroMemory (&constPars, sizeof (API_ConstraintPars));
 
 
CHCopyC ("Click the first point of the line", pointInfo.prompt);
 
err = ACAPI_Interface (APIIo_GetPointID, &pointInfo, nullptr);
 
if (err == NoError) {
    constPars.constType = APIConst_X;
    constPars.constValue = 2.0;
    constPars.useLocOrigo = true;
    err = ACAPI_Interface (APIIo_SetConstraintID, &constPars, nullptr);
    if (err == NoError) {
        CHCopyC ("Enter the second point of the line", lineInfo.prompt);
        lineInfo.startCoord = pointInfo.pos;                  /* line starts with the clicked point */
        err = ACAPI_Interface (APIIo_GetLineID, &lineInfo, nullptr);
    }
    ACAPI_Interface (APIIo_ResetConstraintID, nullptr, nullptr);
}
 
if (err == APIERR_CANCEL)
    ACAPI_WriteReport ("Input was interrupted", true);

ACAPI_UserInput_SetElementHighlight()

void ACAPI_UserInput_SetElementHighlight	(	const GS::HashTable< API_Guid, API_RGBAColor > &	highlightedElems,
		const GS::Optional< bool > &	wireframe3D = GS::NoValue,
		const GS::Optional< API_RGBAColor > &	nonHighlightedElemsColor = GS::NoValue
	)

Highlight elements in the 2D (floor plan and section) and 3D window.

Since

Archicad 26

Parameters

highlightedElems	Hash table containing the elements (identified by their GUIDs) and the colors to highlight the element with.
wireframe3D	Switch other elements in the 3D window to wireframe (does not have effect in case of using Vectorial Engine). Optional, it can be GS::NoValue.
nonHighlightedElemsColor	It contains the color and the transparency of the non highlighted elements. Optional, it can be GS::NoValue.

Remarks

You can remove element highlight by calling ACAPI_UserInput_ClearElementHighlight. 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 ();
        ACAPI_Automate (APIDo_RedrawID)
 
;
    } 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);
            ACAPI_Automate (APIDo_RedrawID)
 
;
        }
    }
 
    hled = !hled;
}

ACAPI_UserInput_SetNeigFilter()

GSErrCode ACAPI_UserInput_SetNeigFilter	(	API_NeigFilter *	neigFilter,
		API_NeigID	neigID
	)

Sets one of the neig types in the neig filter to be filtered.

Parameters

neigFilter	[in] The neig filter.
neigID	[in] Neig type to set for filtering.

Returns

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

Remarks

This function is used to set one of the neig types to be filtered during a user input. More information about neig filtering can be found at the remarks section of the ACAPI_UserInput_InitNeigFilter function. To clear an installed filter use the ACAPI_UserInput_ClearNeigFilter function.

Example

See APIIo_DrawRubberLineID
for example of using input neig filters.

CreateInputHandler()

Result< InputHandler > ACAPI::v1::CreateInputHandler ( )

inline

A function to create an InputHandler instance, that lets you handle input related operations.

Returns

Returns the InputHandler instance. This process cannot fail.