# The Interface Kit: BFont

Derived from: none

Declared in: be/interface/Font.h

Library: libbe.so

## Overview

A BFont object records a set of font attributes, such as the font's family, style, size, and so on. You can set most of these attributes to modify the font and then use the object to set the font of a BView. A BView's font determines how the characters that it draws (with the `DrawString()` and `DrawChar()` functions) will be rendered.

A BFont object can perform calculations based on the metrics of the particular font it represents. For example, it can tell you how much screen real estate it needs to display a given line of text.

To find which fonts are currently installed on the system, call `get_font_family()` and `get_font_style()`.

### Using a BFont Object

A BFont object by itself doesn't do anything. To be able to draw characters in the font, the object must be passed to BView's `SetFont()` function (or BTextView's `SetFontAndColor()`).

A BFont object is always a full representation of a font; all attributes are always set. However, you can choose which of these attributes will modify a BView's current font by passing a mask to `SetFont()` (or `SetFontAndColor()`). For example, this code sets only the font shear and spacing:

       BFont font;
       font.SetShear(60.0);
       font.SetSpacing(B_CHAR_SPACING);
       myView->SetFont(&font, B_FONT_SHEAR | B_FONT_SPACING);

Alternatively, the BView's font could have been modified and reset as follows:

       BFont font;
       myView->GetFont(&font);
       font.SetShear(60.0);
       font.SetSpacing(B_CHAR_SPACING);
       myView->SetFont(&font);

Notice that we had to explicitly reset the view's font (through `SetFont()`) after changing the font's attributes.

### System Fonts

The Interface Kit constructs three BFont objects (plain, bold, and fixed)for each application when the application starts up. The values of these fonts are set by the user through the FontPanel preferences application. You can get to these objects through global pointers :

const BFont *`be_plain_font
` The font that's used to display most gadgets in the user interface, such as check box labels and menu items. All BControl objects use this font.

const BFont *`be_bold_font
` The font that's used to display window titles and BBox labels.

const BFont *`be_fixed_font
` The font that's used to display fixed-width characters.

The global fonts are `const` objects that can't be modified by your application, and aren't updated by the system, even if the user changes their definitions while your app is running. The new values take effect the next time your application is launched.

To use a system font in a view, simply call `SetFont()`:

       myView->SetFont(be_bold_font);

If you want to modify some attributes of a system font, you have to make a copy of it first (and modify the copy):

       BFont font(be_bold_font);
       font.SetSize(13.0);
       myView->SetFont(&font);

Applications should respect the user's choices and base all font choices on these three system fonts, rather than hard-code font names into the application. You should not try to predict the fonts that will be installed on the user's machine.

## Constructor

### BFont()

          BFont(const BFont &font)
          BFont(const BFont *font)
          BFont(void)

Initializes the new BFont object as a copy of another font. If no font is specified, `be_plain_font` is used.

The system BFont objects, including `be_plain_font`, are initialized only when you create a BApplication object for your application. Therefore, the default settings of BFont objects constructed before the BApplication object will be invalid.

See also: `BView::SetFont()`, `BTextView::SetFontAndColor()`

## Member Functions

### CountTuned() see GetTunedInfo()

### Direction(), font_direction

          font_direction Direction(void) const

          enum font_direction {}

`Direction()` returns a `font_direction` constant that describes the direction in which the object's text is meant to be read:

`B_FONT_LEFT_TO_RIGHT`
`B_FONT_RIGHT_TO_LEFT`

This is an inherent property of the font and cannot be set.

The direction of the font affects the direction in which `DrawString()` draws the characters in a string, but not the direction in which it moves the pen.

See also: `BView::DrawString()`

### Encoding() see SetEncoding()

### Face() see SetFace()

### FamilyAndStyle() see SetFamilyAndStyle()

### Flags() see SetFlags()

### GetEscapements(), escapement_delta, GetEdges(), edge_info

          void GetEscapements(const char charArray[], int32 numChars,
             float escapementArray[]) const

          void GetEscapements(const char charArray[], int32 numChars,
             escapement_delta *delta, float escapementArray[]) const

          struct escapement_delta {
             float nonspace;
             float space;
             }

          void GetEdges(const char charArray[], int32 numChars,
             edge_info edgeArray[]) const

          struct edge_info {
             float left;
             float right;
             }

These two functions provide the information required to precisely position characters on the screen or printed page. For each character passed in the charArray, they write information about the horizontal dimension of the character into the escapementArray or the edgeArray. Both functions provide this information in "escapement units" that yield standard coordinate units (72.0 per inch) when multiplied by the font size.

`GetEscapements()` and `GetEdges()` expect the character array they're passed to contain at least numChar characters; neither function checks the charArray for a null terminator. Because the array may hold multibyte characters (in `B_UNICODE_UTF8` encoding), the number of bytes in the array may be greater than the number of characters specified. The escapementArray and edgeArray should be long enough to hold an output value for every input character.

#### Escapements

A character's escapement measures the amount of horizontal space it requires. It includes the space needed to display the character itself, plus some extra room on the left and right edges to separate the character from its neighbors. The illustration below shows the approximate escapements for the letters 'l' and 'p'; the escapement for each character is the distance between the vertical lines:

`GetEscapements()` measures the same space that functions such as `StringWidth()` and BTextView's `LineWidth()` do, but it measures each character individually and records its width in per-point-size escapement units. To translate the escapement value to the width of the character, you must multiply by the point size of the font:

       float width = escapementArray[i] * font.Size();

Because of rounding errors, there may be some difference between the value returned by `StringWidth()` and the width calculated from the individual escapements of the characters in the string.

The escapement value is scalable if the spacing mode of the font is `B_CHAR_SPACING`. In other words, given `B_CHAR_SPACING` and the same set of font characteristics, `GetEscapements()` will report the same measurement for a character regardless of the font size. You can cache one value per character and use it for all font sizes. For the other spacing modes, the reported escapement depends on the font size and therefore can't be scaled.

For most spacing modes, a character has a constant escapement in all contexts; it depends only on the font. However, for `B_STRING_SPACING`, each character's escapement is also contextually dependent on the string it's in. To find the escapement of a character within a particular string, you must pass the entire string in the input charArray.

In the `B_BITMAP_SPACING` and `B_FIXED_SPACING` modes, all characters have integral widths (without a fractional part). For these modes, multiplying an escapement by the font size should yield an integral value. In `B_FIXED_SPACING` mode, all characters have the same escapement.

If a delta argument is provided, `GetEscapements()` will adjust the escapements it reports so that, after multiplying by the font size, the character widths will include the specified increments. An `escapement_delta` structure contains two values:

float `nonspace
` The amount to add to the width of each character with a visible glyph.

float `space
` The amount to add to each whitespace character (characters like `B_TAB` and `B_SPACE` with an escapement but no visible glyph).

A similar argument can be passed to BView's `DrawString()` to adjust the spacing of the characters as they're drawn.

#### Edges

Edge values measure how far a character outline is inset from its left and right escapement boundaries. `GetEdges()` places the edge values into an array of `edge_info` structures. Each structure has a `left` and a `right` data member, as follows:

|  | typedef struct { float `left`; float `right`; } `edge_info`

Edge values, like escapements, are stated in per-point-size units that need to be multiplied by the font size.

The illustration below shows typical character edges. As in the illustration above, the solid vertical lines mark escapement boundaries. The dotted lines mark off the part of each escapement that's an edge, the distance between the character outline and the escapement boundary:

This is the normal case. The left edge is a positive value measured rightward from the left escapement boundary. The right edge is a negative value measured leftward from the right escapement boundary.

However, if the characters of a font overlap, the left edge can be a negative value and the right edge can be positive. This is illustrated below:

Note that the italic 'l' extends beyond its escapement to the right, and that the 'p' begins before its escapement to the left. In this case, instead of separating the adjacent characters, the edges determine how much they overlap.

Edge values are specific to each character and depend on nothing but the character and the font. They don't take into account any contextual information; for example, the right edge for italic 'l' would be the same no matter what letter followed. Edge values therefore aren't sufficient to decide how character pairs can be kerned. Kerning is contextually dependent on the combination of two particular characters.

See also: `StringWidth()`, `SetSpacing()`

### GetFamilyAndStyle() see SetFamilyAndStyle()

### GetHeight(), font_height

          void GetHeight(font_height *height) const

          struct font_height {
             float ascent;
             float descent;
             float leading;
             }

`GetHeight()` writes the three components that determine the height of the font into the structure that the height argument refers to. A `font_height` structure has the following fields:

float `ascent
` How far characters can ascend above the baseline.

float `descent
` How far characters can descend below the baseline.

float `leading
` How much space separates lines (the distance between the descent of the line above and the ascent of the line below).

If you need to round the font height, or any of its components, to an integral value (to figure the spacing between lines of text on-screen, for example), you should always round them up to reduce the amount of vertical character overlap.

See also: `BView::GetFontHeight()`

### GetStringWidths() see StringWidth()

### GetTruncatedStrings()

          void GetTruncatedStrings(const char *inputStringArray[], int32 numStrings,
             uint32 mode, float maxWidth,
             char *truncatedStringArray[]) const

Truncates a set of strings so that each one (and an ellipsis to show where the string was cut) will fit into the maxWidth horizontal space. This function is useful for shortening long strings that are displayed to the user--for showing path names in a list, for example.

The numStrings argument states how many strings in the inputStringArray should be shortened. The mode argument states where the string should be cut. It can be:

`B_TRUNCATE_BEGINNING` | Cut from the beginning of the string until it fits within the specified width.
`B_TRUNCATE_MIDDLE` | Cut from the middle of the string.
`B_TRUNCATE_END` | Cut from the end of the string.
`B_TRUNCATE_SMART` | Cut anywhere, but do so intelligently, so that all the strings remain different after being cut. For example, if a set of similar path names are passed in the inputStringArray, this mode would attempt to cut from the identical parts of the path names and preserve the parts that are different. This mode also pays attention to word boundaries, separators, punctuation, and the like. However, it's not implemented for the current release.

Each output string is written to the truncatedStringArray--into memory that the caller must provide--at an index that matches the index of the full string in the inputStringArray. The truncatedStringArray is a list of pointers to string buffers. Each buffer should be allocated separately and should be at least 3 bytes longer than the matching input string. The 3 bytes allow for the worst-case scenario: `GetTruncatedStrings()` cuts a one-byte character from the input string and replaces it with an ellipsis character, which takes three bytes in UTF-8 encoding, for a net gain of 2 bytes. It then adds a null terminator for the third byte.

The output strings are null-terminated. The input strings should likewise be null-terminated.

See also: `StringWidth()`

### GetTunedInfo(), CountTuned(), tuned_font_info

          void GetTunedInfo(int32 *index, tuned_font_info *info) const

          int32 CountTuned(void) const

          struct tuned_font_info {
             float size;
             float shear;
             float rotation;
             uint32 flags;
             uint16 face;
             }

These functions are used to get information about fonts that have been "tuned" to look good when displayed on-screen. A tuned font is a set of character bitmaps, originally produced from the standard outline font and then modified so that the characters are well proportioned and spaced when displayed at the low resolution of the screen (1 pixel per point).

Because it's a bitmap font, a tuned font captures a specific configuration of font attributes, including size, style, shear, and rotation. A tuned font is a counterpart to an outline font with the same settings. If a BView's current font has a tuned counterpart, `DrawString()` automatically chooses it when drawing on-screen. Tuned fonts are not used for printing.

`CountTuned()` returns how many tuned fonts there are for the family and style represented by the BFont object. `GetTunedInfo()` writes information about the tuned font at index into the structure the info argument refers to. Indices begin at 0 and count only tuned fonts for the BFont's family and style.

With this information, you can set the BFont to values that match those of a tuned font. When a BView draws to the screen, it picks a tuned font if there's one that corresponds to its current font in all respects.

See also: `get_font_family()`

### PrintToStream()

          void PrintToStream(void) const

Writes the following information about the font to the standard output:

|  | family style size (in points) shear (in degrees) rotation (in degrees) ascent descent leading

However, the information in printed on a single line rather than arranged vertically.

### Rotation() see SetRotation()

### SetEncoding(), Encoding()

          void SetEncoding(uint8 encoding)

          uint8 Encoding(void) const

These functions set and return the encoding that maps character values to characters. The following encodings are supported:

`B_UNICODE_UTF8` (UTF-8) | `B_ISO_8859_6` (Latin/Arabic)
`B_ISO_8859_1` (Latin 1) | `B_ISO_8859_7` (Latin/Greek)
`B_ISO_8859_2` (Latin 2) | `B_ISO_8859_8` (Latin/Hebrew)
`B_ISO_8859_3` (Latin 3) | `B_ISO_8859_9` (Latin 5)
`B_ISO_8859_4` (Latin 4) | `B_ISO_8859_10` (Latin 6)
`B_ISO_8859_5` (Latin/Cyrillic) | `B_MACINTOSH_ROMAN`

UTF-8 is an 8-bit encoding for Unicode and is part of the Unicode standard. It matches ASCII values for all 7-bit character codes, but uses multibyte characters for values over 127. The other encodings take only a single byte to represent a character; they therefore necessarily encompass a far smaller set of characters. Most of them represent standards in the ISO/IEC 8859 family of character codes that extend the ASCII set. `B_MACINTOSH_ROMAN` stands for the standard encoding used by the Mac OS.

The encoding affects both input and output functions of the BView. It determines how `DrawString()` interprets the character values it's passed and also how `KeyDown()` encodes character values for the keys the user pressed.

UTF-8 is the preferred encoding and the one that's most compatible with objects defined in the software kits. For example, a BTextView expects all text it takes from the clipboard or from a dragged and dropped message to be UTF-8 encoded. If it isn't, the results are not defined. The more that applications stick with UTF-8 encoding, the more freely they'll be able to exchange data.

See also: Character Encoding of this chapter, `convert_to_utf8()`, `BView::DrawString()`, `BView::KeyDown()`

### SetFace(), Face()

          void SetFace(uint16 face)

          uint16 Face(void) const

These functions set and return a mask that record secondary characteristics of the font, such as whether characters are underlined or drawn in outline. The values that form the face mask have not been defined for this release.

### SetFamilyAndStyle(), GetFamilyAndStyle(), FamilyAndStyle(), font_family, font_style

          void SetFamilyAndStyle(const font_family family, const font_style style)
          void SetFamilyAndStyle(uint32 code)

          void GetFamilyAndStyle(font_family *family, font_style *style) const
          uint32 FamilyAndStyle(void) const

          typedef char font_family[B_FONT_FAMILY_LENGTH + 1]
          typedef char font_style[B_FONT_STYLE_LENGTH + 1]

`SetFamilyAndStyle()` sets the family and style of the font. The family passed to this function must be one of the families enumerated by the `get_font_family()` global function and style must be one of the styles associated with that family, as reported by `get_font_style()`. If the family is `NULL`, `SetFamilyAndStyle()` sets only the style; if style is `NULL`, it sets only the family.

`GetFamilyAndStyle()` writes the names of the current family and style into the `font_value` and `font_style` variables provided.

Internally, the BFont class encodes each family and style combination as a unique integer. `FamilyAndStyle()` returns that code, which can then be passed to `SetFamilyAndStyle()` to set another BFont object. The integer code is not persistent; its meaning may change when the list of installed fonts changes and when the machine is rebooted.

See also: `get_font_family()`

### SetFlags(), Flags()

          void SetFlags(uint32 flags)

          uint32 Flags(void) const

These functions set and return a mask that records various behaviors of the font. Currently, there's just one flag, `B_DISABLE_ANTIALIASING`, which turns off all antialiasing for characters displayed in the font. The default mask has antialiasing turned on.

### SetRotation(), Rotation()

          void SetRotation(float rotation)

          float Rotation(void) const

These functions set and return the rotation of the baseline for characters displayed in the font. The baseline rotates counterclockwise from an axis on the left side of the character. The default (horizontal) baseline is at 0 °. For example, this code

       BFont font;
       font.SetRotation(45.0);
       myView->SetFont(&font, B_FONT_ROTATION);
       myView->DrawString("to the northeast");

would draw a string that extended upwards and to the right.

Rotation is not supported by some Interface Kit classes, including BTextView.

### SetShear(), Shear()

          void SetShear(float shear)

          float Shear(void) const

These functions set and return the angle at which characters are drawn relative to the baseline. The default (perpendicular) shear for all font styles, including oblique and italic ones, is 90.0 °. The shear is measured counterclockwise and can be adjusted within the range 45.0 ° (slanted to the right) through 135.0 ° (slanted to the left). If the shear passed falls outside this range, it will be adjusted to the closest value within range.

### SetSize(), Size()

          void SetSize(float size)

          float Size(void) const

These functions set and return the size of the font in points. Valid sizes range from less than 1.0 point through 10,000 points.

See also: `BView::SetSize()`

### SetSpacing(), Spacing()

          void SetSpacing(uint8 spacing)

          uint8 Spacing(void) const

These functions set and return the mode that determines how characters are horizontally spaced relative to each other when they're drawn. The mode also affects the width or "escapement" of each character as reported by `GetEscapements()`.

There are four spacing modes:

`B_CHAR_SPACING`
Positions each character according to its own inherent width, without adjustment. This produces good results on high-resolution devices like printers, and is the best mode to use for printing. However, when character widths are rounded for the screen, the results are generally poor. Characters are not well-separated and can collide or overlap at small font sizes.

`B_STRING_SPACING`
Keeps the string at the same width as it would have for `B_CHAR_SPACING`, but optimizes the position of each character within that space. The position of a character depends on the surrounding characters and the overall width of the string. Collisions are unlikely in this mode, but because the width of the string constrains what can be done, characters may touch each other.

|  | This mode is preferred when it's important to have the screen match the printed page--for example, to have lines break on-screen where they will break when the display is printed. As the user types new characters into a line of text, the application must redraw the entire line to add each character. The characters in the line may therefore appear to "jiggle" or jump around as new ones are added. New optimal positions are calculated for each character as the width and composition of the string changes.

`B_BITMAP_SPACING`
Calculates the width of each character according to its bitmap appearance on-screen. The widths are chosen for optimal spacing, so that characters never collide and rarely touch. This mode increases the `B_CHAR_SPACING` width of a string if necessary to keep characters separated. (For a small-sized bold font, it may increase the string width substantially.)

|  | In this mode, the spacing between characters is regular and not contextually dependent. Character widths are integral values. This is the best mode for drawing small amounts of text in the user interface; it's the mode that BTextView objects use and it works for both proportional and fixed-width fonts. However, the spacing of text shown on-screen won't correspond to the spacing when the text is printed in `B_CHAR_SPACING` mode.

`B_FIXED_SPACING`
Positions characters according to a constant, integral width. This mode can be used for both proportional and fixed-width fonts, though it treats proportional fonts as if they were fixed-width. All characters have the same escapement.

The `B_CHAR_SPACING` mode is the preferred mode for printing. It's also somewhat faster than `B_STRING_SPACING` or `B_BITMAP_SPACING`. In all modes other than `B_STRING_SPACING`, it's possible to change the character displayed at the end of a string by erasing it and drawing a new character. However, in `B_STRING_SPACING` mode, it's necessary to erase the entire string and redraw it. The longer the string, the better the results.

The `B_STRING_SPACING` and `B_BITMAP_SPACING` modes are relevant only for font sizes in a range of about 7.0 points to 18.0 points. Above that range, `B_CHAR_SPACING` achieves reasonable results on-screen and may be used even where one of the other two modes is specified. Below that range, the screen resolution isn't great enough for the different modes to produce significantly different results, so again `B_CHAR_SPACING` is used.

In addition, `B_CHAR_SPACING` is always used for rotated or sheared text and when antialiasing is disabled.

See also: `BView::DrawString()`, `GetEscapements()`

### Shear() see SetShear()

### Size() see SetSize()

### Spacing() see SetSpacing()

### StringWidth(), GetStringWidths()

          float StringWidth(const char *string) const
          float StringWidth(const char *string, int32 length) const

          void GetStringWidths(const char *stringArray[], const int32 lengthArray[], int32 numStrings, float widthArray[]) const

`StringWidth()` returns how much room is required to draw a string in the font. It measures the characters encoded in length bytes of the string--or, if no length is specified, the entire string up to the null character, '\\0', which terminates it. The return value totals the width of all the characters in coordinate units; it's the length of the baseline required to draw the string.

`GetStringWidth()` provides the same information for a group of strings. It works its way through the stringArray looking at a total of numStrings. For each string, it gets the length at the corresponding index from the lengthArray and places the width of the string in the widthArray at the same index.

These functions take all the attributes of the font--including family, style, size, and spacing--into account.

See also: `BView::StringWidth()`

## Operators

### = (assignment)

          BFont& operator =(const BFont&)

Assigns one BFont object to another. After the assignment, the two objects are identical to each other and do not share any data.

### == (equality), != (inequality)

          bool operator ==(const BFont&) const

          bool operator !=(const BFont&) const

These operators test whether two BFont objects are identical in all respects. If all settable font attributes are the same in both objects, they're equal. If not, they're unequal.

The Be Book, in lovely HTML, for BeOS Release 3.

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.