Scintilla/Text retrieval and modification

Last-modified: 2008-03-01 (土) 06:30:44

テキストの取得と変更

Scintillaドキュメントのそれぞれの文字は、スタイル情報の関連するバイトが後に続く。
文字バイトとスタイルバイトの組み合わせは、セルと呼ぶ。
スタイルバイトはスタイル配列インデックスによって解釈される。
スタイルバイトはインジケータビットのインデックスとセットにわかられるかもしれないが、この使用は薦めない。インジケータは現在SCI_INDICATORFILLRANGEと関連する呼び出しを使用するべきである。
デフォルトの分割は、下位5ビットと上位3ビットのインデックスとしてインジケータがある。
これにより大部分の言語に対応できる 32 種の基本スタイルが可能となり、3個の独立識別子によって文法エラー、非推奨メッセージ、字下げの不整合などの情報も一度に表示可能となる。
スタイルに使うビット数はSCI_SETSTYLEBITSで変更でき、最大7ビットを割り当てることができる。
残りのビットは識別子として利用可能である。


Scintillaドキュメントの位置は、文字か文字の前のギャップに言及する。
ドキュメントの最初の文字が0、2番目が1である。
もしドキュメントがnLen文字を含むなら、最後の文字はnLen-1番目である。
キャレットは文字の間に存在し、最初の文字(0)より前から最後の文字の後(nLen)に配置できる。


キャレットが2文字バイトが1つの文字を作るところに行くことができない場所がある。
列の最後尾がCP/M規格のキャリッジリターンであるとき、ドキュメントに日本語が含まれるような言語からDBCS文字が改行で続いたとき、これは起こる。
INVALID_POSITION定数(-1)はドキュメントの中の無効位置を表す。


Scintillaのテキストのすべての行は同じ高さで、この高さは最も大きい字体からどんな現在のスタイルでも計算される。
この制限は性能のためのものである; 行が高さにおいて異なるなら、テキストの位置決めにかかわる計算は、テキストが最初に流行に合わせられるのを必要とするだろう。

  • SCI_GETTEXT(int length, char *text)
  • SCI_SETTEXT(<unused>, const char *text)
  • SCI_SETSAVEPOINT
  • SCI_GETLINE(int line, char *text)
  • SCI_REPLACESEL(<unused>, const char *text)
  • SCI_SETREADONLY(bool readOnly)
  • SCI_GETREADONLY
  • SCI_GETTEXTRANGE(<unused>, TextRange *tr)
  • SCI_ALLOCATE(int bytes, <unused>)
  • SCI_ADDTEXT(int length, const char *s)
  • SCI_ADDSTYLEDTEXT(int length, cell *s)
  • SCI_APPENDTEXT(int length, const char *s)
  • SCI_INSERTTEXT(int pos, const char *text)
  • SCI_CLEARALL
  • SCI_CLEARDOCUMENTSTYLE
  • SCI_GETCHARAT(int position)
  • SCI_GETSTYLEAT(int position)
  • SCI_GETSTYLEDTEXT(<unused>, TextRange *tr)
  • SCI_SETSTYLEBITS(int bits)
  • SCI_GETSTYLEBITS
  • SCI_TARGETASUTF8(<unused>, char *s)
  • SCI_ENCODEDFROMUTF8(const char *utf8, char *encoded)
  • SCI_SETLENGTHFORENCODE(int bytes)

SCI_GETTEXT(int length, char *text)

文書の先頭からlength-1文字のテキストを取得し、終端文字0を加えて返す。
文書の全テキストを取得するにはSCI_GETLENGTH使って文書が保持する文字数(nLen)を取得する。
長さnLen+1バイトのバッファを確保してからSCI_GETTEXT(nLen+1, char *text)を呼び出す。
text引数が0の場合、文書のすべてを格納するのに必要な大きさが返される。
テキストを保存したときは、SCI_SETSAVEPOINTを用いてテキストを未編集扱いにするべきである。

[star] 関連項目: SCI_GETSELTEXT, SCI_GETCURLINE, SCI_GETLINE, SCI_GETSTYLEDTEXT, SCI_GETTEXTRANGE

SCI_SETTEXT(<unused>, const char *text)

文書内の全テキストを終端文字0のtext文字列で置換する。

SCI_SETSAVEPOINT

現在のドキュメントの状態が未編集であることをScintillaに伝えるメッセージである。
通常はファイルのセーブまたはロードを行ったときに行われることから"セーブポイント"の名前がある。
Scintillaがアンドゥおよびリドゥ操作を行うのと同様に、SCN_SAVEPOINTREACHEDとSCN_SAVEPOINTLEFTの通知メッセージにより、コンテナにファイルが変更されているかどうかを知らせることができる。

[star] 関連項目: SCI_EMPTYUNDOBUFFER, SCI_GETMODIFY

SCI_GETLINE(int line, char *text)

これは指名行のコンテンツでテキストによって定義されたバッファを満たす(行は0で始まる)。
バッファは0の文字によって終わらない。
SCI_LINELENGTH(int line)を使ってテキストのために十分長いバッファを確実する必要がある。
戻り値は、バッファにコピーされた文字数である。
返されたテキストはどんな改行文字も含んでいる。
あなたがドキュメントの行の範囲外に行番号を求めるなら、0個の文字がコピーされる。
テキスト引数が0であれば、全体の行を格納するために割り当てられるべき長さが返される。

[star] 関連項目: SCI_GETCURLINE, SCI_GETSELTEXT, SCI_GETTEXTRANGE, SCI_GETSTYLEDTEXT, SCI_GETTEXT

SCI_REPLACESEL(<unused>, const char *text)

アンカーと現在の位置の間の現在選択されたテキストを0の終わるテキスト文字列に置換する。
アンカーと現在の位置が同じなら、テキストはキャレット位置で挿入される。
キャレットは挿入されたテキストの後に置かれ、キャレットはビュー内にスクロールされる。

SCI_SETREADONLY(bool readOnly)

SCI_GETREADONLY

これらのメッセージは、ドキュメントのためにリードオンリーフラグをセットおよび取得する。
もしリードオンリーとしてドキュメントにマークするなら、テキストを変更しようとするとSCN_MODIFYATTEMPTROが発生する。

SCI_GETTEXTRANGE(<unused>, TextRange *tr)

cpMinとcpMax位置の間のテキストを集めて、lpstrTextにそれをコピーする(Scintilla.hのTextRange構造体を見よ)。
cpMaxが-1であれば、ドキュメントの最後までテキストを返す。
テキストは0で終わるので、あなたが読みたい文字数より少なくとも1文字長いバッファを提供しなければならない。
リターン値は、終わり0を含まない返されたテキスト長である。

[star] 関連項目: SCI_GETSELTEXT, SCI_GETLINE, SCI_GETCURLINE, SCI_GETSTYLEDTEXT, SCI_GETTEXT

SCI_GETSTYLEDTEXT(<unused>, TextRange *tr)

これは、各ペアの下位アドレスに文字、上位アドレスにスタイルバイトの各セルに2倍とのバッファを使ってスタイルされたテキストを集める。
cpMinとcpMax位置の間の文字がlpstrTextにコピーされる(Scintilla.hのTextRange構造体を見よ)。
テキストの最後に2個のバイト0が付加される。lpstrTextポインタバッファは、少なくとも2*(cpMax-cpMin)+2バイト長を提供しなければならない。
cpMinかcpMaxの分別がある値のためにチェックを全くしない。
ドキュメント外における位置は0の文字コードとスタイルバイトを返す。

[star] 関連項目: SCI_GETSELTEXT, SCI_GETLINE, SCI_GETCURLINE, SCI_GETTEXTRANGE, SCI_GETTEXT

SCI_ALLOCATE(int bytes, <unused>)

特定のバイト数を保存できる十分な大きさのドキュメントバッファを確保する。
ドキュメントを現在のコンテンツより小さくすることはないだろう。

SCI_ADDTEXT(int length, const char *s)

これは現在の位置の文字列から最初の長さの文字を挿入する。
これはあなたが挿入操作を止めると予想したかもしれない文字列のどんな0も含む。
現在の位置は挿入されたテキストの終わりに設定されるが、それはビュー内にスクロールされない。

SCI_ADDSTYLEDTEXT(int length, cell *s)

これはSCI_ADDTEXTのように振舞うが、スタイルされたテキストを挿入する。

SCI_APPENDTEXT(int length, const char *s)

これは文字列からドキュメントの最後に最初の長さの文字を加える。
これはあなたが操作を停止すると予想したかもしれない文字列のどんな0も含む。
現在の選択は変えられない。そして、新しいテキストはビュー内にスクロールされない。

SCI_INSERTTEXT(int pos, const char *text)

これは、ゼロ終端テキスト文字列pos位置、またはposが-1であれば現在の位置に挿入する。
現在の位置が挿入ポイントの後にあるなら、それは周囲のテキストと共に動かされるが、スクロールは実行されない。

SCI_CLEARALL

ドキュメントがリードオンリーでなければ、すべてのテキストを削除する。

SCI_CLEARDOCUMENTSTYLE

たとえば解析器を選択した後にドキュメントを完全にリスタイルしたいとき、SCI_CLEARDOCUMENTSTYLEはスタイル情報をすべてクリアし折りたたみ状態をリセットするために使うことができる。

SCI_GETCHARAT(int pos)

ドキュメントのposの文字を返す。posがマイナスまたはドキュメントの最後を越えていれば0を返す。

SCI_GETSTYLEAT(int pos)

ドキュメントのposのスタイルを返す。posがマイナスまたはドキュメントの最後を越えていれば0を返す。

SCI_SETSTYLEBITS(int bits)

SCI_GETSTYLEBITS

ルーチンの組は、最大7スタイルビットをスタイルに使用する各セルの中のビット数を設定および読み返す。
残りのビットはインジケータとして使用できる。
標準の設定はSCI_SETSTYLEBITS(5)である。
SCI_GETSTYLEBITSNEEDEDと共に現在の解析器によって必要とされたスタイルビット数を見つけることができる。

TextRangeとCharacterRange

これらの構造体は、RichEditとしてScintillaを扱うより古いコードが動作することができるよう、Win32のTEXTRANGEとCHARRANGEと同じ形式に定義される。

struct CharacterRange {
    long cpMin;
    long cpMax;
};
struct TextRange {
    struct CharacterRange chrg;
    char *lpstrText;
};

GTK+特有: エンコードされたテキストへのアクセス

SCI_TARGETASUTF8(<unused>, char *s)

このメソッドは、検索および置換ダイアログのようなユーザインタフェースの他の部分で使うためのテキスト取得のためにGTK+でよく使われるデフォルトのUTF-8でエンコードされた対象の値を取得する。
エンコードされたテキスト長がバイトで返される。

SCI_ENCODEDFROMUTF8(const char *utf8, char *encoded)

SCI_SETLENGTHFORENCODE(int bytes)

SCI_ENCODEDFROMUTF8は、検索ダイアログの結果と対話するために使うドキュメントのエンコードであるUTF-8文字列を変換する。たとえば、ドキュメントの中から検索できるバイトの文字列を受信する。
テキストはnulバイトを含むことができる。変換される長さを設定するのにSCI_SETLENGTHFORENCODEメソッドを使用できる。
もし-1をセットするなら、長さはnulバイトを見つけることによって決定される。
変換された文字列長が返される。