Functions
StatusInt	mdlUnits_getStandard (DgnPlatform::UnitInfo *unitInfoP, DgnPlatform::StandardUnit unitNumber)
	Sets up a unit definition for a standard unit. More...

DgnPlatform::StandardUnit	mdlUnits_getStandardNumber (const DgnPlatform::UnitInfo *unitInfoP)
	Gets a standard unit number from a unit definition. More...

StatusInt	mdlUnits_getStandardLabel (WCharP labelP, DgnPlatform::StandardUnit unitNumber)
	Gets the default label for a standard unit, (ex. More...

int	mdlUnits_getStandardName (WCharP nameP, DgnPlatform::StandardUnit unitNumber)
	Gets the plural name of a standard unit, (ex. More...

int	mdlUnits_getStandardNameSingular (WCharP nameP, DgnPlatform::StandardUnit unitNumber)
	Gets the singular name of a standard unit, (ex. More...

StatusInt	mdlUnits_getNextLargerStandard (DgnPlatform::StandardUnit *unitNumberP, DgnPlatform::StandardUnit baseUnitNumber)
	Gets the next larger standard unit after baseUnitNumber. More...

StatusInt	mdlUnits_getNextSmallerStandard (DgnPlatform::StandardUnit *unitNumberP, DgnPlatform::StandardUnit baseUnitNumber)
	Gets the next smaller standard unit after baseUnitNumber. More...

StatusInt	mdlUnits_getSmallestStandard (DgnPlatform::StandardUnit *unitNumberP, DgnPlatform::UnitSystem unitSystem)
	Gets the smallest standard unit in a given unit system. More...

StatusInt	mdlUnits_getLargestStandard (DgnPlatform::StandardUnit *unitNumberP, DgnPlatform::UnitSystem unitSystem)
	Gets the largest standard unit in a given unit system. More...

DgnPlatform::UnitSystem	mdlUnits_getUnitSystemForStandard (DgnPlatform::StandardUnit unitNumber)
	Gets the unit sytem for a standard unit. More...

DgnPlatform::UnitSystem	mdlUnits_getUnitSystem (const DgnPlatform::UnitInfo *pUnit)
	Gets the unit system for a unit definition. More...

DgnPlatform::UnitBase	mdlUnits_getUnitBase (const DgnPlatform::UnitInfo *pUnit)
	Gets the base from a unit definition. More...

bool	mdlUnits_areComparable (const DgnPlatform::UnitInfo pUnit1, const DgnPlatform::UnitInfo pUnit2)
	Determines if two unit definitions can be compared by length. More...

int	mdlUnits_compare (const DgnPlatform::UnitInfo pUnit1, const DgnPlatform::UnitInfo pUnit2)
	Compares two unit definitions to determine which describes the larger unit. More...

StatusInt	mdlUnits_getConversionFactor (double factorP, const DgnPlatform::UnitInfo unitToP, const DgnPlatform::UnitInfo *unitFromP)
	Computes a scale factor used to convert distances from one unit to another. More...

StatusInt	mdlUnits_convertDistance (double distanceOutP, const DgnPlatform::UnitInfo unitToP, double distanceIn, const DgnPlatform::UnitInfo *unitFromP)
	Computes a distance expressed in one unit to the same distance expressed in another unit. More...

StatusInt	mdlUnits_buildUnitListModel (ListModelP ppListModel, DgnPlatform::UnitInfo pCompareUnit, bool bRestrictSize, bool bRestrictSystem, bool bUseSingularNames)
	Constructs a list model of the standard units, suitable for use in a comboBox dialog item. More...

Detailed Description

Function Documentation

bool mdlUnits_areComparable	(	const DgnPlatform::UnitInfo *	pUnit1,
		const DgnPlatform::UnitInfo *	pUnit2
	)

Determines if two unit definitions can be compared by length.

Only units of the same "base" can be compared.

Parameters

[in]	pUnit1	first unit
[in]	pUnit2	second unit

Returns: true if the units can be compared.

Remarks: Required Library: mdlbltin.lib

StatusInt mdlUnits_buildUnitListModel	(	ListModelP *	ppListModel,
		DgnPlatform::UnitInfo *	pCompareUnit,
		bool	bRestrictSize,
		bool	bRestrictSystem,
		bool	bUseSingularNames
	)

Constructs a list model of the standard units, suitable for use in a comboBox dialog item.

Parameters

[out]	ppListModel	Result
[in]	pCompareUnit	Unit on which to base the restrictions bRestrictSize and bRestrictSystem.
[in]	bRestrictSize	If true, only show units equal to or smaller than pCompareUnit.
[in]	bRestrictSystem	If true, only show units in the same system as pCompareUnit.
[in]	bUseSingularNames	ex. true->"Meter" false->"Meters".

Remarks: It is the caller's responsibility to call mdlListModel_destroy when finished with the list model.

Returns: SUCCESS if the list model was created.

See also: mdlDialog_comboBoxSetListModelP mdlListModel_destroy

Remarks: Required Library: mdlbltin.lib

int mdlUnits_compare	(	const DgnPlatform::UnitInfo *	pUnit1,
		const DgnPlatform::UnitInfo *	pUnit2
	)

Compares two unit definitions to determine which describes the larger unit.

Only units of the same "base" can be compared.

Parameters

[in]	pUnit1	first unit
[in]	pUnit2	second unit

Returns

an integer i, such that:

i == ERROR if the units could not be compared
i < 0 if pUnit1 is larger,
i > 0 if pUnit2 is larger,
i == 0 if the two units are the same size.

Remarks: Required Library: mdlbltin.lib

StatusInt mdlUnits_convertDistance	(	double *	distanceOutP,
		const DgnPlatform::UnitInfo *	unitToP,
		double	distanceIn,
		const DgnPlatform::UnitInfo *	unitFromP
	)

Computes a distance expressed in one unit to the same distance expressed in another unit.

Parameters

[out]	distanceOutP	distance expressed in unitToP
[in]	unitToP	ending unit
[in]	distanceIn	distance expressed in unitFromP
[in]	unitFromP	starting unit

Returns: SUCCESS if the distance can be converted, or ERROR if the two units are not comparable.

Remarks: Required Library: mdlbltin.lib

StatusInt mdlUnits_getConversionFactor	(	double *	factorP,
		const DgnPlatform::UnitInfo *	unitToP,
		const DgnPlatform::UnitInfo *	unitFromP
	)

Computes a scale factor used to convert distances from one unit to another.

It is usually preferable to use the function mdlUnits_convertDistance.

Parameters

[out]	factorP	scale factor
[in]	unitToP	ending unit
[in]	unitFromP	starting unit

Returns: SUCCESS if the scale factor can be computed, or ERROR if the two units are not comparable.

See also: mdlUnits_convertDistance

Remarks: Required Library: mdlbltin.lib

StatusInt mdlUnits_getLargestStandard	(	DgnPlatform::StandardUnit *	unitNumberP,
		DgnPlatform::UnitSystem	unitSystem
	)

Gets the largest standard unit in a given unit system.

Parameters

[out]	unitNumberP	largest unit
[in]	unitSystem	one of UNIT_SYSTEM_xxx (defined in msdefs.h)

Returns: SUCCESS if the largest unit was found, otherwise ERROR if unitSystem is not a known system.

Remarks: Can be used with mdlUnits_getNextSmallerStandard to iterate over the standard units.; A unitNumber is a non-persistant id for one of the the standard units. See UNIT_METRIC_xxx or UNIT_ENGLISH_xxx, defined in msdefs.h.

See also: mdlUnits_getNextSmallerStandard

Remarks: Required Library: mdlbltin.lib

StatusInt mdlUnits_getNextLargerStandard	(	DgnPlatform::StandardUnit *	unitNumberP,
		DgnPlatform::StandardUnit	baseUnitNumber
	)

Gets the next larger standard unit after baseUnitNumber.

The resulting unit will be in the same system as the base.

Parameters

[out]	unitNumberP	next larger unit
[in]	baseUnitNumber	current unit

Returns: SUCCESS if the next larger unit was found, or ERROR if baseUnitNumber is the largest standard unit in the system.

Remarks: Can be used with mdlUnits_getSmallestStandard to iterate over the standard units.; A unitNumber is a non-persistant id for one of the the standard units. See UNIT_METRIC_xxx or UNIT_ENGLISH_xxx, defined in msdefs.h.

See also: mdlUnits_getSmallestStandard

Remarks: Required Library: mdlbltin.lib

StatusInt mdlUnits_getNextSmallerStandard	(	DgnPlatform::StandardUnit *	unitNumberP,
		DgnPlatform::StandardUnit	baseUnitNumber
	)

Gets the next smaller standard unit after baseUnitNumber.

The resulting unit will be in the same system as the base.

Parameters

[out]	unitNumberP	next smaller unit
[in]	baseUnitNumber	current unit

Returns: SUCCESS if the next smaller unit was found, or ERROR if baseUnitNumber is the smallest standard unit in the system.

Remarks: Can be used with mdlUnits_getLargestStandard to iterate over the standard units.; A unitNumber is a non-persistant id for one of the the standard units. See UNIT_METRIC_xxx or UNIT_ENGLISH_xxx, defined in msdefs.h.

See also: mdlUnits_getLargestStandard

Remarks: Required Library: mdlbltin.lib

StatusInt mdlUnits_getSmallestStandard	(	DgnPlatform::StandardUnit *	unitNumberP,
		DgnPlatform::UnitSystem	unitSystem
	)

Gets the smallest standard unit in a given unit system.

Parameters

[out]	unitNumberP	smallest unit
[in]	unitSystem	one of UNIT_SYSTEM_xxx (defined in msdefs.h)

Returns: SUCCESS if the smallest unit was found, otherwise ERROR if unitSystem is not a known system.

Remarks: Can be used with mdlUnits_getNextLargerStandard to iterate over the standard units.; A unitNumber is a non-persistant id for one of the the standard units. See UNIT_METRIC_xxx or UNIT_ENGLISH_xxx, defined in msdefs.h.

See also: mdlUnits_getNextLargerStandard

Remarks: Required Library: mdlbltin.lib

StatusInt mdlUnits_getStandard	(	DgnPlatform::UnitInfo *	unitInfoP,
		DgnPlatform::StandardUnit	unitNumber
	)

Sets up a unit definition for a standard unit.

A "unit" describes a context in which users and applications describe distances. All coordinate data in a design file is stored in "units of resolution" or UORs. However, users will prefer to see distances displayed using a unit that is appropriate to their project. For example, "Meters" or "Feet".

A unit is described and stored using the Bentley::DgnPlatform::UnitInfo structure. This structure defines:

The relationship of this unit to a particular base unit.
The unit system to which the unit belongs, one of UNIT_SYSTEM_xxx.
The unit base by which the unit is defined, one of UNIT_BASE_xxx.
A descriptive label, ex. "ft" for feet.

Currently, there are two unit bases supported, UnitBase:: and UnitBase::. All linear distance units are based on the Meter in order to allow meaningful comparisons and conversions of distances. Note that even the english units are defined in terms of the Meter. UnitBase:: is a catch all for all other units. For example, when building a map of the Earth, it is convenient to consider distances along the y-axis to be Latitude and distances along the x-axis to be Longitude. However, there is no way to store a non-uniform scale in a standard Bentley::DgnPlatform::UnitInfo, so UnitBase:: would be used in this case.

A set of known standard units are provided by Microstation. These standard units can be referred to by a "unitNumber". These are defined in msdefs.h, for example StandardUnit::EnglishFeet and StandardUnit::MetricMeters. In order to do comparsons or conversions using a standard unit, the function mdlUnits_getStandard should be used to retrieve the units definition.

Unit numbers should not be used for persistant storage of a unit definition. This is because the Microstation runtime is required to interpret a unitNumber. In future versions, new standard units may be added, and then older versions will be unable to interpret the newer unitNumbers. For this reason and others, it is preferable to store a Bentley::DgnPlatform::UnitInfo. The Bentley::DgnPlatform::UnitInfo is a complete and self-contained definition for a unit that is independent of Microstation.

Design files store their working and storage units using the Bentley::DgnPlatform::UnitInfo structure. These can be accessed using the functions:



mdlModelRef_getMasterUnit 

mdlModelRef_getMasterUnitLabel 

mdlModelRef_getSubUnit 

mdlModelRef_getSubUnitLabel 

mdlModelRef_setWorkingUnits 

mdlModelRef_setSubUnitLabel 

mdlModelRef_setMasterUnitLabel 

mdlModelRef_getStorageUnit 

mdlModelRef_setStorageUnits

Other functions that may be of interest are:



mdlModelRef_getUorPerStorage 

mdlModelRef_getUorPerMaster 

mdlModelRef_getUorPerSub 

mdlModelRef_getSubPerMaster

Parameters

[out]	unitInfoP	a unit definition
[in]	unitNumber	a standard unitNumber to look up Otherwise, an error status is returned.

Remarks: A unitNumber is a non-persistant id for one of the the standard units. See UNIT_METRIC_xxx or UNIT_ENGLISH_xxx, defined in msdefs.h.

Returns: SUCCESS if unitNumber is one of the standard units.

Remarks: Required Library: mdlbltin.lib

StatusInt mdlUnits_getStandardLabel	(	WCharP	labelP,
		DgnPlatform::StandardUnit	unitNumber
	)

Gets the default label for a standard unit, (ex.

"m").

Parameters

[out]	labelP	the default label for the requested unit
[in]	unitNumber	standard unitNumber to look up

Returns: SUCCESS if unitNumber is one the standard units. Otherwise, an error status is returned.

Remarks: A unitNumber is a non-persistant id for one of the the standard units. See UNIT_METRIC_xxx or UNIT_ENGLISH_xxx, defined in msdefs.h.

See also: mdlUnits_getStandardNumber

Remarks: Required Library: mdlbltin.lib

int mdlUnits_getStandardName	(	WCharP	nameP,
		DgnPlatform::StandardUnit	unitNumber
	)

Gets the plural name of a standard unit, (ex.

"Meters").

Parameters

[out]	nameP	the unit's name
[in]	unitNumber	the standard unit to look up

Returns: SUCCESS if unitNumber is one the standard units. Otherwise, an error status is returned.

Remarks: A unitNumber is a non-persistant id for one of the the standard units. See UNIT_METRIC_xxx or UNIT_ENGLISH_xxx, defined in msdefs.h.

See also: mdlUnits_getStandardNumber

Remarks: Required Library: mdlbltin.lib

int mdlUnits_getStandardNameSingular	(	WCharP	nameP,
		DgnPlatform::StandardUnit	unitNumber
	)

Gets the singular name of a standard unit, (ex.

"Meter").

Parameters

[out]	nameP	the unit's name
[in]	unitNumber	the standard unit to look up

Returns: SUCCESS if unitNumber is one the standard units, otherwise an error status.

Remarks: A unitNumber is a non-persistant id for one of the the standard units. See UNIT_METRIC_xxx or UNIT_ENGLISH_xxx, defined in msdefs.h.

See also: mdlUnits_getStandardNumber

Remarks: Required Library: mdlbltin.lib

DgnPlatform::StandardUnit mdlUnits_getStandardNumber ( const DgnPlatform::UnitInfo * unitInfoP )

Gets a standard unit number from a unit definition.

Parameters

[in] unitInfoP a unit to look up

Returns: If unitInfoP describes a standard unit the corresponding unit number is returned. Otherwise, if unitInfoP is a valid unit, StandardUnit::Custom is returned. If unitInfoP is not a valid unit, StandardUnit::None is returned.

Remarks: A unitNumber is a non-persistant id for one of the the standard units. See UNIT_METRIC_xxx or UNIT_ENGLISH_xxx, defined in msdefs.h.

See also: mdlUnits_getStandardLabel mdlUnits_getStandardName

Remarks: Required Library: mdlbltin.lib

DgnPlatform::UnitBase mdlUnits_getUnitBase ( const DgnPlatform::UnitInfo * pUnit )

Gets the base from a unit definition.

Parameters

[in] pUnit unit

Returns: one of UNIT_BASE_xxx (defined in msdefs.h)

Remarks: Required Library: mdlbltin.lib

DgnPlatform::UnitSystem mdlUnits_getUnitSystem ( const DgnPlatform::UnitInfo * pUnit )

Gets the unit system for a unit definition.

Parameters

[in] pUnit unit definition

Returns: one of UNIT_SYSTEM_xxx (defined in msdefs.h)

Remarks: Required Library: mdlbltin.lib

DgnPlatform::UnitSystem mdlUnits_getUnitSystemForStandard ( DgnPlatform::StandardUnit unitNumber )

Gets the unit sytem for a standard unit.

Parameters

[in] unitNumber standard unit

Returns: one of UNIT_SYSTEM_xxx (defined in msdefs.h)

Remarks: A unitNumber is a non-persistant id for one of the the standard units. See UNIT_METRIC_xxx or UNIT_ENGLISH_xxx, defined in msdefs.h.; Required Library: mdlbltin.lib

Functions

Detailed Description

Function Documentation