Functions

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]pUnit1first unit
[in]pUnit2second 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]ppListModelResult
[in]pCompareUnitUnit on which to base the restrictions bRestrictSize and bRestrictSystem.
[in]bRestrictSizeIf true, only show units equal to or smaller than pCompareUnit.
[in]bRestrictSystemIf true, only show units in the same system as pCompareUnit.
[in]bUseSingularNamesex. 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]pUnit1first unit
[in]pUnit2second 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]distanceOutPdistance expressed in unitToP
[in]unitToPending unit
[in]distanceIndistance expressed in unitFromP
[in]unitFromPstarting 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]factorPscale factor
[in]unitToPending unit
[in]unitFromPstarting 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]unitNumberPlargest unit
[in]unitSystemone 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]unitNumberPnext larger unit
[in]baseUnitNumbercurrent 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]unitNumberPnext smaller unit
[in]baseUnitNumbercurrent 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]unitNumberPsmallest unit
[in]unitSystemone 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:

Other functions that may be of interest are:

Parameters
[out]unitInfoPa unit definition
[in]unitNumbera 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]labelPthe default label for the requested unit
[in]unitNumberstandard 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]namePthe unit's name
[in]unitNumberthe 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]namePthe unit's name
[in]unitNumberthe 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]unitInfoPa 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]pUnitunit
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]pUnitunit 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]unitNumberstandard 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

Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.