Source of 自作SAORI/お座りマニュアル

TITLE:Osuwari.dll version 2 取り扱い説明書 version2.1.0.0

*１．これは何をするものか [#j56f3c33]

これはSAORI規格のDLLです。ゴーストの位置を様々なロジックに従い、特定のウィンドウの矩形と同期させる機能を持ちます。ゴーストをウィンドウに「座らせる」「貼り付ける」「ぶら下げる」といった事を目的として作成されました。

&color(Red){Osuwari.dllはversion1が過去に公開されており、これは機能強化したversion2となります。};

尚、本DLLはmateriaでは動作しません。SSPもしくはCROWで利用してください。

*２．利用法概要 [#cbccc995]

ゴーストの位置の制御を開始する、あるいは制御パラメータを変更するには、START構文を用います。&color(Red){START構文はゴーストの存在する間、何度呼んでも構いません。};

一般的には、HWNDイベントの際に呼ぶことを推奨します。一度呼べばその際の制御パラメータに従い、DLLがアンロードされるかSTOP構文が呼ばれるまで位置の制御を行うため、呼び出し続ける必要はありません。

お座りを停止させる場合にはSTOP構文を用いてください。一般的にはゴーストの終了と共にDLLがアンロードされるため、STOP構文を利用しなくても問題ないでしょう。

このDLLはオプションが多彩なため構文が少々複雑です。単純に利用する場合は「５．記載例」を先に見てください。

** 陥りやすい罠 [#a43895ec]

- shell の descript.txt に &color(Red){seriko.alignmenttodesktop,free}; と記載するのを忘れないようにしてください。


*３．START構文 [#c0497df1]

**（１）構文 [#m625e910]

START構文は以下のパラメータを記載してください。~
（''START''等、この書体で記載されているものは、その通りの文字列を記載する事を示します）
(optional)とある項目は、指定しなくても構いません。その場合は前回指定時の値（初回実行時であればデフォルト値）になります。

|Argument|記載内容|説明|h
|Argument0|''START''|大文字文字列で記載|
|Argument1|制御対象のHWND|一般的にはHWNDイベントで渡されます。（５．記載例も見てください）|
|Argument2|追尾対象|下記の何れかを記載してください。&br;''ACTIVE''：アクティブウィンドウを対象にします&br;''FIX''：画面全体もしくはワークエリア（画面からタスクバー等の領域を除いた部分、つまり壁紙が見えている部分）を対象にします。&br;''@''文字列：ウィンドウタイトルに「文字列」を持つウィンドウを対象にします&br;''#''数値：ウィンドウハンドルが「数値」のウィンドウを対象にします|
|Argument3|位置原点|Argument2で指定したウィンドウの、どこを原点とするかを、下記の何れかで指定してください。&br;''TL''：左上隅を原点とします。&br;''TR''：右上隅を原点とします。&br;''BL''：左下隅を原点とします。&br;''BR''：右下隅を原点とします。|
|Argument4|x座標差分|原点からのｘ座標のずれを記載してください。|
|Argument5|y座標差分|原点からのy座標のずれを記載してください。|
|Argument6|更新間隔|位置のチェック間隔をミリセコンドで記載してください((一般的には50～100ms程度が良いと思います。数値が小さい程「なめらかに」移動しますが、システムへの負荷も大きくなります))|
|Argument7&br;(optional)|オプション|下記のオプションをスペース区切りで指定してください。複数指定しても、まったく指定しなくてもかまいません。&br;''XMOVE''：横方向にゴーストを移動可能にします&br;''YMOVE''：縦方向にゴーストを移動可能にします&br;''NOCLIP''：見切れ判定を行いません|
|Argument8&br;(optional)|位置取得失敗時指定|Argument2がFIXの場合、対象の矩形取得に失敗した場合、あるいは見切れが発生した場合の位置を指定します。①と②をそれぞれスペース区切りで指定して下さい。指定しなかった場合はDESKTOP CENTERと指定されたものとして扱います。&br;&br;①位置取得失敗時の対象&br;''DESKTOP''：デスクトップを対象とします。&br;''WORKAREA''：ワークエリアを対象とします。&br;&br;②位置取得失敗時の仮想矩形&br;''CENTER''：デスクトップ又はワークエリアのウィンドウをそのまま用います。&br;''TOP''：対象の矩形の上側に仮想ウィンドウを想定します。&br;''LEFT''：対象の矩形の左側に仮想ウィンドウを想定します。&br;''RIGHT''：対象の矩形の右側に仮想ウィンドウを想定します。&br;''BOTTOM''：対象の矩形の下側に仮想ウィンドウを想定します。|
|Argument9&br;(optional)|見切れマージン|NOCLIPが指定されていない場合はデスクトップ領域から外れると「見切れ」がおきますが、ここに数値を指定すると、見切れ判定にマージンを持たせることができます。&br;数値を４つ、空白またはアンダーバー（_）区切りで記載してください。((里々では空白交じりの数値を扱いにくいようなので))&br;数値の順番は、「左端マージン、上端マージン、右端マージン、下端マージン」になります。&br;（例）0_50_0_100　と指定すると、上に50ピクセル、下に100ピクセルはみ出すまでは、「見切れ」がおきていないものとして扱います。|

**（２）位置指定について [#p44f9471]
位置の指定、原点、差分について、下図を参考にしてください。~
黄色はx,y差分が両方０の場合の位置になります。（例：位置原点＝TR、x差分＝-100、y差分＝-20とした場合）

&attachref(./image001.png,nolink);

**（３）位置取得失敗時・位置固定時の動作について [#i6a7d04a]
以下の場合にはデスクトップかワークエリアを追尾対象とし、Argument8の記載が有効になります。
-追尾対象がFIXの場合 
-追尾対象が @文字列 あるいは #数値 で、対象のウィンドウが存在しなかった場合
-追尾対象がACTIVEで、アクティブウィンドウを追尾対象と出来ない場合（原因は色々あります）
-オプションにNOCLIPが指定されておらず、「見切れ」（そのまま追尾すると位置が画面からはみ出すこと）が発生する場合

その際に「代用として」計算される位置と、位置取得失敗時指定の関係については下図を参考にしてください。~
以下の点線の矩形を「仮想的な追尾対象ウィンドウ」として、（２）で示した位置計算を行います((つまり、位置原点がTLもしくはTRの時にTOPを指定するのは ―― 画面からはみ出して見えなくなってしまうため ―― ナンセンスです。))

&attachref(./image002.png,nolink);


なお、デスクトップとは画面全体のこと、ワークエリアとは画面からタスクバー領域を除いたものだと思って大体間違いありません。


*４．STOP構文 [#m12e73ed]

STOP構文を用いると、DLLの動作を停止できます。以下のパラメータを記載してください。

|Argument|記載内容|説明|h
|Argument0|''STOP''|大文字文字列で記載|

&color(Red){Argument1以降は記載しても無視されます。};
 

*５．記載例 [#m3554f54]

**（１）HWND取得の記載例 [#b3742697]
本DLLを利用するためには、位置制御対象のHWNDを知る必要があります。一般的には\0もしくは\1のHWNDを指定することになると思います。\0、\1のHWNDは本体からHWNDイベントで通知されます。
以下に里々でのHWND取得コード例を記載します。このコードによりsakurahwnd変数に\0のHWNDが入ります。

#pre{{
＊hwnd
＄temp	（split,（Ｒ０）,（sprintf,%c,1））
＄sakurahwnd	（Ｓ０）
}}

**（２）「お座り」 [#xdb59afb]
ゴーストをウインドウの右上に「お座り」させるための構文例を記載します。

#pre{{
Argument2:ACTIVE（アクティブウィンドウに「お座り」させる）
Argument3:TR（ウィンドウの右上を原点とする）
Argument4:-20（ウィンドウの右上から20ピクセル左に寄った場所を初期位置とする）
Argument5:-90（ゴーストの「座高」が90ピクセルの場合）
Argument6:100（100[ms]毎に更新）
Argument7:XMOVE（横方向に移動可能、見切れあり）
Argument8:BOTTOM WORKAREA（「お座り」失敗時にはワークエリアの下端に座る）
}}

※Argument2をFIXとすると、つねにワークエリア下端に「お座り」します。


**（３）「ぶら下がり」 [#u264f301]
ゴーストをウインドウの左下に「ぶら下がり」させるための構文例を記載します。

#pre{{
Argument2:ACTIVE（アクティブウィンドウに「ぶら下がり」させる）
Argument3:BL（ウィンドウの左下を原点とする）
Argument4:30（ウィンドウの左下から30ピクセル右に寄った場所を初期位置とする）
Argument5:160（ゴーストの「手から下の高さ」が160ピクセルの場合）
Argument6:100（100[ms]毎に更新）
Argument7:（移動できない、見切れあり）
Argument8:TOP WORKAREA（「ぶら下がり」失敗時にはワークエリアの上端にぶら下がる）
}}

※Argument2をFIXとすると、つねにワークエリア上端に「ぶら下がり」ます。

**（４）総合例 [#n0bd070f]

以下に、里々でゴーストを「お座り」させる例を記載します。~
メニューで「デスクトップに座る」「アクティブウィンドウに座る」「座らない」を選択可能とします。

【コア部分】
#pre{{
＠お座り
（osuwari,（Ａ０）,（Ａ１）,（Ａ２）,TR,-50,-97,100,XMOVE,BOTTOM WORKAREA）

＊hwnd
＄temp	（split,（Ｒ０）,（sprintf,%c,1））
＄sakurahwnd	（Ｓ０）
＞お座り実行

＊お座り実行
（call,お座り,STOP,0,0）
＞タスクバーモード	（お座りモード）＝＝１
＞座らないモード	（お座りモード）＝＝２
（call,お座り,START,（sakurahwnd）,ACTIVE）

＊タスクバーモード
（call,お座り,START,（sakurahwnd）,FIX）

＊座らないモード
＃なにもしない
}}


【メニュー部分：メニューから各＊が呼ばれるものとします】
#pre{{
＊ウインドウにも座って良いよ
：\u\s[10]\h\s[6]はい…\w5…\w5分かりました…\w5…\w5
＄お座りモード	０
＞お座り実行

＊タスクバーにだけ座ってて
：\u\s[10]\h\s[6]はい…\w5…\w5分かりました…\w5…\w5
＄お座りモード	１
＞お座り実行

＊どこに座ってもいいよ
：\u\s[10]\h\s[6]はい…\w5…\w5分かりました…\w5…\w5
＄お座りモード	２
＞お座り実行
}}

【ｒキー等で里々のリロードを行う場合はその対応が必要になります】
#pre{{
＊OnSatoriLoad
＞辞書リロード後お座り	（辞書リロードずみ）＝＝１

＊辞書リロード後お座り
＄辞書リロードずみ	０
＞お座り実行

＊OnKeyPress
＞（Ｒ０）が押された

＊rが押された
＄辞書リロードずみ	１
＄辞書リロード	実行
：（５）リロード…\w5…\w5します…\w5…\w5
}}

*６．注意事項・制限事項 [#e4c64af4]
-本DLLを利用した事による一切の損害の責任を負いません。at your own riskでお願いします。
-osuwari.dllを利用したゴーストを複数同時起動した場合の動作は未定です。
-現時点では制御対象とできるウィンドウは１つだけです。\0と\1を同時に制御できません((「りむ・えくすとり～む」では、osuwari.dllをosuwari0.dll、osuwari1.dllとリネームし、\0と\1でそれぞれを利用することによってこの制限を回避されています。思いつきませんでした。))。
-その他異常な動作をする事があるかもしれません。その際はどんな事でも報告頂けると有難いです((それは仕様かもしれませんしバグかもしれません、直せるとも限りませんが))。

*７．謝辞 [#yef78bb9]
開発にあたってはえびさわ様のgethwnd.dllソースを大いに参考にさせて頂き、また勝手ながらだいぶ流用させて頂いております。お礼申し上げます。~
http://www33.tok2.com/home/ebi/index.shtml　「何かぬるめの...」byえびさわ様

osuwari.dllの動作確認その他について、黒羽龍矢様及びTJ様にご協力頂いております。お礼申し上げます。~
http://kurobanetatuya.hp.infoseek.co.jp/genkan.htm　「龍屋」by黒羽龍矢様~
http://seriko.nanika.jp/sstpviewer/　「SSTP-viewer’s street」by TJ様

里々のコード例の元については殊海夕音様にご協力頂いております。お礼申し上げます。~
http://yune-kotomi.tarenari.jp/　「雨上がりの青空を探して。」by殊海夕音様

Chameleon Ponapalt様には作成に当たって様々な助言を頂きました。お礼申し上げます。~
http://ssp.shillest.net/ 「SSP (en)BUGTRAQ」by Chameleon Ponapalt様