ELPlaylist解説 - フリーソフトウェアとかその他いろいろ

移転しました

http://www7.atpages.jp/customize/foobar2000/pukiwiki
こちらのページに最新の情報があります

ELPlaylist解説（わかりづらいので少しずつ修正する予定）

暇ができたときに初期ＴＦ見習ってちょっと改良します
<概要>
シングルカラムで、group formatに設定した要素でグルーピングしてリスト表示するプレイリストです。
設定を編集するにはTitleformatの知識が必要ですが、その分自由が利くという利点があります。

<実際に解説を交えてELPlaylistの設定をしてみます>
このようなプレイリストを目標に作ってみましょう。

　・ノート風のプレイリスト
　・Group headerは細めでHide all itemsをしたときにたくさんのアルバムの閲覧をすることが可能
　・Hide all itemsをしたときにGroup headerで画像が表示されるとスクロールが重くなりそうなので
　　Track listにアルバムアートを表示（auto-collapseを設定している場合とか）

まず設定の仕方ですが、ELPlaylistがある場所で右クリック>Settingsをクリックします。
（設定の各項目についてはreadmeを見てください。一応このページの一番下にも引用しておきました）
ELPlaylistはGroup headerとTrack listという構成で成り立っています。
イメージとしてはこんな感じです（これから解説していく中でこの画像をイメージ画像と呼びます）

これはgroup formatでアルバムごとにグルーピングしてリスト表示しています。
（初期設定でアルバムをグルーピングすることになっているので特に設定の必要はありません）
この画像で一番上に表示されているグループで黄色の部分がGroup header、緑色の部分がTrack listです。
二つ以降も塗っていませんがそれぞれGroup header、Track listです。
二つ目の線などはいまは気にしないでください。
（解説の途中ですが上の画像の通りやる場合CUIでPanel Stack Splitterを使いノート風の画像を表示させ、上下左右の端に少し余白を少しやってELPlaylistを置く必要があります）

なんとなくELPlaylistがどんなものか理解できたでしょうか？
では実際にGroup headerの設定をします。
設定画面でgeneralのタブを選択しgroup rowを1にします。
これはGroup headerの縦幅をTrack listの何倍にするかを決める項目ですので、
Track listとGroup headerの縦幅は同じということになります。

次にstyleのタブを選択しtitle format script :のGroup headerを選択します。
最初からコードが書かれているので全部消します。
これから記述するコードはGroup header（イメージ画像の黄色い部分）に反映されます。
では

$font(フォント名,8,)

と入力します。これはこれから文字列を描画するときのフォントの設定です。
いつでも好きなフォントに変えられるように一番最初の行に記述しました。
[注意]フォント名と書いてあるところにふぉんとにフォント名と書かないでください^^;
例：$font(tahoma,8,)

次にアルバム名とアーティスト名を表示します。
関数は$drawtextを使います。
　>$drawtext(text,x,y,W,H,r-g-b,OPTIONS)
　> GDI文字列描画関数
　> textを座標(x,y)に出力
　>
　> OPTIONS
　> left hcenter right 水平アライン指定
　> top vcenter bottom 垂直アライン指定
　> noclip クリップしない
readmeに倣った形式でこのように入力します。

$drawtext(%album% - %artist%,4,0,$sub(%el_width%,12),%el_height%,192-064-064,left vcenter)

xywhは慣れないうちは分かりづらいと思うので画像を作りました

この四角形内で文字が描画されます。
whの部分には関数を使いました。%el_width%がイメージ画像の黄色の部分の横幅で、
%el_height%が縦幅です。$sub(%el_width%,12)は横幅から12を引いています。
これらはよく使うテクニックの一つなので覚えておきましょう。
r-g-bは色の指定です。RED GREEN BLUE（赤、緑、青）で0から255まで使えます。
例：0-0-0は黒で、255-255-255は白、255-0-0は赤です。

次にアルバム名とアーティスト名の隣に赤い横線を引きます。（面倒な記述の仕方をしているのでわからない方はとばしてください）
関数は$fillrectを使います。
　>$fillrect(x,y,w,h,r-g-b,RESERVED)

$fillrect($add($gettextwidth(%album% - %artist%,フォント名,8,),8),$div(%el_height%,2),
$sub(%el_width%,$add($gettextwidth(%album% - %artist%,フォント名,8,),16)),1,192-064-064,)

（２行になっていますが１行で記述してもなんら問題はありません）
これは矩形塗りつぶし関数ですが、高さを1にすることで線のように見せています。
xはアルバム名とアーティスト名 + 余白の計算をしています。
yは高さ / 2をして真ん中に線を引くようにしています。
wは横幅 - (アルバム名とアーティスト名 + 余白)をしています。
hは線なので1を入力しています。

因みにこのような記述もできます

$setcoordinate(1)
$fillrect($add($gettextwidth(%album% - %artist%,フォント名,8,),8),$div(%el_height%,2),
$sub(%el_width%,10),$add($div(%el_height%,2),1),192-064-064,)
$setcoordinate(0)

$setcoordinate(mode)これでx,y,w,hをx,y,right,bottomという指定にできます。
right,bottomで指定するので少し楽になりました。

これでGroup headerの部分はこれで設定完了です。
好みに合わせて線の右隣に%date%や%genre%、%discnumber%、%codec%など表示させてみるといいでしょう。

続いてtitle format script :のTrack listを選択します。
これから記述するものはイメージ画像の緑色の部分に反映されます。
まずはGroup headerでやったようにフォントを設定しておきます。

$font(フォント名,8,)

これは特に説明する必要はないでしょう。

次が難題です。リストに一枚のアルバムアートを表示しますが、
イメージ画像を見ると二つ目のアルバムでは一行だけでは画像の一部しか表示できなさそうな気がしますね。
（これはあとで解決しましょう）
しかもリストの曲が４曲未満だった場合も画像が途中で切れてしまいそうなのでそれを解決します。
generalのタブを選択しmin item numを4に設定します。（初期状態で4と設定されているはず）

次にアルバムアートを表示しますがその前に画像のパスを変数に入れてみます。
（画像はColumnsUI解説でやったような管理の仕方を前提に進めます）

↑Opera以外のブラウザでみると画像がみにくいのでクリックで拡大してください。

一応変数の意味です↓
　>変数 (プログラミング)
　>プログラミングにおいて、変数（へんすう、variable）とは、プログラムのソースコードにおいて、
　>扱われるデータを一定期間記憶し必要なときに利用できるようにするために、データに固有の名前を与えたものである。
　>一人一人の人間が異なる名前によって区別されるように、一つ一つの変数も名前によって区別される。
　>これにより、複数のデータを容易に識別することができる。変数を区別するための名前を特に識別子という。
　>また一般に、変数が表しているデータをその変数の値（あたい）という。
　>出典: フリー百科事典『ウィキペディア（Wikipedia）』
（変数は何度も使う文字列だったり文が複雑すぎる場合に少し見やすくしたりするときに使います。）

次のように記述します

$if($findfile($replace(%path%,%filename_ext%,folder.jpg)),
	$puts(coverpath,$replace(%path%,%filename_ext%,folder.jpg))
,
	$puts(coverpath,./images//nocover.png)
)

まずは$puts(coverpath,$replace(%path%,%filename_ext%,folder.jpg)を見てみます
これはcoverpathという変数を宣言し、その中に$replace(%path%,%filename_ext%,folder.jpg)を格納しています。
因みに$replace(%path%,%filename_ext%,folder.jpg)はTitleFormatting　初心者講座で
丁寧に解説したつもりなのでそちらを参照してください。
$if～の全文をみると、
もし、アルバムアートの画像があればアルバムアートのパスをcoverpathに、
なければnoimageの画像のパスをcoverpathに格納。
という意味です。
（noimageの画像のパスは各自違うと思うので自分で管理している場所のパスを入れましょう）

パスを格納できたので次こそアルバムアートを表示します
　>イメージ画像を見ると二つ目のアルバムでは一行だけでは画像の一部しか表示できなさそうな気がしますね。
　>（これはあとで解決しましょう）
これですが画像を表示する関数のyの部分をリストの２行目以降、
行数が増えるにつれて縦幅の分だけマイナスにずらしていけば問題を打破できます。
式としてはこんな感じ：一行目の画像のyの値 - {縦幅 * (グループ内の行数 - 1)}
（イメージ画像の二つ目以降の緑色を見れば少しイメージしやすくなると思います）
さらにちょうどいい関数がELPlaylistに用意されています。
　>%el_item_index2% : ダミー行を含むグループ内のトラックの個数
これも活用しましょう
関数は$imageabsを使います。

$imageabs(10,$sub(8,$mul(20,%el_item_index2%)),70,70,$get(coverpath),,)
$imageabs(-6,$sub(-5,$mul(20,%el_item_index2%)),96,96,./images/cover/tape.png,,)

$get(coverpath)で先ほどのアルバムアートのパスを呼び出しています。
追記：もっとよい記述の仕方がありました。（わかりやすいreadmeありがとう！）

$setworldtransform(2)
$imageabs(10,8,70,70,$get(coverpath),,)
$imageabs(-6,-5,96,96,./images/cover/tape.png,,)
$setworldtransform(0)

$setworldtransformで座標系を変更できます。
各トラックの原点(x,y)=(0,0)を同グループの最初のトラック行の左上とする。
ということなので先程の面倒な計算を省けます。

これでようやくできたかと思いきやELPlaylistの仕様上（v0.4.0b時点）ダミートラック行の描画をデフォルトでoff
とのことなのでこれだけではこんな風になってしまいます。

これでは何の画像なのかまさに解読不能なので次のように記述する必要があります。
（いままでのアルバムアートを表示する一連のコードです）

$if($findfile($replace(%path%,%filename_ext%,folder.jpg)),
	$puts(coverpath,$replace(%path%,%filename_ext%,folder.jpg))
,
	$puts(coverpath,./images/ibiza/cover/nocover.png)
)
$enabledraw(%el_is_empty%)
$imageabs(10,$sub(8,$mul(20,%el_item_index2%)),70,70,$get(coverpath),,)
$imageabs(-6,$sub(-5,$mul(20,%el_item_index2%)),96,96,./images/cover/tape.png,,)
$enabledraw(%el_is_valid%)
$imageabs(10,$sub(8,$mul(20,%el_item_index2%)),70,70,$get(coverpath),,)
$imageabs(-6,$sub(-5,$mul(20,%el_item_index2%)),96,96,./images/cover/tape.png,,)

$enabledraw(%el_is_empty%)はダミー行なら描画、
$enabledraw(%el_is_valid%)は有効な(ダミー行ではない)行なら描画という意味です。
（つまりどちらでも描画できるようにしています）
$imageabs(-6,$sub(-5,$mul(20,%el_item_index2%)),96,96,./images/cover/tape.png,,)はアルバムアートの上から画像をかぶせることによってアルバムアートがセロテープで貼り付けられているように見せることができます。
参考URL : http://kingdomsephiroth.deviantart.com/art/Scotch-Tape-for-CAD-84506274

次にトラックナンバー・タイトル・トラックの長さを表示します。

$if(%el_isplaying%,,$drawtext(%length%,0,0,$sub(%el_width%,10),%el_height%,064-064-064,vcenter right))
$if(%el_isplaying%,
$drawtext(%tracknumber%,96,0,%el_width%,%el_height%,064-064-255,vcenter)
$drawtext(%title%,128,0,%el_width%,%el_height%,064-064-255,vcenter),
$drawtext(%tracknumber%,96,0,%el_width%,%el_height%,064-064-064,vcenter)
$drawtext(%title%,128,0,%el_width%,%el_height%,064-064-064,vcenter)
)

%el_isplaying%は再生中か否かという意味なので、一行目をみると
もし再生中なら何もしない、再生中でなければトラックの長さを表示ということになります。
（再生中の時はこれからやるPer Secondというところで描画するので今は気にしないでください）
二行目は
もし再生中なら青色でトラックナンバー・タイトルを表示、
再生中でなければ黒でトラックナンバー・タイトルを表示ということになります。
いままでの知識でこの辺はらくらくわかると思います。

次に選択中の曲に波線を引いてみます。

$if(%el_selected%,
$drawtext(~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~,
91,12,$sub(%el_width%,0),%el_height%,192-064-064,vcenter)
,)

やや強引な記述ですがこれは
もし選択中ならば波線を引くということになります。

これでTrack listの設定は終わりです。

最後にPer Secondの設定をします
title format script :のPer Secondを選択します。
これは毎秒更新して描画する必要があるものを記述します。
最初からコードが書かれているので全部消します。
いつものようににフォントを設定しておきます。

$font(フォント名,8,)

続いてトラックの長さと再生中のトラックの長さを表示します。
これは毎秒更新しなければいけないのでPer Secondで書きます。

$drawtext(%playback_time% / %length%,0,0,$sub(%el_width%,10),%el_height%,064-064-255,vcenter right)

%playback_time%が再生中のトラックの長さですそれ以外はいつもの同じ関数なので理解できると思います。

ここまでで上にあった目標の画像と同じように作れたかと思います。
拙い文章でしたがここまで理解でしたでしょうか？
理解しづらい点ありましたらfoobar2000のコメントを利用するか、掲示板でお尋ねください。
奇数行だけ色を変えたりとかする方法もそのうち解説します

それではお疲れ様でした。

いままで使った関数は↓を見るかtitle formatting reference日本語訳などを参考にしてください。

readmeより一部引用(まずかったら連絡ください すぐ消します)

foo_uie_elplaylist.dll v0.4.5beta

●設定項目

<< Style >>
title format script : 描画を制御するTFを記述します。
   Track list         アイテム行の描画を制御するTF
   Group header       グループヘッダの描画を制御するTF
   Per Second         再生トラック行で毎秒更新される描画を制御するTF
                      (Now playing info系のTFが使用できます)

   デフォルトで入る記述では、アルバム画像が存在することが前提になっています。
   General->Title format Processor->__ART_PATH__ に適切な画像のパスを設定してください。

   title format scriptはpresetとして複数保存できます。


pseudo transparent : 
擬似的な背景透過を行います。処理が重くなることが多いです。
(重い場合、表示領域を狭くするとマシになるかもしれません)

system colour mode : 
選択アイテムやフォーカスアイテムの背景をシステム定義の背景色でtitle format scriptの起動前に描画しておきます。


<< General >>
主にグルーピングに関する設定ができます。
複数の設定をpresetとして保存できます。

group format : 
各トラックをグルーピングするためのTitleformatを記述します。
これをTFとして評価した結果が同じになる一続きのトラックをグループとして扱います。
group formatの結果が同じでも、プレイリスト上で離れているトラックは異なるグループとして扱われます。
group formatを"|||"で分割することで、階層的にgroupを設定できます。

 例: %album artist%|||%album%
子グループを持つグループには、トラックを割り当てられないという制約があります。
そのようなグループにトラックを割り当てようとすると、ダミーグループヘッダが挿入されます。
このテキストの最後に少し詳しく書いてあります。

sort format  : 
プレイリスト内のsortを行うためのTitleformatを記述します。
sortの実行は、コンテキストメニューから行います。
[注意] 自動ではsortしません。自動でsortしたい場合は、プレイリスト生成側の方で対応する必要があります。

group row    : 
"row height"を単位としたグループヘッダの高さを設定します。Titleformatが有効がです。
TFとして処理された結果が数値(0～16)を返さなければなりません。
このためグループヘッダの高さは、必ずrow heightの整数倍(0～16倍)になります。
[注意] グループ先頭トラックで、group rowは評価されます。

min item num : 
グルーピングした結果、グループ内のitemの数がこの設定値に満たない場合、ダミー行を挿入して水増しします。
Titleformatが有効で、TFとして処理した結果が0以上の数値を返さなければなりません。
(用途は、アルバム画像の表示範囲を確保することぐらい？)

[注意] グループ先頭トラックで、min item numは評価されます。
       ダミー行では、Track listで$enabledraw()を使わない限り、描画がoffになります。
       他の有効行と同様に描画したい場合は、$enabledraw(1)などで、描画をonにしてください。
       ダミー行のTitleformatはそのグループの最後の有効トラックとして処理されます。

playlist filter : 
enable playlist       filterがonの場合、プレイリストが切り替わったときにプレイリストの名前から
                      presetを自動で選択できるようにします。
enable all playlists  すべてのプレイリストでpresetが有効。
enable only on        指定のプレイリスト名に一致した場合presetが有効。
disable on            指定のプレイリスト名に一致した場合presetが無効。
preset                リストの順序で優先度が決まります。

指定するプレイリストの名前は、";"で区切ることで複数指定できます。TFやワイルドカードは無効です。

titleformat script : このpresetと関連付けたいtileformat scrpitsの名前を1つだけ設定できます。


enable playlist filter     playlist filterを有効にして プレイリスト名からpresetを自動で選択するようにします。

prioritize current preset  有効なpresetを探すときに、まず今選択されているpresetを最優先にします。

row height   : 1行の基本高さを設定します。

scrollbar : スクロールバーの表示状態の設定:default(自動で表示/非表示切り替え)/hide(常に非表示)/show(常に表示)、
            およびスクール量を設定します(0はシステムのデフォルト)。

title format preprocessor :  
各 Titleformat[Track list] [Group header] [Per Second] [Group row] [Min item num] を評価する前に、
テキストの置換を行います。
foo  :  C:\%album%.jpg  と設定した場合、
各 Titleformatの  %foo% が C:\%album%.jpg に置換されます。
デフォルトで設定されている__ART_PATH__なら %__ART_PATH__%となります。


<< behaviour >>
click action : 
リスト上でクリックしたときの動作を変更できます。
ただし、ダミー行では何もしません。

display only the focused group : 
フォーカスしたグループのみ表示します。他のプレイリスト表示パネル(Graphical Browserとか)との連携が前提。

hide all items when playlist is changed : 
デフォルトでグループヘッダのみの表示にして、アイテム行を隠します。
 auto-collapse                          : 
 フォーカスしたグループ以外アイテム行を隠します。
 このオプションがonだと、グループヘッダでsingle clickするだけで
 アイテム行の表示/非表示が切り替わるようになります。
 またクリックアクションで開いたグループは自動では閉じません。
 再生トラックに追従させたい場合、Playback/Cursor Follows Playbackと組み合わせて使ってください。

hide items which have no group header   : 
グループヘッダがない(group rowが0な)グループのitemでも隠すようにします。

update every second : 
再生トラックのPer Secondを有効にする。より正確には、毎秒単位の描画の更新をon/offするだけです。

move items with drag and dop : 
選択アイテムをDrag & Dropで移動できるようにします。
このオプションがoffでも、[Alt] 押しながらの Drag & Dropで移動できます。


●ショートカットキーバインド
Ctrl-c : Copy
Ctrl-v : Paste
Ctrl-x : Cut
Ctrl-a : 全選択
Delete : プレイリストからトラックを除去
Alt-[Up]/[Down] : 選択トラックの移動  ("hide all items when playlist is changed" が offであること)
[注意]: 本体のGeneral->Keyboard Shortcutsの設定が優先されます。

##[Alt] + Drag & Drop でも選択トラックの移動できます。


●拡張コマンドリファレンス
(ここに書いてあるもの以外にもfoobar本体のデフォルトTFはだいたい使えます)

//////////fields///////////

%el_width%
    行の表示領域の横幅を返す
    [Track list] [Group header] [Per Second]


%el_height%
    行の表示領域の高さを返す。
    ( グループ行は%el_height% = %el_group_row% * %el_row_height%
      トラック行は%el_height% = %el_row_height% )
    $setworldtransform()の影響を受ける。
    [Track list] [Group header] [Per Second]


%el_isplaying%
    再生中か否か 
    [Track list] [Group header] [Per Second]


%el_selected%
    プレイリスト上で選択中か否か
    [Track list] [Per Second]


%el_focused%
    プレイリスト上でフォーカス中か否か
    [Track list] [Per Second]


%el_row_height%
    行の基本的な高さを返す。
    (グループヘッダ行では%el_height%と異なる。)
    [Track list] [Group header] [Per Second]


%el_group_row%
    グループヘッダ行の高さが%el_row_height%何個分か。
    グループヘッダでは%el_height% = %el_group_row% * %el_row_height% の関係
    [Track list] [Group header] [Per Second]


%el_item_count%
    グループ内のトラックの個数
    [Track list] [Group header] [Per Second] [Group row] [Min item num]
  

%el_item_count2%
    ダミー行を含むグループ内のトラックの個数
    [Track list] [Group header] [Per Second]


%el_direct_item_count%
    グループに直接割り当てられてるトラックの個数
    特殊な場合を除いて、サブグループを持つグループでは0になる
    [Track list] [Group header] [Per Second] [Group row] [Min item num]


%el_item_index%
    グループ内のトラックのインデックス(0から数えて)
    ダミー行ではカウントアップは中止される。
    [Track list] [Per Second]


%el_item_index2%
    グループ内のトラックのインデックス(0から数えて)
    ダミー行でもカウントアップされる。
    [Track list] [Per Second]


%el_total_group_count%
    グループの個数(すべてのグループヘッダの個数)
    [Track list] [Group header] [Per Second] [Group row] [Min item num]


%el_total_group_index%
    グループのインデックス(リスト上でのグループヘッダのインデックス)
    [Track list] [Group header] [Per Second] [Group row] [Min item num]


%el_group_count%
    同じ親グループに属しているグループの個数
    [Track list] [Group header] [Per Second] [Group row] [Min item num]


%el_group_index%
    親グループから見たときのグループのインデックス(0から数えて)
    [Track list] [Group header] [Per Second] [Group row] [Min item num]


%el_group_depth%
    現在のグループの深さ(0から数えて)
    [Track list] [Group header] [Per Second] [Group row] [Min item num]


%el_subgroup_count%
    サブグループの数
    子グループの数であり、孫グループの数などはカウントされない。
    [Track list] [Group header] [Per Second] [Group row] [Min item num]


%el_subgroup_count2%
    サブグループの累積数
    孫グループ以降も数にカウントされる。
    [Track list] [Group header] [Per Second] [Group row] [Min item num]



%el_group_format%
    現在のグループでgroup formatをTFで処理した結果を返す。
    [Track list] [Group header] [Per Second] [Group row] [Min item num]

%el_is_collapsed% (%el_is_hide_item%)
    アイテム行を隠しているか否か。
    (グループヘッダのみの表示かどうか)
    [Group header] [Group row] 


%el_is_empty%
    ダミー行か否か。
    (単に%el_is_valid%と逆)
    [Track list] [Per Second]
    サブグループ構造を上手く構成できない場合に、ダミーとして入れられるグループ行か否か。
    [Group header] [Group row] [Min item num]


%el_is_valid%
    有効な(ダミー行ではない)行か否か。
    [Track list] [Per Second]
    [Group header] [Group row] [Min item num]


%el_is_noheader%
    グループヘッダがあるかないか
    (%el_group_row%が0なら1)
    [Track list] [Per Second]


%el_sum_length%
    グループのトラックの長さ合計 [hh:]mm:ss
    [Track list] [Group header] [Per Second] [Group row] [Min item num]


%el_sum_length_seconds%
    グループのトラックの長さ合計 (秒)
    [Track list] [Group header] [Per Second] [Group row] [Min item num]


%el_backcolour%
    背景色をr-g-b形式で返す。
    r-g-b-a形式したい場合は、
    %el_backcolour%-192 などでalpha値を追加できる。
    [Track list] [Group header] [Per Second]


%el_preset_index%
    現在のpresetのインデックスを返す。
    [Track list] [Group header] [Per Second] [Group row] [Min item num]
%el_preset_name%  現在のpresetの名前を返す。
    [Track list] [Group header] [Per Second] [Group row] [Min item num]




////////functions///////
描画制御関数
[Track list], [Group header], [Per Second]


$font(name,size,OPTIONS)
    フォント設定
    OPTIONS: bold italic underline strikeout

    例 $font(Tahoma,10,bold italic)


$drawstring(text,x,y,W,H,r-g-b-a,OPTIONS [,OPTIONS2])
    文字列描画関数
    <<注意>>文字列はこの関数とdrawtextとdrawtextexでしか表示できない。
    textを座標(x,y)に出力
    TrueTypeフォントしか使えないかも。使えないフォントについてはdrawtextだと多分使える。


    OPTIONS   アライン指定、描画品質指定、クリップ指定などをする。
      left hcenter right       水平アライン指定
      top  vcenter bottom      垂直アライン指定

      nowrap                   ラップアラウンドしない

      noaa                     ClearTypeもアンチエイリアスも無効。
      aa                       アンチエイリアスをかけるモード。
                               ClearTypeが効かないフォントでもアンチエイリアスがかかる。
      hq                       最高品質で描画するモード。ClearTypeモード。(default)
      glow_aa                  glowの特殊モードを使用するオプション

      trimchar  trimword       表示範囲に収まらない場合のトリミングの設定
      elipchar  elipword       表示範囲に収まらない場合に最後を･･･に置き換える設定

      mempos                   getlastposで、描画した座標を取得できるようにする。   



    OPTIONS2 (実験的オプション, experimental option)
      glow効果の条件を指定する。
      OPTIONSでglow_aa指定の場合のみ、outlineとsemiboldは使用可能になります。

      glow:expand:colour[:strength]       glowオプション
         expand   [0-5]
         colour   r-g-b
         strength [0-3]                   glow_aaの場合は無効

      offset:x:y
         x                     glowの水平方向のオフセット
         y                     glowの垂直方向のオフセット


      outline:colour           文字の縁取りを薄く指定の色で描画します (if glow_aa)
          colour   r-g-b
      semibold                 文字を少しだけ太めにする (if glow_aa)



      ※ これらの仕様は変更される可能性があります。
         特にglowの描画方法の変更、およびoutlineとsemiboldの廃止の可能性があります。
      ※ glow処理は重いです。(特にpseudo transparentのとき)

    例  $drawstring(abcd,10,10,,,255-128-64-128,)
        $drawstring(abcd,10,10,,,255-128-64-128,left vcenter,glow:2:255-255-255)
        $drawstring(efgh,10,10,,,255-255-255,vcenter glow_aa,glow:1:32-168-268 semibold)
        $drawstring(wxyz,10,10,,,255-255-255,glow_aa,glow:0:32-168-268 semibold offset:2:1 outline:32-168-268)
        $drawstring(wxyz,10,10,,,255-255-255,,glow:2:32-168-268:1)
        $drawstring(wxyz,10,10,,,255-255-255,elipchar)



$drawrect(x,y,w,h,R1-G1-B1-A1,R2-G2-B2-A2,OPTIONS)
    矩形描画関数
    座標(x,y)にサイズ(w,h)で矩形を描画
    R1-G1-B1-A1  内部色
    R2-G2-B2-A2  枠の色

    OPTIONS
      aa:アンチエリアスをかける

    例  $drawrect(0,50,50,50,255-128-64-128,,aa)




$gradientrect(x,y,w,h,r1-g1-b1-a1,r2-g2-b2-a2,OPTIONS,peak_point)
    矩形内をグラデーションで塗りつぶす描画関数
    座標(x,y)にサイズ(w,h)で矩形を描画
    r1-g1-b1-a1  グラデーション開始色
    r2-g2-b2-a2  グラデーション終了色

    OPTIONS
      vertical    垂直方向グラデーション
      horizontal  水平方向グラデーション
      aa          アンチエリアスをかける
      nonlinear   グラデーションの仕方が非線形

    peak_point: 0-100
                  グラデーションの変化の仕方をずらす。
                  0はデフォルトで、r1-g1-b1-a1 --> r2-g2-b2-a2
                  50のときは、r1-g1-b1-a1 --> r2-g2-b2-a2--> r1-g1-b1-a1、となる。


    例  $gradientrect(0,50,50,50,255-128-64-128,255-255-255,vertical aa)


$drawblurrect(x,y,w,h,colour,level)
    輪郭をぼかして矩形を塗りつぶす描画関数
    level:1-7


$drawfocusrect(x,y,w,h)
     指定の矩形にフォーカスを示す枠を点線で描画する関数。



$drawthemerect(x,y,w,h,control_name,partId,stateId)
     VisualStyleを使って矩形内にコントロール(ボタンやプログレスバー)を描画する関数。
     画像として描画するだけなので実用性は低いかもしれない。
     VisualStyleで定義されていないコントロールは描画されない。
     少なくともWindowXP以上必須。

     control_name  : 描画したいコントロールの種類の名前を指定する。以下のいずれか。
        window button rebar toolbar status listview header progress tab trackbar tooltip treeview spin scrollbar
        edit combobox taskbar taskband startpanel explorerbar

     partId:  描画したい部品のID。目安としてコントロールごとに以下の範囲の数値が使用出来る可能性が高い。
              ほとんどの場合、定義されているものの方が少ないみたい。
        window: 1-37
        button rebar listview tooltip: 1-5
        toolbar: 1-6
        status treeview taskband: 1-3
        header spin: 1-4
        progress: 1-4
        tab trackbar scrollbar:1-10
        edit: 1-2
        combobox: 1
        taskbar: 1-8
        startpanel: 1-11
        explorerbar: 1-12


     stateId: 選択などの状態のID。 状態を持たない部品の場合は0を指定する。
              stateIdが0か1で描画されないなら、その部品は定義されていない。

     例: $drawthemerect(0,0,%el_width%,%el_height%,tab,10,0)      //tabのbody部分を描画
         $drawthemerect(,,,,progress,3,0)  //プログレスバーのバーを描画


$drawroundrect(x,y,w,h,w2,h2,R1-G1-B1-A1,R2-G2-B2-A2,RESERVED)
    角を丸めた矩形描画関数
    座標(x,y)にサイズ(w,h)で角を丸めた矩形を描画。
    角の丸みは、w2,h2で調整できる。
    w > 4*w2 && h > 4*h2 を満たす必要がある。
    R1-G1-B1-A1  内部色
    R2-G2-B2-A2  枠の色

    例  $drawroundrect(10,20,50,50,4,4,255-255-128-255,,)
 


$drawellipse(x,y,w,h,R1-G1-B1-A1,R2-G2-B2-A2,RESERVED)
    楕円描画関数
    座標(x,y)にサイズ(w,h)で楕円を描画
    R1-G1-B1-A1  内部色
    R2-G2-B2-A2  枠の色



$drawtriangle(x1,y1,x2,y2,x3,y3,R1-G1-B1-A1,R2-G2-B2-A2,OPTIONS)
    (x1,y1),(x2,y2),(x3,y3)を頂点とする三角形描画関数
    R1-G1-B1-A1  内部色
    R2-G2-B2-A2  枠の色

    OPTIONS
      aa:アンチエリアスをかける

    例  $drawtriangle(10,5,20,10,10,15,200-100-100,,aa)



$imageabs(x,y,w,h,path,OPTIONS,n,alpha,OPTIONS2)
    座標(x,y)にサイズ(w,h)で path で指定される画像を表示する。
    リサイズ後の画像をメモリ上に保持して、次に参照された場合の処理効率をあげる。
    参照されなった画像は、そのうちメモリ上から削除される。
    w,hを省略するとオリジナル画像サイズで表示し、キャッシュする。
    (メモリ上にすでにキャッシュされてる場合は、キャッシュしてある画像サイズ)

    複数の縮小率を扱いたい場合、
    縮小した後に拡大されると画質が悪い。
    nodisplayやnoexpansionなどを利用して、
    使用する縮小率の中で最も大きい縮小率で最初にメモリのキャッシュするのがよい。

    画像が存在すればtrue、しなければfalseを返す。

    dipsplays the image specified by path.
    after the image is resized, it is cached on the memory. 
 
    path: 画像の絶対パス(ワイルドカード不可)

    OPTIONS
       nokeepaspect アスペクト比を維持しない(nodisplay,archive,icon以外のオプションと排他)
       left
       right
       top
       bottom
       nodisplay    メモリに読み込むだけで表示しない
       noexpansion  縮小はするが、拡大しない
       archive      archive reader経由でpathの画像を表示する。
                    pathの書式はarchive readerに依存するが、書庫の絶対パス|書庫内ファイルパス が基本。
                    例:  C:\aaa\image.zip|bbb/ccc.jpg
       icon         pathで指定されるiconファイル(*.ico)を表示する。 (archiveとは排他)

    n   rotateflipのためのインデックス
        1: 90
        2: 180
        3: 270
        4: 左右反転 
        5: 90 + 左右反転 
        6: 上下反転 
        7: 90 + 上下反転 

    alpha  0-255
        透明度(transparency)
 

    OPTIONS2 (shadow effect)
       glow:expand:colour
       offset:x:y


    例  $imageabs(10,10,50,50,C:\%album%.jpg)
        $imageabs(10,10,50,50,C:\%album%.jpg,left top)
        $imageabs(10,10,50,50,C:\%album%.jpg,,6)
        $imageabs(10,10,50,50,C:\%album%.jpg,bottom,,128)
        $imageabs(10,10,50,50,C:\%album%.jpg,bottom,,,glow:2:0-0-0 offset:4:4)


$imageabs_rc(rw,rh,srcx,srcy,srcw,srch,x,y,path,OPTIONS,n,alpha,OPTIONS2)
    リサイズしてクリップした画像を表示する。
    path で指定される画像をサイズ(rw,rh)にリサイズ後、
    その部分領域(srcx,srcy,srcw,srch)を座標(x,y)にサイズ(srcw,srch)で表示。

    メモリ上に(rw,rh)でキャッシュする。
    TFを評価したときに(rw,rh)が変化すると、画像を再読み込みする。
    そのため、rw, rhは固定値で指定すべき。

    画像が存在すればtrue、しなければfalseを返す。

    OPTIONS (imageabs参照)
    nokeepaspect アスペクト比を維持しない
    nodisplay    メモリに読み込むだけで表示しない
    archive
    icon
    (  left      
       hcener 
       right
       top
       vcenter
       bottom ) 
    n   rotateflipのためのインデックス
        1: 90
        2: 180
        3: 270
        4: 左右反転 
        5: 90 + 左右反転 
        6: 上下反転 
        7: 90 + 上下反転 

    alpha  0-255
        透明度(transparency)

    
    例
    $imageabs_rc(200,100,0,0,100,50,10,10,C:\%album%.jpg,,6,192)
    $imageabs_rc(200,100,0,0,200,100,10,10,C:\%album%.jpg,,)  ( = $imageabs(10,10,200,100,C:\%album%.jpg,left top,,) )
    $imageabs_rc(150,120,0,0,150,120,20,15,C:\%album%.jpg,hcenter vcenter,)  ( = $imageabs(20,15,150,120,C:\%album%.jpg,,,) )

///////描画補助/////////

$getlastpos(elem)
   画像表示関数imageabs, imageabs_rcの直後で、実際に画像を描画した座標を取得する。
   また、measurestringの結果を取得するときにも使う。
   drawstringの場合は、mempos指定した場合のみ直後に座標を取得できる。

   elem  取得したい要素を指定する。
        x :  left
        y :  top
        w :  width
        h :  height
        r :  right
        b :  bottom

   例:  
        $setworldtransform(2)
        $puts(img_path,C:\%album%.jpg)
        $imageabs(10,4,100,100,$get(img_path),top noexpansion,)
        $imageabs($getlastpos(x),$getlastpos(b),$getlastpos(w),20,$get(img_path),top nokeepaspect,6)
        $gradientrect($getlastpos(x),$getlastpos(y),$getlastpos(w),$getlastpos(h),%el_backcolour%-128,%el_backcolour%-255)
        $setworldtransform(0)


$measurestring(text,x,y,W,H,OPTIONS)
   $drawstringで文字列を描画した場合の表示領域を計算する。
   また、結果として、表示領域の水平幅を返す。
   表示領域の結果は$getlastposで取得する。
   OPTIONSは$drawstringと同じ。
   また、drawstringで、glow_aaでglow効果をかけた場合、その表示範囲はmeasurestringの結果とは一致しないことがある。  



$getimagewidth(path), $getimageheight(path)
    pathで指定される画像が$imageabs $imageabs_rcで メモリにキャッシュ中の
    画像であれば、そのリサイズ済みの水平幅、垂直幅を返す。
    つまり$imageabs $imageabs_rcの後ろでしか使用できない。
    nokeepaspectを適用していなければアスペクト比を計算できる。



$setcoordinate(mode)
$setcoordinate(0,X,Y,W,H)
$setcoordinate(1,X,Y,R,B)
    描画関数で引数に "(x,y,w,h)" 指定を持つものを、(x,y,right,bottom)指定に変える。
    $imageabs_rcや$drawtriangleに対しては無効。
    またX,Y,W,Hを指定すると、描画関数で座標指定を省略した場合のデフォルト描画位置を変更することができる。
    $imageab, $imageabs_rcや$drawtriangleに対しては無効。
    X,Y,W,Hを省略した場合は、デフォルト値にリセットされる。

    mode : 座標の指定モード
      0    default  (x,y,w,h)
      1    (x,y,right,bottom)

 (x,y)<------w------->
    |----------------|
    |                |
  h |                |
    |                |
    |________________| 
                    (right,bottom)



$setworldtransform(mode)
    座標系を変更する。
    座標系を変えても別の行に描画できるわけではない。
    Group全体や複数のトラックをまたいだ描画を行うときに便利なはず。
    特に画像を表示する場合に有効。
    (例は初期TFを参照。)

    mode 
    0:default
      各トラックの原点(x,y)=(0,0)は、それぞれのトラックの左上。

    1:group 共通座標系
      Groupと各トラックの原点(x,y)=(0,0)をGroup行の左上とする。
      %el_height% = (%el_item_count2% + %el_group_row%) * %el_row_height%になる。

    2:item list共通座標系
      各トラックの原点(x,y)=(0,0)を同グループの最初のトラック行の左上とする。
      %el_height% = %el_item_count2% * %el_row_height%になる。


default
  (0,0)
     |----------------|
     |________________| 
                    (el_width,el_height)

group 共通座標系
  (0,0)
     |----------------|
     |  group header  |
     |----------------|
     |----------------|
     |----------------|
     |----------------|
     |________________|
                    (el_width,el_height)

item list共通座標系
     |----------------|
     |  group header  |
(0,0)|----------------|
     |----------------|
     |----------------|
     |----------------|
     |________________|
                    (el_width,el_height)


$enabledraw(mode)
    描画系関数($draw**** や$imageabs**)の描画を行うかどうかを制御する。
    この関数が再び呼ばれるまでの描画をon/offする。
    主にダミー行での描画の制御に使う。

    mode
    0: 描画系関数無効
    1: 有効

    例:   $enabledraw(1)
          $enabledraw(%el_is_valid%)



$getsyscolour(index)
    システムカラーをr-g-b形式で返す。

    index:[0-30] システムカラーのインデックス


$averagecolour(colour1,colour2[,･･･])
    r-g-b-a形式の色の平均する。
    (colour1 + colour2 +･･･)/N

$blendcolour(colour1,w1,colour2,w2,[,･･･])
   r-g-b-a形式で重みつき平均を返す。
   (w1*colur1 + w2*colour2 + ･･･ + wN * colourN)/ (w1 + w2 + ･･･ + wN)

$addcolour(colour1,colour2[,･･･])
    r-g-b-a形式の色を加算する。
    colour1 + colour2 + ･･･ + colourN

$subcolour(colour1,colour2[,･･･])
    r-g-b-a形式の色を減算する。
    colour1 - colour2 - colour3 ･･･ - colourN


/////////////その他/////////////////
ここの関数は、[Track list] [Group header] [Per Second] [Group row] [Min item num]で使える。


$getgroupformat(group_index)
    group_indexで指定されるグループでgroup formatをTFとして処理した結果を返す。
    group_index : 指定するgroupが何番目か(0から数えて)
    %el_group_format% = $getgroupformat(%el_total_group_index%)の関係



$findfile(path)
    path(ワイルドカード可)で指定されるファイルが存在すれば、最初に見つかったファイルのパスを返す。
    ファイルが無ければ何も返さない。
    


$el_scale(val,factor[,DIV])
     val * factor/100 または val * factor / DIVを返す。
     valとfactorが大きすぎるとオーバーフローします。



/////////////////////////////
<<GDI系描画関数>>
GDIで描画する。シンプルだけど処理が軽い場合がある。

$drawtext(text,x,y,W,H,r-g-b,OPTIONS)
     GDI文字列描画関数
     textを座標(x,y)に出力

     OPTIONS
       left hcenter right       水平アライン指定
       top  vcenter bottom      垂直アライン指定
       noclip                   クリップしない


$drawtextex(text,x,y,W,H,r-g-b,OPTIONS)
     GDI文字列描画関数2
     textを座標(x,y)に出力

     OPTIONS
       left hcenter right       水平アライン指定
       top  vcenter bottom      垂直アライン指定
       noclip                   クリップしない
       wrap                     ラップアラウンド許可指定(vcenter、bottomとは排他)
       end_ellipsis             テキストがクリップされる場合、テキストの最後を...に置き換える

     例 $drawtextex(text,0,0,%_width%,%_height%,0-0-0,hcenter vcenter end_ellipsis)



$gettextwidth(text,FONTNAME,SIZE,OPTIONS)
     GDI(drawtext,drawtextex)でtextを描画したときのテキストの水平幅を返す。
     fontの指定も可(オプションは$font参照)。font指定は省略可


$gettextheight(FONTNAME,SIZE,OPTIONS)
     GDIで描画したときのテキストの垂直幅を返す。
     fontの指定も可(オプションは$font参照)。font指定は省略可


$fillrect(x,y,w,h,r-g-b,RESERVED)
     矩形塗りつぶし関数


////////////////////////////


==============================================================================

[注意]: drawstringとdrawtextとdrawtextex 
         はそれぞれ違う方法で文字を描画しており、それぞれ一長一短があります。
        各関数で出来ることと出来ないことがあっても(おそらく)バグではないです。
        とりあえずdrawtextを使っておけば問題はないと思います。

[余談]: 関数の中で色を引数にとるところでは r-g-b-a形式以外にも $rgb(r,g,b)で指定したりできる(はず)。
        またdrawtextのみ、引数のtext部分に、$rgb関数や$transition関数を使用して色の指定をすることが出来る(はず)。


==============================================================================

Appendix
グループ構成の制約
このような子グループを持つグループ(group1)がtrackを持つ構成はとれません。
group1
  |-group2
  |   |-track1
  |   |-track2
  |
  |-group3
  |   |-track3
  |   |-track4
  |   |-track5
  |
  |-----track6
  |-----track7

この場合、上の構成は下のように変換されます。
group1
  |-group2
  |   |-track1
  |   |-track2
  |
  |-group3
  |   |-track3
  |   |-track4
  |   |-track5
  |
  |-group4(dummy)
  |   |-track6
  |   |-track7