The DgnFontManager is the root for all font access.
More...
|
| struct | DgnFontList |
| | A list of fonts. Generally this list is created for you by a search method. DgnFontLists are reference counted, so the last reference to the list frees it. More...
|
| |
| struct | DgnFontVisitor |
| | Implement this interface to traverse a set of fonts. More...
|
| |
| struct | DgnFontNamedSymbol |
| | Data structure to represent a named symbol for a font, as specified in the font configuration file. More...
|
| |
| struct | DgnFont |
| | All fonts in MicroStation, regardless of type, are referenced through an instance of this class. Fonts each have a name and type. It is possible to have multiple fonts in the system with the same name but different types. More...
|
| |
| struct | DgnFontNumMap |
| | A DgnFontNumMap is a per-DgnFile object that maps "FontID" (int) values to Font objects. FontNumMaps are loaded from the FontTable element stored in the dictionary model of a DgnFile. More...
|
| |
| struct | DgnFontManager |
| | The DgnFontManager provides access to all font related services. More...
|
| |
| struct | DgnGlyph |
| | Represents a glyph in a Font (agnostic of DgnFontType). The primary use is to be able to get a GPA of this glyph for export purposes. To acquire a Glyph object, see DgnFont::GetGlyph. More...
|
| |
|
| enum | SpecialCharValues {
SPECIALCHAR_Degree_Shx = 0x007f,
SPECIALCHAR_PlusMinus_Shx = 0x0080,
SPECIALCHAR_Diameter_Shx = 0x0081,
SPECIALCHAR_Degree_Unicode = 0x00b0,
SPECIALCHAR_PlusMinus_Unicode = 0x00b1,
SPECIALCHAR_Diameter_Unicode = 0x2205,
SPECIALCHAR_DiameterSign_Unicode = 0x2300,
SPECIALCHAR_CapitalOWithStroke_Unicode = 0x00d8,
SPECIALCHAR_SmallOWithStroke_Unicode = 0x00f8,
SPECIALCHAR_FirstStandardRscFraction = 0x81,
SPECIALCHAR_LastStandardRscFraction = 0xbf,
SPECIALCHAR_UnicodeFraction_1_4 = 0x00bc,
SPECIALCHAR_UnicodeFraction_1_2 = 0x00bd,
SPECIALCHAR_UnicodeFraction_3_4 = 0x00be,
SPECIALCHAR_UnicodeFraction_1_7 = 0x2150,
SPECIALCHAR_UnicodeFraction_1_9 = 0x2151,
SPECIALCHAR_UnicodeFraction_1_10 = 0x2152,
SPECIALCHAR_UnicodeFraction_1_3 = 0x2153,
SPECIALCHAR_UnicodeFraction_2_3 = 0x2154,
SPECIALCHAR_UnicodeFraction_1_5 = 0x2155,
SPECIALCHAR_UnicodeFraction_2_5 = 0x2156,
SPECIALCHAR_UnicodeFraction_3_5 = 0x2157,
SPECIALCHAR_UnicodeFraction_4_5 = 0x2158,
SPECIALCHAR_UnicodeFraction_1_6 = 0x2159,
SPECIALCHAR_UnicodeFraction_5_6 = 0x215a,
SPECIALCHAR_UnicodeFraction_1_8 = 0x215b,
SPECIALCHAR_UnicodeFraction_3_8 = 0x215c,
SPECIALCHAR_UnicodeFraction_5_8 = 0x215d,
SPECIALCHAR_UnicodeFraction_7_8 = 0x215e,
SPECIALCHAR_PrivateUse_Degree_Unicode = 0xe000,
SPECIALCHAR_PrivateUse_PlusMinus_Unicode = 0xe001,
SPECIALCHAR_PrivateUse_Diameter_Unicode = 0xe002,
SPECIALCHAR_PrivateUse_FirstRscFraction = 0xe100,
SPECIALCHAR_PrivateUse_LastRscFraction = 0xe100 + 63
} |
| | Code points for various special characters. More...
|
| |
| enum | DgnFontType { None = 0,
Rsc = 1,
TrueType = 2,
Shx = 3
} |
| | The types of fonts supported by MicroStation. More...
|
| |
| enum | DgnFontFilter {
None = 0,
Resource = 1<<0,
Shx = 1<<1,
ShxBig = 1<<2,
TrueType = 1<<3,
Missing = 1<<4,
Symbol = 1<<5,
Hidden = 1<<6,
Normal = 0x000b,
AllShx = 0x0006,
All = 0x007f,
ResourceShx = 0x0003
} |
| | Flags to filter font searches. More...
|
| |
| enum | DgnFontNamedSymbolSource { HardCoded,
CustomFromFontConfig
} |
| | Describes the type/source of a FontNamedSymbol. More...
|
| |
|
| DgnFontFilter | operator| (DgnFontFilter a, DgnFontFilter b) |
| |
| DgnFontFilter | operator& (DgnFontFilter a, DgnFontFilter b) |
| |
| DgnFontFilter | operator~ (DgnFontFilter a) |
| |
| bool | operator! (DgnFontFilter a) |
| |
The DgnFontManager is the root for all font access.
At startup, the DgnFontManager locates all "known" fonts on the system and creates three separate DgnFontCatalogs of these fonts by font type (RSC, SHX, and TrueType). These catalogs collectively are called the "system fonts". Throughout the course of a session, the system font catalogs can be searched to find a font by name and type, and the value returned is guaranteed to be the same every time (that is, it is valid to compare font pointer values to determine font equivalence.) Stated differently, for a given font name and type there will be either zero or one DgnFont objects extant in the DgnFontCatalogs (see discussion of "missing" fonts below for special case of DgnFont objects that are not in any DgnFontCatalog.)
Fonts
All fonts are referenced through an instance of the DgnPlatform::DgnFont class. DgnFonts are identified by a name and type. It is possible to have multiple fonts in the system with the same name but different types (in this case it is also possible to "hide" fonts from the UI so that administrators can control which font is used.) However, for a given font type, names uniquely identify a font.
Design File Directory Fonts
MicroStation allows users to reference SHX and TrueType fonts that are located in the same directory as a design file. Whenever MicroStation detects that a design file references a font that cannot be found in the system catalogs, it searches the directory of the design file for font files and, if any are present, adds them to the system catalog. [N.B. note that fonts are never deleted from the system catalog. Once a font is found in a design file directory, from that point forward it has the same standing as all other system fonts. That means that when switching to a new design file in a different directory, that font may be referenced, and in future sessions may cause a missing font. For this reason fonts that are to be used beyond a single directory should always be added to the system font directory.
Font Numbers
Fonts are identified by their name and type. However, it would be inefficient to store a copy of the font name every time it is referenced inside a design file. For this reason MicroStation stores a "font table" in the non-model storage area of design files. The font table stores a mapping between a "font number" and a font name. So, for a given design file, all elements that refer to a given font number refer to the same font. However, it should be obvious that elements from a different design file may refer to same font through a different font number. Also, note that there is only one font table for the entire design file, so that all elements from all models use the same font table. To find a DgnFont object from the font number in an MSElement, the procedure is:
-
get the DgnFile that contains the element (or that will contain the element)
-
get the DgnFontNumMap from that DgnFile via one of the methods of DgnFontManager
-
call either GetFont or ResolveFont on the DgnFontNumMap to get a pointer to the DgnFont
There is a convenience method on DgnFontManager to return a DgnFontNumMap from a DgnModelRef, since that is frequently the most convenient value from which to find a DgnFile. Note that this is merely a convenience method and it does not imply that there is a DgnFontNumMap associated with DgnModelRef's. DgnModelRef's are associated with DgnFiles and DgnFiles have DgnFontNumMaps. Therefore, all calls to GetDgnFontMapP through DgnModelRefs from the same DgnFile will return the same value.
- Note
- There can be some confusion about font numbers related to legacy APIs. For example:
-
Font number ranges. Much of the existing MicroStation API encodes meaning to the values of font numbers. It implicitly defines that font numbers from 0-255 are RSC fonts, font numbers from 256-1023 are SHX fonts, and font numbers 1024 and above are TrueType fonts. One reason that these ranges are implied is that the font table only stores a mapping between font number and font name. It does not store the font type. Therefore, the font number implicitly specifies the font type. In retrospect this association between font number and font type is a mistake and causes limitations and errors. In a future version of MicroStation, this limitation will be corrected and font numbers will NOT imply font type. Programmers should never, henceforth with the DgnFontManager API, presume an association between font number and font name. The proper way to tell the font type for a font number is to follow the instructions above and then interrogate the font.
-
RSC font numbers. RSC fonts existed before font tables were invented. So a given RSC font has the same font number across all files. [N.B. In fact, RSC fonts do not even appear in the font table. This is a severe limitation in that it is impossible to tell the name of the RSC font referenced in an element without the appropriate font library (.rsc), and the font will change unexpectedly if a different font library is present on the target computer from the originating one.] Therefore, lazy or uninformed programmers can pass "any" file to lookup an RSC and it will succeed. It is best to forget this fact and write code that works for all font types.
Missing Fonts
Missing fonts are merely font names that exist in a font table for which no font exists in a system DgnFontCatalog. This can only happen by either removing fonts or (more commonly) by transferring a design file from one computer to another on which the font is not present. When a design file's font table references a missing font, the corresponding DgnFontNumMap for the design file will contain a reference to a font whose "IsPresent" flag is false. If this font is used to render text, MicroStation will use a default "fallback" font that varies depending on the missing font's type, as specified in the font configuration file. The concept of missing fonts appears in the DgnFontManager APIs because in certain cases it is desirable to show the user a list of possible fonts that may or may not include missing fonts, depending on the purpose for the list. Remember, missing fonts only have relevance in the context of a design file's DgnFontNumMap - it makes no sense to speak of "missing fonts" in the context of the system font catalog lookups.
SHX BigFonts
In reality there are three forms of SHX font files (and some SHX files are not font files, but that's not relevant here): "normal" shx fonts, "big" shx fonts, and "Unicode" fonts. Normal SHX files existed first, but suffered from the limitation that they could only hold 255 (locale-encoded) characters. To support Asian character sets, they introduced the "BigFont" shx files that can hold 64K character. However, instead of making big fonts contain all characters, they decided that big font files would only provide the characters above 255, and each text style would specify both a normal (which has now come to be called a "small") shx font and a "big" shx font. For this reason, the DgnFontManager sometimes takes two values for font to specify both the small and big fonts for SHX fonts. You can tell whether a font is a SHX Bigfont by calling DgnFont.IsShxBigFont(). Generally speaking, big fonts should be hidden from the user interface other than the text styles, since they are not valid on their own - only in combination with another valid small SHX font. Where possible, BigFonts should be avoided in favor of Unicode SHX fonts.
Font Encoding
Generally speaking it would be nice if all strings in MicroStation were encoded using Unicode. Fortunately, when using TrueType fonts you can basically presume that [N.B. not all TrueType fonts are unicode encoded, but the DgnFontManager API allows you to presume they are. All strings passed to the font API associated with TrueType fonts are Unicode encoded.] Unfortunately the RSC and SHX font definitions are more difficult to deal with since the encoding of the font "glyphs" is locale specific. Worse, for RSC fonts the encoding is not specified in the font anywhere so there is no programmatic way to tell the meaning of any of the glyph values. To further complicate matters, RSC font designers have used some "obscure" ascii values to mean fractions, and special symbols (e.g. the plus/minus, degree and diameter symbols). So to render strings stored in MicroStation text elements it is absolutely essential to pass them to the font system "raw" and there can be no conversions to/from Unicode, etc. When displaying strings in user interface fields, most of MicroStation simply presumes that the encoding must match the current system locale, but this may or may not be true.
Font FAQ
Q: Given a font, how do I get its font number?
A: The question makes no sense. The same font may be referenced by many different font numbers from different design file. Now, if the question is "how can I determine if a font exists in the font table for a design file, and if so by what number?", then the answer is to get the DgnFontNumMap for that file and call GetFontNumber().
Q: Given a font number, how do I get a Font?
A: The question makes no sense unless you qualify the font number with a DgnFile. In that case, get the DgnFontNumMap for the file and call either GetFont or ResolveFont.
| typedef RefCountedPtr<DgnFontList> DgnFontListPtr |
| typedef RefCountedPtr<DgnFontNamedSymbol> DgnFontNamedSymbolPtr |
| typedef bvector<DgnFontCP> T_DgnFontCPVector |
A bvector of DgnFontCP objects, with allocations handled by Bentley.dll (so it can be passed across DLLs targetting different C runtimes).
| typedef T_DgnFontCPVector const* T_DgnFontCPVectorCP |
| typedef T_DgnFontCPVector const& T_DgnFontCPVectorCR |
| typedef T_DgnFontCPVector* T_DgnFontCPVectorP |
| typedef T_DgnFontCPVector & T_DgnFontCPVectorR |
Flags to filter font searches.
| Enumerator |
|---|
| None |
|
| Resource |
find RSC fonts
|
| Shx |
find SHX fonts
|
| ShxBig |
find SHX Bigfonts
|
| TrueType |
find TrueType fonts
|
| Missing |
include missing fonts
|
| Symbol |
include symbol fonts
|
| Hidden |
include hidden fonts
|
| Normal |
|
| AllShx |
find normal "known" fonts (does not return SHX bigfonts)
|
| All |
find all SHX fonts (including bigfonts)
|
| ResourceShx |
find all existing fonts, including missing and hidden fonts
|
| enum DgnFontNamedSymbolSource |
|
strong |
Describes the type/source of a FontNamedSymbol.
| Enumerator |
|---|
| HardCoded |
|
| CustomFromFontConfig |
|
The types of fonts supported by MicroStation.
| Enumerator |
|---|
| None |
|
| Rsc |
|
| TrueType |
|
| Shx |
|
Code points for various special characters.
| Enumerator |
|---|
| SPECIALCHAR_Degree_Shx |
|
| SPECIALCHAR_PlusMinus_Shx |
|
| SPECIALCHAR_Diameter_Shx |
|
| SPECIALCHAR_Degree_Unicode |
|
| SPECIALCHAR_PlusMinus_Unicode |
|
| SPECIALCHAR_Diameter_Unicode |
This is really "empty set" in unicode, should be 0x2300 but stuck with this for compatibility.
|
| SPECIALCHAR_DiameterSign_Unicode |
|
| SPECIALCHAR_CapitalOWithStroke_Unicode |
|
| SPECIALCHAR_SmallOWithStroke_Unicode |
|
| SPECIALCHAR_FirstStandardRscFraction |
|
| SPECIALCHAR_LastStandardRscFraction |
|
| SPECIALCHAR_UnicodeFraction_1_4 |
|
| SPECIALCHAR_UnicodeFraction_1_2 |
|
| SPECIALCHAR_UnicodeFraction_3_4 |
|
| SPECIALCHAR_UnicodeFraction_1_7 |
|
| SPECIALCHAR_UnicodeFraction_1_9 |
|
| SPECIALCHAR_UnicodeFraction_1_10 |
|
| SPECIALCHAR_UnicodeFraction_1_3 |
|
| SPECIALCHAR_UnicodeFraction_2_3 |
|
| SPECIALCHAR_UnicodeFraction_1_5 |
|
| SPECIALCHAR_UnicodeFraction_2_5 |
|
| SPECIALCHAR_UnicodeFraction_3_5 |
|
| SPECIALCHAR_UnicodeFraction_4_5 |
|
| SPECIALCHAR_UnicodeFraction_1_6 |
|
| SPECIALCHAR_UnicodeFraction_5_6 |
|
| SPECIALCHAR_UnicodeFraction_1_8 |
|
| SPECIALCHAR_UnicodeFraction_3_8 |
|
| SPECIALCHAR_UnicodeFraction_5_8 |
|
| SPECIALCHAR_UnicodeFraction_7_8 |
|
| SPECIALCHAR_PrivateUse_Degree_Unicode |
|
| SPECIALCHAR_PrivateUse_PlusMinus_Unicode |
|
| SPECIALCHAR_PrivateUse_Diameter_Unicode |
|
| SPECIALCHAR_PrivateUse_FirstRscFraction |
|
| SPECIALCHAR_PrivateUse_LastRscFraction |
|
| bool Bentley::DgnPlatform::operator! |
( |
DgnFontFilter |
a | ) |
|
| DgnFontFilter Bentley::DgnPlatform::operator& |
( |
DgnFontFilter |
a, |
|
|
DgnFontFilter |
b |
|
) |
| |
| DgnFontFilter Bentley::DgnPlatform::operator| |
( |
DgnFontFilter |
a, |
|
|
DgnFontFilter |
b |
|
) |
| |
| DgnFontFilter Bentley::DgnPlatform::operator~ |
( |
DgnFontFilter |
a | ) |
|