User input management

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

Classes
class	ACAPI::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_NeigElemPartID {   APINeigElemPart_None = 0 , APINeigElemPart_Edge , APINeigElemPart_Vertex , APINeigElemPart_Face ,   APINeigElemPart_Subelem }
	Type of the element part in case of partial selection (currently available with Morph only) More...
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_RubberLineThickness { APIRubberLine_Simple = 1 , APIRubberLine_Double = 2 }
	Rubber line thickness. More...
enum	API_RubberArcTypeID { APIRubberArc_OrigoAngles = 0 , APIRubberArc_ThreePoint = 1 }
	Defines the modes for placing an arc. More...
enum	API_PolyGetMethod { APIPolyGetMethod_General , APIPolyGetMethod_Rect , APIPolyGetMethod_RotRect , APIPolyGetMethod_Polyline }
	The polygon input method. 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::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.
GSErrCode	ACAPI_Markup_PDFImportOptions (const GS::UniString &parentName)
	Opens the Issue Import from PDF file Options dialog where you can choose an option for how the imported Issues should appear in Issue Organizer.

Detailed Description

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

Typedef Documentation

API_NeigFilter

typedef char API_NeigFilter[API_NeigFilterSize]

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

Enumerator
APIConst_X	Constraint by X
APIConst_Y	Constraint by Y
APIConst_Z	Constraint by Z
APIConst_A	Constraint by angle
APIConst_R	Constraint by 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. For example of using custom cursor sets see ACAPI_UserInput_GetArc.

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

API_InitNeigFilterID

enum API_InitNeigFilterID

Type of the neig filter initialization.

Remarks

For the utilization of API_InitNeigFilterID see the ACAPI_UserInput_InitNeigFilter function.

Enumerator
APIInitNeigFilter_Full	Filter all neig types
APIInitNeigFilter_Empty	Filter nothing
APIInitNeigFilter_On	Filter line type neigs only
APIInitNeigFilter_Node	Filter node type neigs only

API_NeigElemPartID

enum API_NeigElemPartID

Type of the element part in case of partial selection (currently available with Morph only)

Enumerator
APINeigElemPart_None	The whole element is selected.
APINeigElemPart_Edge	An edge of the element is selected.
APINeigElemPart_Vertex	A vertex of the element is selected.
APINeigElemPart_Face	A face of the element is selected.
APINeigElemPart_Subelem	A subelement is selected.

API_PolyGetMethod

enum API_PolyGetMethod

The polygon input method.

Enumerator
APIPolyGetMethod_General	Gets an arbitrary closed polygon
APIPolyGetMethod_Rect	Gets a rectangle
APIPolyGetMethod_RotRect	Gets a base vector then a rectangle perpendicular to it
APIPolyGetMethod_Polyline	Gets a polyline (can be open)

API_RubberArcTypeID

enum API_RubberArcTypeID

Defines the modes for placing an arc.

Enumerator
APIRubberArc_OrigoAngles	Define arc by origo point and radius
APIRubberArc_ThreePoint	Define arc by three points

API_RubberLineThickness

enum API_RubberLineThickness

Rubber line thickness.

Enumerator
APIRubberLine_Simple	Simple rubber line
APIRubberLine_Double	Double rubber line

Function Documentation

ACAPI_Markup_PDFImportOptions()

GSErrCode ACAPI_Markup_PDFImportOptions

(

const GS::UniString &

parentName

)

Opens the Issue Import from PDF file Options dialog where you can choose an option for how the imported Issues should appear in Issue Organizer.

Parameters

parentName

Archicad Issue's name as a parent of the imported issues. The imported Issues will be inserted as sub-Issues.

Returns

• NoError - The function has completed successfully.

Since

Archicad 29

Remarks

To create a separate "category" for the imported Issues, first create a new Issue in Archicad, and give it a name (e.g. "Imported Issues from PDF".) Then, pass this name as the parentName parameter.

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.

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 {};
 
    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_UserInput_DrawRubberArc (&rubberArc);
    return;
}
 
/*------------------------------------------------------**
** Filtered point input with rubberline feedback        **
**------------------------------------------------------*/
void PutColumnOnAHotspot (void)
 
{
    GSErrCode           err;
    API_GetPointType    pointInfo {};
    API_Element         elem {};
 
    CHCopyC ("Click onto a hotspot to create column", pointInfo.prompt);
 
    pointInfo.changeFilter = true;      /* let the cursor gravitate to hotspot neigs only */
    ACAPI_UserInput_InitNeigFilter (&pointInfo.filter, APIInitNeigFilter_Empty);
    ACAPI_UserInput_SetNeigFilter (&pointInfo.filter, APINeig_Hot);
 
    err = ACAPI_UserInput_GetPoint (&pointInfo, 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 {
            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 {};
 
    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_UserInput_DrawRubberLine (&rubberLine);
 
    rubberLine.c1 = rubberLine.c2;
    rubberLine.c2.x += 1.0;
    ACAPI_UserInput_DrawRubberLine (&rubberLine);
 
    rubberLine.c1 = rubberLine.c2;
    rubberLine.c2.y -= 1.0;
    ACAPI_UserInput_DrawRubberLine (&rubberLine);
 
    rubberLine.c1 = rubberLine.c2;
    rubberLine.c2.x -= 1.0;
    ACAPI_UserInput_DrawRubberLine (&rubberLine);
 
    return;
}
 
/*------------------------------------------------------**
** Filtered point input with rubberline feedback        **
**------------------------------------------------------*/
void PutColumnOnAHotspot (void)
 
{
    GSErrCode           err;
    API_GetPointType    pointInfo {};
    API_Element         elem {};
 
    CHCopyC ("Click onto a hotspot to create column", pointInfo.prompt);
 
    pointInfo.changeFilter = true;      /* let the cursor gravitate to hotspot neigs only */
    ACAPI_UserInput_InitNeigFilter (&pointInfo.filter, APIInitNeigFilter_Empty);
    ACAPI_UserInput_SetNeigFilter (&pointInfo.filter, APINeig_Hot);
 
    err = ACAPI_UserInput_GetPoint (&pointInfo, 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 {
            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;
 
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_UserInput_GetPoint (&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_UserInput_GetLine (&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_UserInput_GetArc (&arcInfo, nullptr);
}
 
if (!err) {
    sprintf (buffer, "Origo coordinates:  (%f, %f)", arcInfo.origo.x, arcInfo.origo.y);
    ACAPI_WriteReport (buffer, false);
    if (arcInfo.negArc)
        sprintf (buffer, "Arc begins:  (%f, %f)\nArc ends:  (%f, %f)",
                arcInfo.pos.x, arcInfo.pos.y, arcInfo.startCoord.x, arcInfo.startCoord.y);
    else
        sprintf (buffer, "Arc begins:  (%f, %f)\nArc ends:  (%f, %f)",
                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

/*------------------------------------------------------**
** Callback function to draw the rubber lines          **
**------------------------------------------------------*/
static void RubberLineCallBack (const API_RubberLineInfo *info)
 
{
    API_RubberLineType rubberLine {};
 
    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_UserInput_DrawRubberLine (&rubberLine);
 
    rubberLine.c1 = rubberLine.c2;
    rubberLine.c2.x += 1.0;
    ACAPI_UserInput_DrawRubberLine (&rubberLine);
 
    rubberLine.c1 = rubberLine.c2;
    rubberLine.c2.y -= 1.0;
    ACAPI_UserInput_DrawRubberLine (&rubberLine);
 
    rubberLine.c1 = rubberLine.c2;
    rubberLine.c2.x -= 1.0;
    ACAPI_UserInput_DrawRubberLine (&rubberLine);
 
    return;
}
 
/*------------------------------------------------------**
** Filtered point input with rubberline feedback        **
**------------------------------------------------------*/
void PutColumnOnAHotspot (void)
 
{
    GSErrCode           err;
    API_GetPointType    pointInfo {};
    API_Element         elem {};
 
    CHCopyC ("Click onto a hotspot to create column", pointInfo.prompt);
 
    pointInfo.changeFilter = true;      /* let the cursor gravitate to hotspot neigs only */
    ACAPI_UserInput_InitNeigFilter (&pointInfo.filter, APIInitNeigFilter_Empty);
    ACAPI_UserInput_SetNeigFilter (&pointInfo.filter, APINeig_Hot);
 
    err = ACAPI_UserInput_GetPoint (&pointInfo, 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 {
            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_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 {};
 
return ACAPI_UserInput_GetMagicWandSets (&magicInfo);

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

/*------------------------------------------------------**
** Callback function to draw the rubber lines          **
**------------------------------------------------------*/
static void RubberLineCallBack (const API_RubberLineInfo *info)
 
{
    API_RubberLineType rubberLine {};
 
    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_UserInput_DrawRubberLine (&rubberLine);
 
    rubberLine.c1 = rubberLine.c2;
    rubberLine.c2.x += 1.0;
    ACAPI_UserInput_DrawRubberLine (&rubberLine);
 
    rubberLine.c1 = rubberLine.c2;
    rubberLine.c2.y -= 1.0;
    ACAPI_UserInput_DrawRubberLine (&rubberLine);
 
    rubberLine.c1 = rubberLine.c2;
    rubberLine.c2.x -= 1.0;
    ACAPI_UserInput_DrawRubberLine (&rubberLine);
 
    return;
}
 
/*------------------------------------------------------**
** Filtered point input with rubberline feedback        **
**------------------------------------------------------*/
void PutColumnOnAHotspot (void)
 
{
    GSErrCode           err;
    API_GetPointType    pointInfo {};
    API_Element         elem {};
 
    CHCopyC ("Click onto a hotspot to create column", pointInfo.prompt);
 
    pointInfo.changeFilter = true;      /* let the cursor gravitate to hotspot neigs only */
    ACAPI_UserInput_InitNeigFilter (&pointInfo.filter, APIInitNeigFilter_Empty);
    ACAPI_UserInput_SetNeigFilter (&pointInfo.filter, APINeig_Hot);
 
    err = ACAPI_UserInput_GetPoint (&pointInfo, 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 {
            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_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_ElementMemo     memo;
    API_Neig            neig;
    API_ElemType        type;
    GSErrCode           err;
 
    if (!ClickAnElem ("Click a polygon to insert a new hole into", API_ZombieElemID, &neig, &type)) {
        WriteReport_Alert ("No element was clicked");
        return;
    }
 
    switch (type.typeID) {
        case API_SlabID:
        case API_RoofID:
        case API_MeshID:
        case API_ZoneID:
        case API_HatchID:   break;
 
        default:            WriteReport_Alert ("Only slab, roof, mesh, zone or fill nodes/edges are excepted");
                            return;
    }
 
    API_GetPointType pointInfo {};
    API_GetPolyType  polyInfo  {};
    GS::StrCpy (pointInfo.prompt, "Click the first node of the hole");
    err = ACAPI_UserInput_GetPoint (&pointInfo);
    if (err == NoError) {
        GS::StrCpy (polyInfo.prompt, "Enter the polygon nodes");
        polyInfo.startCoord = pointInfo.pos;
        err = ACAPI_UserInput_GetPoly (&polyInfo);
    }
    if (err != NoError) {
        BMKillHandle ((GSHandle *) &polyInfo.coords);
        BMKillHandle ((GSHandle *) &polyInfo.parcs);
        return;
    }
 
    err = ACAPI_Element_GetMemo (neig.guid, &memo);
    if (err != NoError) {
        BMKillHandle ((GSHandle *) &polyInfo.coords);
        BMKillHandle ((GSHandle *) &polyInfo.parcs);
        return;
    }
 
    API_ElementMemo insMemo {};
    insMemo.coords          = polyInfo.coords;
    insMemo.parcs           = polyInfo.parcs;
 
    polyInfo.coords = nullptr;
    polyInfo.parcs  = nullptr;
 
    err = ACAPI_Polygon_InsertSubPoly (&memo, &insMemo);
    if (err == NoError) {
        API_ElementMemo tmpMemo {};
        tmpMemo.coords = memo.coords;
        tmpMemo.pends = memo.pends;
        tmpMemo.parcs = memo.parcs;
        tmpMemo.vertexIDs = memo.vertexIDs;
        tmpMemo.meshPolyZ = memo.meshPolyZ;
        tmpMemo.edgeIDs = memo.edgeIDs;
        tmpMemo.edgeTrims = memo.edgeTrims;
        tmpMemo.contourIDs = memo.contourIDs;
        err = ACAPI_Element_ChangeMemo (neig.guid, GetMemoMask (neig), &tmpMemo);
        if (err != NoError)
            ErrorBeep ("ACAPI_Element_ChangeMemo", err);
    } else
        ErrorBeep ("APIAny_InsertSubPolyID", err);
 
    ACAPI_DisposeElemMemoHdls (&insMemo);
    ACAPI_DisposeElemMemoHdls (&memo);
 
    return;

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

/*------------------------------------------------------**
** Callback function to draw the rubber lines          **
**------------------------------------------------------*/
static void RubberLineCallBack (const API_RubberLineInfo *info)
 
{
    API_RubberLineType rubberLine {};
 
    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_UserInput_DrawRubberLine (&rubberLine);
 
    rubberLine.c1 = rubberLine.c2;
    rubberLine.c2.x += 1.0;
    ACAPI_UserInput_DrawRubberLine (&rubberLine);
 
    rubberLine.c1 = rubberLine.c2;
    rubberLine.c2.y -= 1.0;
    ACAPI_UserInput_DrawRubberLine (&rubberLine);
 
    rubberLine.c1 = rubberLine.c2;
    rubberLine.c2.x -= 1.0;
    ACAPI_UserInput_DrawRubberLine (&rubberLine);
 
    return;
}
 
/*------------------------------------------------------**
** Filtered point input with rubberline feedback        **
**------------------------------------------------------*/
void PutColumnOnAHotspot (void)
 
{
    GSErrCode           err;
    API_GetPointType    pointInfo {};
    API_Element         elem {};
 
    CHCopyC ("Click onto a hotspot to create column", pointInfo.prompt);
 
    pointInfo.changeFilter = true;      /* let the cursor gravitate to hotspot neigs only */
    ACAPI_UserInput_InitNeigFilter (&pointInfo.filter, APIInitNeigFilter_Empty);
    ACAPI_UserInput_SetNeigFilter (&pointInfo.filter, APINeig_Hot);
 
    err = ACAPI_UserInput_GetPoint (&pointInfo, 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 {
            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_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

API_GetPointType    pointInfo {};
API_GetLineType     lineInfo {};
API_ConstraintPars  constPars {};
GSErrCode           err;
 
CHCopyC ("Click the first point of the line", pointInfo.prompt);
 
err = ACAPI_UserInput_GetPoint (&pointInfo, nullptr);
 
if (err == NoError) {
    constPars.constType = APIConst_X;
    constPars.constValue = 2.0;
    constPars.useLocOrigo = true;
    err = ACAPI_UserInput_SetConstraint (&constPars);
    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_UserInput_GetLine (&lineInfo, nullptr);
    }
    ACAPI_UserInput_ResetConstraint ();
}
 
if (err == APIERR_CANCEL)
    ACAPI_WriteReport ("Input was interrupted", true);

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 {};
GSErrCode           err;
 
CHCopyC ("Click the first point of the line", pointInfo.prompt);
 
err = ACAPI_UserInput_GetPoint (&pointInfo, nullptr);
 
if (err == NoError) {
    constPars.constType = APIConst_X;
    constPars.constValue = 2.0;
    constPars.useLocOrigo = true;
    err = ACAPI_UserInput_SetConstraint (&constPars);
    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_UserInput_GetLine (&lineInfo, nullptr);
    }
    ACAPI_UserInput_ResetConstraint ();
}
 
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
//------------------------------------------------------
void Do_HighlightElements (void)
{
    static bool hled = false;
 
    if (hled) {
        // remove the highlight
        ACAPI_UserInput_ClearElementHighlight ();
        ACAPI_View_Redraw ();
    } 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_View_Redraw ();
        }
    }
 
    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

/*------------------------------------------------------**
** Callback function to draw the rubber lines          **
**------------------------------------------------------*/
static void RubberLineCallBack (const API_RubberLineInfo *info)
 
{
    API_RubberLineType rubberLine {};
 
    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_UserInput_DrawRubberLine (&rubberLine);
 
    rubberLine.c1 = rubberLine.c2;
    rubberLine.c2.x += 1.0;
    ACAPI_UserInput_DrawRubberLine (&rubberLine);
 
    rubberLine.c1 = rubberLine.c2;
    rubberLine.c2.y -= 1.0;
    ACAPI_UserInput_DrawRubberLine (&rubberLine);
 
    rubberLine.c1 = rubberLine.c2;
    rubberLine.c2.x -= 1.0;
    ACAPI_UserInput_DrawRubberLine (&rubberLine);
 
    return;
}
 
/*------------------------------------------------------**
** Filtered point input with rubberline feedback        **
**------------------------------------------------------*/
void PutColumnOnAHotspot (void)
 
{
    GSErrCode           err;
    API_GetPointType    pointInfo {};
    API_Element         elem {};
 
    CHCopyC ("Click onto a hotspot to create column", pointInfo.prompt);
 
    pointInfo.changeFilter = true;      /* let the cursor gravitate to hotspot neigs only */
    ACAPI_UserInput_InitNeigFilter (&pointInfo.filter, APIInitNeigFilter_Empty);
    ACAPI_UserInput_SetNeigFilter (&pointInfo.filter, APINeig_Hot);
 
    err = ACAPI_UserInput_GetPoint (&pointInfo, 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 {
            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;
}

CreateInputHandler()

Result< InputHandler > ACAPI::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.