# CGpFont Class

The `CGpFont` class allows the creation of Font objects. The Font object encapsulates the characteristics, such as family, height, size, and style (or combination of styles), of a specific font. A Font object is used when drawing strings.

Inherits from: CGpBase.
Include file: CGpFont.inc.

Name | Description
--- | ---
Constructors | Creates a Font object.
Clone | Copies the contents of the existing Font object into a new Font object.
GetFamily | Gets the font family on which this font is based.
GetHeight | Gets the line spacing of this font in the current unit of a specified Graphics object.
GetHeight(DPI) | Gets the line spacing of this font in pixels.
GetLogFontA | Uses a LOGFONTA structure to get the attributes of this Font object.
GetLogFontW | Uses a LOGFONTW structure to get the attributes of this Font object.
GetSize | Returns the font size (commonly called the em size) of this Font object.
GetStyle | Returns the font size (commonly called the em size) of this Font object.
GetUnit | Returns the unit of measure of this Font object.
IsAvailable | Determines whether this Font object was created successfully.

# CGpFontCollection Class

The `CGpFontCollection` class contains methods for enumerating the font families in a collection of fonts. Objects built from this class include the InstalledFontCollection and PrivateFontCollection.

Inherits from: CGpBase.
Include file: CGpFont.inc.

Name | Description
--- | ---
Constructor | Creates a FontCollection object.
GetFamilies | Gets the font families contained in this font collection.
GetFamilyCount | Gets the number of font families contained in this font collection.

# CGpInstalledFontCollection Class

Extends `CGpFontCollection`. Does not implement new additional methods.

The InstalledFontCollection object represents the fonts installed on the system.

Inherits from: CGpFontCollection.
Include file: CGpFont.inc.

# CGpPrivateFontCollection Class

Extends `CGpFontCollection`. The PrivateFontCollection object is a collection for fonts. This object keeps a collection of fonts specifically for an application. The fonts in the collection can include installed fonts as well as fonts that have not been installed on the system.

Inherits from: CGpFontCollection.
Include file: CGpFont.inc.

Name | Description
--- | ---
AddFontFile | Adds a font file to this private font collection.
AddMemoryFont | Adds a font that is contained in system memory to a Windows GDI+ font collection.

# CGpFontFamily Class

The `CGpFontFamily` class encapsulates a set of fonts that make up a font family. A font family is a group of fonts that have the same typeface but different styles.

Inherits from: CGpBase. Include file: CGpFont.inc.

Name | Description
--- | ---
Constructor | Creates a FontFamily object based on a specified font collection.
Clone | Copies the contents of the existing FontFamily object into a new FontFamily object.
GenericMonospace | Gets a FontFamily object that a specifies a generic monospace typeface.
GenericSansSerif | Gets a FontFamily object that a specifies a generic sans serif typeface.
GenericSerif | Gets a FontFamily object that a specifies a generic serif typeface.
GetCellAscent | Gets the cell ascent, in design units, of this font family for the specified style or style combination.
GetCellDescent | Gets the cell descent, in design units, of this font family for the specified style or style combination.
GetEmHeight | Gets the size (commonly called em size or em height), in design units, of this font family.
GetFamilyName | Gets the name of this font family.
GetLineSpacing | Gets the line spacing, in design units, of this font family for the specified style or style combination.
IsAvailable | Determines whether this Font object was created successfully.
IsStyleAvailable | Determines whether the specified style is available for this font family.

## Constructors (CGpFont)

Creates a Font object.

    CONSTRUCTOR CGpFont

Creates and initializes a Font object from another Font object.

    CONSTRUCTOR CGpFont (BYVAL pFont AS CGpFont PTR)

Creates a Font object based on the Windows Graphics Device Interface (GDI) font object that is currently selected into a specified device context. This constructor is provided for compatibility with GDI.

    CONSTRUCTOR CGpFont (BYVAL hdc AS HDC)

Parameter | Description
--- | ---
hdc | Handle to a Windows device context that has a font selected. A handle is a number that Windows uses internally to reference an object.

Creates a Font object indirectly from a Windows Graphics Device Interface (GDI) logical font by using a handle to a GDI LOGFONT structure.

    CONSTRUCTOR CGpFont (BYVAL hdc AS HDC, BYVAL hFont AS HFONT)

Parameter | Description
--- | ---
hdc | Handle to a Windows device context. A handle is a number that Windows uses internally to reference an object.
hFont | Handle to a logical font.

Creates a Font object directly from a Windows Graphics Device Interface (GDI) logical font. This constructor is provided for compatibility with GDI.

    CONSTRUCTOR CGpFont (BYVAL hdc AS HDC, BYVAL plogfont AS LOGFONTA PTR)
    CONSTRUCTOR CGpFont (BYVAL hdc AS HDC, BYVAL plogfont AS LOGFONTW PTR)

Parameter | Description
--- | ---
hdc | Handle to a Windows device context. A handle is a number that Windows uses internally to reference an object.
plogfont | Pointer to a LOGFONT structure variable that contains attributes of the font.

Creates a Font object based on a FontFamily object, a size, a font style, and a unit of measurement.

    CONSTRUCTOR CGpFont (BYVAL pFamily AS CGpFontFamily PTR, BYVAL emSize AS SINGLE, _
       BYVAL nStyle AS INT_ = 0, BYVAL nUnit AS GpUnit = 0)

Parameter | Description
--- | ---
pFamily | Pointer to a FontFamily object that specifies information such as the string that identifies the font family and the font family’s text metrics measured in design units.
emSize | The em size of the font measured in the units specified in the unit parameter.
nStyle | Optional. Integer that specifies the style of the typeface. This value must be an element of the FontStyle enumeration or the result of a bitwise OR applied to two or more of these elements. For example, FontStyleBold OR FontStyleUnderline OR FontStyleStrikeout sets the style as a combination of the three styles. The default value is FontStyleRegular.
nUnit | Optional. Element of the Unit enumeration that specifies the unit of measurement for the font size. The default value is UnitPoint.

Creates a Font object based on a font family, a size, a font style, and a unit of measurement.

    CONSTRUCTOR CGpFont (BYVAL pwszFamilyName AS WSTRING PTR, BYVAL emSize AS SINGLE, _
       BYVAL nStyle AS INT_ = 0, BYVAL nUnit AS GpUnit = 0, BYVAL pFontCollection AS CGpFontCollection PTR = NULL)

Parameter | Description
--- | ---
pwszFamilyName | Name of the font family.
emSize | The em size of the font measured in the units specified in the unit parameter.
nStyle | Optional. Integer that specifies the style of the typeface. This value must be an element of the FontStyle enumeration or the result of a bitwise OR applied to two or more of these elements. For example, FontStyleBold OR FontStyleUnderline OR FontStyleStrikeout sets the style as a combination of the three styles. The default value is FontStyleRegular.
nUnit Optional. | Element of the Unit enumeration that specifies the unit of measurement for the font size. The default value is UnitPoint.
pFontCollection | Optional. Pointer to a FontCollection object that specifies a user-defined group of fonts. If the value of this parameter is NULL, the system font collection is used. The default value is NULL.

## Clone (CGpFont)

Copies the contents of the existing Font object into a new Font object.

    FUNCTION Clone (BYVAL pCloneFont AS CGpFont PTR) AS GpStatus

Parameter | Description
--- | ---
pCloneFont | Pointer to the Font object where to copy the contents of the existing object.

#### Return value

If the function succeeds, it returns Ok, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

#### Example

    ' ========================================================================================
    ' The following example creates a Font object, clones it, and then uses the clone to draw text.
    ' ========================================================================================
    SUB Example_CloneFont (BYVAL hdc AS HDC)

       ' // Create a graphics object from the window device context
       DIM graphics AS CGpGraphics = hdc
       ' // Set the scale transform
       graphics.ScaleTransformForDpi

       ' // Create a Font object.
       DIM font AS CGpFont = CGpFont("Arial", AfxGdipPointsToPixels(16, TRUE))

       ' // Create a clone of the Font object
       DIM cloneFont AS CGpFont
       font.Clone(@cloneFont)

       ' // Draw Text with cloneFont.
       DIM solidBrush AS CGpSolidBrush = ARGB_BLACK
       DIM wszText AS WSTRING * 260 = "This is a cloned Font"
       graphics.DrawString(@wszText, -1, @cloneFont, 0, 0, @solidbrush)

    END SUB
    ' ========================================================================================

## GetFamily (CGpFont)

Gets the font family on which this font is based.

    FUNCTION GetFamily (BYVAL pFamily AS CGpFontFamily PTR) AS GpStatus

Parameter | Description
--- | ---
pFamily | Pointer to a FontFamily object that receives the font family.

#### Return value

If the function succeeds, it returns Ok, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

#### Example

    ' ========================================================================================
    ' The following example creates a Font object, retrieves the information about the font
    ' family on which it is based, and then uses the FontFamily object to create a second Font
    ' object. The example then uses the second Font object to draw text.
    ' ========================================================================================
    SUB Example_GetFamily (BYVAL hdc AS HDC)

       ' // Create a graphics object from the window device context
       DIM graphics AS CGpGraphics = hdc
       ' // Set the scale transform
       graphics.ScaleTransformForDpi

       ' // Create a Font object.
       DIM font AS CGpFont = CGpFont("Arial", AfxGdipPointsToPixels(16, TRUE))

       ' // Get the FontFamily of myFont.
       DIM fontFamily AS CGpFontFamily
       font.GetFamily(@fontFamily)

       ' // Create a new Font object from fontFamily.
       DIM familyFont AS CGpFont = CGpFont(@fontFamily, AfxGdipPointsToPixels(16, TRUE))

       ' // Draw Text with familyFont
       DIM solidBrush AS CGpSolidBrush = ARGB_BLACK
       DIM wszText AS WSTRING * 260 = "This is a Font created from a FontFamily"
       graphics.DrawString(@wszText, -1, @familyFont, 0, 0, @solidbrush)

    END SUB
    ' ========================================================================================

## GetHeight (CGpFont)

Gets the line spacing of this font in the current unit of a specified Graphics object. The line spacing is the vertical distance between the base lines of two consecutive lines of text. Thus, the line spacing includes the blank space between lines along with the height of the character itself.

    FUNCTION GetHeight (BYVAL pGraphics AS CGpGraphics PTR) AS SINGLE

Parameter | Description
--- | ---
pGraphics | Pointer to a Graphics object whose unit and vertical resolution are used in the height calculation.

#### Return value

This method returns the line spacing of this font.

#### Remarks

If the font unit is set to anything other than UnitPixel, the height, in pixels, is calculated using the vertical resolution of the specified Graphics object. For example, suppose the font unit is inches and the font size is 0.3. Also suppose that for the corresponding font family, the em height is 2048 and the line spacing is 2355. If the unit of the Graphics object is UnitPixel and the vertical resolution of the Graphics object is 96 dots per inch, the height is calculated as follows:

    2355*(0.3/2048)*96 = 33.1171875

Continuing with the same example, suppose the unit of the Graphics object is something other than UnitPixel, say UnitMillimeter. Then (using 1 inch = 25.4 millimeters) the height, in millimeters, is calculated as follows:

    2355*(0.3/2048)25.4 = 8.762256

## GetHeight (DPI) (CGpFont)

Gets the line spacing, in pixels, of this font. The line spacing is the vertical distance between the base lines of two consecutive lines of text. Thus, the line spacing includes the blank space between lines along with the height of the character itself.

    FUNCTION GetHeight (BYVAL dpi AS SINGLE) AS SINGLE

Parameter | Description
--- | ---
dpi | Single precision number that specifies the vertical resolution, in dots per inch, of the device that displays the font.

#### Return value

This method returns the line spacing of the font in pixels.

#### Remarks

If the font unit is set to anything other than UnitPixel, the height, in pixels, is calculated using the specified vertical resolution. For example, suppose the font unit is inches and the font size is 0.3. Also suppose that for the corresponding font family, the em height is 2048 and the line spacing is 2355. If the specified vertical resolution is 96 dots per inch, the height is calculated as follows:

    2355*(0.3/2048)*96 = 33.1171875

#### Example

    ' ========================================================================================
    ' The following example creates a Font object, retrieves the height of the Font object, and
    ' uses the height to position two lines of text, with the second line directly below the first.
    ' ========================================================================================
    SUB Example_GetHeight (BYVAL hdc AS HDC)

       ' // Create a graphics object from the window device context
       DIM graphics AS CGpGraphics = hdc
       ' // Set the scale transform
       graphics.ScaleTransformForDpi

       ' // Create a Font object.
       DIM font AS CGpFont = CGpFont("Arial", AfxGdipPointsToPixels(16, TRUE))

       ' // Draw text with myFont.
       DIM solidbrush_1 AS CGpSolidBrush = ARGB_BLACK
       DIM wszText AS WSTRING * 260 = "The first line of text"
       graphics.DrawString(@wszText, -1, @font, 0, 0, @solidbrush_1)

       ' // Get the height of myFont.
       DIM height AS SINGLE = font.GetHeight(@graphics)

       ' // Draw text immediately below the first line of text
       DIM solidbrush_2 AS CGpSolidBrush = ARGB_RED
       DIM wszText2 AS WSTRING * 260 = "The second line of text"
       graphics.DrawString(@wszText2, -1, @font, 0, height, @solidbrush_2)

    END SUB
    ' ========================================================================================

## GetLogFontA (CGpFont)

Uses a LOGFONT structure to get the attributes of this Font object.

    FUNCTION GetLogFontA (BYVAL pGraphics AS CGpGraphics PTR, BYVAL pLogFont AS LOGFONTA PTR) AS GpStatus
    FUNCTION GetLogFontW (BYVAL pGraphics AS CGpGraphics PTR, BYVAL pLogFont AS LOGFONTW PTR) AS GpStatus

Parameter | Description
--- | ---
pGraphics | Pointer to a Graphics object that contains attributes of the display device.
pLogFont | Pointer to a LOGFONT structure variable that receives the font attributes.

#### Return value

If the function succeeds, it returns Ok, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

#### Example

    ' ========================================================================================
    ' The following example creates a Font object, gets the font attributes from the Font object,
    ' and uses these attributes (contained in the LOGFONTA structure) to create a second Font
    ' object. The second Font object is then used to draw text.
    ' ========================================================================================
    SUB Example_GetLogFontA (BYVAL hdc AS HDC)

       ' // Create a graphics object from the window device context
       DIM graphics AS CGpGraphics = hdc
       ' // Set the scale transform
       graphics.ScaleTransformForDpi

       ' // Create a Font object according to the DPI setting
       DIM font AS CGpFont = CGpFont("Arial", AfxGdipPointsToPixels(16, TRUE))

       ' // Get attributes of font
       DIM logFont AS LOGFONTA
       font.GetLogFontA(@graphics, @logFont)
       ' // Adjust for DPI
       logFont.lfHeight /= rxRatio

       ' // Create a second Font object from logFont
       DIM logfontFont AS CGpFont = CGpFont(hdc, @logFont)

       ' // Draw text using logfontFont.
       DIM solidbrush AS CGpSolidBrush = ARGB_BLACK
       DIM wszText AS WSTRING * 260 = "Font from a LOGFONTA"
       graphics.DrawString(@wszText, -1, @logfontFont, 0, 0, @solidbrush)

    END SUB
    ' ========================================================================================

#### Example

    ' ========================================================================================
    ' The following example creates a Font object, gets the font attributes from the Font object,
    ' and uses these attributes (contained in the LOGFONTW structure) to create a second Font
    ' object. The second Font object is then used to draw text.
    ' ========================================================================================
    SUB Example_GetLogFontW (BYVAL hdc AS HDC)

       ' // Create a graphics object from the window device context
       DIM graphics AS CGpGraphics = hdc
       ' // Set the scale transform
       graphics.ScaleTransformForDpi

       ' // Create a Font object according to the DPI setting
       DIM font AS CGpFont = CGpFont("Arial", AfxGdipPointsToPixels(16, TRUE))

       ' // Get attributes of font
       DIM logFont AS LOGFONTW
       font.GetLogFontW(@graphics, @logFont)
       ' // Adjust for DPI
       logFont.lfHeight /= rxRatio

       ' // Create a second Font object from logFont
       DIM logfontFont AS CGpFont = CGpFont(hdc, @logFont)

       ' // Draw text using logfontFont.
       DIM solidbrush AS CGpSolidBrush = ARGB_BLACK
       DIM wszText AS WSTRING * 260 = "Font from a LOGFONTW"
       graphics.DrawString(@wszText, -1, @logfontFont, 0, 0, @solidbrush)

    END SUB
    ' ========================================================================================

## GetSize (CGpFont)

Returns the font size (commonly called the em size) of this Font object. The size is in the units of this Font object.

    FUNCTION GetSize () AS SINGLE

#### Return value

The method returns the font size. The size is in the units of this Font object.

#### Example

    ' ========================================================================================
    ' The following example creates a Font object, gets the size of the font, and creates a second
    ' Font object of the same size as the first. The second Font object is then used to draw text.
    ' ========================================================================================
    SUB Example_GetSize (BYVAL hdc AS HDC)

       ' // Create a graphics object from the window device context
       DIM graphics AS CGpGraphics = hdc
       ' // Set the scale transform
       graphics.ScaleTransformForDpi

       ' // Create a Font object according to the DPI setting
       DIM font AS CGpFont = CGpFont("Arial", AfxGdipPointsToPixels(16, TRUE))

       ' // Get the size of font
       DIM size AS SINGLE = font.GetSize

       ' // Create a second Font object with the same emSize as myFont.
       DIM sizeFont AS CGpFont = CGpFont("Arial", size)

       ' // Draw text using sizeFont
       DIM solidbrush AS CGpSolidBrush = ARGB_BLACK
       DIM wszText AS WSTRING * 260 = "Font with an acquired size"
       graphics.DrawString(@wszText, -1, @sizeFont, 0, 0, @solidbrush)

    END SUB
    ' ========================================================================================

## GetStyle (CGpFont)

Returns the font size (commonly called the em size) of this Font object. The size is in the units of this Font object.

    FUNCTION GetStyle () AS INT_

#### Return value

The method returns the font size. The size is in the units of this Font object.

#### Example

    ' ========================================================================================
    ' The following example creates a Font object, gets the FontStyle associated with the font,
    ' and creates a second Font object by using the same style. The second Font object is then
    ' used to draw text.
    ' ========================================================================================
    SUB Example_GetStyle (BYVAL hdc AS HDC)

       ' // Create a graphics object from the window device context
       DIM graphics AS CGpGraphics = hdc
       ' // Set the scale transform
       graphics.ScaleTransformForDpi

       ' // Create a Font object according to the DPI setting
       DIM font AS CGpFont = CGpFont("Arial", AfxGdipPointsToPixels(16, TRUE)), FontStyleItalic)

       ' // Get the style of font
       DIM style AS SINGLE = font.GetStyle

       ' // Create a second Font object with the same emSize as myFont.
       DIM styleFont AS CGpFont = CGpFont("Arial", AfxGdipPointsToPixels(20, TRUE)), style)

       ' // Draw text using sizeFont
       DIM solidbrush AS CGpSolidBrush = ARGB_BLACK
       DIM wszText AS WSTRING * 260 = "Font with an acquired style"
       graphics.DrawString(@wszText, -1, @styleFont, 0, 0, @solidbrush)

    END SUB
    ' ========================================================================================

## GetUnit (CGpFont)

Returns the unit of measure of this Font object.

    FUNCTION GetUnit () AS GpUnit

#### Return value

This method returns one of the elements of the Unit enumeration.

#### Example

    ' ========================================================================================
    ' The following example creates a Font object, gets the unit of measure of the font, and
    ' then sets the page units of the Graphics object to the returned unit. It then uses the
    ' Font object to draw text.
    ' ========================================================================================
    SUB Example_GetUnit (BYVAL hdc AS HDC)

       ' // Create a graphics object from the window device context
       DIM graphics AS CGpGraphics = hdc
       ' // Set the scale transform
       graphics.ScaleTransformForDpi

       ' // Create a Font object according to the DPI setting
       DIM font AS CGpFont = CGpFont("Arial", AfxGdipPointsToPixels(12, TRUE))

       ' // Get the unit of measure for font
       DIM unit AS GpUnit = font.GetUnit
       ' // Set the Graphics units of graphics to the retrieved unit value.
       graphics.SetPageUnit(unit)

       ' // Draw text using font
       DIM solidbrush AS CGpSolidBrush = ARGB_BLACK
       DIM wszText AS WSTRING * 260 = "Here is some text"
       graphics.DrawString(@wszText, -1, @font, 0, 0, @solidbrush)

    END SUB
    ' ========================================================================================

## IsAvailable (CGpFont)

Determines whether this Font object was created successfully.

    FUNCTION IsAvailable () AS BOOLEAN

#### Return value

If the font was constructed successfully, this method returns TRUE; otherwise, it returns FALSE.

#### Example

    ' ========================================================================================
    ' The following example creates a Font object and then tests whether the Font object is
    ' available. If the Font object is available, it is used to draw text.
    ' ========================================================================================
    SUB Example_IsAvailable (BYVAL hdc AS HDC)

       ' // Create a graphics object from the window device context
       DIM graphics AS CGpGraphics = hdc
       ' // Set the scale transform
       graphics.ScaleTransformForDpi

       ' // Create a Font object according to the DPI setting
       DIM font AS CGpFont = CGpFont("Arial", AfxGdipPointsToPixels(18, TRUE))

       ' // Check whether font is available
       DIM available AS BOOLEAN = font.IsAvailable

       ' // Draw text using font, if it is availiable
       IF available THEN
          DIM solidbrush AS CGpSolidBrush = ARGB_BLACK
          DIM wszText AS WSTRING * 260 = "Here is some text"
          graphics.DrawString(@wszText, -1, @font, 0, 0, @solidbrush)
       END IF

    END SUB
    ' ========================================================================================

## Constructor (CGpFontCollection)

Creates a FontCollection object.

    CONSTRUCTOR CGpFontCollection

# GetFamilies (CGpFontCollection)

Gets the font families contained in this font collection.

    FUNCTION GetFamilies (BYVAL numSought AS INT_, BYVAL gpfamilies AS CGpFontFamily PTR, _
       BYVAL numFound AS INT_ PTR) AS GpStatus

Parameter | Description
--- | ---
numSought | Integer that specifies the number of font families in this font collection.
gpfamilies | Out. Pointer to an array that receives the FontFamily objects.
numFound | Out. Pointer to an LONG that receives the number of font families found in this collection. This number should be the same as the numSought value.

#### Return value

If the function succeeds, it returns Ok, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

#### Remarks

A font family consists of a single font type with related styles. An example of a single font type is Arial Regular. An example of a font family is a set of fonts containing Arial Regular, Arial Italic, and Arial Bold style fonts.

## GetFamilyCount (CGpFontCollection)

Gets the number of font families contained in this font collection.

    FUNCTION GetFamilyCount () AS LONG

#### Return value

This method returns the number of font families contained in this font collection.

#### Remarks

A font family consists of a single font type with related styles. An example of a single font type is Arial Regular. An example of a font family is a set of fonts containing Arial Regular, Arial Italic, and Arial Bold style fonts.

## AddFontFile (CGpPrivateFontCollection)

Adds a font file to this private font collection.

    FUNCTION AddFontFile (BYVAL pwszFileName AS WSTRING PTR) AS GpStatus

Parameter | Description
--- | ---
pwszFileName | Pointer to a wide-character string that specifies the name of a font file.

#### Return value

If the function succeeds, it returns Ok, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

#### Remarks

When you use the GDI+ API, you must never allow your application to download arbitrary fonts from untrusted sources. The operating system requires elevated privileges to assure that all installed fonts are trusted.

## AddMemoryFont (CGpPrivateFontCollection)

Adds a font that is contained in system memory to a Windows GDI+ font collection.

    FUNCTION AddMemoryFont (BYVAL pMemory AS ANY PTR, BYVAL length AS INT_) AS GpStatus

Parameter | Description
--- | ---
pMemory | Pointer to a font that is contained in memory.
length | Integer that specifies the number of bytes of data in the font.

#### Return value

If the function succeeds, it returns Ok, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

#### Remarks

When you use the GDI+ API, you must never allow your application to download arbitrary fonts from untrusted sources. The operating system requires elevated privileges to assure that all installed fonts are trusted.

## Constructor (CGpFontFamily)

Creates a FontFamily object based on a specified font collection.

    CONSTRUCTOR CGpFontFamily
    CONSTRUCTOR CGpFontFamily (BYVAL pFontFamily AS CGpFontFamily PTR)
    CONSTRUCTOR CGpFontFamily (BYVAL pwszName AS WSTRING PTR, pFontCollection AS CGpFontCollection PTR = NULL)

Parameter | Description
--- | ---
pwszName | Name of the font family. For example, Arial.ttf is the name of the Arial font family.
pFontCollection | Optional. Pointer to a FontCollection object that specifies the collection that the font family belongs to. If FontCollection is NULL, this font family is not part of a collection. The default value is NULL.

## Clone (CGpFontFamily)

Copies the contents of the existing FontFamily object into a new FontFamily object.

    FUNCTION Clone (BYVAL pFontFamily AS CGpBrush PTR) AS GpStatus

Parameter | Description
--- | ---
pFontFamily | Pointer to a variable that will receive a pointer to the cloned FontFamily object.

#### Return value

If the function succeeds, it returns Ok, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

#### Example

    ' ========================================================================================
    ' The following example creates a FontFamily object, clones that object, and then creates
    ' a Font object from the clone. It then uses the Font object to draw text.
    ' ========================================================================================
    SUB Example_CloneFontFamily (BYVAL hdc AS HDC)

       ' // Create a graphics object from the window device context
       DIM graphics AS CGpGraphics = hdc
       ' // Set the scale transform
       graphics.ScaleTransformForDpi

       ' // Create a FontFamily object
       DIM arialFontFamily AS CGpFontFamily = "arial"

       ' // Clone the FontFamily object and use it to create a Font object
       DIM cloneFontFamily AS CGpFontFamily
       arialFontFamily.Clone(@cloneFontFamily)
       DIM arialFont AS CGpFont = CGpFont(@cloneFontFamily, AfxGdipPointsToPixels(16, TRUE))

       ' // Draw text using the new font
       DIM solidBrush AS CGpSolidBrush = ARGB_BLACK
       graphics.DrawString("This is an Arial font", -1, @arialFont, 0, 0, @solidbrush)

    END SUB
    ' ========================================================================================

## GenericMonospace (CGpFontFamily)

Gets a FontFamily object that a specifies a generic monospace typeface.

    FUNCTION GenericMonospace (BYVAL pFontFamily AS CGpFontFamily PTR) AS GpStatus

Parameter | Description
--- | ---
pFontFamily | Pointer to a variable that will receive a pointer to the FontFamily object.

#### Return value

If the function succeeds, it returns Ok, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

#### Example

    ' ========================================================================================
    ' The following example creates a Font object by using a generic monospace FontFamily
    ' object and then uses that Font object to draw text.
    ' ========================================================================================
    SUB Example_GenericMonospace (BYVAL hdc AS HDC)

       ' // Create a graphics object from the window device context
       DIM graphics AS CGpGraphics = hdc
       ' // Set the scale transform
       graphics.ScaleTransformForDpi

       ' // Use a generic monospace FontFamily object to create a Font object.
       DIM fontFamily AS CGpFontFamily
       fontFamily.GenericMonospace(@fontFamily)
       DIM genericMonoFont AS CGpFont = CGpFont(@fontFamily, AfxGdipPointsToPixels(16, TRUE))

       ' // Draw text using the new font
       DIM solidBrush AS CGpSolidBrush = ARGB_BLACK
       graphics.DrawString("This is a generic monospace font", -1, @genericMonoFont, 0, 0, @solidbrush)

    END SUB
    ' ========================================================================================

## GenericSansSerif (CGpFontFamily)

Gets a FontFamily object that a specifies a generic sans serif typeface.

    FUNCTION GenericSansSerif (BYVAL pFontFamily AS CGpFontFamily PTR) AS GpStatus

Parameter | Description
--- | ---
pFontFamily | Pointer to a variable that will receive a pointer to the FontFamily object.

#### Return value

If the function succeeds, it returns Ok, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

#### Example

    ' ========================================================================================
    ' The following example creates a Font object by using a generic sans serif FontFamily
    ' object and then uses that Font object to draw text.
    ' ========================================================================================
    SUB Example_GenericSansSerif (BYVAL hdc AS HDC)

       ' // Create a graphics object from the window device context
       DIM graphics AS CGpGraphics = hdc
       ' // Set the scale transform
       graphics.ScaleTransformForDpi

       ' // Use a generic sans serif FontFamily object to create a Font object.
       DIM fontFamily AS CGpFontFamily
       fontFamily.GenericSansSerif(@fontFamily)
       DIM genericSansSerifFont AS CGpFont = CGpFont(@fontFamily, AfxGdipPointsToPixels(16, TRUE))

       ' // Draw text using the new font
       DIM solidBrush AS CGpSolidBrush = ARGB_BLACK
       graphics.DrawString("This is a generic sans serif font", -1, @genericSansSerifFont, 0, 0, @solidbrush)

    END SUB
    ' ========================================================================================

## GenericSerif (CGpFontFamily)

Gets a FontFamily object that a specifies a generic serif typeface.

    FUNCTION GenericSansSerif (BYVAL pFontFamily AS CGpFontFamily PTR) AS GpStatus

Parameter | Description
--- | ---
pFontFamily | Pointer to a variable that will receive a pointer to the FontFamily object.

#### Return value

If the function succeeds, it returns Ok, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

#### Example

    ' ========================================================================================
    ' The following example creates a Font object by using a generic serif FontFamily
    ' object and then uses that Font object to draw text.
    ' ========================================================================================
    SUB Example_GenericSerif (BYVAL hdc AS HDC)

       ' // Create a graphics object from the window device context
       DIM graphics AS CGpGraphics = hdc
       ' // Set the scale transform
       graphics.ScaleTransformForDpi

       ' // Use a generic serif FontFamily object to create a Font object.
       DIM fontFamily AS CGpFontFamily
       fontFamily.GenericSerif(@fontFamily)
       DIM genericSerifFont AS CGpFont = CGpFont(@fontFamily, AfxGdipPointsToPixels(16, TRUE))

       ' // Draw text using the new font
       DIM solidBrush AS CGpSolidBrush = ARGB_BLACK
       graphics.DrawString("This is a generic serif font", -1, @genericSerifFont, 0, 0, @solidbrush)

    END SUB
    ' ========================================================================================

## GetCellAscent (CGpFontFamily)

Gets the cell ascent, in design units, of this font family for the specified style or style combination.

    FUNCTION GetCellAscent (BYVAL nStyle AS INT_) AS UINT16

Parameter | Description
--- | ---
nStyle | Integer that specifies the style of the typeface. This value must be an element of the FontStyle enumeration or the result of a bitwise OR applied to two or more of these elements. For example, FontStyleBold OR FontStyleUnderline OR FontStyleStrikeout specifies a combination of the three styles.

#### Return value

This method returns the cell ascent, in design units, of this font family for the specified style or style combination.

#### Example

    ' ========================================================================================
    ' The following example creates a FontFamily object, gets the cell ascent in design units,
    ' and outputs the value as text.
    ' ========================================================================================
    SUB Example_GetCellAscent (BYVAL hdc AS HDC)

       ' // Create a graphics object from the window device context
       DIM graphics AS CGpGraphics = hdc
       ' // Set the scale transform
       graphics.ScaleTransformForDpi

       ' // Create a FontFamily object
       DIM ascentFontFamily AS CGpFontFamily = "arial"

       ' // Get the cell ascent of the font family in design units
       DIM cellAscent AS LONG = ascentFontFamily.GetCellAscent(FontStyleRegular)

       ' // Copy the cell ascent into a string and draw the string
       DIM solidBrush AS CGpSolidBrush = ARGB_BLACK
       DIM font AS CGpFont = CGpFont(@ascentFontFamily, AfxGdipPointsToPixels(16, TRUE))
       DIM wszText AS WSTRING * 260
       wszText = "ascentFontFamily.GetCellAscent() returns " & STR(cellAscent)
       graphics.DrawString(@wszText, -1, @font, 0, 0, @solidbrush)

    END SUB
    ' ========================================================================================

## GetCellDescent (CGpFontFamily)

Gets the cell descent, in design units, of this font family for the specified style or style combination.

    FUNCTION GetCellDescent (BYVAL nStyle AS INT_) AS UINT16

Parameter | Description
--- | ---
nStyle | Integer that specifies the style of the typeface. This value must be an element of the FontStyle enumeration or the result of a bitwise OR applied to two or more of these elements. For example, FontStyleBold OR FontStyleUnderline OR FontStyleStrikeout specifies a combination of the three styles.

#### Return value

This method returns the cell ascent, in design units, of this font family for the specified style or style combination.

#### Example

    ' ========================================================================================
    ' The following example creates a FontFamily object, gets the cell descent in design units,
    ' and outputs the value as text.
    ' ========================================================================================
    SUB Example_GetCellDescent (BYVAL hdc AS HDC)

       ' // Create a graphics object from the window device context
       DIM graphics AS CGpGraphics = hdc
       ' // Set the scale transform
       graphics.ScaleTransformForDpi

       ' // Create a FontFamily object
       DIM descentFontFamily AS CGpFontFamily = "arial"

       ' // Get the cell ascent of the font family in design units
       DIM cellDescent AS LONG = descentFontFamily.GetCellDescent(FontStyleRegular)

       ' // Copy the cell descent into a string and draw the string
       DIM solidBrush AS CGpSolidBrush = ARGB_BLACK
       DIM font AS CGpFont = CGpFont(@descentFontFamily, AfxGdipPointsToPixels(16, TRUE))
       DIM wszText AS WSTRING * 260
       wszText = "ascentFontFamily.GetCellAscent() returns " & STR(cellDescent)
       graphics.DrawString(@wszText, -1, @font, 0, 0, @solidbrush)

    END SUB
    ' ========================================================================================

## GetEmHeight (CGpFontFamily)

Gets the size (commonly called em size or em height), in design units, of this font family.

    FUNCTION GetEmHeight (BYVAL nStyle AS INT_) AS UINT16

Parameter | Description
--- | ---
nStyle | Integer that specifies the style of the typeface. This value must be an element of the FontStyle enumeration or the result of a bitwise OR applied to two or more of these elements. For example, FontStyleBold OR FontStyleUnderline OR FontStyleStrikeout specifies a combination of the three styles.

#### Return value

This method returns the size, in design units, of this font family.

#### Example

    ' ========================================================================================
    ' The following example creates a FontFamily object, gets the em height in design units,
    ' and outputs the value as text.
    ' ========================================================================================
    SUB Example_GetEmHeight (BYVAL hdc AS HDC)

       ' // Create a graphics object from the window device context
       DIM graphics AS CGpGraphics = hdc
       ' // Set the scale transform
       graphics.ScaleTransformForDpi

       ' // Create a FontFamily object
       DIM emHeightFontFamily AS CGpFontFamily = "arial"

       ' // Get the cell ascent of the font family in design units.
       DIM emHeight AS LONG = emHeightFontFamily.GetEmHeight(FontStyleRegular)

       ' // Copy the height into a string and draw the string.
       DIM solidBrush AS CGpSolidBrush = ARGB_BLACK
       DIM font AS CGpFont = CGpFont(@emHeightFontFamily, AfxGdipPointsToPixels(16, TRUE))
       DIM wszText AS WSTRING * 260
       wszText = "emHeightFontFamily.GetEmHeight() returns " & STR(emHeight)
       graphics.DrawString(@wszText, -1, @font, 0, 0, @solidbrush)

    END SUB
    ' ========================================================================================

## GetFamilyName (CGpFontFamily)

Gets the name of this font family.

    FUNCTION GetFamilyName (BYVAL pwszName AS WSTRING PTR, BYVAL language AS LANGID = LANG_NEUTRAL) AS GpStatus

Parameter | Description
--- | ---
pwszName | Out. Name of this font family.
language | In, optional. Sixteen-bit value that specifies the language to use. The default value is LANG_NEUTRAL, which is the user’s default language.

#### Return value

If the function succeeds, it returns Ok, which is an element of the GpStatus enumeration.

If the function fails, it returns one of the other elements of the GpStatus enumeration.

#### Example

    ' ========================================================================================
    ' The following example creates a FontFamily object, gets the family name, and outputs the
    ' name as text.
    ' ========================================================================================
    SUB Example_GetFamilyName (BYVAL hdc AS HDC)

       ' // Create a graphics object from the window device context
       DIM graphics AS CGpGraphics = hdc
       ' // Set the scale transform
       graphics.ScaleTransformForDpi

       ' // Create a FontFamily object
       DIM nameFontFamily AS CGpFontFamily = "arial"

       ' // Get the cell ascent of the font family in design units.
       DIM familyName AS WSTRING * LF_FACESIZE
       nameFontFamily.GetFamilyName(@familyName)

       ' // Draw the family name
       DIM solidBrush AS CGpSolidBrush = ARGB_BLACK
       DIM font AS CGpFont = CGpFont(@nameFontFamily, AfxGdipPointsToPixels(16, TRUE))
       graphics.DrawString(@familyName, -1, @font, 0, 0, @solidbrush)

    END SUB
    ' ========================================================================================

## GetLineSpacing (CGpFontFamily)

Gets the line spacing, in design units, of this font family for the specified style or style combination. The line spacing is the vertical distance between the base lines of two consecutive lines of text.

    FUNCTION GetLineSpacing (BYVAL nStyle AS INT_) AS UINT16

Parameter | Description
--- | ---
nStyle | Integer that specifies the style of the typeface. This value must be an element of the FontStyle enumeration or the result of a bitwise OR applied to two or more of these elements. For example, FontStyleBold OR FontStyleUnderline OR FontStyleStrikeout specifies a combination of the three styles.

#### Return value

This method returns the line spacing of this font family.

##### Example

    ' ========================================================================================
    ' The following example creates a FontFamily object, gets the line spacing in design units,
    ' and outputs the value as text.
    ' ========================================================================================
    SUB Example_GetLineSpacing (BYVAL hdc AS HDC)

       ' // Create a graphics object from the window device context
       DIM graphics AS CGpGraphics = hdc
       ' // Set the scale transform
       graphics.ScaleTransformForDpi

       ' // Create a FontFamily object
       DIM lineSpacingFontFamily AS CGpFontFamily = "arial"

       ' // Get the cell ascent of the font family in design units.
       DIM lineSpacing AS LONG = lineSpacingFontFamily.GetLineSpacing(FontStyleRegular)

       ' // Copy the line spacing into a string and draw the string.
       DIM solidBrush AS CGpSolidBrush = ARGB_BLACK
       DIM font AS CGpFont = CGpFont(@lineSpacingFontFamily, AfxGdipPointsToPixels(16, TRUE))
       DIM wszText AS WSTRING * 260 = "lineSpacingFontFamily.GetLineSpacing() returns " & STR(lineSpacing)
       graphics.DrawString(@wszText, -1, @font, 0, 0, @solidbrush)

    END SUB
    ' ========================================================================================

## IsAvailable (CGpFontFamily)

Determines whether this Font object was created successfully.

    FUNCTION IsAvailable () AS BOOLEAN

#### Return value

If the font was constructed successfully, this method returns TRUE; otherwise, it returns FALSE.

#### Example

    ' ========================================================================================
    ' The following example creates a FontFamily object. If the FontFamily object is created
    ' successfully, the example draws text.
    ' ========================================================================================
    SUB Example_IsAvailable (BYVAL hdc AS HDC)

       ' // Create a graphics object from the window device context
       DIM graphics AS CGpGraphics = hdc
       ' // Set the scale transform
       graphics.ScaleTransformForDpi

       ' // Create a FontFamily object
       DIM myFontFamily AS CGpFontFamily = "arial"

       ' // Check to see if myFontFamily is available.
       DIM isAvailable AS BOOLEAN = myFontFamily.IsAvailable

       ' // If myFontFamily is available, draw text.
       IF isAvailable THEN
          DIM solidBrush AS CGpSolidBrush = ARGB_BLACK
          DIM font AS CGpFont = CGpFont(@myFontFamily, AfxGdipPointsToPixels(16, TRUE))
          DIM wszText AS WSTRING * 260 = "myFontFamily is available"
          graphics.DrawString(@wszText, -1, @font, 0, 0, @solidbrush)
       END IF

    END SUB
    ' ========================================================================================

## IsStyleAvailable (CGpFontFamily)

Determines whether the specified style is available for this font family.

    FUNCTION IsStyleAvailable (BYVAL nStyle AS INT_) AS BOOLEAN

Parameter | Description
--- | ---
nStyle | Integer that specifies the style of the typeface. This value must be an element of the FontStyle enumeration or the result of a bitwise OR applied to two or more of these elements. For example, FontStyleBold OR FontStyleUnderline OR FontStyleStrikeout specifies a combination of the three styles.

#### Return value

If the style or combination of styles is available, this method returns TRUE; otherwise, it returns FALSE.

#### Remarks

This method returns a misleading result on some third-party fonts. For example, IsStyleAvailable(FontStyleUnderline) may return FALSE because it is really testing for a regular style font that also is an underlined font: FontStyleRegular OR FontStyleUnderline. If the font does not have a regular style, the IsStyleAvailable method returns FALSE.

#### Example

    ' ========================================================================================
    ' The following example creates a FontFamily object. If the font family has a regular style
    ' available, the example draws text.
    ' ========================================================================================
    SUB Example_IsStyleAvailable (BYVAL hdc AS HDC)

       ' // Create a graphics object from the window device context
       DIM graphics AS CGpGraphics = hdc
       ' // Set the scale transform
       graphics.ScaleTransformForDpi

       ' // Create a FontFamily object
       DIM myFontFamily AS CGpFontFamily = "arial"

       ' // Check to see if the regular style is available.
       DIM isStyleAvailable AS BOOLEAN = myFontFamily.IsStyleAvailable(FontStyleRegular)

       ' // If regular style is available, draw text.
       IF isStyleAvailable THEN
          DIM solidBrush AS CGpSolidBrush = ARGB_BLACK
          DIM font AS CGpFont = CGpFont(@myFontFamily, AfxGdipPointsToPixels(16, TRUE))
          DIM wszText AS WSTRING * 260 = "myFontFamily is available in regular style"
          graphics.DrawString(@wszText, -1, @font, 0, 0, @solidbrush)
       END IF

    END SUB
    ' ========================================================================================