Classes | Typedefs | Enumerations | Functions
Font Manager

The DgnFontManager is the root for all font access. More...

Classes

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...
 

Typedefs

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). More...
 
typedef T_DgnFontCPVector * T_DgnFontCPVectorP
 
typedef T_DgnFontCPVector & T_DgnFontCPVectorR
 
typedef T_DgnFontCPVector const * T_DgnFontCPVectorCP
 
typedef T_DgnFontCPVector const & T_DgnFontCPVectorCR
 

Enumerations

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...
 

Functions

DgnFontFilter operator| (DgnFontFilter a, DgnFontFilter b)
 
DgnFontFilter operator& (DgnFontFilter a, DgnFontFilter b)
 
DgnFontFilter operator~ (DgnFontFilter a)
 
bool operator! (DgnFontFilter a)
 

Detailed Description

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:

  1. get the DgnFile that contains the element (or that will contain the element)
  2. get the DgnFontNumMap from that DgnFile via one of the methods of DgnFontManager
  3. 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 Documentation

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

Enumeration Type Documentation

enum DgnFontFilter
strong

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 
enum DgnFontType
strong

The types of fonts supported by MicroStation.

Enumerator
None 
Rsc 
TrueType 
Shx 
enum SpecialCharValues

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 

Function Documentation

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)

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