ドキュメントのコンテンツにプログラムでアクセスする

4D v17

4D Write Proではドキュメント内でテキストと画像の属性を変更するためのコマンドをフルセット提供しています。これらの機能のおかげで、4Dデベロッパーは4D Write Proドキュメントに対して(ボタン、メニュー、チェックボックス等を使用した)独自のインターフェースをデザインすることができます。コマンドはドキュメント全体、または特定の部分(レンジ)に対して適用可能で、どちらもユーザー選択あるいはカスタムの値に基づきます。利用可能なプロパティには、ドキュメント単位、マージン、パッディング、背景、段落設定、カラー、フォント、フォントスタイル、そして画像プロパティなどが含まれます。

例えば、4D Write Pro エリアライブラリオブジェクトはこれらの機能を存分に活用し、洗練された4D Write Proインターフェースを提供しています。

セレクションレンジコマンド

4D Write Proでは、ドキュメントのコンテンツをプログラムによって選択し操作することができます。選択されたコンテンツにはテキスト、画像、表、そして(非表示の)フォーマット用タグなどが含まれうることから、4D Write Proではレンジと呼ばれるオブジェクト型を使用することができます。

レンジとは、4D Write Pro ドキュメントの一部を表すオブジェクト型です。これを使用することで、選択する要素を指定したり、(WP GET ATTRIBUTES および WP SET ATTRIBUTESを使用して)ドキュメントの一部の要素を操作することができます。

レンジとは、4D Write Pro ドキュメントの一部を表すオブジェクト型です:

文字、段落、ピクチャー、表などのレンジは、その親ドキュメント内の文字の位置を通して定義されます。
セル、カラム、行のレンジは、セルの位置を通して定義されており、親の表へとアンカーされます。

レンジを使用することで選択したい要素を指定したり、ドキュメントの一部の属性を(WP GET ATTRIBUTES および WP SET ATTRIBUTESを使用して)編集したりすることができます。

レンジには異なるタイプのレンジがあります。wk type 属性(読み込みのみ)を用いて、レンジのタイプを決定することができます。それぞれのレンジには、そのレンジを定義する複数の非公開の属性が含まれます:

定数	値	コメント
wk end	end	(読み込み専用のレンジ属性)
wk owner	owner	(読み込み専用のレンジ属性)
wk start	start	(読み込み専用のレンジ属性)
wk type	type	(読み込みのみ可能なレンジ属性) 4D Write Pro オブジェクトの型。取りうる値: wk type default: 未定義の型のレンジ wk type paragraph: 段落型のレンジ wk type image: 画像(アンカーされた画像およびインライン画像) wk type image anchored: アンカーされた画像 wk type image inline: インライン画像 wk type container: 例えばヘッダーやフッターなど wk type table: 表参照 wk type table row: 表の行参照 wk type table cell: 表のセル参照 wk type table column: 表のカラム参照(カラムレンジに対してのみ) wk type body: 本文参照

注: セル、カラム、行のレンジは、特別な属性をもっています(以下の段落参照)。

ドキュメントのレンジを定義するために、複数のコマンドが用意されています:

WP Create range( wpArea ; startRange ; endRange ) -> rangeObj: 引数として渡した境界に対応する新しい範囲を返します。
WP Get selection( {*;} wpArea ) -> rangeObj: カレントのユーザーセレクションに対応した新しいレンジを返します。
WP Create picture range( rangeObj ) -> rangeObj: ピクチャーのみを含んだ新しいレンジを返します。
WP Create paragraph range( rangeObj ) -> rangeObj: 段落のみを含んだ新しいレンジを返します。
WP Create table range( rangeObj ) -> rangeObj: 表のみを含んだ新しいレンジを変ええします。

WP Get position コマンドを使用することで、ドキュメント内でのレンジの位置(ベージ番号、カラム番号など)についての情報を取得することができます。

表コマンド

4D Write Pro の表は以下のコマンドを使用することでプログラムによって作成することができます:

WP Insert table によって表を挿入し、その参照を取得
WP Table append row によって行を表に追加し、対応するレンジを取得
WP Table get rows によって行のレンジを取得
WP Table get columns によってカラムのレンジを取得(*)
WP Table get cells によってセルのレンジを取得

(*) htmlにはカラムに相当するものがありません。4D Write Proでは、カラムのレンジは実際にはセルのレンジです。

行、カラムとセルのレンジには、それらを定義するための非公開の属性が存在します:

定数	値	コメント
wk column count	columnCount	(テーブル、ドキュメント、セクション用の属性)カラムの数。値:倍長整数テーブルの場合: 読み込みのみ属性ドキュメントあるいはセクションの場合: 読み込み/書き込み可能属性。デフォルト値=1(単一の行)。最大値=20
wk first column	firstColumn	(読み込みのみ属性)テーブル内にある最初のカラムの数。値:倍長整数
wk first row	firstRow	(読み込みのみ属性)テーブル内の最初の行の数。値:倍長整数
wk row count	rowCount	(読み込みのみ属性)行の総数。値:倍長整数
wk table ID	tableID	(読み込みのみ属性)親テーブルのID。値:文字列

ブックマークコマンド

4D Write Proではブックマークと呼ばれる、ドキュメントの一部に対して動的な参照を作成し、使用することができます。ブックマークとは、4D Write Proドキュメント内の特定のレンジに関連づけられた名前付き参照です。

ブックマークは動的です。これはつまり、ブックマークに関連付いた文章をユーザーが移動または削除した場合には、紐付いているレンジも自動的に更新され、ブックマークはドキュメント内の同じ内容を引き続き参照し続けるという事です。例えば:

ドキュメント内の20ページ目にある"Hello world"を参照する、"MyBM"というブックマークを作成したとします。
次に、ドキュメントの最初に50ページ挿入したとします。
"MyBM"ブックマークを使用する事で、今度はドキュメント内の70ページ目にある、同じ"Hello world"というテキストに自動的にアクセスすることができます。

ドキュメント内には無制限のブックマークを含める事ができます。複数のブックマークが同じレンジを参照することもできますし、ブックマークのレンジは重複することもできます。しかしながら、それぞれブックマーク名はドキュメント内において固有でなければなりません。ブックマークは、WP INSERT DOCUMENT コマンドを使用した場合にはインポートされません(保存先のドキュメントのブックマークは上書きされません)。

一度作成すると、ブックマークはドキュメント内に保存されています。ブックマークはドキュメントとともに保存され、複数のコマンドによって管理することができます。また、テンプレートドキュメントの一部を参照するのにも使用できます。これらの部分はデータベース内のドキュメントと自動的に組み合わせることもでき、その結果請求書やカタログといった動的な出力ドキュメントを生成することもできます。

複数のコマンドを使用して、ブックマークを作成、削除、使用することができます:

WP CREATE BOOKMARK はレンジから新しいブックマークを作成します。
WP GET BOOKMARKS はドキュメント内で定義されている全てのブックマークを取得します。
WP Get bookmark range は既存のブックマークからレンジを取得します。
WP DELETE BOOKMARK はブックマークを削除します。

属性管理コマンド

以下のコマンドはドキュメントの属性を取得あるいは設定します:

WP SET ATTRIBUTES( rangeObj | wpDoc ; attribName ; attribValue {; attribName2 ; attribValue2 ; ... ; attribNameN ; attribValueN} ): ドキュメントまたはレンジ内の一つ以上の属性/値のペアを設定します。
WP GET ATTRIBUTES( rangeObj | wpDoc ; attribName ; attribValue {; attribName2 ; attribValue2 ; ... ; attribNameN ; attribValueN} ): ドキュメントまたはレンジ内の属性のカレントの値を取得します。
WP RESET ATTRIBUTES( rangeObj ; attribName {; attribName2 ; ... ; attribNameN } ): ドキュメントまたはレンジ内の属性の値を再設定します。

属性は4D Write Pro属性の章に詳細な説明があります。

フォント管理コマンド

このコマンドはレンジのスタイルサポートに関する情報を取得します:

WP Is font style supported( rangeObj ; wpFontStyle ) -> true または false: レンジが特定のスタイルをサポートするかどうかを調べます(インターフェースのデザインに有用です)。

URL

4D Write Pro では任意のドキュメントレンジ (テキスト、段落、画像、テーブルの行、セル) に対してハイパーリンクを設定することができます。たとえば、画像レンジにハイパーリンクを設定した場合、その4D Write ProドキュメントをHTMLに出力すれば、ユーザーはその画像をクリックすることで指定されたアドレスのページを開くことができます。

注: 4D Write Pro ドキュメント内でも Ctrl+クリック (Windows) または Cmd+クリック (macOS) 操作でハイパーリンクを実行することができます。

ハイパーリンクはレンジ属性として扱われるため、WP SET ATTRIBUTES および WP RESET ATTRIBUTES コマンドを wk link url 定数と組み合わせて設定します。たとえば、ユーザーが選択したテキストをリンク化したい場合:

次のように書きます:

 $range:=WP Get selection(*;"WParea")

 WP SET ATTRIBUTES($range;wk link url;"http://doc.4d.com")

注: URLに特殊文字が含まれている場合、それらの変換は自動ではおこなわれないため、別途エンコードする必要があります。URLが有効でない場合には、エラーが発生します。

対象レンジにテキストスタイルが定義されていない場合、挿入されたURLにはデフォルトのハイパーリンク形式 (下線付き青文字) が設定されます。

ドキュメント内のURLに対して、4D Write Proは次のルールを適用します:

リンクの対象レンジに複数の段落が含まれている場合、リンクは複数作成されます。
すでにリンクを含んでいるレンジに対してリンクを設定した場合:
- 既存リンクは新しいリンクで上書きされます。
- 既存リンクのレンジが新しいリンクの対象レンジと交差している場合、対象レンジ内は新しいリンクで上書きされ、その外では既存リンクが維持されます。
WP GET ATTRIBUTES コマンドでリンクを取得する場合、次のケースが考えられます:
- レンジにハイパーリンクが1つ含まれている: コマンドはそのURL文字列を返します。
- レンジにハイパーリンクが複数含まれている: コマンドは最初のURL文字列を返します。
- レンジにハイパーリンクが含まれていない: コマンドは空文字列を返します。
レンジからリンクを削除するには、次の方法があります:
WP RESET ATTRIBUTES($range;wk link url)

または
WP SET ATTRIBUTES($range;wk link url;"")

参照