Archicad 29 C++ API
Loading...
Searching...
No Matches
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_ConstraintType {
  APIConst_X = 1 , APIConst_Y = 2 , APIConst_Z = 3 , APIConst_A = 4 ,
  APIConst_R = 5
}
 Type of the drawing constraint. More...
 

Functions

Result< InputHandlerACAPI::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
infoInformation on the actual input state.
Remarks
None.

◆ RubberLineInfoProc

typedef void RubberLineInfoProc(const API_RubberLineInfo *info)

Callback function for custom feedback drawing.

Parameters
infoInformation 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

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

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

Type of the neig filter initialization.

Remarks
For the utilization of API_InitNeigFilterID see the ACAPI_UserInput_InitNeigFilter function.

◆ 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.

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
parentNameArchicad 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 with success.
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;
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;
rubberLine.c1 = rubberLine.c2;
rubberLine.c2.x += 1.0;
rubberLine.c1 = rubberLine.c2;
rubberLine.c2.y -= 1.0;
rubberLine.c1 = rubberLine.c2;
rubberLine.c2.x -= 1.0;
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;
rubberLine.c1 = rubberLine.c2;
rubberLine.c2.x += 1.0;
rubberLine.c1 = rubberLine.c2;
rubberLine.c2.y -= 1.0;
rubberLine.c1 = rubberLine.c2;
rubberLine.c2.x -= 1.0;
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 {};

◆ 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;
rubberLine.c1 = rubberLine.c2;
rubberLine.c2.x += 1.0;
rubberLine.c1 = rubberLine.c2;
rubberLine.c2.y -= 1.0;
rubberLine.c1 = rubberLine.c2;
rubberLine.c2.x -= 1.0;
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_Neig neig;
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 {};
strcpy (pointInfo.prompt, "Click the first node of the hole");
err = ACAPI_UserInput_GetPoint (&pointInfo);
if (err == NoError) {
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);
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;
rubberLine.c1 = rubberLine.c2;
rubberLine.c2.x += 1.0;
rubberLine.c1 = rubberLine.c2;
rubberLine.c2.y -= 1.0;
rubberLine.c1 = rubberLine.c2;
rubberLine.c2.x -= 1.0;
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);
}
}
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);
}
}
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
highlightedElemsHash table containing the elements (identified by their GUIDs) and the colors to highlight the element with.
wireframe3DSwitch other elements in the 3D window to wireframe (does not have effect in case of using Vectorial Engine). Optional, it can be GS::NoValue.
nonHighlightedElemsColorIt 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
} else {
GS::Array<API_Guid> meshList;
if (meshList.GetSize () > 0) {
GS::HashTable<API_Guid, API_RGBAColor> hlElems;
API_RGBAColor hlColor = { 0.0, 0.5, 0.75, 0.5 };
for (auto it = meshList.Enumerate (); it != nullptr; ++it) {
hlElems.Add (*it, hlColor);
hlColor.f_red += 0.1;
if (hlColor.f_red > 1.0)
hlColor.f_red = 0.0;
}
bool wireframe3D = false;
API_RGBAColor nonHighlightedElemsColor = {0.7, 0.7, 0.7, 0.95};
ACAPI_UserInput_SetElementHighlight (hlElems, wireframe3D, nonHighlightedElemsColor);
}
}
hled = !hled;
}

◆ ACAPI_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;
rubberLine.c1 = rubberLine.c2;
rubberLine.c2.x += 1.0;
rubberLine.c1 = rubberLine.c2;
rubberLine.c2.y -= 1.0;
rubberLine.c1 = rubberLine.c2;
rubberLine.c2.x -= 1.0;
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.