===========
annotatable
===========

``annotatable`` モジュールは、アノテーションを付加できる要素である Page
クラスおよび Annotation クラスを総合して扱います。

モジュール変数
==============

``MIN_ANN_SIZE = 3``
    アノテーションの最小サイズです。縦横とも 3 ミリメートルが最小サイズです。

``MIN_FUSEN_SIZE = 5``
    付箋の最小サイズです。縦横とも 5 ミリメートルが最小サイズです。

Annotatable オブジェクト
========================

Annotatable クラスは、アノテーションを付加できる Page クラスと Annotation
クラスとの基底クラスです。

Annotatable オブジェクトに添字表記を用いて、子要素の Annotation
オブジェクトを取得できます。添字部分にスライスを指定すると、子要素の
Annotation オブジェクト群をタプルとして取得できます。

Annotatable クラスはイテレータプロトコルをサポートしており、子要素の
Annotation オブジェクトを順次取得できます。

コンストラクタ
--------------

クラス ``Annotatable()``
    Annotatable オブジェクトを返します。

インスタンスメソッド
--------------------

``add_arc(rect=Rect(75, 25, 150, 50), **kw)``
    楕円形アノテーションを付加します。
    ``rect`` は楕円形が収まる矩形領域を表す Rect オブジェクトです。
    ``**kw`` はアノテーションの属性を指定する辞書です。Annotation
    オブジェクトのインスタンス属性を参照してください。

``add_bitmap(position=Point(25,75), path=None, **kw)``
    ビットマップアノテーションを付加します。
    ``position`` はアノテーションを付加する位置です。
    ``path`` は元となる画像ファイルのパス名です。
    ``**kw`` はアノテーションの属性を指定する辞書です。Annotation
    オブジェクトのインスタンス属性を参照してください。

``add_ellipse(rect=Rect(75, 25, 150, 50), **kw)``
    ``add_arc(rect)`` と同じです。

``add_line(points=[Point(75, 25), Point(150, 25)], **kw)``
    直線アノテーションを付加します。
    ``points`` は Point オブジェクト 2 要素からなるシーケンスです。
    ``**kw`` はアノテーションの属性を指定する辞書です。Annotation
    オブジェクトのインスタンス属性を参照してください。

``add_link(position=Point(25,75), **kw)``
    リンクアノテーションを付加します。
    ``position`` はテキストアノテーションを付加する位置です。
    ``**kw`` はアノテーションの属性を指定する辞書です。Annotation
    オブジェクトのインスタンス属性を参照してください。

``add_marker(points=[Point(75, 25), Point(150, 25), Point(150, 50), Point(75, 50)], **kw)``
    マーカーアノテーションを付加します。
    ``points`` は任意の個数の Point オブジェクトからなるシーケンスです。
    ``**kw`` はアノテーションの属性を指定する辞書です。Annotation
    オブジェクトのインスタンス属性を参照してください。

``add_polygon(points=[Point(75, 25), Point(150, 25), Point(150, 50), Point(75, 50)], **kw)``
    多角形アノテーションを付加します。
    ``points`` は任意の個数の Point オブジェクトからなるシーケンスです。
    ``**kw`` はアノテーションの属性を指定する辞書です。Annotation
    オブジェクトのインスタンス属性を参照してください。

``add_rect(rect=Rect(75, 25, 150, 50), **kw)``
    ``add_rectangle(rect)`` と同じです。

``add_rectangle(rect=Rect(75, 25, 150, 50), **kw)``
    矩形アノテーションを付加します。
    ``rect`` は矩形の領域です。
    ``**kw`` はアノテーションの属性を指定する辞書です。Annotation
    オブジェクトのインスタンス属性を参照してください。

``add_stickey(position=Point(25,75), size=Point(75, 25), **kw)``
    ``position`` は付箋を付加する位置です。
    ``size`` は付箋の大きさを指定する Point オブジェクトです。
    ``**kw`` はアノテーションの属性を指定する辞書です。Annotation
    オブジェクトのインスタンス属性を参照してください。

``add_straightline(points=[Point(75, 25), Point(150, 25)], **kw)``
    ``add_line(points)`` と同じです。

``add_text(position=Point(25,75), **kw)``
    テキストアノテーションを付加します。
    ``position`` はテキストアノテーションを付加する位置です。
    ``**kw`` はアノテーションの属性を指定する辞書です。Annotation
    オブジェクトのインスタンス属性を参照してください。

``annotation(pos)``
    ``pos`` で示される子要素のアノテーションを取得します。 ``pos`` は
    子要素のアノテーションの位置です。これは内部の番号であり、表示とは
    関係がありません。生成順になる保証もありません。ただし、0 から始まる
    整数であり、間に欠落値は生じません。
    (注) 得られるアノテーションには、アノテーションタイプが ``'PAGEFORM'``
    (見出し・ページ番号) や ``'TITLE'`` (タイトルアノテーション) である
    ものが含まれます。これらは Annotation オブジェクトですが、
    扱いが特異です。 xdwlib では、 ``'PAGEFORM'`` については 主に PageForm
    オブジェクトとして扱います。 ``'TITLE'`` (タイトルアノテーション)
    についてはほとんど操作できません。

``annotation_text(recursive=True)``
    子要素のアノテーションに含まれるテキストを返します。  ``recursive`` が
    ``True`` である場合は、子孫となるすべてのアノテーションから得られる
    テキストを返します。アノテーションから得られるテキストの種類については、
    Annotation オブジェクトを参照してください。

``copy_annotation(ann)``
    ``ann`` は Annotation オブジェクトです。 ``ann`` を複製した新たな
    アノテーションを返します。カスタムアノテーションは複製できません。
    ビットマップアノテーションは複製できますが、処理時間がかかります。

``delete(pos)``
    ``pos`` で示される子要素のアノテーションを削除します。 ``pos`` に
    ついては ``annotation()`` メソッドを参照してください。
    ``del self[pos]`` としても同じです。

``find_annotations(criteria=None, handles=None, types=None, rect=None, half_open=True, recursive=False)``
    ページまたはアノテーションの中で特定のアノテーションを検索し、
    該当するアノテーションをリストで返します。
    ``criteria``, ``handles``, ``types``, ``rect`` については、
    指定のすべてを満たすアノテーションを選択することになります。
    ``criteria`` は、アノテーションの選択基準を表す関数です。引数に単独の
    アノテーションをとり、そのアノテーションが選択されるべきものであれば
    ``True`` を、そうでなければ ``False`` を返すような関数を指定します。
    指定しなければ、すべてのアノテーションを指定したことになります。
    ``handles`` は、アノテーションハンドルのシーケンスです。アノテーション
    ハンドルがわかっている場合に、そこから Annotation オブジェクトを
    取得するのに利用します。
    ``types`` は、アノテーションタイプのシーケンスです。アノテーション
    タイプは、 ``'STICKEY'``, ``'TEXT'``, ``'STAMP'``, ``'STRAIGHTLINE'``,
    ``'RECTANGLE'``, ``'ARC'``, ``'POLYGON'``, ``'MARKER'``, ``'LINK'``,
    ``'OLE'``, ``'BITMAP'``, ``'CUSTOM'`` または ``'GROUP'``
    (アノテーションをグループ化したときの親となる表示されないアノテーション)
    で指定します。
    ``rect`` は、アノテーションが完全に収まるような領域を表す Rect
    オブジェクトです。
    ``half_open`` が ``True`` である場合は、 ``rect`` は半開矩形領域であり、
    右端および下端の座標は領域に含まれません。アノテーションの占める
    矩形領域 (の右端と下端) と ``rect`` を一致させたい (``rect`` を
    閉鎖矩形領域としたい) 場合は、 ``half_open=False`` としてください。
    ``recursive`` が ``True`` である場合は、子孫となるすべてのアノテーション
    について、上記の条件を満たすアノテーションを返します。

``fulltext()``
    ページまたはアノテーション自身と、その子孫となるすべてのアノテーション
    から得られるテキストを返します。