Win32 API 日本語リファレンス
ホームSystem.Ole › IFont

IFont

COM
IIDbef6e002-a874-101a-8bba-00aa00300cab継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

Windows のフォントオブジェクトのラッパーを提供します。

解説(Remarks)

IFont インターフェイスの各プロパティには、そのプロパティが読み取りアクセスをサポートする場合は get_PropertyName メソッドが、書き込みアクセスをサポートする場合は put_PropertyName メソッドが 含まれます。これらのプロパティのほとんどは、読み取りと書き込みの両方のアクセスをサポートします。

プロパティ 読み取りアクセスメソッド 書き込みアクセスメソッド 説明
Name BSTR get_Name put_Name フォントのフェイス名(例: Arial)。
Size CY get_Size put_Size フォントのポイントサイズ。小数のポイントサイズを扱えるよう CY 型で表現されます。
Bold BOOL get_Bold put_Bold フォントが太字かどうかを示します。
Italic BOOL get_Italic put_Italic フォントが斜体かどうかを示します。
Underline BOOL get_Underline put_Underline フォントに下線が付いているかどうかを示します。
Strikethrough BOOL get_Strikethrough put_Strikethrough フォントに取り消し線が付いているかどうかを示します。
Weight short get_Weight put_Weight フォントの太さ。
Charset short get_Charset put_Charset フォントで使用される文字セット。ANSI_CHARSETDEFAULT_CHARSETSYMBOL_CHARSET など。
hFont HFONT get_hFont レンダリングのためにデバイスコンテキストに選択できる Windows のフォントハンドル。

OLE 実装

システムは、基盤となるシステムのフォントサポート上に、 IFont インターフェイスを備えたフォントオブジェクトの標準実装を提供します。 フォントオブジェクトは、関数 OleCreateFontIndirect を通じて作成されます。フォントオブジェクトは、 IFont インターフェイスを通じて多数の読み取り/書き込みプロパティと一連のメソッドをサポートし、 さらに、Automation を通じてフォントのプロパティへのアクセスを提供するために IDispatch から派生した ディスパッチインターフェイス IFontDisp を通じて、 同じプロパティセット(ただしメソッドは除く)をサポートします。フォントオブジェクトのシステム実装は、 両方のインターフェイスを提供します。

メソッド 24

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT get_Name(LPWSTR* pName)

フォントファミリーの名前を取得します。

pNameLPWSTR*out名前を受け取る、呼び出し側が確保した変数へのポインター。この文字列は不要になったら SysFreeString で解放する必要があります。

戻り値

このメソッドは、標準の戻り値 E_UNEXPECTED のほか、次の値をサポートします。

戻り値コード 説明
S_OK
名前が正常に返されました。
E_POINTER
pname パラメーターのアドレスが無効です。たとえば NULL である可能性があります。
vtbl 4 HRESULT put_Name(LPWSTR name)

フォントファミリーの新しい名前を指定します。

nameLPWSTRinフォントファミリーの新しい名前。この値の確保と解放は、 どちらも呼び出し側が行います。

戻り値

このメソッドは、標準の戻り値 E_UNEXPECTED のほか、 次の値をサポートします。

戻り値コード 説明
S_OK
名前が正常に変更されました。
E_POINTER
name パラメーターのアドレスが無効です。たとえば NULL である可能性があります。

解説(Remarks)

呼び出し側への注意

文字列の値は呼び出し側が確保します。この呼び出しが返った後、呼び出し側がその解放に責任を負います。
vtbl 5 HRESULT get_Size(CY* pSize)

フォントのポイントサイズを取得します。

pSizeCY*outサイズを HIMETRIC 単位で受け取る、 呼び出し側が確保した変数へのポインター。

戻り値

このメソッドは、標準の戻り値 E_UNEXPECTED のほか、 次の値をサポートします。

戻り値コード 説明
S_OK
サイズが正常に取得されました。
E_POINTER
pSize パラメーターのアドレスが無効です。たとえば NULL である可能性があります。
vtbl 6 HRESULT put_Size(CY size)

フォントのポイントサイズを設定します。

sizeCYinフォントの新しいサイズ(HIMETRIC 単位)。

戻り値

このメソッドは、標準の戻り値 E_UNEXPECTED のほか、次の値をサポートします。

戻り値コード 説明
S_OK
フォントのサイズが正常に変更されました。
E_POINTER
size パラメーターの値が無効です。たとえば、使用可能なフォントサイズが含まれていません。
vtbl 7 HRESULT get_Bold(BOOL* pBold)

フォントの現在の Bold プロパティを取得します。

pBoldBOOL*outフォントの現在の Bold プロパティを受け取る、 呼び出し側が確保した変数へのポインター。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

戻り値コード 説明
S_OK
状態が正常に取得されました。状態が不定の場合、フォントオブジェクトは *pBoldFALSE に設定し、S_OK を返す必要があります。
E_POINTER
pBold のアドレスが無効です。たとえば NULL である可能性があります。
vtbl 8 HRESULT put_Bold(BOOL bold)

フォントの Bold プロパティを設定します。

boldBOOLinフォントの新しい Bold プロパティ。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

戻り値コード 説明
S_OK
太字の状態が正常に変更されました。
S_FALSE
フォントが太字の状態をサポートしていません。これはエラー状態ではないことに注意してください。

解説(Remarks)

Bold プロパティを変更すると、Weight プロパティも変更される場合があります。Bold プロパティを TRUE に設定すると Weight プロパティが FW_BOLD(700)に設定され、 Bold プロパティを FALSE に設定すると Weight プロパティが FW_NORMAL(400)に設定されます。

vtbl 9 HRESULT get_Italic(BOOL* pItalic)

フォントの現在の Italic プロパティを取得します。

pItalicBOOL*outフォントの現在の Italic プロパティを受け取る、呼び出し側が確保した変数へのポインター。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

戻り値コード 説明
S_OK
状態が正常に取得されました。状態が不定の場合、フォントオブジェクトは *pItalicFALSE に設定し、 S_OK を返す必要があります。
E_POINTER
pitalic のアドレスが無効です。たとえば NULL である可能性があります。
vtbl 10 HRESULT put_Italic(BOOL italic)

フォントの Italic プロパティを設定します。

italicBOOLinフォントの新しい Italic プロパティ。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

戻り値コード 説明
S_OK
斜体の状態が正常に変更されました。
S_FALSE
フォントが斜体の状態をサポートしていません。この値はエラー状態ではありません。
vtbl 11 HRESULT get_Underline(BOOL* pUnderline)

フォントの現在の Underline プロパティを取得します。

pUnderlineBOOL*outフォントの現在の Underline プロパティを受け取る、呼び出し側が確保した変数へのポインター。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

戻り値コード 説明
S_OK
状態が正常に取得されました。状態が不定の場合、フォントオブジェクトは *pUnderlineFALSE に設定し、 S_OK を返す必要があります。
E_POINTER
pUnderline パラメーターのアドレスが無効です。たとえば NULL である可能性があります。
vtbl 12 HRESULT put_Underline(BOOL underline)

フォントの Underline プロパティを設定します。

underlineBOOLinフォントの新しい Underline プロパティ。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

戻り値コード 説明
S_OK
下線の状態が正常に変更されました。
S_FALSE
フォントが下線の状態をサポートしていません。この値はエラー状態ではありません。
vtbl 13 HRESULT get_Strikethrough(BOOL* pStrikethrough)

フォントの現在の Strikethrough プロパティを取得します。

pStrikethroughBOOL*outフォントの現在の Strikethrough プロパティを受け取る、呼び出し側が確保した変数へのポインター。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

戻り値コード 説明
S_OK
状態が正常に取得されました。状態が不定の場合、フォントオブジェクトは *pStrikethroughFALSE に設定し、 S_OK を返す必要があります。
E_POINTER
pStrikethrough パラメーターのアドレスが無効です。たとえば NULL である可能性があります。
vtbl 14 HRESULT put_Strikethrough(BOOL strikethrough)

フォントの Strikethrough プロパティを設定します。

strikethroughBOOLinフォントの新しい Strikethrough プロパティ。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

戻り値コード 説明
S_OK
Strikethrough プロパティが正常に変更されました。
S_FALSE
フォントが取り消し線の状態をサポートしていません。この値はエラー状態ではありません。
vtbl 15 HRESULT get_Weight(SHORT* pWeight)

フォントの現在の Weight プロパティを取得します。

pWeightSHORT*outフォントの現在の Weight プロパティを受け取る、呼び出し側が確保した変数へのポインター。指定可能な値の一覧については、LOGFONT 構造体の lfWeight メンバーを参照してください。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

戻り値コード 説明
太さが正常に取得されました。太さが不定の場合、フォントオブジェクトは *pWeightFW_NORMAL を格納し、S_OK を返す必要があります。
pWeight パラメーターのアドレスが無効です。たとえば NULL である可能性があります。
vtbl 16 HRESULT put_Weight(SHORT weight)

フォントの Weight プロパティを設定します。

weightSHORTinフォントの新しい Weight。利用可能なフォントの太さの一覧については、 LOGFONT 構造体の lfWeight メンバーの説明を参照してください。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

戻り値コード 説明
S_OK
Weight プロパティが正常に変更されました。
S_FALSE
このフォントは異なる太さをサポートしていません。この値はエラー状態ではありません。

解説(Remarks)

このプロパティは Bold プロパティにも影響する場合があります。Weight プロパティが FW_NORMAL(400)と FW_BOLD(700)の平均値、すなわち 550 より大きい場合、 Bold プロパティは TRUE に設定されます。

vtbl 17 HRESULT get_Charset(SHORT* pCharset)

フォントで使用されている文字セットを取得します。

pCharsetSHORT*out文字セットの値を受け取る、呼び出し側が確保した変数への ポインター。

戻り値

このメソッドは、次のいずれかの値を返すことがあります。

戻り値コード 説明
S_OK
文字セットが正常に取得されました。
E_POINTER
pCharset パラメーターのアドレスが無効です。たとえば NULL である可能性があります。
vtbl 18 HRESULT put_Charset(SHORT charset)

フォントの文字セットを設定します。

charsetSHORTinフォントの新しい文字セット。

戻り値

このメソッドは、標準の戻り値 E_INVALIDARGS_OK をサポートします。

vtbl 19 HRESULT get_hFont(HFONT* phFont)

このフォントオブジェクトが表すフォントへのハンドルを取得します。

phFontHFONT*outフォントハンドルを受け取る、呼び出し側が確保した変数へのポインター。 呼び出し側はこのリソースを所有せず、フォントを破棄しようとしてはなりません。

戻り値

このメソッドは、標準の戻り値 E_UNEXPECTED および E_OUTOFMEMORY のほか、次の値をサポートします。

戻り値コード 説明
S_OK
フォントハンドルが正常に取得されました。
E_POINTER
phFont パラメーターのアドレスが無効です。たとえば NULL である可能性があります。

解説(Remarks)

呼び出し側への注意

フォントオブジェクトは HFONT の所有権を保持し、事前の通知なしにいつでもそれを破棄できます。 呼び出し側が限られた期間このフォントを確保する必要がある場合は、 IFont::AddRefHfontIFont::ReleaseHfont を呼び出すことができます。
vtbl 20 HRESULT Clone(IFont** ppFont)

フォントオブジェクトの複製を作成します。

ppFontIFont**out新しいフォントオブジェクトへのインターフェイスポインターを受け取る IFont ポインター変数のアドレス。呼び出し側は、 この新しいフォントオブジェクトが不要になったときに IFont::Release を呼び出す必要があります。

戻り値

このメソッドは、標準の戻り値 E_UNEXPECTED および E_OUTOFMEMORY のほか、次の値をサポートします。

戻り値コード 説明
S_OK
新しいフォントオブジェクトが正常に作成されました。
E_NOTIMPL
このフォントオブジェクトは複製をサポートしていません。
E_POINTER
ppfont のアドレスが無効です。たとえば NULL である可能性があります。

解説(Remarks)

呼び出し側への注意

新しいフォントオブジェクトは、元のオブジェクトから完全に独立しています。呼び出し側は、この新しい オブジェクトが不要になったときにそれを解放する責任を負います。このメソッドは、複製元のフォントの参照カウントには影響しません。
vtbl 21 HRESULT IsEqual(IFont* pFontOther)

このフォントオブジェクトを別のフォントオブジェクトと比較して、同等かどうかを判定します。

pFontOtherIFont*inこのフォントと比較するフォントオブジェクトの IFont インターフェイスへのポインター。このポインターが参照するオブジェクトの参照カウントは、比較操作の影響を受けません。

戻り値

このメソッドは、標準の戻り値 E_UNEXPECTED のほか、 次の値をサポートします。

戻り値コード 説明
S_OK
2 つのフォントは同等です。
S_FALSE
2 つのフォントは同等ではありません。
E_POINTER
pFontOther パラメーターのアドレスが無効です。たとえば NULL である可能性があります。
vtbl 22 HRESULT SetRatio(INT cyLogical, INT cyHimetric)

このフォントの論理単位と HIMETRIC 単位との間のスケーリング係数を変換します。

cyLogicalINTinフォントサイズ(論理単位)。
cyHimetricINTinフォントサイズ(HIMETRIC 単位)。

戻り値

このメソッドは、標準の戻り値 E_UNEXPECTEDE_INVALIDARG、および S_OK をサポートします。

vtbl 23 HRESULT QueryTextMetrics(TEXTMETRICW* pTM)

呼び出し側が確保した構造体に、フォントに関する情報を格納します。

pTMTEXTMETRICW*outフォント情報を受け取る、呼び出し側が確保した構造体へのポインター。 TEXTMETRICOLE 構造体は TEXTMETRICW 構造体として定義されています。

戻り値

このメソッドは、標準の戻り値 E_UNEXPECTED のほか、 次の値をサポートします。

戻り値コード 説明
S_OK
テキストメトリックが正常に返されました。
E_POINTER
ptm パラメーターのアドレスが無効です。たとえば NULL である可能性があります。

解説(Remarks)

実装者への注意

E_NOTIMPL は有効な戻り値ではありません。フォントオブジェクトは、他のエラーが発生しない限り、 この呼び出しを通じて常にフォント情報を提供しなければなりません。
vtbl 24 HRESULT AddRefHfont(HFONT hFont)

hFont で識別される、以前に実体化されたフォントを、ReleaseHfont が呼び出されるか、またはフォントオブジェクト自体が完全に解放されるまで有効な状態に保つよう、フォントオブジェクトに通知します。

hFontHFONTinフォントオブジェクトのキャッシュ内でロックする、get_hFont を通じて以前に実体化されたフォントハンドル。

戻り値

このメソッドは、標準の戻り値 E_UNEXPECTED および E_INVALIDARG のほか、次の値をサポートします。

戻り値コード 説明
S_OK
フォントがキャッシュ内で正常にロックされました。
vtbl 25 HRESULT ReleaseHfont(HFONT hFont)

IFont::AddRefHfont で以前にこのフォントをキャッシュ内にロックした呼び出し側が、そのロックを必要としなくなったことをフォントオブジェクトに通知します。

hFontHFONTinIFont::get_hFont を通じて以前に実体化されたフォントハンドル。 この値は、フォントをロックするために IFont::AddRefHfont への以前の 呼び出しに渡されたものであり、呼び出し側は、キャッシュ内のこのフォントのロックを解除しようとしています。

戻り値

このメソッドは、標準の戻り値 E_UNEXPECTED および E_INVALIDARG のほか、次の値をサポートします。

戻り値コード 説明
S_OK
フォントが正常にロック解除されました。
S_FALSE
フォントはキャッシュ内でロックされていませんでした。この戻り値は、フォントの参照カウントに問題がある 可能性があることを呼び出し側に知らせる、無害な通知です。
vtbl 26 HRESULT SetHdc(HDC hDC)

論理マッピングモードを記述するデバイスコンテキストをフォントに提供します。

hDCHDCinフォントを選択するデバイスコンテキストへのハンドル。

戻り値

このメソッドは、標準の戻り値 E_INVALIDARG のほか、 次の値をサポートします。

戻り値コード 説明
S_OK
フォントが正常に選択されました。
E_NOTIMPL
このフォントオブジェクトではフォントの選択がサポートされていません。

解説(Remarks)

論理マッピングモードは、フォントのポイントサイズの内部計算に影響します。これにより、呼び出し側が IFont::get_hFont を呼び出してフォントハンドルを要求したときに、 フォントはすでにデバイスコンテキストに合わせて適切にスケーリングされています。

呼び出し側への注意

呼び出し側はこのデバイスコンテキストの所有権を保持し、フォントオブジェクトが存続する間、それは有効で なければなりません。したがって、渡すデバイスコンテキストは、(関数 CreateCompatibleDC による)メモリデバイスコンテキストであるべきであり、 画面デバイスコンテキスト(CreateDCGetDC、 または BeginPaint による)であってはなりません。画面デバイスコンテキストは限られたシステム リソースだからです。
出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"

出力引数:
#define global IID_IFont "{BEF6E002-A874-101A-8BBA-00AA00300CAB}"
#usecom global IFont IID_IFont "{}"
#comfunc global IFont_get_Name           3 var
#comfunc global IFont_put_Name           4 wstr
#comfunc global IFont_get_Size           5 var
#comfunc global IFont_put_Size           6 int
#comfunc global IFont_get_Bold           7 var
#comfunc global IFont_put_Bold           8 int
#comfunc global IFont_get_Italic         9 var
#comfunc global IFont_put_Italic         10 int
#comfunc global IFont_get_Underline      11 var
#comfunc global IFont_put_Underline      12 int
#comfunc global IFont_get_Strikethrough  13 var
#comfunc global IFont_put_Strikethrough  14 int
#comfunc global IFont_get_Weight         15 var
#comfunc global IFont_put_Weight         16 int
#comfunc global IFont_get_Charset        17 var
#comfunc global IFont_put_Charset        18 int
#comfunc global IFont_get_hFont          19 sptr
#comfunc global IFont_Clone              20 sptr
#comfunc global IFont_IsEqual            21 sptr
#comfunc global IFont_SetRatio           22 int,int
#comfunc global IFont_QueryTextMetrics   23 var
#comfunc global IFont_AddRefHfont        24 sptr
#comfunc global IFont_ReleaseHfont       25 sptr
#comfunc global IFont_SetHdc             26 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。