TextWriter (テキストライター)#

PDFのみ。

v1.16.18で新たに追加

このクラスはMuPDFの text オブジェクトを表します。基本的なアイデアは、（1）テキストの準備と（2）PDFページへのテキストの出力を切り離すことです 。

準備**中、テキストライターはテキストピース（「スパン」）を任意の数保存し、それぞれの位置と個別のフォント情報とともに保存します。ライターの準備されたコンテンツの **出力は、互換性のあるページサイズを持つ任意のPDFページに複数回行われる可能性があります。

テキストライターは、Page.insert_text() などと比較して、次の点で優れた代替手段です：

改良されたテキスト配置： テキストを挿入する開始点を任意に選択できます。テキストの保存はスパンの 最後の文字の後 の「カーソル位置」を返します。
自由なフォントの選択： 各テキストスパンには独自のフォントと fontsize があります。大きなテキストを作成する際に簡単に切り替えることができます。
自動フォントのフォールバック： 選択したフォントが文字をサポートしていない場合、代替フォントが自動的に検索されます。これにより、出力で印刷できない記号を見るリスク（「TOFUs」 - 小さな四角形に見える）が大幅に減少します。PyMuPDFはまた、すべてのラテン**文字（キリル文字とギリシャ文字を含む）および **すべてのCJK**文字（中国語、日本語、韓国語）をサポートする **ユニバーサルフォント「Droid Sans Fallback Regular」を提供します。
キリル文字とギリシャ文字のサポート：PDFベース14フォントには、エンコーディングを指定せずにキリル文字とギリシャ文字の統合サポートがあります。テキストはラテン文字、ギリシャ文字、キリル文字の混合である可能性があります。
透明度のサポート： パラメータの 透明度 がサポートされています。これはウォーターマークスタイルのテキストを作成する便利な方法を提供します。
両端揃えのテキスト： Page.insert_textbox() のような単純なフォントだけでなく、すべてのフォントでサポートされています。
再利用性： テキストライターオブジェクトはPDFページとは独立して存在します。同じページまたは異なるページ、同じPDFまたは異なるPDFに、異なる色や透明度を選択して複数回書き込むことができます。

このオブジェクトを使用するには、次の3つのステップが必要です：

作成時に、テキストライターはテキストの位置を計算するために関連する固定 ページの矩形 を必要とします。テキストライターは、このサイズのページにのみ書き込むことができます。
テキストライターを使用してテキストを TextWriter.append()、TextWriter.appendv()、および TextWriter.fill_textbox() メソッドで必要な回数だけ保存します。
TextWriter オブジェクトをいくつかのPDFページに出力します。

注釈

バージョン1.17.0から、TextWriterは TextWriter.write_text() の morph パラメータを介したテキストの回転を サポートしています 。
また、 Page.write_text() も存在し、1つ以上のTextWriterを組み合わせて、指定された矩形と回転角に共同で書き込みます - Page.show_pdf_page() のように。

メソッド / 属性	短い説明
`append()`	水平書き込みモードでテキストを追加します。
`appendv()`	垂直書き込みモードでテキストを追加します。
`fill_textbox()`	矩形を埋めます（水平書き込みモード）。
`write_text()`	TextWriterをPDFページに出力します。
`color`	テキストの色（変更可能です）。
`last_point`	最後に書かれた文字がここで終了します。
`opacity`	テキストの透明度（変更可能です）。
`rect`	このTextWriterが使用するページの矩形。
`text_rect`	現在までに占有された領域。

クラスAPI

class TextWriter#

__init__(self, rect, opacity=1, color=None)#

パラメータ:

rect (rect-like) -- テキストの配置計算に内部的に使用される矩形。
opacity (float) -- ここに保存されるテキストの透明度を設定します。区間 [0, 1) 外の値は無視されます。例：0.5の場合、50％の透明度を意味します。
color (float,sequ) -- テキストの色。すべての色は浮動小数点数 0 <= color <= 1 として指定されます。単一の浮動小数点数は一定の灰色レベルを表し、シーケンスはその長さを介して色空間を示します。

append(pos, text, font=None, fontsize=11, language=None, right_to_left=False, small_caps=0)#

バージョン1.18.9で変更
バージョン1.18.15で変更

水平書き込みで新しいテキストを追加します。

パラメータ:

pos (point_like) -- テキストの開始位置、最初の文字の左下の点です。
text (str) -- 任意の長さの文字列。位置「pos」から書き始められます。
font -- Font (フォント)。省略された場合、pymupdf.Font("helv") が使用されます。
fontsize (float) -- fontsize、正の数、デフォルトは11です。
language (str) -- 使用する言語、例：英語の場合は "en"。意味のある値はISO 639規格1、2、3、または5に準拠している必要があります。将来の使用を予約しています：現在はわかる限りでは何の効果もありません。
right_to_left (bool) -- （バージョン1.18.9で新機能） テキストを右から左に書くかどうか。アラビア語やヘブライ語などの言語に適用されます。デフォルトは False です。True の場合、テキスト内のラテン語部分は自動的に変換されます。他に何の影響もないため、TextWriter.last_point は依然として最右の文字ですし、配置も行われません。そのため、代わりに TextWriter.fill_textbox() を使用することがあります。
small_caps (bool) --
（バージョン1.18.15で新機能） フォント内の文字の小文字バージョンを探します。存在する場合、その値が使用されます。それ以外の場合、元の文字（このフォントまたはフォールバックフォント）が使用されます。フォールバックフォントは小文字バージョンを返しません。たとえば、次のスニペット:
```
>>> doc = pymupdf.open()
>>> page = doc.new_page()
>>> text = "PyMuPDF: the Python bindings for MuPDF"
>>> font = pymupdf.Font("figo")  # choose a font with small caps
>>> tw = pymupdf.TextWriter(page.rect)
>>> tw.append((50,100), text, font=font, small_caps=True)
>>> tw.write_text(page)
>>> doc.ez_save("x.pdf")
```
これにより、このPDFテキストが生成されます：

戻り値:

text_rect および last_point。 （v1.18.0 で変更）：サポートされていないフォントの場合、Font.is_writable を介してチェックされた例外が発生します。

appendv(pos, text, font=None, fontsize=11, language=None, small_caps=0)#

バージョン1.18.15で変更

縦書きの新しいテキストを追加します。

パラメータ:

pos (point_like) -- テキストの開始位置、最初の文字の左下の点です。
text (str) -- 文字列。 "pos" から開始して書き込まれます。
font -- Font (フォント)。省略された場合、pymupdf.Font("helv") が使用されます。
fontsize (float) -- fontsize、正の浮動小数点数、デフォルトは 11 です。
language (str) -- 使用する言語、例：英語の場合は "en"。意味のある値はISO 639規格1、2、3、または5に準拠している必要があります。将来の使用を予約しています：現在はわかる限りでは何の効果もありません。
small_caps (bool) -- （v1.18.15 で新しい） 詳細は append() を参照してください。

戻り値:

text_rect および last_point。 （v1.18.0 で変更）：サポートされていないフォントの場合、Font.is_writable を介してチェックされた例外が発生します。

fill_textbox(rect, text, *, pos=None, font=None, fontsize=11, align=0, right_to_left=False, warn=None, small_caps=0)#

1.17.3で変更：新しいパラメーター pos を追加して、矩形内での書き込みを開始する位置を指定できるようにしました。
v1.18.9で変更：矩形に収まらない行のリストを返すようにしました。右から左に書くサポートを追加（アラビア語、ヘブライ語など）。
v1.18.15で変更：フォントがサポートしている場合、小文字のテキストを優先します。

指定された矩形を水平書きモードでテキストで埋めます。これは、append() の代替手段として使用する便利な方法です。

パラメータ:

rect (rect_like) -- 埋める領域。テキストのいずれの部分もこれの外には表示されません。
text (str,sequ) -- テキスト。UTF-8文字列または文字列のリスト/タプルとして指定できます。文字列は最初に splitlines() を使用してリストに変換されます。各リストアイテムは新しい行で始まります（強制的な改行が行われます）。
pos (point_like) -- （v1.17.3で新規） このポイントから記憶を開始します。デフォルトは矩形の左上近くのポイントです。
font -- Font (フォント)、デフォルトは pymupdf.Font("helv")。
fontsize (float) -- fontsize
align (int) -- テキストの配置。TEXT_ALIGN_LEFT、TEXT_ALIGN_CENTER、TEXT_ALIGN_RIGHT、またはTEXT_ALIGN_JUSTIFYのいずれかを使用します。
right_to_left (bool) -- (v1.18.9で新規） テキストを右から左に書くかどうか。アラビア語やヘブライ語などの言語に適用可能です。デフォルトは False です。True の場合、ラテン文字部分は自動的に反転されます。右寄せを希望する場合、引き続き配置を設定する必要があります（他の配置オプションも利用可能）。
warn (bool) --
テキストのオーバーフローがある場合、何もしない、警告する、または例外を発生させるかどうか。オーバーフローテキストは書き込まれません。v1.18.9で変更：
- デフォルトは None です。
- オーバーフローラインのリストが返されます。
small_caps (bool) -- （v1.18.15 で新しい） 詳細は append() を参照してください。

戻り値の型:

list

戻り値:

v1.18.9で新規 -矩形に収まらなかった行のリスト。各アイテムは、文字列とそのページ上の長さ（長さ）を含むタプル (text, length) です。

注釈

これらのメソッドは必要な回数だけ使用できます。技術的な制限はありません（システムのメモリ制約を除く）。また、append() とテキストボックスを混在させ、それぞれ複数持つこともできます。テキストの配置は挿入ポイントによってのみ制御されます。したがって、特定の順序に従う必要はありません。（v1.18.0で変更） ：サポートされていないフォントに対して例外を発生させます - Font.is_writable をチェックします。

write_text(page, opacity=None, color=None, morph=None, overlay=True, oc=0, render_mode=0)#

TextWriterのテキストをページに書き込みます。これは唯一の必須パラメータで、TextWriterが作成されたときに使用される値を一時的にオーバーライドするために、他のパラメータを使用できます。

パラメータ:

page -- この Page (ページ) に書き込みます。
opacity (float) -- この出力のためにTextWriterの値をオーバーライドします。
color (sequ) -- この出力のためにTextWriterの値をオーバーライドします。
morph (sequ) -- テキストの外観を変更するために、それに行列を適用して修正します。提供される場合、これは （fixpoint、matrix） としてシーケンスでなければなりません。point-like fixpoint とmatrix-like matrix を持っています。典型的な例は、テキストを fixpoint の周りで回転させることです。
overlay (bool) -- 前景（デフォルト）または背景に配置します。
oc (int) -- （v1.18.4で新規） OCG または OCMD の xref。
render_mode (int) --
PDF Tr 演算子の値。値：0（デフォルト）、1、2、3（不可視）。

text_rect#

現在占有されている領域。

戻り値の型:: Rect (矩形)

last_point#

最後に書かれた文字の後にある「カーソル位置」 - Point (ポイント) 形式。

戻り値の型:: Point (ポイント)

opacity#

テキストの不透明度（変更可能）。

戻り値の型:: float

color#

テキストの色（変更可能）。

戻り値の型:: float,tuple

rect#

このTextWriterが作成されたページの長方形。変更しないでください。

戻り値の型:: Rect (矩形)

注釈

TextWriterを扱うデモスクリプトを見るには、このリポジトリをご覧ください。

不透明度と色は、このオブジェクト内の すべてのテキスト に適用されます。
異なる色/透明度が必要な場合、別々のTextWriterを作成する必要があります。色が変更されるべきと判断した場合、新しいテキストスパンの位置として前回返された last_point を使用して、対応するTextWriterにテキストを追加するだけです。
アイテムまたはテキストボックスの追加は任意の順序で発生できます：テキストが表示される位置を制御するのは、位置パラメータのみです。
同じTextWriter内でフォントと fontsize を自由に変更できます。これは、異なるプロパティを持つテキストが同じ表示される行に表示されるようにするために使用できます。posを適切に指定し、前に追加したアイテムの last_point に設定してください。
TextWriter.fill_textbox() の pos 引数を使用して、最初のテキスト文字の位置を設定できます。これにより、異なる TextWriter (テキストライター) オブジェクトからのコンテンツを含む同じテキストボックスを埋めることができ、複数の色、不透明度などが可能になります。
MuPDFは、この機能を持つすべてのフォントをサポートしているわけではありません。たとえば、Type3フォントはサポートされていません。v1.18.0以降、Font.is_writable 属性を使用して、これを確認できます。この属性は、TextWriter (テキストライター) メソッドを使用する際にもチェックされます。

Do you have any feedback on this page?

This software is provided AS-IS with no warranty, either express or implied. This software is distributed under license and may not be copied, modified or distributed except as expressly authorized under the terms of that license. Refer to licensing information at artifex.com or contact Artifex Software Inc., 39 Mesa Street, Suite 108A, San Francisco CA 94129, United States for further information.