Scintilla/Notifications

通知

コンテナに関心があるかもしれないイベントが発生したとき、Scintillaコントロールからコンテナに通知を送る(fire)。
通知は、WindowsではWM_NOTIFYメッセージ、GTK+では"通知"信号を使って送信する。
コンテナは、イベント情報を含むSCNotification構造体を渡される。

struct NotifyHeader {   // This matches the Win32 NMHDR structure
    void *hwndFrom;     // environment specific window handle/pointer
    uptr_t idFrom;	// CtrlID of the window issuing the notification
    unsigned int code;  // The SCN_* notification code
};

struct SCNotification {
    struct NotifyHeader nmhdr;
    int position;
    // SCN_STYLENEEDED, SCN_DOUBLECLICK, SCN_MODIFIED, SCN_DWELLSTART,
    // SCN_DWELLEND, SCN_CALLTIPCLICK,
    // SCN_HOTSPOTCLICK, SCN_HOTSPOTDOUBLECLICK
    int ch;             // SCN_CHARADDED, SCN_KEY
    int modifiers;      // SCN_KEY, SCN_DOUBLECLICK, SCN_HOTSPOTCLICK, SCN_HOTSPOTDOUBLECLICK
    int modificationType; // SCN_MODIFIED
    const char *text;   // SCN_MODIFIED, SCN_USERLISTSELECTION, SCN_AUTOCSELECTION
    int length;         // SCN_MODIFIED
    int linesAdded;     // SCN_MODIFIED
    int message;        // SCN_MACRORECORD
    uptr_t wParam;      // SCN_MACRORECORD
    sptr_t lParam;      // SCN_MACRORECORD
    int line;           // SCN_MODIFIED, SCN_DOUBLECLICK
    int foldLevelNow;   // SCN_MODIFIED
    int foldLevelPrev;  // SCN_MODIFIED
    int margin;         // SCN_MARGINCLICK
    int listType;       // SCN_USERLISTSELECTION, SCN_AUTOCSELECTION
    int x;              // SCN_DWELLSTART, SCN_DWELLEND
    int y;              // SCN_DWELLSTART, SCN_DWELLEND
};

あなたのコンテナが扱うのを選択できる通知メッセージとそれらに関連しているメッセージは以下の通りである:

• SCN_STYLENEEDED
• SCN_CHARADDED
• SCN_SAVEPOINTREACHED
• SCN_SAVEPOINTLEFT
• SCN_MODIFYATTEMPTRO
• SCN_KEY
• SCN_DOUBLECLICK
• SCN_UPDATEUI
• SCN_MODIFIED
• SCN_MACRORECORD
• SCN_MARGINCLICK
• SCN_NEEDSHOWN
• SCN_PAINTED
• SCN_USERLISTSELECTION
• SCN_URIDROPPED
• SCN_DWELLSTART
• SCN_DWELLEND
• SCN_ZOOM
• SCN_HOTSPOTCLICK
• SCN_HOTSPOTDOUBLECLICK
• SCN_INDICATORCLICK
• SCN_INDICATORRELEASE
• SCN_CALLTIPCLICK
• SCN_AUTOCSELECTION

以下のSCI_*メッセージはこれらの通知に関連している:

• SCI_SETMODEVENTMASK(int eventMask)
• SCI_GETMODEVENTMASK
• SCI_SETMOUSEDWELLTIME
• SCI_GETMOUSEDWELLTIME

以下の追加の通知にWindowsではWM_COMMANDメッセージ、GTK+では"Command"信号を使用する。
これはWindowsのEditコントロールを見習う。
コントロールIDの下位16ビットだけがこれらの通知で渡される。

• SCEN_CHANGE
• SCEN_SETFOCUS
• SCEN_KILLFOCUS

SCN_STYLENEEDED

SCI_SETLEXER(SCLEX_CONTAINER)によりコンテナが解析器の役割をも担うように設定するとこの通知が送られるようになる。
装飾が必要なテキスト表示もしくは印刷を行おうとするとき受信される。
SCI_GETENDSTYLEDの戻り値を含んでいる行からSCNotification.positionで渡される位置までの装飾を要求されていることになる。
端的には次のようなコードが必要となる。

startPos = SCI_GETENDSTYLED()
lineNumber = SCI_LINEFROMPOSITION(startPos);
startPos = SCI_POSITIONFROMLINE(lineNumber);
MyStyleRoutine(startPos, SCNotification.position);

SCN_CHARADDED

ユーザが通常の(コマンド文字ではない、と言う意味での)テキスト文字をタイプしたときに送られるメッセージである。
メッセージを受け取ったコンテナはコールチップや自動補完候補項目を表示するかどうかなどを決めることができる。
タイプされた文字はSCNotification.chに入っている。
通知は、スタイルされる前の文字を送信するので、スタイリングに依存する処理はSCN_UPDATEUI通知で実行されるべきである。

SCN_SAVEPOINTREACHED

SCN_SAVEPOINTLEFT

保存点に戻ってきたかそこから変化していくときに送られてくるメッセージである。
コンテナはこれにより"文書変更済み"のサインを表示し、関連メニューを変更できる。

関連項目: SCI_SETSAVEPOINT, SCI_GETMODIFY

SCN_MODIFYATTEMPTRO

読み出し専用モードの時にユーザがテキストの変更を試みた場合に送信されるメッセージである。
バージョン管理システムからの文書を調べることに利用できる。
文書を読み出し専用にするにはSCI_SETREADONLYを使う。

SCN_KEY

あらゆるキーの押下を報告するメッセージである。
GTK+のキーボードフォーカスの問題から、GTK+でのみ使われる。
Windows版では送信されない。
SCNotification.chにキーコード、SCNotification.modifiersに修飾キー情報が入っている。
この通知は修飾キーにSCMOD_ALTもしくはSCMOD_CTRLが含まれていて、キーコードが256未満の場合に送信される。

SCN_DOUBLECLICK

エディタの中でマウスボタンがダブルクリックされたときに送信される。
位置フィールドはダブルクリックのテキスト位置に設定され、行フィールドはダブルクリックの行に設定される。

SCN_UPDATEUI

文書内のテキストもしくは装飾が変更されたり、選択範囲が変化したりしたときに送信される。
文書や表示状態に依存するユーザインタフェイス要素を更新する機会となる。
かつてはSCN_CHECKBRACEとして使われていたもので、主な利用方法が括弧の隣にキャレットがあるかどうかの調査、またあるのであればその括弧及び対応する括弧の強調にあったからである。
このメッセージはSCN_POSCHANGEDをも廃止統合している。

SCN_MODIFIED

テキストや装飾が変更されたか、あるいはされようとしているときに発行される通知である。
コンテナに送信される通知はSCI_SETMODEVENTMASKによって選別することができる。
何がどのように変化するか、また総行数を変更したかどうかが通知構造体に収められている。
SCN_MODIFIEDイベントが起きている間は実際の変化は起こらない。
SCNotificationの使われ方は次の通りである:

表: 変更通知タイプ

SCNotification.modificationTypeは何が行われたかを示すビット集合である。
SC_MOD_*が行動と関連づけられる。
SC_PREFORMED_*ビットでユーザの操作によるものか、またはやり直し・再実行の結果によるものかが示される。

表: 変更通知タイプフラグ

SCEN_CHANGE

ドキュメントの原本(スタイルでない)が変化するとき、SCEN_CHANGE(768)は実行にされる。
これが標準のEditコントロールの働きであるので、この通知にWindowsではWM_COMMANDメッセージとGTK+では"コマンド"シグナルを使用する(SCEN_CHANGEは、Windows EditコントロールのEN_CHANGEと同じ値である)。
他の情報を全く送らない。
より詳細な情報を必要とするなら、SCN_MODIFIEDを使用する。
あなたはあなたがSCI_SETMODEVENTMASKと共に通知される変化のタイプをフィルターにかけることができる。

SCI_SETMODEVENTMASK(int eventMask)

SCI_GETMODEVENTMASK

これらのメッセージは、どのドキュメント変化イベントがSCN_MODIFIEDとSCEN_CHANGEと共にコンテナに通知されるかを決定するイベントマスクを、設定および取得する。
たとえば、コンテナは、SCI_をSETMODEVENTMASK(SC_MOD_INSERTTEXT|SC_MOD_DELETETEXT)と呼ぶことによってスタイルの変化ではなく、テキストへの変化に関する通知だけを見ると決めるかもしれない。


可能な通知種別はmodificationTypeがSCN_MODIFIEDによって使用されたフラグビットと同じである:

SCN_MODIFIED: SC_MOD_INSERTTEXT, SC_MOD_DELETETEXT, SC_MOD_CHANGESTYLE, SC_MOD_CHANGEFOLD, SC_PERFORMED_USER, SC_PERFORMED_UNDO, SC_PERFORMED_REDO, SC_MULTISTEPUNDOREDO, SC_LASTSTEPINUNDOREDO, SC_MOD_CHANGEMARKER, SC_MOD_BEFOREINSERT, SC_MOD_BEFOREDELETE, SC_MULTILINEUNDOREDO, and SC_MODEVENTMASKALL.

SCEN_SETFOCUS

SCEN_KILLFOCUS

SCEN_SETFOCUS(512)はScintillaがフォーカスを受信するときに実行され、SCEN_KILLFOCUS(256)はフォーカスを失うときに実行される。
これが標準のEditコントロールの働きであるので、これらの通知にWindowsではWM_COMMANDメッセージとGTK+では"コマンド"シグナルを使用させる。
残念ながら、これらのコードはWindows Edit通知コードのEN_SETFOCUS(256)とEN_KILLFOCUS(512)に合っていない。
クライアントが現行値によるとき、Scintillaコードを変えるのは、現在、遅過ぎる。

SCN_MACRORECORD

SCI_STARTRECORDとSCI_STOPRECORDメッセージは、マクロ記録を有効および無効にする。
書き込み可能な変化が起こるたびに可能にすると、SCN_MACRORECORD通知をコンテナに送る。
動作を記録するのは、コンテナ次第である。
書き込み可能なSCI_*メッセージに関する全リストを見るために、Editor::NotifyMacroRecordのためのScintillaソースEditor.cxxを探す。
この通知で用意ができているSCNotificationフィールドは以下のとおりである:

表: マクロ記録通知データ

SCN_MARGINCLICK

この通知は、マウスが敏感であるとしてマークされたマージンの中をクリックされたとコンテナに教える(SCI_SETMARGINSENSITIVENを見よ)。
折りたたみを実行するか、または区切り点を置くのにこれを使用できる。
以下のSCNotificationフィールドは使用されている:

表: マージンクリック通知

SCN_NEEDSHOWN

Scintillaは、現在目に見えないさまざまな行を目に見えるようにするべきであることを決定する。
これが必要であるかもしれないところの例は収縮した折りたたみポイントの行末が削除されるかどうかということである。
全体のドキュメントを目に見えるようになどなどの珍しい何らかの方法で行を目に見えるようにしたがっていたときのためにこのメッセージをコンテナに送る。
ほとんどのコンテナが、SCI_をENSUREVISIBLEと呼ぶことによって範囲のそれぞれの行が目に見えるのをただ確実にするだろう。
SCNotificationの位置と長さフィールドは目に見えるようにされるべきであるドキュメントの範囲を示す。
コンテナコードは以下のコードスケルトンと同様になるだろう:

firstLine = SCI_LINEFROMPOSITION(scn.position)
lastLine = SCI_LINEFROMPOSITION(scn.position+scn.length-1)
for line = lineStart to lineEnd do SCI_ENSUREVISIBLE(line) next

SCN_PAINTED

ペイントはちょうど完了していたところである。
あなたがScintillaで変化に基づくある他のウィジェットを更新したいとき役に立つ。しかし、ペイントを、最初に、より敏感に見えるために起こるようにしたい。
他の情報は全くSCNotificationにない。

SCN_USERLISTSELECTION

ユーザはユーザリストのアイテムを選択した。
SCNotificationフィールドは以下のとおりである:

表: ユーザリスト通知

SCN_URIDROPPED

GTK+バージョンのみである。
ユーザがScintilla上でファイル名かウェブアドレスのようなURIをドラッグしたことを示す。
コンテナはファイルを開くという要求としてこれを解釈するかもしれない。
SCNotificationに関するテキストフィールドはURIテキストを指し示す。

SCN_DWELLSTART

SCN_DWELLEND

ユーザが1つの位置にマウスを保つとSCN_DWELLSTARTが発生する(SCI_SETMOUSEDWELLTIMEを見よ)。
SCN_DWELLENDはSCN_DWELLSTARTの後に発生する。マウスは、キー押下が示すようなほかの動作でdwellが終わり移動する。
両方の通知はSCNotificationの同じフィールドにセットする:

表: マウス移動通知

SCI_SETMOUSEDWELLTIME

SCI_GETMOUSEDWELLTIME

これらの2つのメッセージは、マウスを保つ時間をミリ秒でSCN_DWELLSTART通知を発生させるようにセットおよび取得する。

SCN_ZOOM

ユーザがキーボードを使用することで表示をズームさせるとき、この通知が発生するか、またはSCI_SETZOOMメソッドが呼ばれる。
ピクセルよりむしろ文字に関してサイズを維持する行番号マージンの幅などのように、位置を再検討するのにこの通知を使用できる。
SCNotificationには、追加情報が全くない。

SCN_HOTSPOTCLICK

SCN_HOTSPOTDOUBLECLICK

ユーザがスタイルにはホットスポット属性集合であるテキストをクリックするか、またはダブルクリックするとき、これらの通知は発生する。
可変定義かウェブページにリンクするのにこの通知を使用できる。
位置フィールドは、クリックまたはダブルクリックのテキスト位置を設定する。そして、修飾語フィールドは同じようにSCN_KEYに押さえられた主要な修飾語をセットする。

SCN_INDICATORCLICK

SCN_INDICATORRELEASE

ユーザがインディケータを持っているテキストでマウスをクリックするか、またはリリースするとき、これらの通知は発生する。
位置フィールドはクリックまたはダブルクリックのテキスト位置を設定し、修飾フィールドはSCN_KEYに同じように押さえられた修飾子をセットする。

SCN_CALLTIPCLICK

ユーザがコールチップをクリックするとき、この通知は発生する。
引数が異なるオーバーロードされた関数名のとき、次の関数プロトタイプを表示するのにこの通知を使用できる。
位置フィールドはクリックが上矢印なら1、下矢印なら2、そのほかなら0をセットする。

SCN_AUTOCSELECTION

ユーザは自動補完リストで項目を選択しました。
選択を挿入する前に通知を送る。
通知から戻る前にSCI_AUTOCCANCELメッセージを送ることによって、自動挿入を中止できる。
使用したSCNotificationフィールドが使うのは以下の通りである:

表: 自動補完リスト通知

---