1
<?xml version="1.0" encoding="UTF-8" ?>
3
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5
<html xmlns="http://www.w3.org/1999/xhtml" lang="ja" xml:lang="ja">
7
<meta http-equiv="Content-type" content="text/html; charset=UTF-8" />
8
<title>Cairo::UserFontFaceクラス</title>
9
<link href="../doc.css" type="text/css" rel="stylesheet" />
13
<li><a href="./">索引</a></li>
19
<h1><a name="label-0" id="label-0">Cairo::UserFontFaceクラス</a></h1><!-- RDLabel: "Cairo::UserFontFaceクラス" -->
20
<p><em>Since 1.7</em>: ユーザが独自のフォントを使うためのフォント
22
<p>on_XXXメソッドでコールバックを登録する方法と
23
<a href="cairo-user-font-face.html">Cairo::UserFontFace</a>を継承して、そのクラスにコールバック用のメ
25
<p>継承した場合のコールバック用メソッドの名前はon_XXXメソッドか
26
ら「on_」を除いた部分です。例えば、on_initに対応するメソッド
27
名はinitです。引数は同じです。以下は継承する例です。
28
render_glyph以外は定義しなくてもかまいません。</p>
29
<pre>class CustomUserFontFace < Cairo::UserFontFace
30
def init(scaled_font, context, font_extents)
33
def render_glyph(scaled_font, glyph, context, text_extents)
36
def text_to_glyphs(scaled_font, utf8, data)
39
def unicode_to_glyph(scaled_font, unicode)
42
<h2><a name="label-1" id="label-1">オブジェクト階層</a></h2><!-- RDLabel: "オブジェクト階層" -->
46
<li><a href="cairo-font-face.html">Cairo::FontFace</a>
48
<li>Cairo::UserFontFace</li>
52
<h2><a name="label-2" id="label-2">クラスメソッド</a></h2><!-- RDLabel: "クラスメソッド" -->
54
<dt><a name="label-3" id="label-3"><code>Cairo::UserFontFace.new</code></a></dt><!-- RDLabel: "Cairo::UserFontFace.new" -->
56
<p><em>Since 1.7</em>: 新しくCario::UserFontFaceオブジェクト
58
<p>オブジェクトを生成したら、on_XXXメソッドでコールバック
60
<a href="cairo-user-font-face.html#label-6">Cairo::UserFontFace#on_render_glyph</a>です。それ以外のコー
62
<p>継承して利用する場合、そのクラスのメソッドよりもon_XXX
63
メソッドで登録したコールバックの方が優先されます。</p>
65
<li>戻り値: 新しく生成したCario::UserFontFaceオブジェク
69
<h2><a name="label-4" id="label-4">インタンスメソッド</a></h2><!-- RDLabel: "インタンスメソッド" -->
71
<dt><a name="label-5" id="label-5"><code>on_init {|<var>scaled_font</var>, <var>context</var>, <var>font_extents</var>| ...}</code></a></dt><!-- RDLabel: "on_init" -->
73
<p><em>Since 1.7</em>: 拡大・縮小したフォントを初期化するコー
74
ルバックを登録します。このコールバックは省略可能です。</p>
75
<p><var>context</var>は呼び出し元では使われませんが、フォント空
77
<a href="cairo-user-font-face.html#label-6">Cairo::UserFontFace#on_render_glyph</a>で登録するコールバッ
78
クに渡される<var>context</var>と同様です。コールバック中では
79
この<a href="cairo-context.html">Cairo::Context</a>をフォントの範囲を計算するために使う
81
<p><var>font_extents</var>には<var>scaled_font</var>用のフォントの範
82
囲を設定します。座標はフォント空間です。そのため、多く
83
の場合は<a href="cairo-font-extents.html#label-5">Cairo::FontExtents#ascent</a>と
84
<a href="cairo-font-extents.html#label-8">Cairo::FontExtents#descent</a>に1.0を足す必要があります。
85
<var>font_extents</var>は以下のように初期化されています。</p>
90
<li>max_x_advance: 1.0</li>
91
<li>max_y_advance: 0.0</li>
93
<p>このコールバックを指定しなかった場合は上記のデフォルト
95
<p>注: <var>scaled_font</var>はこの時点では完全には初期化されて
96
いません。そのため、コールバック中でテキスト操作を行う
99
<a href="cairo-user-font-error.html">Cairo::UserFontError</a>例外、あるいは問題に対応する例外を
102
<li>scaled_font: 生成中の拡大・縮小したフォント。
103
（<a href="cairo-scaled-font.html">Cairo::ScaledFont</a>）</li>
104
<li>context: <a href="cairo-context.html">Cairo::Context</a>。座標はフォント空間。</li>
105
<li>font_extents: 設定するフォントの範囲
106
（<a href="cairo-font-extents.html">Cairo::FontExtents</a>）。座標はフォント空間。</li>
108
<dt><a name="label-6" id="label-6"><code>on_render_glyph {|<var>scaled_font</var>, <var>glyph</var>, <var>context</var>, <var>text_extents</var>| ...}</code></a></dt><!-- RDLabel: "on_render_glyph" -->
110
<p><em>Since 1.7</em>: グリフ描画コールバックを登録します。こ
111
のコールバックが唯一必須のコールバックです。</p>
112
<p>コードが<var>glyph</var>のグリフを<var>context</var>に描画してく
113
ださい。<var>context</var>はグリフ描画がフォント空間の座標で
114
行われるように準備されています。つまり、<var>context</var>に
115
設定されている変換行列は<var>scaled_font</var>の拡大・縮小行
117
<p><var>text_extents</var>には<var>scaled_font</var>のフォントの範囲
118
を設定してください。しかし、もし、ユーザ空間座標で描画
119
したい場合は<var>context</var>の変換行列を設定してください。
120
すべての<var>context</var>に対する操作は許可されていますが、
121
もし、<var>context</var>のデフォルトソース以外のソースが使わ
122
れた場合の動作は未定義です。つまり、グリフのビットマッ
123
プは<a href="cairo-context.html#label-82">Cairo::Context#paint</a>ではなく<a href="cairo-context.html#label-68">Cairo::Context#mask</a>で描
125
<p>他のデフォルトではない<var>context</var>の設定は以下の通り
128
<li>フォントサイズが1.0である（座標がフォント空間に設定
130
<li>フォントオプションの設定が<var>scaled_font</var>に対応し
133
<p><var>text_extents</var>は以下のように設定されています。</p>
135
<li>x_bearing: 0.0</li>
136
<li>y_bearing: -font_extents.ascent</li>
138
<li>height: font_extents.ascent + font_extents.descent</li>
139
<li>x_advance: font_extents.max_x_advance</li>
140
<li>y_advance: 0.0</li>
142
<p>多くの場合、設定しなければいけない項目はx_advanceだけで
143
す。もし、コールバックの後でもwidthが0（デフォルト値）
144
のままだった場合は、グリフの範囲は<var>context</var>への描画
145
操作を元に自動的に計算されます。多くの場合、これは望ま
146
れた動作です。しかし、もし、コールバックがグリフの範囲
147
を設定する理由がある場合は、インクで塗る部分のグリフの
148
範囲を設定してください。また、その範囲はコールバック中
149
で<var>context</var>に描画したものすべてを含むようにしてくだ
151
<p>コールバック中で問題が発生した場合は
152
<a href="cairo-user-font-error.html">Cairo::UserFontError</a>例外、あるいは問題に対応する例外を
155
<li>scaled_font: ユーザ用の拡大・縮小したフォント。
156
（<a href="cairo-scaled-font.html">Cairo::ScaledFont</a>）</li>
157
<li>glyph: 描画するグリフコード（Integer）</li>
158
<li>context: <a href="cairo-context.html">Cairo::Context</a>。座標はフォント空間。</li>
159
<li>text_extents: 設定するグリフの範囲</li>
161
<p>（<a href="cairo-text-extents.html">Cairo::TextExtents</a>）。座標はフォント空間。</p></dd>
162
<dt><a name="label-7" id="label-7"><code>on_text_to_glyphs {|<var>scaled_font</var>, <var>utf8</var>, <var>data</var>| ...}</code></a></dt><!-- RDLabel: "on_text_to_glyphs" -->
164
<p><em>Since 1.7</em>: テキストをグリフに変換するコールバック
165
を登録します。このコールバックは省略可能です。</p>
166
<p>このコールバックは<a href="cairo-context.html#label-110">Cairo::Context#show_text</a>のときに使わ
168
<p>このコールバックを使うとき、ユーザフォントはグリフとそ
169
の位置をすべて制御できます。つまり、リガチャ、カーニン
170
グといった機能や、アラビア語やインド語のような文字体系
171
が要求するような複雑な形を実現できます。</p>
172
<p>変換した結果は<var>data</var>に設定します。</p>
174
<a href="cairo-user-font-face-text-to-glyphs-data.html#label-13">data.need_glyphs?</a>
175
が<code>true</code>の場合は
176
<a href="cairo-user-font-face-text-to-glyphs-data.html#label-12">data.glyphs=</a>
177
で計算したグリフのインデックスと位置を設定します。グリ
178
フの位置はフォント空間座標です。テキストは起点から表示
181
<a href="cairo-user-font-face-text-to-glyphs-data.html#label-10">data.need_clusters?</a>
182
が<code>true</code>の場合は
183
<a href="cairo-user-font-face-text-to-glyphs-data.html#label-9">data.clusters=</a>
184
で計算したクラスタ対応情報を設定します。</p>
185
<p>もし、このコールバックが省略されているか
186
<a href="cairo-user-font-face-text-to-glyphs-data.html#label-11">data.glyphs</a>
187
が<code>nil</code>の場合は
188
<a href="cairo-user-font-face.html#label-8">Cairo::UserFontFace#on_unicode_to_glyph</a>が呼ばれます。</p>
189
<p>注: cairoはグリフのインデックス付けには制限を設けていま
190
せんが、いくつかのアプリケーションはグリフのインデック
191
スは16ビットの符号無し整数に収まると仮定しています。そ
192
のため、ユーザフォントはグリフの範囲を0から65535の範囲
193
に収めるようにするとよいでしょう。さらに、いくつかのアプ
194
リケーションは0番目のグリフは「グリフがない」という特別
195
なグリフと仮定しているかもしれません。ユーザフォントは0
196
番目のグリフをそのような目的として使い、他の目的には使
198
<p>コールバック中で問題が発生した場合は
199
<a href="cairo-user-font-error.html">Cairo::UserFontError</a>例外、あるいは問題に対応する例外を
202
<li>scaled_font: ユーザ用の拡大・縮小したフォント。
203
（<a href="cairo-scaled-font.html">Cairo::ScaledFont</a>）</li>
204
<li>utf8: UTF-8で符号化されたテキスト</li>
205
<li>data: 変換結果を保存するオブジェクト
206
（<a href="cairo-user-font-face-text-to-glyphs-data.html">Cairo::UserFontFace::TextToGlyphsData</a>）</li>
208
<dt><a name="label-8" id="label-8"><code>on_unicode_to_glyph {|<var>scaled_font</var>, <var>unicode</var>| ...}</code></a></dt><!-- RDLabel: "on_unicode_to_glyph" -->
210
<p><em>Since 1.7</em>: Unicodeからグリフへ変換するコールバッ
211
クを登録します。このコールバックは省略可能です。</p>
212
<p>このコールバックは<a href="cairo-context.html#label-110">Cairo::Context#show_text</a>で使われます。</p>
213
<p>登録したコールバックは<var>unicode</var>で指定されたUnicode
214
のコードポイントに対応するグリフのインデックスを返して
216
<p>このコールバックは<a href="cairo-user-font-face.html#label-7">Cairo::UserFontFace#on_text_to_glyphs</a>
217
で登録するコールバックと同じ機能を提供します。
218
on_text_to_glyphsほど出力を制御できませんが、使いやすい
219
です。このコールバックを使うということは、各文字はそれ
220
ぞれひとつのグリフに対応し、その対応は文脈に依存しない
221
という前提があるということです。また、グリフは前のグリ
222
フの幅に対応して配置されるという仮定もしています。つま
223
り、リガチャやカーニングや複雑な文字体系などはこのコー
224
ルバックを使っては実装できないということです。</p>
225
<p>このコールバックは<a href="cairo-user-font-face.html#label-7">Cairo::UserFontFace#on_text_to_glyphs</a>
226
でコールバックを登録していない場合や、登録したコールバッ
227
クがグリフを返せなかった場合にだけ呼ばれます。このコー
228
ルバックが登録されていない場合はUnicodeのコードポイ
229
ントがそのままグリフのインデックスになっていると仮定さ
231
<p>注: cairoはグリフのインデックス付けには制限を設けていま
232
せんが、いくつかのアプリケーションはグリフのインデック
233
スは16ビットの符号無し整数に収まると仮定しています。そ
234
のため、ユーザフォントはグリフの範囲を0から65535の範囲
235
に収めるようにするとよいでしょう。さらに、いくつかのアプ
236
リケーションは0番目のグリフは「グリフがない」という特別
237
なグリフと仮定しているかもしれません。ユーザフォントは0
238
番目のグリフをそのような目的として使い、他の目的には使
240
<p>コールバック中で問題が発生した場合は
241
<a href="cairo-user-font-error.html">Cairo::UserFontError</a>例外、あるいは問題に対応する例外を
244
<li>scaled_font: ユーザ用の拡大・縮小したフォント。
245
（<a href="cairo-scaled-font.html">Cairo::ScaledFont</a>）</li>
246
<li>unicode: Unicode文字のコードポイント</li>
247
<li>ブロックの戻り値: グリフのインデックス</li>
250
<h2><a name="label-9" id="label-9">参考</a></h2><!-- RDLabel: "参考" -->
252
<li><a href="cairo-context.html#label-137">Cairo::Context#show_text_glyphs</a></li>
253
<li><a href="cairo-scaled-font.html#label-13">Cairo::ScaledFont#text_to_glyphs</a></li>
255
<h2><a name="label-10" id="label-10">変更履歴</a></h2><!-- RDLabel: "変更履歴" -->
257
<li>2008-08-17: kou: スタート。</li>
262
<li><a href="./">索引</a></li>
added
removed
doc/ja/cairo-user-font-face.html
