IFont Interface

IID_IFont

{BEF6E002-A874-101A-8BBA-00AA00300CAB}

A 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.

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

Returns a copy of the name of the font family.

put_Name

Specifies a new name for the font family.

get_Size

Retrieves the point size of the font expressed in a 64-bit CY variable. The upper 32-bits of this value contains the integer point size and the lower 32-bits contains the fractional point size.

put_Size

Sets the current point size of the font given a CY structure.

get_Bold

Indicates whether the font is bold or not.

put_Bold

Sets the font's current bold property. Changing the Bold property may also change the Weight property. Setting Bold to TRUE sets the Weight to FW_BOLD (700); setting Bold to FALSE sets Weight to FW_NORMAL (400).

get_Italic

Indicates whether the font is italic or not.

put_Italic

Sets the font's current italic property.

get_Underline

Indicates whether the font is underlined or not.

put_Underline

Sets the font's current underline property.

get_Strikethrough

Indicates whether the font has the strikethrough property or not.

put_Strikethrough

Sets the font's current strikethrough property.

get_Weight

Returns the font weight, where a weight is defined as any of the FW_* values that are valid for Windows fonts.

put_Weight

Sets the font's weight. This property may affect the bold property as well. Bold is set to TRUE if the weight is greater than the average of FW_NORMAL (400) and FW_BOLD (700), that is 550.

get_Charset

Returns the character set used in the font. The character set can be any of those defined for Windows fonts.

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 equivalence.

SetRatio

Converts the scaling factor for this font between logical units and HIMETRIC units. HIMETRIC units are used to express the point size in the IFont::get_Size and IFont::put_Size methods. The values passed to IFont::SetRatio are used to compute the display size of the font in logical units from the value in the Size property:

Display Size= (cyLogical/cyHimetric) * Size

QueryTextMetrics

Fills a caller-allocated TEXTMETRIC structure for the font. The TEXTMETRICOLE structure is defined as a TEXTMETRICW structure on Win32 platforms. For more information on this structure, consult the Platform SDK.

AddRefHfont

Notifies the font object that the previously realized font identified with hFont (obtained from IFont::get_hFont) should remain valid until IFont::ReleaseHfont is called or the font object itself is released completely.

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 to the font that describes the logical mapping mode.

TEXTMETRICOLE Structure

TYPE TEXTMETRICOLE
   tmHeight AS LONG
   tmAscent AS LONG
   tmDescent AS LONG
   tmInternalLeading AS LONG
   tmExternalLeading AS LONG
   tmAveCharWidth AS LONG
   tmMaxCharWidth AS LONG
   tmWeight AS LONG
   tmOverhang AS LONG
   tmDigitizedAspectX AS LONG
   tmDigitizedAspectY AS LONG
   tmFirstChar AS BYTE
   tmLastChar AS BYTE
   tmDefaultChar AS BYTE
   tmBreakChar AS BYTE
   tmItalic AS BYTE
   tmUnderlined AS BYTE
   tmStruckOut AS BYTE
   tmPitchAndFamily AS BYTE
   tmCharSet AS BYTE
END TYPE

GetName

FUNCTION IFont_GetName ( _

  BYVAL pthis AS DWORD PTR _

, BYREF pname AS STRING _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[3] USING IFont_GetName (pthis, pname) TO HRESULT

  pName = ACODE$(pName)
  FUNCTION = HRESULT

END FUNCTION

SetName

FUNCTION IFont_SetName ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pname AS STRING _

  ) AS LONG

  LOCAL HRESULT AS LONG
  pName = UCODE$(pName)
  CALL DWORD @@pthis[4] USING IFont_SetName (pthis, pname) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

GetSize

FUNCTION IFont_GetSize ( _

  BYVAL pthis AS DWORD PTR _

, BYREF psize AS CUR _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[5] USING IFont_GetSize (pthis, psize) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

SetSize

FUNCTION IFont_SetSize ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL psize AS CUR _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[6] USING IFont_SetSize (pthis, psize) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

GetBold

FUNCTION IFont_GetBold ( _

  BYVAL pthis AS DWORD PTR _

, BYREF pbold AS INTEGER _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[7] USING IFont_GetBold (pthis, pbold) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

SetBold

FUNCTION IFont_SetBold ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pbold AS INTEGER _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[8] USING IFont_SetBold (pthis, pbold) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

GetItalic

FUNCTION IFont_GetItalic ( _

  BYVAL pthis AS DWORD PTR _

, BYREF pitalic AS INTEGER _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[9] USING IFont_GetItalic (pthis, pitalic) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

SetItalic

FUNCTION IFont_SetItalic ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pitalic AS INTEGER _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[10] USING IFont_SetItalic (pthis, pitalic) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

GetUnderline

FUNCTION IFont_GetUnderline ( _

  BYVAL pthis AS DWORD PTR _

, BYREF punderline AS INTEGER _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[11] USING IFont_GetUnderline (pthis, punderline) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

SetUnderline

FUNCTION IFont_SetUnderline ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL punderline AS INTEGER _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[12] USING IFont_SetUnderline (pthis, punderline) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

GetStrikethorugh

FUNCTION IFont_GetStrikethrough ( _

  BYVAL pthis AS DWORD PTR _

, BYREF pstrikethrough AS INTEGER _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[13] USING IFont_GetStrikethrough (pthis, pstrikethrough) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

SetStrikethorugh

FUNCTION IFont_SetStrikethrough ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pstrikethrough AS INTEGER _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[14] USING IFont_SetStrikethrough (pthis, pstrikethrough) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

GetWeight

FUNCTION IFont_GetWeight ( _

  BYVAL pthis AS DWORD PTR _

, BYREF pweight AS INTEGER _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[15] USING IFont_GetWeight (pthis, pweight) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

SetWeight

FUNCTION IFont_SetWeight ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pweight AS INTEGER _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[16] USING IFont_SetWeight (pthis, pweight) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

GetCharset

FUNCTION IFont_GetCharset ( _

  BYVAL pthis AS DWORD PTR _

, BYREF pcharset AS INTEGER _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[17] USING IFont_GetCharset (pthis, pcharset) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

SetCharset

FUNCTION IFont_SetCharset ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pcharset AS INTEGER _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[18] USING IFont_SetCharset (pthis, pcharset) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

GethFont

FUNCTION IFont_GethFont ( _

  BYVAL pthis AS DWORD PTR _

, BYREF phfont AS LONG _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[19] USING IFont_GethFont (pthis, phfont) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

Clone

FUNCTION IFont_Clone ( _

  BYVAL pthis AS DWORD PTR _

, BYREF ppfont AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[20] USING IFont_Clone (pthis, ppfont) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

IsEqual

FUNCTION IFont_IsEqual ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pfontOther AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[21] USING IFont_IsEqual (pthis, pfontOther) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

SetRatio

FUNCTION IFont_SetRatio ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL cyLogical AS LONG _

, BYVAL cyHimetric AS LONG _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[22] USING IFont_SetRatio (pthis, cyLogical, cyHimetric) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

QueryTextMetrics

FUNCTION IFont_QueryTextMetrics ( _

  BYVAL pthis AS DWORD PTR _

, BYREF pTM AS TEXTMETRICOLE _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[23] USING IFont_QueryTextMetrics (pthis, pTM) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

AddRefHfont

FUNCTION IFont_AddRefHfont ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL hFont AS LONG _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[24] USING IFont_AddRefHfont (pthis, hFont) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

ReleaseHfont

FUNCTION IFont_ReleaseHfont ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL hFont AS LONG _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[25] USING IFont_ReleaseHfont (pthis, hFont) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

SetHdc

FUNCTION IFont_SetHdc ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL hDc AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[26] USING IFont_SetHdc (pthis, hDc) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

IFontDisp

This interface exposes a font object's properties through Automation. It provides a subset of the IFont methods.

The dispIDs for the various picture properties are the following:

DISPID_FONT_NAME = 0

DISPID_FONT_CHARSET = 8

Each property in the IFontDisp 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.

CreateFontIndirect

Creates a standard font object using OleCreateFontIndirect.

FUNCTION IFont_CreateFontIndirect ( _

  BYVAL strFontName AS STRING _

, BYVAL cySize AS CUR _

, BYVAL sWeight AS INTEGER _

, BYVAL sCharset AS INTEGER _

, BYVAL fItalic AS LONG _

, BYVAL fUnderline AS LONG _

, BYVAL fStrikethrough AS LONG _

, BYREF ppFont AS DWORD _

) AS LONG

  LOCAL udtFontDesc AS FONTDESC
  LOCAL riid AS GUID

  ' Use IUnknown to create an IFont object that can be

  ' manipulated using the IFont interface

  riid = GUID$("{00000000-0000-0000-c000-000000000046}")

  ' Use IDispatch to create an IFontDisp object

  ' that can be manipulated using Automation (Invoke)
'  riid = GUID$("{00020400-0000-0000-c000-000000000046}")
 

  strFontName = UCODE$(strFontName)
  udtFontDesc.cbSizeOfStruct = SIZEOF(FONTDESC)
  udtFontDesc.lpstrName = STRPTR(strFontName)
  udtFontDesc.cySize = cySize
  udtFontDesc.sWeight = sWeight
  udtFontDesc.sCharset = sCharset
  udtFontDesc.fItalic = fItalic
  udtFontDesc.fUnderline = fUnderline
  udtFontDesc.fStrikethrough = fStrikethrough
  FUNCTION = OleCreateFontIndirect (udtFontDesc, riid, ppFont)

END FUNCTION