Selection Sets

Typedefs
typedef StatusInt(*	Select_UserFunction )(DgnPlatform::SelectionSetAction *action, UInt32 filePos, DgnModelRefP modelRef)
	UserFunction for LOCATE_SELECT_CMD (set via mdlLocate_setFunction). More...

Functions
int	mdlSelect_addElement (UInt32 filePos, DgnModelRefP modelRef)
	Add an element to the current Selection Set. More...
StatusInt	mdlSelect_allElements ()
	Add all of the displayable elements from the active model to the Selection Set. More...
void	mdlSelect_freeAll ()
	Empty the Selection Set. More...
void	mdlSelect_activatePrevious ()
	Make the Previous Selection Set become the active Selection Set. More...
int	mdlSelect_numSelected ()
	Get the number of elements currently in the Selection Set. More...
bool	mdlSelect_isActive ()
	Determine whether any elements are currently selected. More...
StatusInt	mdlSelect_removeElement (UInt32 filePos, DgnModelRefP modelRef)
	Remove the element at file position filePos and modelRef from the Selection Set. More...
StatusInt	mdlSelect_returnPositions (UInt32 **filePosArray, DgnModelRefP **modelRefArray, int *nSelected)
	Return the file positions of all of the elements currently in the Selection Set. More...
StatusInt	mdlSelect_getElement (int index, ElementRefP *elemRef, DgnModelRefP *modelRef)
	Return the ElementRefP and DgnPlatform::DgnModelRef for a particular entry in the Selection Set. More...
bool	mdlSelect_isElementSelected (UInt32 filePos, DgnModelRefP modelRef)
	Determine whether the element specified by filePos and modelRef is in the current Selection Set. More...

Detailed Description

Typedef Documentation

typedef StatusInt(* Select_UserFunction)(DgnPlatform::SelectionSetAction *action, UInt32 filePos, DgnModelRefP modelRef)

UserFunction for LOCATE_SELECT_CMD (set via mdlLocate_setFunction).

Selection Sets

The MicroStation Selection Tool (the "Chooser") can be used to create a set of elements that are of interest to the user. This set is called the Selection Set. Modification and query tools frequently use the Selection Set as the basis for picking the elements upon which to act. It is important to note that at any given time, there either is or isn't a Selection Set active. Most tools are designed to work with or without a Selection Set, but in the case where there is a Section Set active, the "Identify Element" step is bypassed, assuming that the user intends the tool to work on the active Selection Set.

Modification Tools are generally started via a call to mdlState_startModifyCommand. That function has an argument that indicates whether to use the Selection Set or not. If that argument is true, and there is an active Selection Set, the Accept function is called before mdlState_startModifyCommand returns to it's caller, and the tool should perform it's action immediately.

Entries in the Selection Set are identified by both an ElementRefP and a ModelRef. Therefore, if a Model is referenced multiple times (e.g. a self-referenced or multiply-attached model), each instance of the elements in the model can be uniquely identified with the Selection Set via an ElementRefP/ModelRef pair.

The Previous Selection Set

Whenever a Selection Sets is dismissed (either via the Selection Tool or by starting a modification tool that doesn't support Selection Sets), all of the elements in the current Selection Set are stored. This becomes the Previous Selection Set. Applications can reinstate the Previous Selection Set via mdlSelect_activatePrevious. This is equivalent to the MicroStation keyin CHOOSE PREVIOUS.

Handles

In the case where there is only a single, editable, element in the Selection Set, MicroStation draws Handles on the element. Handles allow the user to modify the element by simply moving the Handles on the screen via the Selection Tool. Applications sometimes need to erase the Handles from the screen before modifying elements.

Parameters

[in]	action	the event that cause this call.
[in]	filePos	the filePos of the element for which the action applies.
[in]	modelRef	the modelRef of the element for which the action applies.

Returns

SUCCESS to allow the action, ERROR to abort it.

Function Documentation

void mdlSelect_activatePrevious

(

)

Make the Previous Selection Set become the active Selection Set.

If there was no Previous Selection Set, this function does nothing.

Remarks

Required Library: mdlbltin.lib

int mdlSelect_addElement	(	UInt32	filePos,
		DgnModelRefP	modelRef
	)

Add an element to the current Selection Set.

Parameters

[in]	filePos	filePos of element
[in]	modelRef	source of element

Remarks

Only simple elements or complex headers should be added to Selection Sets; complex components should never be added.

Returns

SUCCESS if the element is added to the Selection Set and ERROR if the element is invalid.

See also

mdlSelect_isActive mdlSelect_removeElement

Remarks

Required Library: mdlbltin.lib

StatusInt mdlSelect_allElements

(

)

Add all of the displayable elements from the active model to the Selection Set.

This function ignores the levels or views not currently displayed. It is equivalent to the MicroStation CHOOSE ALL command.

Returns

SUCCESS if the elements were selected.

See also

mdlSelect_isActive mdlSelect_freeAll

Remarks

Required Library: mdlbltin.lib

void mdlSelect_freeAll

(

)

Empty the Selection Set.

The current Selection Set becomes the "previous" set, and can be reinstated via the CHOOSE PREVIOUS command.

See also

mdlSelect_isActive

Remarks

Required Library: mdlbltin.lib

StatusInt mdlSelect_getElement	(	int	index,
		ElementRefP *	elemRef,
		DgnModelRefP *	modelRef
	)

Return the ElementRefP and DgnPlatform::DgnModelRef for a particular entry in the Selection Set.

Parameters

[in]	index	the entry to return
[out]	elemRef	the ElementRefP for the entry.
[out]	modelRef	the modelRef for the entry,

Returns

SUCCESS if there is an entry at the specified index and ERROR otherwise.

See also

mdlSelect_returnPositions

Remarks

Required Library: mdlbltin.lib

bool mdlSelect_isActive

(

)

Determine whether any elements are currently selected.

Returns

true if any elements are currently selected.

Remarks

If you want to use Selection Sets as part of an element modification function, mdlState_startModifyCommand automatically determines whether there are any elements currently selected, and calls your accept function accordingly.

See also

mdlSelect_allElements mdlSelect_freeAll userLocate_selectCmd

Remarks

Required Library: mdlbltin.lib

bool mdlSelect_isElementSelected	(	UInt32	filePos,
		DgnModelRefP	modelRef
	)

Determine whether the element specified by filePos and modelRef is in the current Selection Set.

Parameters

[in]	filePos	filePos of the element to be tested
[in]	modelRef	modelRef for the element to be tested

Returns

true if the element is currently in the Selection Set.

Remarks

Required Library: mdlbltin.lib

See also

mdlSelect_isActive elementRef_isInSelectionSet

int mdlSelect_numSelected

(

)

Get the number of elements currently in the Selection Set.

Returns

the number of elements currently in the Selection Set.

See also

mdlSelect_isActive

Remarks

Required Library: mdlbltin.lib

StatusInt mdlSelect_removeElement	(	UInt32	filePos,
		DgnModelRefP	modelRef
	)

Remove the element at file position filePos and modelRef from the Selection Set.

Parameters

[in]	filePos	file position of element
[in]	modelRef	source of element

Remarks

This function does not delete the element from the file. It merely removes it from the Selection Set.

Returns

SUCCESS if the element is removed from the Selection Set and ERROR if it is not currently in the Selection Set.

See also

mdlSelect_isActive mdlSelect_addElement

Remarks

Required Library: mdlbltin.lib

StatusInt mdlSelect_returnPositions	(	UInt32 **	filePosArray,
		DgnModelRefP **	modelRefArray,
		int *	nSelected
	)

Return the file positions of all of the elements currently in the Selection Set.

This function allocates two arrays in memory. These arrays list elements currently in the Selection Set, each of which has nSelected entries. The first array, filePosArray, lists file positions, one for each element in the Selection Set; the second array, modelRefArray, contains the model references for the same.

Parameters

[out]	filePosArray	array of file positions
[out]	modelRefArray	modelRefs of elements in Selection Set
[out]	nSelected	number of elements selected (also the size of each array returned).

Remarks

MDL applications should pass a pointer-to-a-pointer to a UInt32 for filePositions, and a pointer-to-a-pointer to an DgnModelRefP for modelRefs.

NOTE: each array is allocated internally by this function, but MUST BE FREED by the caller!

Returns

SUCCESS if it allocated the memory for filePositions and modelRefs and MDLERR_INSFMEMORY if it did not.

See also

mdlSelect_isActive mdlSelect_getElement

Remarks

Required Library: mdlbltin.lib