Selection handling

Functions related to selection and marquee, including selecting elements and listing selected elements or elements included in the marquee. More...

Classes
struct	API_SelectionInfo
	Information about the current selection. More...
struct	API_MarqueeFilter
	Defines the filter for 3D filter and cut settings. More...

Typedefs
typedef GSErrCode	APISelectionChangeHandlerProc(const API_Neig *selElemNeig)
	User supplied callback procedure for handling selection changes.

Enumerations
enum	API_SelTypeID {   API_SelEmpty = 0 , API_SelElems , API_MarqueePoly , API_MarqueeHorBox ,   API_MarqueeRotBox }
	Types of the selection. More...
enum	API_SelRelativePosID { API_InsidePartially = 0 , API_InsideEntirely , API_OutsidePartially , API_OutsideEntirely }
	Types of the relative position to marquee criteria. More...

Functions
GSErrCode	ACAPI_Selection_GetSelectedElement (const API_Neig *apiNeig, API_Guid *apiGuid)
	Converts an API_Neig structure to an API_Guid.
GSErrCode	ACAPI_Selection_SetSelectedElementNeig (const API_Guid *apiGuid, API_Neig *apiNeig)
	Converts an API_Guid structure to an API_Neig.
GSErrCode	ACAPI_Selection_Select (const GS::Array< API_Neig > &selNeigs, bool add)
	Adds/removes a number of elements to/from the current selection.
GSErrCode	ACAPI_Selection_DeselectAll ()
	Adds/removes a number of elements to/from the current selection.
GSErrCode	ACAPI_Selection_Get (API_SelectionInfo *selectionInfo, GS::Array< API_Neig > *selNeigs, bool onlyEditable, bool ignorePartialSelection=true, API_SelRelativePosID relativePosToMarquee=API_InsidePartially)
	Returns information on the selection, and the selected elements.
GSErrCode	ACAPI_Selection_SetMarquee (API_SelectionInfo *selectionInfo)
	Changes the current marquee selection.
GSErrCode	ACAPI_Notification_CatchSelectionChange (APISelectionChangeHandlerProc *handlerProc)
	Turns the monitoring of selection changes on/off.

Detailed Description

Functions related to selection and marquee, including selecting elements and listing selected elements or elements included in the marquee.

Typedef Documentation

APISelectionChangeHandlerProc

typedef GSErrCode APISelectionChangeHandlerProc(const API_Neig *selElemNeig)

User supplied callback procedure for handling selection changes.

Parameters

selElemNeig

[in] This structure identifies the last selected element.

Returns

• NoError - The function has completed with success.

Remarks

This is the function which will be called when your add-on installed it with ACAPI_Notification_CatchSelectionChange.

Enumeration Type Documentation

API_SelRelativePosID

enum API_SelRelativePosID

Types of the relative position to marquee criteria.

Remarks

This enum is used when you get information about the current marquee based selection. See the ACAPI_Selection_Get function.

API_SelTypeID

enum API_SelTypeID

Types of the selection.

Remarks

This enum is used when you get information about the current selection. See the ACAPI_Selection_Get function. There are two basic type of selection methods in Archicad:

• The selection may be controlled by individually selected elements.
• The other possibility is to rely on the marquee area. The API_SelEmpty identifier means that no selection is actually used in Archicad. The API_SelElems identifier corresponds to the first method when elements are individually selected. Other values identify that the selection is done by some kind of marquee shape.

Function Documentation

ACAPI_Notification_CatchSelectionChange()

GSErrCode ACAPI_Notification_CatchSelectionChange

(

APISelectionChangeHandlerProc *

handlerProc

)

Turns the monitoring of selection changes on/off.

Parameters

handlerProc

[in] The callback procedure to call when notifications are sent out on changes in the selection. Specifying nullptr here means you don't need the notifications any more.

Returns

• NoError - The function completed successfully.

Remarks

This function is used to register/unregister an add-on which wants to monitor the changes in selection. You do not have to call ACAPI_KeepInMemory afterwards, as the API ensures that add-ons with installed notification handlers won't be unloaded. After registration your add-on's handlerProc you will be called when the selection changes.

Example

// -----------------------------------------------------------------------------
// Selection change handler function
// -----------------------------------------------------------------------------
static GSErrCode SelectionChangeHandler (const API_Neig *selElemNeig)
 
{
    char    msgStr[256];
 
    if (selElemNeig->neigID != APINeig_None) {
        sprintf (msgStr, "Last selected element: NeigID %d; index: %d, inIndex: %d",
                 selElemNeig->neigID, selElemNeig->index, selElemNeig->inIndex);
        ACAPI_WriteReport (msgStr, false);
    } else
        ACAPI_WriteReport ("All elements deselected", false);
 
    return NoError;
}   // SelectionChangeHandler
 
 
// -----------------------------------------------------------------------------
// Called after the Add-On has been loaded into memory
// -----------------------------------------------------------------------------
GSErrCode Initialize (void)
 
{
    // catch changes in the selection
    GSErrCode err = ACAPI_Notification_CatchSelectionChange (SelectionChangeHandler);
 
    return err;
}   // Initialize

ACAPI_Selection_DeselectAll()

GSErrCode ACAPI_Selection_DeselectAll

(

)

Adds/removes a number of elements to/from the current selection.

Returns

• NoError - The function has completed with success.
• APIERR_BADDATABASE - The current database is not proper for the operation.

Remarks

This function acts as "Deselect All". Use ACAPI_Selection_Select function to add/remove elements to/from the current selection.

Example

GSErrCode    Do_SelectAllWalls (void)
{
    ACAPI_Selection_DeselectAll ();
 
    GS::Array<API_Guid> wallGuids;
    ACAPI_Element_GetElemList (API_WallID, &wallGuids);
 
    GS::Array<API_Neig> selNeigs;
    for (const API_Guid& guid : wallGuids) {
        API_Neig neig (guid);
        selNeigs.Push (neig);
        // Note: the following 1 commented line is equivalent to the previous 2 lines
        // selNeigs.PushNew (guid);
    }
 
    return ACAPI_Selection_Select (selNeigs, true);
}

ACAPI_Selection_Get()

GSErrCode ACAPI_Selection_Get	(	API_SelectionInfo *	selectionInfo,
		GS::Array< API_Neig > *	selNeigs,
		bool	onlyEditable,
		bool	ignorePartialSelection = true,
		API_SelRelativePosID	relativePosToMarquee = API_InsidePartially
	)

Returns information on the selection, and the selected elements.

Parameters

selectionInfo	[out] The parameters of the current selection. The typeID field of the selectionInfo gives the selection type.
selNeigs	[out] An array containing the GUIDs of the selected elements. Can be nullptr if you are interested in the selection information only.
onlyEditable	[in] Tells whether you are interested in editable elements only.
ignorePartialSelection	[in] Retrieves also partial element selection information or the element itself only selected as whole (for legacy compatibility reasons, the default value of this parameter is true, meaning partial selection is ignored). This parameter is ignored in case of marquee based selection.
relativePosToMarquee	[in] Retrieves elements relative to marquee (for legacy compatibility reasons, the default value of this parameter is API_InsidePartially, meaning only those elements will be returned which have an intersection with the marquee area). This parameter is ignored in case of individually selected elements.

Returns

• NoError - The function has completed with success.
• APIERR_NOPLAN - There is no open project.
• APIERR_NOSEL - There is no selection. Note that this is not a real error!

Remarks

This function is used to get information about the current selection and to retrieve the selected elements. The information is returned in the selectionInfo parameter. If individual elements are selected the API_SelElems identifier is returned. The number of the selected and selected and editable elements are also returned. In case of marquee based selection, the function gives back the actual polygon of the current selection in the API_SelectionInfo structure; don't forget to dispose this handle. The API_SelEmpty identifier in the typeID field of the selectionInfo parameter means that no selection is actually used in Archicad. In case of individually selected elements, Archicad returns all the elements which are selected. In the case of marquee based selection, only those will be returned which match the position criteria defined by relativePosToMarquee.

Example

//------------------------------------------------------------
// Collect in inds the guids of the dimensions to work with
//------------------------------------------------------------
static GSErrCode SelectDimensions (GS::Array<API_Guid>& inds)
 
{
    API_SelectionInfo selectionInfo;
    GS::Array<API_Neig> selNeigs;
    if (const GSErrCode err = ACAPI_Selection_Get (&selectionInfo, &selNeigs, true); err != NoError && err != APIERR_NOSEL) {
        ACAPI_WriteReport ("ACAPI_Selection_Get failed with error code: %d", false, &err);
        return err;
    }
    BMKillHandle ((GSHandle*) &selectionInfo.marquee.coords);
 
    if (selectionInfo.typeID == API_SelEmpty) {
        return APIERR_NOSEL;
    }
    
    // collect guids of selected dimensions
    for (const API_Neig& selNeig : selNeigs) {
        API_Elem_Head tElemHead;
        tElemHead.type = Neig_To_ElemID (selNeig.neigID);
        if (tElemHead.type.typeID != API_DimensionID)
            continue;
 
        if (!ACAPI_Element_Filter (selNeig.guid, APIFilt_IsEditable))
            continue;
 
        tElemHead.guid = selNeig.guid;
        if (ACAPI_Element_GetHeader (&tElemHead) != NoError)
            continue;
 
        // Add dimension to the array
        inds.Push (tElemHead.guid);
    }
 
    return NoError;
}   // SelectDimensions

ACAPI_Selection_GetSelectedElement()

GSErrCode ACAPI_Selection_GetSelectedElement	(	const API_Neig *	apiNeig,
		API_Guid *	apiGuid
	)

Converts an API_Neig structure to an API_Guid.

Parameters

apiNeig	[in] The Neig describing a point of the Element.
apiGuid	[out] The GUID of the Subelement at that point.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - apiGuid or apiNeig is nullptr.

ACAPI_Selection_Select()

GSErrCode ACAPI_Selection_Select	(	const GS::Array< API_Neig > &	selNeigs,
		bool	add
	)

Adds/removes a number of elements to/from the current selection.

Parameters

selNeigs	[in] The elements to be added/removed (array of API_Neig objects);
add	[in] If true, adds the elements to the current selection, otherwise removes them from the selection.

Returns

• NoError - The function has completed with success.
• APIERR_BADDATABASE - The current database is not proper for the operation.
• APIERR_BADID - The element unique ID is invalid. The element type is invalid, or the element type is not supported by the server application.
• APIERR_BADPARS - The passed parameter contains invalid data; selNeigs.

Remarks

You can use this function to add/remove (add flag) a number of (nItem) elements to/from the current selection. The elements are defined by the selNeigs array of type API_Neig. Use ACAPI_Selection_DeselectAll function to remove all elements from the selection. The neigID and the guid fields are required (inIndex and/or holeSel only where applicable). The API_NeigID is differs from the API_ElemTypeID, because it refers to the selectable parts of the elements, not the elements themselves. You can select not only whole elements but element parts, such as vertices, edges and faces, specified in the elemPartType and elemPartIndex fields of API_Neig.

Example

static GSErrCode    Do_SelectAllWalls (void)
{
    ACAPI_Selection_DeselectAll ();
 
    GS::Array<API_Guid> wallGuids;
    ACAPI_Element_GetElemList (API_WallID, &wallGuids);
 
    GS::Array<API_Neig> selNeigs;
    for (const API_Guid& guid : wallGuids) {
        API_Neig neig (guid);
        selNeigs.Push (neig);
        // Note: the following 1 commented line is equivalent to the previous 2 lines
        // selNeigs.PushNew (guid);
    }
 
    return ACAPI_Selection_Select (selNeigs, true);
}

ACAPI_Selection_SetMarquee()

GSErrCode ACAPI_Selection_SetMarquee

(

API_SelectionInfo *

selectionInfo

)

Changes the current marquee selection.

Parameters

selectionInfo

[in] The parameters of the marquee to be set.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The selectionInfo parameter is nullptr
• APIERR_BADDATABASE - The active database is neither the floorplan, nor a section database

Remarks

This function is used to change the marquee on a floorplan or section window. The typeID field of the selectionInfo must be API_MarqueePoly, API_MarqueeHorBox or API_MarqueeRotBox in order to set a new marquee outline, otherwise the actual marquee will be removed. The function has no effect on the individual selection of elements. In case of API_MarqueePoly type marquee do not forget to release the coordinate handle passed in the selectionInfo parameter.

ACAPI_Selection_SetSelectedElementNeig()

GSErrCode ACAPI_Selection_SetSelectedElementNeig	(	const API_Guid *	apiGuid,
		API_Neig *	apiNeig
	)

Converts an API_Guid structure to an API_Neig.

Parameters

apiGuid	[in] The GUID of the Subelement at that point.
apiNeig	[out] The Neig describing a point of the Element.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - apiGuid or apiNeig is nullptr.