D2Font function

Requires: Direct2D.lg32

Purpose

Creates a D2Font object for use with D2SetFont.

Syntax

Set Fnt = D2Font(hFont)
Set Fnt = D2Font(fontstring$)
Set Fnt = D2Font(fname$ [, height! , weight%][,italic?][,stretch%] [,locale$])

Fnt	: Object variable
fname$, fontstring$, locale$	: string expression
height!	: float expression
weight%	: integer expression
italic?	: boolean expression
stretch%	: integer expression
hFont	: Handle expression

Description

D2Font creates a D2Font object (DirectWrite IDWriteTextFormat object) which describes a font to be used with D2Text and D2DrawText. In its simplest form - D2Font(hFont) - the function takes a GDI font handle and converts it into a D2Font object (which is actually a IDWriteTextFormat object). hFont may specify a GDI stockfont constant. The properties of the GDI font are converted to Direct2D font-properties that are used to create the D2Font (IDWriteTextFormat) object. The D2Font object must be selected using D2SetFont.

The second form takes a fontstring$ argument containing all the parameters of the current font (like _Font$, but the format is different). The format of the string is “fontname, height!, weight%, italic?, strectch%,localename”. All parts are optional (i.e. “,20,400,,10,” is allowed) with the missing parts taken from the current font.

The third form requires a font description. Most parameters may use default values, but at a minimum the application needs to specify the font's name.

The height must be specified in DIPs (1/96 inch == 1 logical pixel) . The parameter is optional and defaults to 11 DIPs, which conforms to the default size of the DEFAULT_GUI_FONT stock font.

The height in DIPs can be calculated using the D2PointsToDips() function that converts the font's pointsize to DIPs.

The font weight defaults to a normal font, but it can be one of the following values:

• DWRITE_FONT_WEIGHT_THIN - Thin (100).
• DWRITE_FONT_WEIGHT_EXTRA_LIGHT - Extra-light (200).
• DWRITE_FONT_WEIGHT_ULTRA_LIGHT - Ultra-light (200).
• DWRITE_FONT_WEIGHT_LIGHT - Light (300).
• DWRITE_FONT_WEIGHT_SEMI_LIGHT - Semi-Light (350).
• DWRITE_FONT_WEIGHT_NORMAL - Normal (400), default.
• DWRITE_FONT_WEIGHT_REGULAR - Regular (400).
• DWRITE_FONT_WEIGHT_MEDIUM - Medium (500).
• DWRITE_FONT_WEIGHT_DEMI_BOLD - Demi-bold (600).
• DWRITE_FONT_WEIGHT_SEMI_BOLD - Semi-bold (600).
• DWRITE_FONT_WEIGHT_BOLD - Bold (700).
• DWRITE_FONT_WEIGHT_EXTRA_BOLD - Extra-bold (800).
• DWRITE_FONT_WEIGHT_ULTRA_BOLD - Ultra-bold (800).
• DWRITE_FONT_WEIGHT_BLACK - Black (900).
• DWRITE_FONT_WEIGHT_HEAVY - Heavy (900).
• DWRITE_FONT_WEIGHT_EXTRA_BLACK - Extra-black (950).
• DWRITE_FONT_WEIGHT_ULTRA_BLACK - Ultra-black (950).

Set the italics boolean parameter to True for an intalics font (default is off).

The default for the stretch parameter is a normal stretch, but it can take one of these values:

• DWRITE_FONT_STRETCH_UNDEFINED - Not known (0).
• DWRITE_FONT_STRETCH_ULTRA_CONDENSED - Ultra-condensed (1).
• DWRITE_FONT_STRETCH_EXTRA_CONDENSED - Extra-condensed (2).
• DWRITE_FONT_STRETCH_CONDENSED - Condensed (3).
• DWRITE_FONT_STRETCH_SEMI_CONDENSED - Semi-condensed (4).
• DWRITE_FONT_STRETCH_NORMAL - Normal (5), default.
• DWRITE_FONT_STRETCH_MEDIUM - Medium (5).
• DWRITE_FONT_STRETCH_SEMI_EXPANDED - Semi-expanded (6).
• DWRITE_FONT_STRETCH_EXPANDED - Expanded (7).
• DWRITE_FONT_STRETCH_EXTRA_EXPANDED - Extra-expanded (8).
• DWRITE_FONT_STRETCH_ULTRA_EXPANDED - Ultra-expanded (9).

The localename$ may specify the locale name, like "en-us".

Example

'

' D2Font sample

' (dpi-unaware & dpi-aware)

'

$Library "direct2d"

$Library "gfawinx"

OpenW 1, 0, 0, 320, 300, 16 + 32

Global Object Win1RT

Set Win1RT = D2GetRT()

Global Object Fnt, FntBold   ' cache the fonts

Set Fnt = D2Font("Gabriola", D2PointsToDIPs(13))

Set FntBold = D2Font("Gabriola", D2PointsToDIPs(13), DWRITE_FONT_WEIGHT_BOLD)

Do

Sleep

Until Me Is Nothing

Sub Win_1_Paint

D2BeginDraw Win1RT, D2C_White

D2SetFont Fnt     ' high performance

D2Text 16, 16, "Hello Direct2D (Normal)"

D2SetFont FntBold

D2Text 16, 40, "DirectWrite (Bold)"

D2EndDraw

EndSub

Remarks

D2Font() invokes IDWriteFactory::CreateTextFormat which is part of DirectWrite. The IDWriteTextFormat object is used with the render target object's method ID2D1RenderTarget::DrawText (used by D2Text and D2DrawText).

D2Font() may be used anywhere in the program, a D2Font object is not a render target resource.

For more information: see here.

See Also

D2GetFontObj, D2RFont, D2SetFont, D2Text, D2DrawText, D2TextSize, D2PointsToDips

{Created by Sjouke Hamstra; Last updated: 27/12/2021 by James Gaite}