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... | |
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.
[in] | pUnit1 | first unit |
[in] | pUnit2 | second unit |
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.
[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". |
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.
[in] | pUnit1 | first unit |
[in] | pUnit2 | second unit |
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.
[out] | distanceOutP | distance expressed in unitToP |
[in] | unitToP | ending unit |
[in] | distanceIn | distance expressed in unitFromP |
[in] | unitFromP | starting unit |
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.
[out] | factorP | scale factor |
[in] | unitToP | ending unit |
[in] | unitFromP | starting unit |
StatusInt mdlUnits_getLargestStandard | ( | DgnPlatform::StandardUnit * | unitNumberP, |
DgnPlatform::UnitSystem | unitSystem | ||
) |
Gets the largest standard unit in a given unit system.
[out] | unitNumberP | largest unit |
[in] | unitSystem | one of UNIT_SYSTEM_xxx (defined in msdefs.h) |
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.
[out] | unitNumberP | next larger unit |
[in] | baseUnitNumber | current unit |
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.
[out] | unitNumberP | next smaller unit |
[in] | baseUnitNumber | current unit |
StatusInt mdlUnits_getSmallestStandard | ( | DgnPlatform::StandardUnit * | unitNumberP, |
DgnPlatform::UnitSystem | unitSystem | ||
) |
Gets the smallest standard unit in a given unit system.
[out] | unitNumberP | smallest unit |
[in] | unitSystem | one of UNIT_SYSTEM_xxx (defined in msdefs.h) |
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:
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:
[out] | unitInfoP | a unit definition |
[in] | unitNumber | a standard unitNumber to look up Otherwise, an error status is returned. |
StatusInt mdlUnits_getStandardLabel | ( | WCharP | labelP, |
DgnPlatform::StandardUnit | unitNumber | ||
) |
Gets the default label for a standard unit, (ex.
"m").
[out] | labelP | the default label for the requested unit |
[in] | unitNumber | standard unitNumber to look up |
int mdlUnits_getStandardName | ( | WCharP | nameP, |
DgnPlatform::StandardUnit | unitNumber | ||
) |
Gets the plural name of a standard unit, (ex.
"Meters").
[out] | nameP | the unit's name |
[in] | unitNumber | the standard unit to look up |
int mdlUnits_getStandardNameSingular | ( | WCharP | nameP, |
DgnPlatform::StandardUnit | unitNumber | ||
) |
Gets the singular name of a standard unit, (ex.
"Meter").
[out] | nameP | the unit's name |
[in] | unitNumber | the standard unit to look up |
DgnPlatform::StandardUnit mdlUnits_getStandardNumber | ( | const DgnPlatform::UnitInfo * | unitInfoP | ) |
Gets a standard unit number from a unit definition.
[in] | unitInfoP | a unit to look up |
DgnPlatform::UnitBase mdlUnits_getUnitBase | ( | const DgnPlatform::UnitInfo * | pUnit | ) |
Gets the base from a unit definition.
[in] | pUnit | unit |
DgnPlatform::UnitSystem mdlUnits_getUnitSystem | ( | const DgnPlatform::UnitInfo * | pUnit | ) |
Gets the unit system for a unit definition.
[in] | pUnit | unit definition |
DgnPlatform::UnitSystem mdlUnits_getUnitSystemForStandard | ( | DgnPlatform::StandardUnit | unitNumber | ) |
Gets the unit sytem for a standard unit.
[in] | unitNumber | standard unit |