IFont
COM公式ドキュメント
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_CHARSET、 DEFAULT_CHARSET、SYMBOL_CHARSET など。 |
| hFont | HFONT | get_hFont | レンダリングのためにデバイスコンテキストに選択できる Windows のフォントハンドル。 |
OLE 実装
システムは、基盤となるシステムのフォントサポート上に、 IFont インターフェイスを備えたフォントオブジェクトの標準実装を提供します。 フォントオブジェクトは、関数 OleCreateFontIndirect を通じて作成されます。フォントオブジェクトは、 IFont インターフェイスを通じて多数の読み取り/書き込みプロパティと一連のメソッドをサポートし、 さらに、Automation を通じてフォントのプロパティへのアクセスを提供するために IDispatch から派生した ディスパッチインターフェイス IFontDisp を通じて、 同じプロパティセット(ただしメソッドは除く)をサポートします。フォントオブジェクトのシステム実装は、 両方のインターフェイスを提供します。メソッド 24
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
フォントファミリーの名前を取得します。
| pName | LPWSTR* | out | 名前を受け取る、呼び出し側が確保した変数へのポインター。この文字列は不要になったら SysFreeString で解放する必要があります。 |
戻り値
このメソッドは、標準の戻り値 E_UNEXPECTED のほか、次の値をサポートします。
| 戻り値コード | 説明 |
|---|---|
| 名前が正常に返されました。 | |
| pname パラメーターのアドレスが無効です。たとえば NULL である可能性があります。 |
フォントファミリーの新しい名前を指定します。
| name | LPWSTR | in | フォントファミリーの新しい名前。この値の確保と解放は、 どちらも呼び出し側が行います。 |
戻り値
このメソッドは、標準の戻り値 E_UNEXPECTED のほか、 次の値をサポートします。
| 戻り値コード | 説明 |
|---|---|
| 名前が正常に変更されました。 | |
| name パラメーターのアドレスが無効です。たとえば NULL である可能性があります。 |
解説(Remarks)
フォントのポイントサイズを取得します。
| pSize | CY* | out | サイズを HIMETRIC 単位で受け取る、 呼び出し側が確保した変数へのポインター。 |
戻り値
このメソッドは、標準の戻り値 E_UNEXPECTED のほか、 次の値をサポートします。
| 戻り値コード | 説明 |
|---|---|
| サイズが正常に取得されました。 | |
| pSize パラメーターのアドレスが無効です。たとえば NULL である可能性があります。 |
フォントのポイントサイズを設定します。
| size | CY | in | フォントの新しいサイズ(HIMETRIC 単位)。 |
戻り値
このメソッドは、標準の戻り値 E_UNEXPECTED のほか、次の値をサポートします。
| 戻り値コード | 説明 |
|---|---|
| フォントのサイズが正常に変更されました。 | |
| size パラメーターの値が無効です。たとえば、使用可能なフォントサイズが含まれていません。 |
フォントの現在の Bold プロパティを取得します。
| pBold | BOOL* | out | フォントの現在の Bold プロパティを受け取る、 呼び出し側が確保した変数へのポインター。 |
戻り値
このメソッドは、次のいずれかの値を返すことがあります。
| 戻り値コード | 説明 |
|---|---|
| 状態が正常に取得されました。状態が不定の場合、フォントオブジェクトは *pBold を FALSE に設定し、S_OK を返す必要があります。 | |
| pBold のアドレスが無効です。たとえば NULL である可能性があります。 |
フォントの Bold プロパティを設定します。
| bold | BOOL | in | フォントの新しい Bold プロパティ。 |
戻り値
このメソッドは、次のいずれかの値を返すことがあります。
| 戻り値コード | 説明 |
|---|---|
| 太字の状態が正常に変更されました。 | |
| フォントが太字の状態をサポートしていません。これはエラー状態ではないことに注意してください。 |
解説(Remarks)
Bold プロパティを変更すると、Weight プロパティも変更される場合があります。Bold プロパティを TRUE に設定すると Weight プロパティが FW_BOLD(700)に設定され、 Bold プロパティを FALSE に設定すると Weight プロパティが FW_NORMAL(400)に設定されます。
フォントの現在の Italic プロパティを取得します。
| pItalic | BOOL* | out | フォントの現在の Italic プロパティを受け取る、呼び出し側が確保した変数へのポインター。 |
戻り値
このメソッドは、次のいずれかの値を返すことがあります。
| 戻り値コード | 説明 |
|---|---|
| 状態が正常に取得されました。状態が不定の場合、フォントオブジェクトは *pItalic を FALSE に設定し、 S_OK を返す必要があります。 | |
| pitalic のアドレスが無効です。たとえば NULL である可能性があります。 |
フォントの Italic プロパティを設定します。
| italic | BOOL | in | フォントの新しい Italic プロパティ。 |
戻り値
このメソッドは、次のいずれかの値を返すことがあります。
| 戻り値コード | 説明 |
|---|---|
| 斜体の状態が正常に変更されました。 | |
| フォントが斜体の状態をサポートしていません。この値はエラー状態ではありません。 |
フォントの現在の Underline プロパティを取得します。
| pUnderline | BOOL* | out | フォントの現在の Underline プロパティを受け取る、呼び出し側が確保した変数へのポインター。 |
戻り値
このメソッドは、次のいずれかの値を返すことがあります。
| 戻り値コード | 説明 |
|---|---|
| 状態が正常に取得されました。状態が不定の場合、フォントオブジェクトは *pUnderline を FALSE に設定し、 S_OK を返す必要があります。 | |
| pUnderline パラメーターのアドレスが無効です。たとえば NULL である可能性があります。 |
フォントの Underline プロパティを設定します。
| underline | BOOL | in | フォントの新しい Underline プロパティ。 |
戻り値
このメソッドは、次のいずれかの値を返すことがあります。
| 戻り値コード | 説明 |
|---|---|
| 下線の状態が正常に変更されました。 | |
| フォントが下線の状態をサポートしていません。この値はエラー状態ではありません。 |
フォントの現在の Strikethrough プロパティを取得します。
| pStrikethrough | BOOL* | out | フォントの現在の Strikethrough プロパティを受け取る、呼び出し側が確保した変数へのポインター。 |
戻り値
このメソッドは、次のいずれかの値を返すことがあります。
| 戻り値コード | 説明 |
|---|---|
| 状態が正常に取得されました。状態が不定の場合、フォントオブジェクトは *pStrikethrough を FALSE に設定し、 S_OK を返す必要があります。 | |
| pStrikethrough パラメーターのアドレスが無効です。たとえば NULL である可能性があります。 |
フォントの Strikethrough プロパティを設定します。
| strikethrough | BOOL | in | フォントの新しい Strikethrough プロパティ。 |
戻り値
このメソッドは、次のいずれかの値を返すことがあります。
| 戻り値コード | 説明 |
|---|---|
| Strikethrough プロパティが正常に変更されました。 | |
| フォントが取り消し線の状態をサポートしていません。この値はエラー状態ではありません。 |
フォントの現在の Weight プロパティを取得します。
| pWeight | SHORT* | out | フォントの現在の Weight プロパティを受け取る、呼び出し側が確保した変数へのポインター。指定可能な値の一覧については、LOGFONT 構造体の lfWeight メンバーを参照してください。 |
戻り値
このメソッドは、次のいずれかの値を返すことがあります。
| 戻り値コード | 説明 |
|---|---|
|
|
太さが正常に取得されました。太さが不定の場合、フォントオブジェクトは *pWeight に FW_NORMAL を格納し、S_OK を返す必要があります。 |
|
|
pWeight パラメーターのアドレスが無効です。たとえば NULL である可能性があります。 |
フォントの Weight プロパティを設定します。
| weight | SHORT | in | フォントの新しい Weight。利用可能なフォントの太さの一覧については、 LOGFONT 構造体の lfWeight メンバーの説明を参照してください。 |
戻り値
このメソッドは、次のいずれかの値を返すことがあります。
| 戻り値コード | 説明 |
|---|---|
| Weight プロパティが正常に変更されました。 | |
| このフォントは異なる太さをサポートしていません。この値はエラー状態ではありません。 |
解説(Remarks)
このプロパティは Bold プロパティにも影響する場合があります。Weight プロパティが FW_NORMAL(400)と FW_BOLD(700)の平均値、すなわち 550 より大きい場合、 Bold プロパティは TRUE に設定されます。
フォントで使用されている文字セットを取得します。
| pCharset | SHORT* | out | 文字セットの値を受け取る、呼び出し側が確保した変数への ポインター。 |
戻り値
このメソッドは、次のいずれかの値を返すことがあります。
| 戻り値コード | 説明 |
|---|---|
| 文字セットが正常に取得されました。 | |
| pCharset パラメーターのアドレスが無効です。たとえば NULL である可能性があります。 |
フォントの文字セットを設定します。
| charset | SHORT | in | フォントの新しい文字セット。 |
戻り値
このメソッドは、標準の戻り値 E_INVALIDARG と S_OK をサポートします。
このフォントオブジェクトが表すフォントへのハンドルを取得します。
| phFont | HFONT* | out | フォントハンドルを受け取る、呼び出し側が確保した変数へのポインター。 呼び出し側はこのリソースを所有せず、フォントを破棄しようとしてはなりません。 |
戻り値
このメソッドは、標準の戻り値 E_UNEXPECTED および E_OUTOFMEMORY のほか、次の値をサポートします。
| 戻り値コード | 説明 |
|---|---|
| フォントハンドルが正常に取得されました。 | |
| phFont パラメーターのアドレスが無効です。たとえば NULL である可能性があります。 |
解説(Remarks)
呼び出し側への注意
フォントオブジェクトは HFONT の所有権を保持し、事前の通知なしにいつでもそれを破棄できます。 呼び出し側が限られた期間このフォントを確保する必要がある場合は、 IFont::AddRefHfont と IFont::ReleaseHfont を呼び出すことができます。フォントオブジェクトの複製を作成します。
| ppFont | IFont** | out | 新しいフォントオブジェクトへのインターフェイスポインターを受け取る IFont ポインター変数のアドレス。呼び出し側は、 この新しいフォントオブジェクトが不要になったときに IFont::Release を呼び出す必要があります。 |
戻り値
このメソッドは、標準の戻り値 E_UNEXPECTED および E_OUTOFMEMORY のほか、次の値をサポートします。
| 戻り値コード | 説明 |
|---|---|
| 新しいフォントオブジェクトが正常に作成されました。 | |
| このフォントオブジェクトは複製をサポートしていません。 | |
| ppfont のアドレスが無効です。たとえば NULL である可能性があります。 |
解説(Remarks)
呼び出し側への注意
新しいフォントオブジェクトは、元のオブジェクトから完全に独立しています。呼び出し側は、この新しい オブジェクトが不要になったときにそれを解放する責任を負います。このメソッドは、複製元のフォントの参照カウントには影響しません。このフォントオブジェクトを別のフォントオブジェクトと比較して、同等かどうかを判定します。
| pFontOther | IFont* | in | このフォントと比較するフォントオブジェクトの IFont インターフェイスへのポインター。このポインターが参照するオブジェクトの参照カウントは、比較操作の影響を受けません。 |
戻り値
このメソッドは、標準の戻り値 E_UNEXPECTED のほか、 次の値をサポートします。
| 戻り値コード | 説明 |
|---|---|
| 2 つのフォントは同等です。 | |
| 2 つのフォントは同等ではありません。 | |
| pFontOther パラメーターのアドレスが無効です。たとえば NULL である可能性があります。 |
このフォントの論理単位と HIMETRIC 単位との間のスケーリング係数を変換します。
| cyLogical | INT | in | フォントサイズ(論理単位)。 |
| cyHimetric | INT | in | フォントサイズ(HIMETRIC 単位)。 |
戻り値
このメソッドは、標準の戻り値 E_UNEXPECTED、E_INVALIDARG、および S_OK をサポートします。
呼び出し側が確保した構造体に、フォントに関する情報を格納します。
| pTM | TEXTMETRICW* | out | フォント情報を受け取る、呼び出し側が確保した構造体へのポインター。 TEXTMETRICOLE 構造体は TEXTMETRICW 構造体として定義されています。 |
戻り値
このメソッドは、標準の戻り値 E_UNEXPECTED のほか、 次の値をサポートします。
| 戻り値コード | 説明 |
|---|---|
| テキストメトリックが正常に返されました。 | |
| ptm パラメーターのアドレスが無効です。たとえば NULL である可能性があります。 |
解説(Remarks)
実装者への注意
E_NOTIMPL は有効な戻り値ではありません。フォントオブジェクトは、他のエラーが発生しない限り、 この呼び出しを通じて常にフォント情報を提供しなければなりません。hFont で識別される、以前に実体化されたフォントを、ReleaseHfont が呼び出されるか、またはフォントオブジェクト自体が完全に解放されるまで有効な状態に保つよう、フォントオブジェクトに通知します。
| hFont | HFONT | in | フォントオブジェクトのキャッシュ内でロックする、get_hFont を通じて以前に実体化されたフォントハンドル。 |
戻り値
このメソッドは、標準の戻り値 E_UNEXPECTED および E_INVALIDARG のほか、次の値をサポートします。
| 戻り値コード | 説明 |
|---|---|
| フォントがキャッシュ内で正常にロックされました。 |
IFont::AddRefHfont で以前にこのフォントをキャッシュ内にロックした呼び出し側が、そのロックを必要としなくなったことをフォントオブジェクトに通知します。
| hFont | HFONT | in | IFont::get_hFont を通じて以前に実体化されたフォントハンドル。 この値は、フォントをロックするために IFont::AddRefHfont への以前の 呼び出しに渡されたものであり、呼び出し側は、キャッシュ内のこのフォントのロックを解除しようとしています。 |
戻り値
このメソッドは、標準の戻り値 E_UNEXPECTED および E_INVALIDARG のほか、次の値をサポートします。
| 戻り値コード | 説明 |
|---|---|
| フォントが正常にロック解除されました。 | |
| フォントはキャッシュ内でロックされていませんでした。この戻り値は、フォントの参照カウントに問題がある 可能性があることを呼び出し側に知らせる、無害な通知です。 |
論理マッピングモードを記述するデバイスコンテキストをフォントに提供します。
| hDC | HDC | in | フォントを選択するデバイスコンテキストへのハンドル。 |
戻り値
このメソッドは、標準の戻り値 E_INVALIDARG のほか、 次の値をサポートします。
| 戻り値コード | 説明 |
|---|---|
| フォントが正常に選択されました。 | |
| このフォントオブジェクトではフォントの選択がサポートされていません。 |
解説(Remarks)
論理マッピングモードは、フォントのポイントサイズの内部計算に影響します。これにより、呼び出し側が IFont::get_hFont を呼び出してフォントハンドルを要求したときに、 フォントはすでにデバイスコンテキストに合わせて適切にスケーリングされています。
呼び出し側への注意
呼び出し側はこのデバイスコンテキストの所有権を保持し、フォントオブジェクトが存続する間、それは有効で なければなりません。したがって、渡すデバイスコンテキストは、(関数 CreateCompatibleDC による)メモリデバイスコンテキストであるべきであり、 画面デバイスコンテキスト(CreateDC、 GetDC、 または BeginPaint による)であってはなりません。画面デバイスコンテキストは限られたシステム リソースだからです。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 指定が可能。#define global IID_IFont "{BEF6E002-A874-101A-8BBA-00AA00300CAB}" #usecom global IFont IID_IFont "{}" #comfunc global IFont_get_Name 3 sptr #comfunc global IFont_put_Name 4 wstr #comfunc global IFont_get_Size 5 sptr #comfunc global IFont_put_Size 6 int #comfunc global IFont_get_Bold 7 sptr #comfunc global IFont_put_Bold 8 int #comfunc global IFont_get_Italic 9 sptr #comfunc global IFont_put_Italic 10 int #comfunc global IFont_get_Underline 11 sptr #comfunc global IFont_put_Underline 12 int #comfunc global IFont_get_Strikethrough 13 sptr #comfunc global IFont_put_Strikethrough 14 int #comfunc global IFont_get_Weight 15 sptr #comfunc global IFont_put_Weight 16 int #comfunc global IFont_get_Charset 17 sptr #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 sptr #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が無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。