IFont

An COM font object is an object wrapper around a Windows font object. The COM font object supports a number of read-write properties as well as a set of methods through its IFont interface. It supports the same set of properties (but not the methods) through the dispatch interface IFontDisp, which is derived from IDispatch to provide access to the font's properties through Automation. The system provides a standard implementation of the font object with both interfaces.

The font object also supports the outgoing interface IPropertyNotifySink so a client can determine when font properties change. Because the font object supports at least one outgoing interface, it also implements IConnectionPointContainer and related interfaces for this purpose.

The font object provides an hFont property, which is a Windows font handle that conforms to the other attributes specified for the font. The font object delays realizing this hFont object when possible, so consecutively setting two properties on a font won't cause an intermediate font to be realized. In addition, as an optimization, the system-implemented font object maintains a cache of font handles. Two font objects in the same process that have identical properties will return the same font handle. The font object can remove font handles from this cache at will, which introduces special considerations for clients using the hFont property. See the description for IFont::get_hFont for more details.

The font object also supports IPersistStream so it can save and load itself from an instance of IStream. An object that uses a font object internally would normally save and load the font as part of the object's own persistence handling.

In addition, the font object supports IDataObject, which can render a property set containing the font's attributes, allowing a client to save these properties as text.

When to Implement

Typically, you use the COM-provided font object, which implements the IFont interface as its primary interface. It allows the caller to manage font properties and to use that font in graphical rendering. Each property in the IFont interface includes a get_PropertyName method if the property supports read access and a put_PropertyName method if the property supports write access. Most of the properties support both read and write access, and thus expose both "get" and "put" methods for these properties.


Property

Type
Access
Allowed

Description
Name BSTR RW The name of the font family, e.g. Arial.
Size CY RW The point size of the font, expressed in a CY type to allow for fractional point sizes.
Bold BOOL RW Indicates whether the font is boldfaced.
Italic BOOL RW Indicates whether the font is italicized.
Underline BOOL RW Indicates whether the font is underlined.
Strikethrough BOOL RW Indicates whether the font is strikethrough.
Weight short RW The boldness or weight of the font.
Charset short RW The character set used in the font, such as ANSI_CHARSET, DEFAULT_CHARSET, or SYMBOL_CHARSET.
hFont HFONT R The Windows font handle that can be selected into a device context for rendering.

When to Use

Use this interface to change or retrieve the properties of a font object.

Methods in Vtable Order

IUnknown Methods Description
QueryInterface Returns pointers to supported interfaces.
AddRef Increments reference count.
Release Decrements reference count.

IFont Methods Description
get_Name Gets the name of the font family.
put_Name Sets a new name for the font family.
get_Size Gets the point size for the font.
put_Size Sets the point size for the font.
get_Bold Indicates whether the font is bold or not.
put_Bold Sets the boldness property for the font.
get_Italic Indicates whether the font is italic or not.
put_Italic Sets the italic property for the font.
get_Underline Indicates whether the font is underlined or not.
put_Underline Sets the underline property for the font.
get_Strikethrough Indicates whether the font is strikethrough or not.
put_Strikethrough Sets the strikethrough property for the font.
get_Weight Gets the weight (boldness) for the font.
put_Weight Sets the weight (boldness) for the font.
get_Charset Gets the font's character set.
put_Charset Sets the font's character set.
get_hFont Returns a Windows HFONT handle for the font described by this font object.
Clone Creates a duplicate font object with a state identical to the current font.
IsEqual Compares this font object to another for equality.
SetRatio Converts the scaling factor for this font between logical units and HIMETRIC units (in which is expressed the point size in the Size property).
QueryTextMetrics Fills a TEXTMETRIC structure describing the font.
AddRefHfont Notifies the font object that the previously realized font identified with hFont (from IFont::GetHfont) should remain valid until IFont::ReleaseHfont is called or the font object itself is released.
ReleaseHfont Notifies the font object that the caller that previously locked this font in the cache with IFont::AddRefHfont no longer requires the lock.
SetHdc Provides a device context handle to the font that describes the logical mapping mode.

QuickInfo

  Windows NT: Use version 4.0 or later.
  Windows: Use Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in ocidl.h.

See Also

IFont - Ole Implementation, IFontDisp