IFont interface (ocidl.h)
Provides a 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 will not 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.
The font object also supports IPersistStream so that 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.
Inheritance
The IFont interface inherits from the IUnknown interface. IFont also has these types of members:
Methods
The IFont interface has these methods.
| IFont::AddRefHfont Notifies the font object that the previously realized font identified with hFont should remain valid until ReleaseHfont is called or the font object itself is released completely. |
| IFont::Clone Creates a duplicate font object. |
| IFont::get_Bold Gets the font's current Bold property. |
| IFont::get_Charset Retrieves the character set used in the font. |
| IFont::get_hFont Retrieves a handle to the font described by this font object. |
| IFont::get_Italic Gets the font's current Italic property. |
| IFont::get_Name Retrieves the name of the font family. |
| IFont::get_Size Retrieves the point size of the font. |
| IFont::get_Strikethrough Gets the font's current Strikethrough property. |
| IFont::get_Underline Gets the font's current Underline property. |
| IFont::get_Weight Gets the font's current Weight property. |
| IFont::IsEqual Compares this font object to another for equivalence. |
| IFont::put_Bold Sets the font's Bold property. |
| IFont::put_Charset Sets the font's character set. |
| IFont::put_Italic Sets the font's Italic property. |
| IFont::put_Name Specifies a new name for the font family. |
| IFont::put_Size Sets the point size of the font. |
| IFont::put_Strikethrough Sets the font's Strikethrough property. |
| IFont::put_Underline Sets the font's Underline property. |
| IFont::put_Weight Sets the font's Weight property. |
| IFont::QueryTextMetrics Fills a caller-allocated structure with information about the font. |
| IFont::ReleaseHfont Notifies the font object that the caller that previously locked this font in the cache with IFont::AddRefHfont no longer requires the lock. |
| IFont::SetHdc Provides a device context to the font that describes the logical mapping mode. |
| IFont::SetRatio Converts the scaling factor for this font between logical units and HIMETRIC units. |
Remarks
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 these properties support both read and write access.
| Property | Type | Read Access Method | Write Access Method | Description |
|---|---|---|---|---|
| Name | BSTR | get_Name | put_Name | The facename of the font, e.g. Arial. |
| Size | CY | get_Size | put_Size | The point size of the font, expressed in a CY type to allow for fractional point sizes. |
| Bold | BOOL | get_Bold | put_Bold | Indicates whether the font is boldfaced. |
| Italic | BOOL | get_Italic | put_Italic | Indicates whether the font is italicized. |
| Underline | BOOL | get_Underline | put_Underline | Indicates whether the font is underlined. |
| Strikethrough | BOOL | get_Strikethrough | put_Strikethrough | Indicates whether the font is strikethrough. |
| Weight | short | get_Weight | put_Weight | The boldness of the font. |
| Charset | short | get_Charset | put_Charset | The character set used in the font, such as ANSI_CHARSET, DEFAULT_CHARSET, or SYMBOL_CHARSET. |
| hFont | HFONT | get_hFont | The Windows font handle that can be selected into a device context for rendering. |
OLE Implementation
The system provides a standard implementation of a font object with the IFont interface on top of the underlying system font support. A font object is created through the function OleCreateFontIndirect. A font object supports a number of read/write properties as well as a set of methods through its IFont interface and supports the same set of properties (but not the methods) through a dispatch interface IFontDisp which is derived from IDispatch to provide access to the font's properties through Automation. The system implementation of the font object supplies both interfaces.Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps | UWP apps] |
| Minimum supported server | Windows 2000 Server [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | ocidl.h |
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for