スクリプトの仕様

「スクリプト」は、プレイヤーに主に画面表示の処理を行わせるときに使用される独自のプログラミング言語と、それで書かれたファイルのことを指します。 プレイヤーの外観を決める「スキン」の内容は全てこの言語で書かれています。他に、プレイヤーに自動処理を行わせるときにも利用されます。
例えば

pos=5*10
mes=arX MusicPlayer!

というスクリプトは、プレイヤーのメイン画面の左から 5px 上から 10px の位置に "arX MusicPlayer!" という文字を表示させます。

一行に一つの命令を書きます。複数行に渡るスクリプトは、上の行から順番に実行されます。
命令にはそれをどのように実行するかを決めるオプション、すなわち「パラメータ」が指定でき、例えば上の例では pos という表示位置を決める命令に 5 と 10 というパラメータが指定されています。 命令とパラメータは =(半角のイコール) で区切り、パラメータ同士は *(半角のアスタリスク) で区切ります。 どんなパラメータをいくつどういう順番で指定できるかは命令により異なり、パラメータの指定が必要ない場合もあります。
スクリプト中に注釈を入れたい場合は

::: 文字を表示

のように :::(半角のコロンを三つ) 並べることが推奨されていますが、実は命令として存在しない文字列はプレイヤーにより無視されるのであまりこだわらないでも大丈夫です。

座標指定

画面上の位置は、画面左端(→X座標)及び上端(→Y座標)からの距離で表現します。 例えば pos のパラメータは [X座標]*[Y座標] のように指定する、と各命令の解説にありますから、スクリプト中に

pos=5*10

という命令があれば、これは "画面左から 5px 上から 10px の位置に何かをしようとしている" と分かります。具体的には mes で文字を表示したり imgdraw で画像を描画したり、objxset でオブジェクトを設置したりする前に pos で位置を指定します。オブジェクトについては次々項で解説しています。

ファイル名指定

imgload は画像ファイルを読み込み、表示の準備をする命令です。 ここで、画像ファイル名は、例えば arX MusicPlayer が C:\arxmp\ フォルダにインストールされているとして

imgload=C:\arxmp\s\test\abc.bmp

のような絶対パスや、

imgload=test\abc.bmp

という C:\arxmp\s\ を省略した相対パスで指定します。
絶対パスはユーザーの環境に依存するので通常は使いません。

オブジェクト

Windowsが提供するインターフェース、つまりユーザーが触る部分としてはボタンやリストボックス、チェックボックスなどがあります。スクリプトの解説ではこれらを総称してオブジェクトと呼んでいます。 オブジェクトは、スキンが読み込まれるときに一度だけ行われる初期化処理の中でメイン画面上に設置されます。他の場合に実行されるスクリプトの中でも設置できるようになっていますが、オブジェクトの設置数には限界(64コまで)があり、更に一度設置したオブジェクトは次にスキンを読み込むときまで破棄出来ないことからエラーが起きかねないので止めて下さい。(cf. スキンの仕様)
オブジェクトの持つ機能は設置する際に「識別子」や「機能番号」により指定します。また、オブジェクトには設置された順にID(0〜)が割り振られ、後からそのスタイルを変更したりするときはそのIDでオブジェクトを区別します。IDをオブジェクトの持つ機能から割り出すための「特殊キー」が用意されています。詳しくは後の解説をご覧下さい。

機能番号

ver.403.00α1から導入された概念で、プレイヤーの様々な機能を16進法8ケタの数字で表したものです。(cf. 全機能一覧)
16進法とは、数を、数字を0123456789ABCDEFの16通りとして表す方法のことで、スクリプトでは頭に $ をつけることで10進数(フツウの数)と区別しています。例えば

• $12 = 16×1 + 2 = 18
• $4B = 16×4 + B = 16×4 + 11 = 75
• $A3F = 16×16×A + 16×3 + F = 256×10 + 48 + 15 = 2623
• ...

です。

exefunc=$12040000*C:\

pos=5*5
objsize=270*21
objxset=$23000000*再生中の音楽のファイル名をクリップボードにコピー
objstyl=%o.$23000000%*9
objstyl=%o.$23000000%*13

のようにして使います。 正直言って分かり辛いので、複雑な機能を使うとき以外は、プレイヤーの機能は次項の識別子を使って表した方が良いです。
% で挟んである部分は「特殊キー」です。解説は「識別子」の次の項に書いてあります。

識別子

プレイヤーの機能を表す文字列のことです。下表のような種類があり、スクリプト中では

exefunc=%f.play%

pos=5*5
objsize=100*21
objxset=next*次のファイルを再生
objstyl=%o.next%*6

のようにして使います。

識別子	機能	(機能番号)	(サポート状況)
ウィンドウ操作
listwindow	リスト画面を開く	$01200006	ver.402.00〜
closelistwindow	リスト画面を閉じる	$01400006
listarea	メイン画面のリスト領域を開閉	$02080000
infowindow	音楽情報画面を開閉	$01080005
minimize	メイン画面を最小化/元に戻す	$05080000
showfolder	再生中の音楽ファイルの親フォルダを開く	$03080001
showproperty	〃　　　　　プロパティを開く	$04080001
cfgvolume	音量調整画面を開く	$21080002
exit	プレイヤーを終了	$01000000
メニュー表示
favorite	お気に入りメニューを表示	$06000008	ver.402.00〜
savefavr	お気に入り保存メニューを表示	$06000009
popup	右クリックメニューを表示	$06000000
音楽再生
play	選択されている音楽を再生	$07080000	ver.402.00〜
prev	再生中の音楽の一つ前を再生	$07080003
next	再生中の音楽の一つ後を再生	$07080002
pause	再生中の音楽を一時停止/再開	$08000000
stop	再生中の音楽を停止	$09000000
再生リスト編集
mainlist	再生リスト(リストボックス)	$E0000000	ver.402.00〜
mainlistc	〃　　(コンボ─)	$E1080003
addfolderchk	サブフォルダまで検索(チェック─)	$250a1000
mode	再生モードを切り替え	$0A080000
repmode	リスト繰返し再生設定切り替え	$0A080010
addfile	再生リストにファイルを追加	$11000000
addfolder	再生リストにフォルダ内ファイルを追加	$12000000
clearlist	再生リストを空に	$15100000
clearfile	再生リストの選択項目を除去	$15080000
rename	〃　　　　　変名	$17080000
delete	〃　　　　　ごみ箱に廃棄	$16080000
moveup	〃　　　　　上に移動	$18080000
movedown	〃　　　　　下に移動	$19080000
showproperty_s	〃　　　　のプロパティを開く	$03080000
showfolder_s	〃　　　　　親フォルダを開く	$04080000
checklist	再生リスト中の全ファイル存在確認	$14100000
sortlist	再生リスト中の全項目名前順並び替え	$13100000
loadlist	再生リスト内容をファイルから読み込み	$1A000000
savelist	再生リストをファイルに保存	$1B000000
ユーザー定義ボタン
userdef1 userdef2 userdef3 userdef4 userdef5	スキンのユーザー定義エリアに書かれたスクリプトを実行(cf. スキン ユーザー定義エリア)	$30000010〜$30000014	ver.402.00〜

特殊キー

スクリプト中に %(半角のパーセント) で挟んだ文字列を挿入すると、それを含む行が実行される前にプレイヤーの情報などに置換されます。スキン中で音楽情報を表示させる処理などは全てこの機能を利用しています。

キー		置換される内容	(サポート状況)
%p.	fpth%	再生中の音楽のフルパス	ver.402.00〜
	file%	〃　　　ファイル名
	indx%	〃　　　再生リスト中での位置(通し番号)
	posi%	〃　　　再生位置 "HH時間MM分SS秒"
	posh%	〃　　　再生位置 "HH"
	posm%	〃　　　再生位置 "MM"
	poss%	〃　　　再生位置 "SS"
	lgth%	〃　　　長さ "HH時間MM分SS秒"
	lgtH%	〃　　　長さ "HH"
	lgtm%	〃　　　長さ "MM"
	lgts%	〃　　　長さ "SS"
	auth%	〃　　　著作者
	titl%	〃　　　タイトル
	atit%	〃　　　含まれるアルバム名
	rele%	〃　　　発売日
	type%	〃　　　ファイル種 (cf. 言語ファイル .Type)	ver.403.00α1〜
	form%	〃　　　フォーマット情報	ver.402.00〜
	comm%	〃　　についてのコメント
	stat%	音楽の再生状態(cf. 言語ファイル .Status)
	mode%	再生モード(cf. 言語ファイル .Mode)
	alias%	プレイヤーが使用するMCIのエイリアス名	〜ver.402.15
%s.	user%	ユーザー名	ver.402.00〜
	col%	Windowsが利用するボタンの表面色 "R*G*B"
	cols%	〃　　　　　　　影色 "R*G*B"
	repmode%	再生リストを繰返し再生する設定の状況 (cf. 言語ファイル .RepMode)	ver.402.04〜
	dir%	arxmp.exe があるフォルダのパス (末尾 \ 無し)	ver.403.00α1〜
	scrl.x%	スクロール情報表示位置(X座標)(※1)
	scrl.y%	〃　　　　位置(Y座標)
	scrl.pos%	〃　　　　位置 "X*Y"
	seek.x%	シークバー表示位置(左上X座標)(※2)
	seek.y%	〃　　　位置(左上Y座標)
	seek.pos%	〃　　　位置 "左上X*Y"
	seek.ex%	〃　　　位置(右下X座標)
	seek.ey%	〃　　　位置(右下Y座標)
	seek.epos%	〃　　　位置 "右下X*Y"
	seek.width%	〃　　　幅
	seek.height%	〃　　　高さ
	seek.size%	〃　　　サイズ "幅*高さ"
	seek.rect%	〃　　　矩形領域座標 "左上X*Y*右下X*Y"
%v.	(※3)%	スキン変数の中身	ver.402.00〜
%o.	(※4)%	オブジェクトID	ver.402.00〜
%f.	(※5)%	機能番号	ver.403.00α1〜

• (※1) スクロール情報とはメイン画面で右から左へ流れる音楽情報のことです。
  従来は音楽再生中に継続的に実行されるスクリプト中で

  pos=5*10
  messcrl
  

  としてスクロール情報を表示していましたが、messcrl 命令は内部で pos 命令の機能を呼び出しており、これを表示位置の設定＋文字表示の基本的な２命令に分離して処理の流れを分かりやすくする試みとして導入されたキーが %s.scrl.x% などです。

  ::: まずスクロール情報の表示基準位置を指定
  pos=5*10
  pos=%scrl.x%*%scrl.y%
  ::: ↑のX座標は表示更新ごとに左にずれて行くから
  ::: ↓がスクロールして見える
  mes=%p.scrl%
  

  逆に分かり辛くなってしまったでしょうか(^^; %s.scrl.x% は、現在 pos で指定されているX座標から"画面更新ごとに大きくなり表示したスクロール文字列左端がそのX座標より左に出るとき0に戻る"値を引いた数として置換されるのです。 %s.scrl.y% は現在 pos で指定されているY座標そのものに置換されますが、将来的に縦スクロールが導入されるかもしれないことを考え、また対称性からキーとして使えるようにしてあります。
  とは言え messcrl は互換性の観点からまだ使用できるようにしてありますし、

  messcrl
  

  が

  pos=%s.scrl.x%*%s.scrl.y%
  mes=%p.scrl%
  

  または

  pos=%s.scrl.pos%
  mes=%p.scrl%
  

  の二行に展開できるようになったのだな、という程度に思っておけば良いでしょう。
  スクロール情報を表示するスクリプトの具体的な書き方についてはスキン イベント処理エリアで言及しています。
• (※2) シークバーはスキンの冒頭部分(cf. スキン 宣言エリア)で伸びきった状態の位置と大きさを指定しますが、従来は drwboxs 命令でしか現在の再生の進行状況を表す長さのバーを描画できませんでした。矩形領域を描ける命令には他に imgdraw があり、これを利用した画像によるシークバーを可能にするために %s.seek.x% などが導入されました。
  実際にスキンを作る際に注意しなければならないのは imgdraw と drwboxf で描画領域の指定方法が違うことです。

  drwboxf=%s.seek.x%*%s.seek.y%*%s.seek.ex%*%s.seek.ey%
  

  drwboxf=%s.seek.pos%*%s.seek.epos%
  

  drwboxf=%s.seek.rect%
  

  drwboxs
  

  pos=%s.seek.x%*%s.seek.y%
  imgdraw=(コピー元X座標)*(Y座標)*%s.seek.width%*%s.seek.height%
  

  pos=%s.seek.pos%
  imgdraw=(コピー元X座標)*(Y座標)*%s.seek.size%
  

  以上の６例は全て同じ位置と伸びきったときの長さを持つシークバーを描画します。もちろん、実際の描画幅(または高さ)は再生位置により異なります。
  なお、これらの長さが半端なシークバーを描画する命令の前には、伸びきったときのシークバー表示領域をクリアする処理を書きます。「前回イベントが実行されたときの表示を消す処理は全てのイベント処理エリアで書く必要がある」(cf. スキン イベント処理エリア MainLoop)ためです。
• (※3) 次項で解説しています。
• (※4) ここには、IDを調べたいオブジェクトが持つ機能の識別子、または機能番号を記述します。該当するオブジェクトの(二つ以上ある場合はID順ではじめの一つの)IDで置換されます。 ページ上方にある利用例を再掲します。

  pos=5*5
  objsize=100*21
  objxset=next*次のファイルを再生
  objstyl=%o.next%*6
  

  objstyl 命令の一つ目のパラメータは [オブジェクトID] と各命令の解説にありますが、この例ではIDを直接指定せずに済んでいます。この特殊キーを使うとIDを調べるためオブジェクト設置数を自前で数えたりする必要が無く便利です。
• (※5) ここには、機能番号を調べたい識別子を記述します。ページ上方にある利用例を再掲します。

  exefunc=%f.play%
  

  exefunc 命令の一つ目のパラメータは [機能番号] と各命令の解説にありますが、この例では機能番号を直接指定せずに済んでいます。識別子が用意されている機能については、この特殊キーを使うと、人間にはどうしても分かり辛い数字の羅列を自力で記述する必要が無く便利です。

スキン変数

スキンに、プレイヤーの一般ユーザーが設定可能な項目を設けたいとき利用する機能です。 スキンの冒頭で使用する数や種類を宣言する(cf. スキン 宣言エリア)と、プレイヤーの右クリックメニュー > [スキン] > [現在のスキンを編集] から変数の内容を編集できるようになります。 変数の種類には文字列、画像ファイル名などがあり、変数の内容を編集する画面はそれらに応じて切り替わります。例えば文字列なら入力ウィンドウが、画像ファイルなら選択ダイアログが表示されます。
変数はそれぞれIDを持ち、スクリプト内で変数の値を利用するには前項で解説してある特殊キーの %v.(変数ID)% を使います。
例えば冒頭で

.Var.num=3
.Var.0.comm=BMP/JPEG画像(320×240px)
.Var.0.type=2
.Var.0.default=写真立て\青空.jpg
(以下、変数ID1と2についての宣言は略)

とID0の変数について宣言し、初期化部分で

imgload=%v.0%
pos=0*0
imgdraw=0*0*320*240

とすると %v.0% は初期状態では 写真立て\青空.jpg に置換されますが、ユーザーが右クリックメニューからその値を編集した場合には任意の画像ファイル名となります。 こうして、写真立てスキンではユーザーが画面の背景画像を自由に切り替えられるようになっています。
スキンの冒頭で宣言する変数の種類を以下に挙げます。

.Var.(ID).type=	スキン変数の種類	置換文字列	(サポート状況)
0	色	[r]*[g]*[b]	ver.402.00〜
1	文字列	[文字列]
2	画像ファイル	[画像ファイル名]
4	フォント	[font]*[size]*[style]
5	スキン作者の用意した選択肢から選択	[選択肢に対応した文字列]	ver.403.00α1〜

.Var.(ID).type=5 では、そのIDのスキン変数について

.Var.(ID).list=	[一つ目の選択肢]<BR>[二つ目の選択肢]...
.Var.(ID).list+=	[一つ目の選択肢が選択されたときの置換文字列]<BR>[二つ目の選択肢が選択されたときの...]...

という宣言が必須となります。
このとき変数の内容編集画面が選択肢をリストから選ぶかたちになり、選ばれた選択肢に対応した文字列が %v.(ID)% と置換されます。実際の動作例として pebble スキンがあります。

pos=[x]*[y]

メイン画面左上から測って横に [x]px 縦に [y]px 行った点を文字や画像表示の開始点にします。

col=[r]*[g]*[b]

描画色を指定した色に変えます。パラメータは順に赤、緑、青がどれだけ強いかを示し、0〜255($00〜$FF) の値で指定します。255*255*255 が白で、0*0*0 が黒となります。

mesfont=[font]*[size]*[style]

mes で表示する文字のフォント [font] とサイズ [size] pt 、スタイル [style] を指定します。スタイルは 1 太字、2 斜体、3 太字かつ斜体です。省略するか 0 としたときは標準(太字でも斜体でもない)となります。

mes=[message]*[align]

[message] を pos で指定した位置に、col で指定した色で表示します。[align] は right とすると pos で指定した位置が文字列右端になるように(右揃え)、centerとすると中央になるように(中央揃え)表示します。これを省略したり left としたときは左揃えになります。

mes=[message]*box*[width]

[message] を幅 [width]px で自動改行して表示します。

messcrl

pos で指定した位置を基点として、時間経過とともに段々と表示開始位置が左にずれていくスクロール情報を表示します。ver.403.00α1〜ではこの命令を使わず、特殊キー %s.scrl.pos% などを利用することで pos 及び mes の基本的な２命令でスクロール文字列を表示できるようになりました。詳細は特殊キー %s.scrl.x% の解説項を参照下さい。

drwboxf=[x]*[y]*[ex]*[ey]

画面左上から横に [x]px 縦に [y]px を基点、[ex]px [ey]px を終点として、col で指定した色の塗りつぶし四角形を表示します。

drwline=[x]*[y]*[ex]*[ey]

画面左上から横に [x]px 縦に [y]px を始点、[ex]px [ey]px を終点として、col で指定した色の線分を表示します。

drwboxs

スキンの冒頭で宣言した領域にシークバーを表示します。ver.403.00α1〜ではこの命令を使わず、特殊キー %s.seek.size% などと drwboxf や imgdraw 命令を併用して、より自由度の高いシークバーを表示できるようになりました。詳細は特殊キー %s.seek.x% の解説項やスキンの仕様を参照下さい。

imgload=[file]*[x]*[y]

画像ファイル [file](BMP/JPEG形式) を裏画面の左上から横に [x]px 縦に [y]px の位置に読み込みます。裏画面は画像を描きためておく仮想の画用紙のようなもので、幅 640px 高さ 480px あります。既に裏画面の該当位置に何かの画像がある場合は新しく読み込まれる画像の内容で上書きされます。 ここにためた画像は次の imgdraw 命令でメイン画面に貼り付けることができます。

imgdraw=[x]*[y]*[width]*[height]

裏画面の左上から [x]px [y]px を基点として幅 [width]px 高さ [height]px の矩形領域を、メイン画面の pos で指定した位置に貼り付けます。裏画面の内容は imgload または imgxdrw で編集できます。

imgxdrw=[x]*[y]*[width]*[height]*[bx]*[by]

メイン画面の左上から [x]px [y]px を基点として幅 [width]px 高さ [height]px の矩形領域の表示状態を、裏画面の左上から [bx]px [by]px の位置にコピーします。

objsize=[width]*[height]

objxset で設置するオブジェクトの大きさを幅 [width]px 高さ [height]px に指定します。(位置は pos で指定します。)

objxset=[obj-type or obj-func]*[text]

識別子が [obj-type] 、または機能番号が [obj-func] の機能を持つオブジェクトを設置します。オブジェクトがボタンやチェックボックスの場合は表面に [text] と表示します。 オブジェクトや識別子、機能番号については各解説項を参照下さい。

objpimg=[obj-id]*[x]*[y]*[width]*[height]

IDが [obj-id] のオブジェクト表面に、メイン画面の左上から [x]px [y]px を基点として幅 [width]px 高さ [height]px の矩形領域を貼り付けます。

objstyl=[obj-id]*[style]

IDが [obj-id] のオブジェクトのスタイル(表示様式)を [style] に変えます。

[style]	スタイル
0	有効=フツウの状態
1	無効=淡色表示、操作不能
2	不可視
3	可視=フツウの状態
5	透明化=不可視だがその領域をクリックすると機能がちゃんと実行される
6	枠強調(ボタン)
7	文字を左揃えに(ボタン)
8	〃　右揃えに(ボタン)
9	〃　中央揃えに(ボタン)=フツウの状態
10	〃　上揃えに(ボタン)
11	〃　下揃えに(ボタン)
13	平ら(ボタン)
14	平ら、かつ枠強調(ボタン)
19	文字を左側に表示(チェックボックス)

objhelp=[obj-id]*[text]

IDが [obj-id] のオブジェクトに、[text] というチップヘルプを付します。
チップヘルプとはユーザーが何かのオブジェクト上に暫くマウスカーソルを置いた際に表示される文字列のことです。

objresz=[obj-id]*[width]*[height]

objxset で設置済みの、IDが [obj-id] のオブジェクトの大きさを幅 [width]px 高さ [height]px に変更します。(位置は objreps で変更できます。)

objreps=[obj-id]*[x]*[y]

objxset で設置済みの、IDが [obj-id] のオブジェクトの位置をメイン画面の左上から [x]px [y]px に変更します。

exefunc=[obj-func]*[funcopts]

機能番号 [obj-func] を、[funcopts] という文字列オプション付きで(機能によっては省略可)実行します。(cf. arX MusicPlayer 全機能一覧)

• -(04/12/27) 微調整
  
  
  • ユーザー定義ボタンの機能番号を +$10
  
  
• ver.403.00α1(04/12/19) 仕様書再作成
  
  旧版からの変更点; スキン関連命令の互換性はほとんど保ちながら、利用する機会の少なかったプラグイン関連命令を exefunc ひとつにまとめました。
  • 命令の追加
    • imgxdrw
    • objhelp
    • objresz
    • objreps
    • exefunc
  • 命令の削除
    • mesauth, mestitl, mesposi など、音楽情報表示命令
      • mes=%p.auth% %p.titl% %p.posi% などで代用してください。
      • messcrl は例外的にまだ使用できます。
    • fncbttn, fncmenu
      • exefunc 命令で代用してください。
      • 元々プラグイン向けで、利用する機会が殆どなかった命令です。
    • setmcic, setmcia, setmode など、設定変更命令
      • 殆ど exefunc 命令で代用できます。
      • 元々プラグイン向けで、利用する機会が殆どなかった命令です。
  
  
• ver.402.15以前 旧仕様書