NiVE2用エフェクトプラグイン『マルチテキスト』（ruche.nive2.effects.wpf.MultiText.dll）の使用方法マニュアル。

この文書について †

この文書では、NiVE2用エフェクトプラグインセット ruche.nive2.effects に含まれているエフェクトの1つである『マルチテキスト』の使い方を解説します。

基本的に最新バージョンについて取り扱います。
過去のバージョンからの変更箇所については更新履歴を参照してください。

なお、導入手順等の基本的なことについては解説していませんので、添付のreadme.txtを参照してください。

エフェクト概要 †

できること †

『マルチテキスト』では次のようなことが行えます。

• 1エフェクトでの複数テキスト配置
  • 描画順序設定
• 文字の装飾
  • フォント、太字、斜体設定
  • 塗り潰し、縁取り設定
  • 下線、取り消し線、傍点*1設定
  • 影設定
• 文字間や行間のマージン設定
• 表示速度設定
  • フェードイン時間設定
• テキスト全体、背景全体の不透明度、明度、彩度設定
• テキストのブレンド方法設定
• 変数表示＆設定
• HTMLライクなタグによる装飾
  • 独自タグ設定
• エクスプレッションによるデリゲート設定

テキスト装飾例 †

例えば、表示文字列に次のような文字列を設定したとします。

<u>HTML</u>みたいに<font color="red">タグ付け</font>できるよ！
<i>デフォルトで<big>定義</i>されている</big>
<shadow color="red" depth="3">タグ</shadow>や<b fill="blue">属性</b>もあるし、
<grad>自分でタグを<wide>定義</wide>することもできるよ！</grad>
&lt;エンティティ文字&gt;にも対応<font color="violet">&hearts;</font>
変数を使うことも$sample

これは次のように表示されます。
なお、タグ設定で grad タグと wide タグを、変数設定で sample 変数を予め設定してあります。

基本的な使い方 †

基本的に、最初に必要な分のテキストを配置して、キーフレームを打ちながら表示文字列を設定する流れになります。

1. テキストの描画対象となるレイヤーを用意する。

2. レイヤーに『マルチテキスト』エフェクトを追加する。

3. ベーススタイル、ベース表示速度等を設定する。

4. テキストを必要な数だけ追加する。

5. 各テキストの配置を設定する。

6. 各テキストの表示文字列を設定する。様々なテキスト書式を用いることができる。

7. その他の設定項目を適宜設定する。

設定項目一覧 †

プロパティ名はエクスプレッション用ですが、『マルチテキスト』では各プロパティを直接操作するよりもデリゲート隠しプロパティを用いることを推奨します。
詳しくはエクスプレッション対応の項を参照してください。

ルート項目 †

テキスト †

スタイル †

文字の見栄えを設定します。
ベーススタイル以外はチェックボックスによって各項目を設定するか否かを選択でき、設定しなかった項目についてはデフォルト値が用いられます。

• テキストごとのスタイル設定におけるデフォルト値はベーススタイルで設定した値になります。
• タグごとのスタイル設定におけるデフォルト値についてはタグ書式の項を参照してください。

表示速度 †

各文字が表示されるタイミングを設定します。
テキストごとの表示速度設定はチェックボックスによって各項目を設定するか否かを選択でき、設定しなかった項目についてはベース表示速度で設定した値が用いられます。

変数 †

変数書式で用いることができる変数を設定します。
文字列値と数値（小数点以下桁数可変＆固定）がありますが、どちらもその値がそのまま変数値となります。

なお、変数はエクスプレッションからデリゲート隠しプロパティを用いて設定することも可能です。

タグ †

タグ書式で用いることができるタグを設定します。

ここで設定していない名前のタグを用いることも可能で、その場合は一切スタイル設定のされていないタグとして扱われます。
ただし、予めいくつかのスタイルが設定されている標準タグもあります。

ポスト処理 †

エフェクト適用対象のレイヤーや各テキストに対して、レイヤーとテキストを合成する直前に行う画像変換処理を設定します。
『範囲変更』エフェクトを適用している場合、レイヤーへの処理は有効範囲のみに適用されます。

テキスト書式 †

各テキストの表示文字列には変数書式、タグ書式、エンティティ書式を用いることができます。
これらの書式はテキストの拡張書式設定で無効にすることも可能です。

各書式は、有効である場合、次の順序で適用されます。

1. 変数書式
2. タグ書式
3. エンティティ書式

変数書式 †

あらかじめ設定した変数値を任意の位置に文字列として展開できます。

構文と記述例 †

変数の構文は次の通りです。
[ と ] で囲まれた部分は省略可能です。

$name

$(name[,width[.digits][,pad]])

${name[,width[.digits][,pad]]}

変数名 name には半角の英数字および _ (アンダーバー)を使うことが可能です。

変数名以外の各パラメータの解説も兼ねて、具体的な構文の一覧を以下に示します。
ここでは説明の便宜上、変数名 foo の変数に 12.3 という小数値が設定されているものとします。

なお、定義されていない変数名が用いられた場合、空の文字列を変数値として処理します。
$ の後に英数字が続くような文字列そのものを表示したい場合、エンティティ書式を用いる必要があります。

ネスト †

変数のネストが有効である場合、表示文字列内の変数は最大10回まで繰り返し展開されます。

例えば次のような変数が定義されているとします。

この時、次のような記述をすることができます。

ネスト展開を10回行っても完了しなかった場合、ネストを無効化して処理されます。

タグ書式 †

HTML風の記述で1つのテキスト内に複数のスタイル設定や表示速度設定を混在させることができます。

構文 †

タグの構文は次の通りです。
[ と ] で囲まれた部分は省略可能です。

開始タグ

タグによるスタイル適用の開始を表します。
タグ名と、それに続く0個以上の属性で記述します。

<tag[ attr="value"[ attr="value"[...]]]>

終端タグ

開始タグとセットで用いることでタグ設定適用範囲の終端を表します。

</tag>

独立タグ

単体で効果を発揮する属性や特殊タグで用いる書式です。
開始タグの直後に対応する終端タグを書くことと同じです。

<tag[ attr="value"[ attr="value"[...]]]/>

tag をタグ名、 attr を属性名、 value を属性値と呼びます。
また、属性名と属性値をイコールで結んだ attr="value" をまとめて属性と呼びます。

タグ名 tag には半角の英数字および _ - . : ! @ を使うことが可能です。
スタイルタグで定義したタグを用いる場合、タグ名の項目で設定した文字列をここに記述します。
定義されていないタグ名を記述することも可能です。

属性名 attr には半角の英数字および _ - . : を使うことが可能です。
定義されていない属性名を記述することも可能ですが、特に表示上の意味はありません。

属性値 value は基本的にダブルクォートで囲んで記述しますが、空白文字を含まない場合はダブルクォート無しで記述することも可能です。
とはいえ、基本的に属性値はダブルクォートで囲むものと考えておいた方が良いでしょう。
属性名と属性値の内容がマッチしない場合、その属性は無視されます。

タグの適用範囲

タグは開始タグから終端タグの間にある文字列に対して適用されます。
開始タグに対応する終端タグが存在しない場合は表示文字列の末尾まで適用されます。

範囲外<b>b の適用範囲</b>範囲外<span fill.color="red">span の適用範囲(文末まで)

独立タグの場合は記述した位置に対して適用されます。

タグをネストすることも可能です。
ネストされた表示文字列には両方のタグが適用されます。

<b>b の適用範囲<span fill.color="red">b と span の適用範囲</span>b の適用範囲</b>

また、適用範囲の一部だけを重ねることも可能です。
例えば次のような記述が行えます。

適用なし<u>下線適用<font color="#0000FF">両方適用</u>青字適用</font>適用なし

これは次のように表示されます。

あるタグで囲まれた表示文字列に適用されるスタイルおよび表示速度は次のように定まります。

1. そのタグ自体や属性によって明示的に指定されているスタイルおよび表示速度についてはそれを適用する。
2. そのタグでは指定されていないが、更に外側を囲むタグで指定されているスタイルおよび表示速度についてはそれを適用する。
3. いずれのタグでも指定されていないスタイルおよび表示速度についてはテキストごとのベーススタイル設定およびベース表示速度設定を用いる。

記述例 †

標準属性 †

あらゆるタグにおいて指定可能な属性の一覧です。
スタイル指定および一部の表示速度指定を行うことができます。

• あらゆる属性値には auto および inherit を指定可能です。いずれも何も行わないことを表します。
  • 複数の属性値記述が必要な場合に用いることで、特定の属性値だけ指定しないようにすることができます。
• 属性値内容において「一括」となっているものについては、対応スタイルや対応表示速度に書かれているものを一括で指定できることを表します。
  • 備考に特記されていない限り、すべての値は順不同で、任意の値だけを選んで記述可能です。
  • 複数種類の属性値として認識されうる値を記述した場合、対応スタイルや対応表示速度に書かれているもののうち先頭から順に決定されます。
    • 例えば font="normal" と記述すると、フォントのスタイルが太さよりも前にあるため、 font.style="normal" として解釈されます。
• 属性値内容において「○○指定」となっているものについては属性値指定の項で説明します。
• 属性値内容において「×2」や「×3」などのようになっているものは、空白を挟んでその数だけ値を記述することを表します。
  • 例えば「サイズ指定×3」ならば 1px auto 3mm のように記述します。

スタイルタイプ

属性名	属性値内容	対応スタイル				備考
		項目			対応値*4
valign	top	文字配置	行内位置		上端
	middle				中央
	baseline				ベースライン
	bottom				下端
scale.x	割合指定		スケール	横
scale.y	割合指定			縦
scale	割合指定			横縦		横と縦に同一値を適用する。
	割合指定×2			横,縦
margin.top	サイズ指定		マージン	上
margin.bottom	サイズ指定			下
margin.left	サイズ指定			左
margin.right	サイズ指定			右
margin	サイズ指定			上下左右		全方向に同一値を適用する。
	サイズ指定×2			上下,左右		上下と左右に同一値を適用する。
	サイズ指定×3			上,左右,下		左右には同一値を適用する。
	サイズ指定×4			上,右,下,左
font.family	フォント名	フォント	ファミリ
font.size	サイズ指定		サイズ
font.weight	normal		太さ		通常
	regular
	medium
	bold				太字
	heavy
font.style	normal		スタイル		通常
	italic				イタリック体
	oblique				斜体
font	一括		スタイル,太さ,サイズ,ファミリ			ファミリは末尾で指定する。
fill.color	色指定	塗り色
fill	色指定					fill.color と同じ。
edge.color	色指定	縁	色
edge.width	サイズ指定		幅
edge.type	normal		形状		鋭角
	miter
	bevel				面取り
	round				丸角
edge	一括		形状,幅,色			色は末尾で指定する。
underline.color	色指定	下線	色
underline.width	サイズ指定		幅
underline.cap	normal		端形状		なし
	none
	flat
	square				四角
	tri				三角
	triangle
	circle				半円
	round
underline.pattern	数値×1以上		破線パターン
underline.offset	割合指定		オフセット
underline.z	数値		Z位置
underline	一括		端形状,幅,色			色は末尾で指定する。
strike.color	色指定	取り消し線	色
strike.width	サイズ指定		幅
strike.cap	normal		端形状		なし
	none
	flat
	square				四角
	tri				三角
	triangle
	circle				半円
	round
strike.pattern	数値×1以上		破線パターン
strike.offset	割合指定		オフセット
strike.z	数値		Z位置
strike	一括		端形状,幅,色			色は末尾で指定する。
dot.color	色指定	傍点	色
dot.width	サイズ指定		幅
dot.offset	割合指定		オフセット
dot.z	数値		Z位置
dot	一括		幅,色			色は末尾で指定する。
shadow.color	色指定	影	色
shadow.dir	数値		方向
shadow.depth	サイズ指定		距離
shadow.blur	サイズ指定		ぼかし幅			大きくし過ぎないこと。
shadow.quality	normal		品質		通常
	performance
	high				高品質
	quality
shadow	一括		品質,方向,距離,色			色は末尾で指定する。

表示速度タイプ

属性名	属性値内容	対応表示速度		備考
		項目	対応値*5
speak.letter	時間指定	文字間隔
speak.row	時間指定	改行間隔
speak.fadein	時間指定	フェードイン
speak.wait	時間指定	（対応なし）		指定時間だけ停止する。 独立タグに対して指定しなければ効果なし。

属性値指定 †

末尾に単位を付けたり特殊な記述をしたりする属性値指定の一覧です。

N のようなイタリック体の英字は任意の数値を表します。
指定可能な数値の範囲は指定方法や対象属性により異なります。

標準タグ †

予めいくつかのスタイルが定義済みであるタグの一覧です。
スタイルタグ設定によって他のスタイルを追加したり、定義済みのスタイルを上書きすることも可能です。

特殊タグ＆属性 †

特殊属性を指定できたり一般のタグとは異なる挙動をしたりするタグと、それに対応する特殊属性の一覧です。

一部を除き、基本的には標準属性よりも少ない文字数で記述できることが利点です。
例えば、次の2行は同じ表示結果となります。

<span fill.color="black" font.size="20">あいうえお</span>
<font color="black" size="20">あいうえお</font>

エンティティ書式 †

変数書式、タグ書式で用いる文字（$ < >）や、通常では入力しづらい文字を表示できます。

構文 †

エンティティの構文は次の通りです。

&name;

&#dec;

&#xhex;
&#Xhex;

name は定義済みの名前です。
HTMLエンティティで定義されている名前を用いることができます。

• 参考：HTML ISO-8859-1 Reference - w3school.com

dec はUnicode文字コードを表す10進数値、 hex はUnicode文字コードを表す16進数値です。
いずれも指定したUnicode文字コードに対応する文字を表示できます。
名前が定義されている必要はありません。
なお、数値の頭には任意個数の 0 を付けても構いません。

記述例 †

代表的なエンティティ文字の一覧です。

エクスプレッション対応 †

エクスプレッションで用いることのできる当プラグイン独自クラスの簡単な説明です。

C#言語およびエクスプレッションの知識があることが前提となります。
C#言語はわかるけどエクスプレッションをよく知らないという方には次のサイトが大変参考になります。

• NiVE2のエクスプレッションについて - 金の髭のNiVE(NicoVisualEffects)まとめメモ

前準備 †

当プラグインをエクスプレッションで用いるにあたり推奨される設定は次の通りです。
以降、この設定がされているものとして解説します。

なお、参照の設定における C:\Program Files の部分は標準のプログラムフォルダに適宜置き換えてください。
例えばWindowsをDドライブにインストールした場合は D:\Program Files となります。

その他、基本的なことについてはNiVE2のマニュアルや添付のreadme_expression.txtを参照してください。

デリゲート隠しプロパティ †

デリゲート隠しプロパティは、 ruche.nive2.effects.wpf.TextEffectDelegateProperty クラス型のNiVE2プロパティです。
このプロパティの各メンバに対して適切なデリゲートを設定することで、通常の設定では行えない高度な表示制御が可能となります。

このプロパティはルート項目および各テキストが保持しています。
ルート項目のものはすべてのテキストに対して適用され、各テキストのものは各々に対してのみ適用されます。
両方に対してデリゲートを設定した場合、ルート項目→テキストの順に呼び出されます。

エフェクトのエクスプレッションでデリゲート隠しプロパティを取得および設定するコードは次の通りです。

ルート項目

// 取得 TextEffectDelegateProperty propRoot = (TextEffectDelegateProperty)property.GetProperty(thisItem, "delegate"); // 設定 property.SetProperty(thisItem, propRoot);

各テキスト

// 0 番目のテキストから取得する例 AddablePropertyBase texts = (AddablePropertyBase)property.GetProperty(thisItem, "texts"); FormattedTextPropertySet ps = (FormattedTextPropertySet)texts.Properties[0]; // 0 番目 TextEffectDelegateProperty propText = (TextEffectDelegateProperty)ps["delegate"]; // 設定(テキスト可変長プロパティを設定することでデリゲートも上書きされる) property.SetProperty(thisItem, texts);

このプロパティの主要なメンバ、およびそのデリゲート型は次の通りです。
各デリゲート型は ruche.nive2.effects.wpf.TextEffectDelegateProperty クラスの内部型として定義されています。

変数デリゲート

NiVE2上で設定されている変数リストを受け取り、それを操作したり新たな変数を追加したりできます。

/// <summary> /// 変数リストに対する処理を行うデリゲート。 /// </summary> /// <param name="variables">変数リスト。</param> public delegate void VariableDelegate( Dictionary<string, object> variables); /// <summary> /// 変数リストデリゲートを取得または設定する。 /// </summary> public VariableDelegate Variable { get; set; }

表示文字列デリゲート

NiVE2上で設定されている表示文字列とその文字列が表示開始されてからの経過秒数を受け取り、表示文字列を変更して返すことができます。

/// <summary> /// テキストに対する処理を行い、最終的なテキストを返すデリゲート。 /// </summary> /// <param name="text">テキスト。</param> /// <param name="elapsedTime"> /// テキストが表示されてからの経過秒数。 /// </param> /// <returns>最終的に使われるテキスト。</returns> public delegate string TextDelegate( string text, double elapsedTime); /// <summary> /// テキストデリゲートを取得または設定する。 /// </summary> public TextDelegate Text { get; set; }

描画情報デリゲート

最終的な描画処理に用いられる情報と対象の表示文字列が表示開始されてからの経過秒数を受け取り、座標等の情報を直接修正することができます。

/// <summary> /// テキスト描画情報に対する処理を行うデリゲート。 /// </summary> /// <param name="info">テキスト描画情報。</param> /// <param name="elapsedTime"> /// テキストが表示されてからの経過秒数。 /// </param> public delegate void RenderingInfoDelegate( ruche.nive2.effects.wpf.TextRenderingInfo info, double elapsedTime); /// <summary> /// テキスト描画情報デリゲートを取得または設定する。 /// </summary> public RenderingInfoDelegate RenderingInfo { get; set; }

描画情報デリゲートの引数 info の型である ruche.nive2.effects.wpf.TextRenderingInfo の詳細については別配布のクラスリファレンスを参照してください。
具体的なコーディング例は次節を参照してください。

コーディング例 †

簡単なコーディング例をいくつか示します。
ここではルート項目のデリゲート隠しプロパティに対してデリゲートを設定していますが、各テキストに対しても同様のことが行えます。

レイヤーのローカル時間 time を変数に追加する。

1 2 3 4 5 6 7 8 9 10 11 12 13

- ! - ! - - ! ! - !

// プロパティ取得 TextEffectDelegateProperty propRoot = (TextEffectDelegateProperty)property.GetProperty(thisItem, "delegate"); // 変数デリゲート設定 propRoot.Variable = delegate(Dictionary<string, object> variables) { // レイヤーのローカル時間を変数 $time に設定 variables["time"] = time; }; // プロパティ設定 property.SetProperty(thisItem, propRoot);

文字列が表示されてからの経過秒数（小数点以下切り捨て）を元文字列の末尾に追加する。

1 2 3 4 5 6 7 8 9 10 11 12 13

- ! - ! - - ! ! - !

// プロパティ取得 TextEffectDelegateProperty propRoot = (TextEffectDelegateProperty)property.GetProperty(thisItem, "delegate"); // 表示文字列デリゲート設定 propRoot.Text = delegate(string text, double elapsedTime) { // 経過秒数(小数点以下切り捨て)を表示文字列の末尾に追加して返す return (text + (int)elapsedTime); }; // プロパティ設定 property.SetProperty(thisItem, propRoot);

各文字がフェードイン時に上から落ちてくるような表示にする。

予めNiVE2上で表示速度の設定を行っておいてください。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28

- ! - ! - - ! - - ! - - ! | - | | ! | | ! ! ! - !

// プロパティ取得 TextEffectDelegateProperty propRoot = (TextEffectDelegateProperty)property.GetProperty(thisItem, "delegate"); // 描画情報デリゲート設定 propRoot.RenderingInfo = delegate(TextRenderingInfo info, double elapsedTime) { // 行ごとに処理 foreach (TextRowRenderingInfo ri in info.RowInfos) { // 文字ごとに処理 foreach (LetterRenderingInfo li in ri.LetterInfos) { // 現在のフェードイン割合を取得(0.0〜1.0) double rate = li.CalcOpacity(elapsedTime); // 次のように平行移動させる // rate==0.0 -> 文字の高さ分だけ本来の位置より上 // rate==1.0 -> 本来の位置 Point2D pos = li.Position; pos.Y -= li.CalcHeight() * (1.0 - rate); li.Position = pos; } } }; // プロパティ設定 property.SetProperty(thisItem, propRoot);

FAQ †

ありがちな（ありそうな）疑問点とそれに対する答えをまとめています。

変数書式やタグ書式が有効な状態で $ や < といった文字を表示したい。

エンティティ書式を用いてください。
$ は $ 、 < は < 、 > は > と記述することで表示できます。

長い行を特定の幅で折り返し表示したい。

テキストの「行配置/最大サイズ」の幅を折り返したい幅に設定してください。

フォント指定がメイリオの場合に行間が空きすぎてしまう。

行間が空くのはメイリオフォントの仕様です。
テキストの「行配置/行間」を 75 程度にするとちょうどいい具合になります。

下線や取り消し線の位置が微妙にずれる。

下線および取り消し線はアンチエイリアス処理によってぼやけることを防ぐためにピクセル位置を調整しています。
この調整処理は、線が水平である場合はY方向について、線が垂直である場合はX方向について行われ、それ以外の場合は行われません。
また、この調整によって0.5ピクセル以上ずれることはありません。

更新履歴 †

2011-07-31

• 特殊タグ＆属性の u, underline, s, strike, dot 各タグの width 属性が指定されなかった場合の挙動を変更した。
  • 指定されなければ 1 固定だったものを、指定されなければ最小値を 1 とするようにした。

2011-07-30

• 初版。

Now place: 文書/NiVE2 マルチテキスト

PukiWiki 1.5.0 Copyright © 2001-2006 PukiWiki Developers Team. License is GPL.
Based on "PukiWiki" 1.3 by yu-ji.
Skin "GS2" is designed by yiza.
Powered by PHP 5.6.40. HTML convert time: 0.097 sec.