std::narrative::text

安定性: 安定 — テキスト値、t![…] の展開先のビルトイン、テキスト効果、テキストスタイル。

std::narrative::text は、すべてのメッセージ・名前・ラベルの型である Text、フォーム t![…] が展開されるビルトイン関数、埋め込みの境界である ToText、テキストの一部を装飾し表示のきっかけを与えるテキスト効果（TextEffect とそのコンストラクタ）、そしてテキストボックス全体のスタイル TextStyle を宣言します。

関数はすべて const fn です。Text、TextEffect、Mark は std::narrative から再エクスポートされます。プレリュードは Text、TextEffect と、コンストラクタ emphasis、dots、color_text、bold、pause、click_wait、mark をインポートします。それ以外は std::narrative::text からインポートします。

概要

Struct: Text

#[builtin] pub struct Text;

定数テキストです：プレーン（"Mio"）またはリッチ（t![…]）。

• Kind: — · Builtin: yes

• 文字列リテラルの型は Text です：who = "Mio" に t! は要りません。

• Text は Eq かつ有限型です：物語の中では、Text の値はプログラムの定数テキストです。fn のコードは to_text で実行時に別のテキストを作れます。

• そのため、エントリーシーンの引数と戻り値の型は Text を含んではなりません（E3009）。

t![…] の展開

t![…] はフォームで、各要素が 1 つの呼び出しになります。

フォーム全体は次のようになります。

• 要素がなければ ""
• 要素が 1 つならその要素の式。つまり t![{DAY}] は to_text(DAY)
• それ以外は要素の concat([…])

t!["Day " {DAY} ": " !["the festival"](emphasis())]
// concat(["Day ", to_text(DAY), ": ", effect("the festival", emphasis())])

フォームの構文は フォーム で説明しています。

Function: ruby(base, reading)

#[builtin] pub const fn ruby(base: Text, reading: Text) -> Text;

• base Text — 親文字。文字列リテラルでなければなりません（E3021）。
• reading Text — 読み。
• Returns: Text — base の上に reading をルビとして付けたもの（グループルビ：親文字全体に 1 つの読み）。
• Kind: const fn · Builtin: yes

別のルビの親文字の中に入れ子にしたルビは、読みが捨てられます。ルビ辞書（繰り返し出る語のルビを一度だけ宣言するもの）は予定していません：ルビは使う箇所ごとに書きます。

Function: mono_ruby(base, readings)

#[builtin] pub const fn mono_ruby<const N: usize>(base: Text, readings: [Text; N]) -> Text;

• base Text — 親文字。文字列リテラルでなければなりません。
• readings [Text; N] — base の 1 文字ごとの読み。配列リテラルでなければなりません。
• Returns: Text — 1 文字ごとにルビを付けた base。
• Kind: const fn · Builtin: yes

N は親文字の文字数と等しくなければなりません（E3021）。

Function: effect(base, effect)

#[builtin] pub const fn effect(base: Text, effect: TextEffect) -> Text;

• base Text — 装飾するテキスト。
• effect TextEffect — 効果。定数式でなければなりません（E3022）。
• Returns: Text — effect を適用した base。
• Kind: const fn · Builtin: yes

Function: concat(items)

#[builtin] pub const fn concat<const N: usize>(items: [Text; N]) -> Text;

• items [Text; N] — 部品。
• Returns: Text — 要素を順に並べたもの。空白の追加や畳み込みはしません。
• Kind: const fn · Builtin: yes

Trait: ToText

#[builtin] pub trait ToText {}
impl ToText for Text {}
impl ToText for String {}
impl<const LO: i64, const HI: i64> ToText for Int<LO, HI> {}
impl ToText for u8 {}
impl ToText for u16 {}
impl ToText for u32 {}
impl ToText for u64 {}
impl ToText for u128 {}
impl ToText for i8 {}
impl ToText for i16 {}
impl ToText for i32 {}
impl ToText for i64 {}
impl ToText for i128 {}
impl ToText for usize {}
impl ToText for isize {}
impl ToText for Rat {}
impl ToText for Decimal {}

t![…] の {expr} 要素で埋め込める型です：Text、String、すべての整数型、Rat、Decimal。

• Kind: — · Builtin: yes

Function: to_text(value)

#[builtin] pub const fn to_text<T: ToText>(value: T) -> Text;

• value T — 表示する値。

• Returns: Text — テキストにした value。t![…] の {expr} の展開先です。

• Kind: const fn · Builtin: yes

• {expr} には T: ToText である expr: T が必要です。

• 整数は十進で、Rat と Decimal は正確に書き出されます。

• 物語の中では、有限型の値に対する to_text は他の const fn 呼び出しと同じく表化されるので、{DAY} を含む行も物語の状態の有限な関数のままです。

• バックログでは、ステップが history を設定していない限り、埋め込んだ値は表示時のまま記録されます。

static mut DAY: Int<1, 7> = 1;

#[scene]
pushdown fn Morning() {
    s!(t!["Day " {DAY}]);
}

Struct: Mark

pub struct Mark(pub u8);

テキストの表示の中の名前付きの点で、レンダーはタイムラインをここに合わせられます（Screen::at_mark、std::screen を参照）。mark(n) で設定します。Mark は Rust の整数を保持するので有限型ではありません。物語は定数式の中で使います。

• Kind: — · Builtin: no

Enum: Weight

pub enum Weight {
    Regular,
    Bold,
}

フォントの太さです。

• Kind: — · Builtin: no

Enum: Emphasis

pub enum Emphasis {
    Styled,
    Dots,
}

強調したテキストの描き方です。

• Styled — ウィンドウの TextStyle::emphasis で描きます。
• Dots — ウィンドウのスタイルにかかわらず、全文字に圏点（傍点）を付けます。
• Kind: — · Builtin: no

Enum: Reveal

pub enum Reveal {
    Player,
    PerChar(Duration),
    Scaled(Decimal),
    Instant,
}

テキストが現れる速さです。

• Kind: — · Builtin: no

Enum: Pause

pub enum Pause {
    Time(Duration),
    Click,
}

効果の基になるテキストの前で、表示を止めます。

• Time(d) — d の間止めます。
• Click — クリックまで止め、そのクリックでテキストの続きを表示します。
• Kind: — · Builtin: no

Struct: Outline

pub struct Outline {
    pub color: Color,
    pub width: u32,
}

テキストの縁取りです：color と、ピクセル単位の width。

• Kind: — · Builtin: no

Struct: Shadow

pub struct Shadow {
    pub color: Color,
    pub offset: Offset,
    pub blur: u32,
}

テキストの影です：color、ピクセル単位の offset、ピクセル単位のぼかし半径 blur。

• Kind: — · Builtin: no

Struct: TextEffect

pub struct TextEffect {
    pub color: Option<Color>,
    pub size: Option<Decimal>,
    pub weight: Option<Weight>,
    pub italic: Option<bool>,
    pub font: Option<FontAsset>,
    pub outline: Option<Outline>,
    pub shadow: Option<Shadow>,
    pub emphasis: Option<Emphasis>,
    pub reveal: Option<Reveal>,
    pub pause: Option<Pause>,
    pub mark: Option<Mark>,
}

テキストの一部に適用するスタイルときっかけです。None のフィールドは継承します（ウィンドウのスタイルをそのまま使います）。size はウィンドウの文字サイズに対する倍率です。

• Kind: — · Builtin: no

テキスト効果は関数ではなく値です。!["…"](…) の効果は定数式でなければならないので、メッセージはそのステップの定数のままです。効果は and で組み合わせます。

const RED: Color = rgb(220, 40, 40);

const LINE: Text = t!["It was " !["right there"](bold().and(color_text(RED))) "."];

TextEffect::and(self, other)

pub const fn and(self, other: TextEffect) -> TextEffect

• other TextEffect — この効果の上に重ねる効果。
• Returns: TextEffect — 右優先のマージ：other で設定されたフィールドが勝ち、それ以外は self から取ります。
• Kind: const fn · Builtin: no

Constant: PLAIN

pub const PLAIN: TextEffect = TextEffect {
    color: None,
    size: None,
    weight: None,
    italic: None,
    font: None,
    outline: None,
    shadow: None,
    emphasis: None,
    reveal: None,
    pause: None,
    mark: None,
};

何も変えない効果です：すべてのフィールドが None。

効果のコンストラクタ

各コンストラクタは、PLAIN のフィールドを 1 つだけ設定したものです。すべて const fn で、Builtin: no です。

スタイル

color_text(color)、size(scale)、bold()、italic()、font(font)、outline(color, width)、shadow(color, offset, blur)、emphasis()、dots()。

スタイルのフィールド（color、size、weight、italic、font、outline、shadow、emphasis）は、効果の基になるテキストに適用されます。

• emphasis() はウィンドウの TextStyle::emphasis で描きます。
• dots() はウィンドウのスタイルにかかわらず、常に圏点を付けます。

const LINE: Text = t!["これは" ["数多"]("あまた") "の" !["赤い"](emphasis()) "花。"];

表示速度

speed(per_char)、speed_scale(scale)、reveal_instant()。

reveal は基になるテキストが現れる速さを設定します。Reveal を参照してください。speed_scale には 0 より大きい倍率が必要です。

use std::narrative::text::speed;

const LINE: Text = t![!["Slowly, slowly…"](speed(ms(80))) " then all at once."];

ポーズ

pause(duration)、click_wait()。

ポーズは、効果の基になるテキストの前で表示を止めます。基になるテキストは通常 "" です。

• pause(d) は表示を d の間止めます。
• click_wait() はクリックまで表示を止めます。そのクリックはテキストの続きを表示するもので、テキストを完了させず、NextStep でもありません。セーブにも記録されません。
• オートモードでは、クリック待ちのポーズは auto_delay 設定の後に続きます。

const LINE: Text = t!["Wait" ![""](pause(ms(500))) "… " ![""](click_wait()) "there it is."];

マーク

mark(n)。

マークは表示の中の点に名前を付け、レンダーがそこにアニメーションを予約できるようにします（std::screen::anim を参照）。

• mark(n) は表示がその点に達した時刻を記録します。
• 1 つのテキスト内でマークが重複すると定数評価エラーです（E4010）。
• ステップのテキストに含まれないマークは、表示の終わりとして扱われます。

use std::narrative::Mark;

const fn startled(mut screen: Screen) -> Screen {
    screen.at_mark(Mark(1));
    // changes scheduled here start when the reveal reaches mark 1
    screen
}

#[scene]
pushdown fn Surprise() {
    s!(render = startled, t!["Wait" ![""](pause(ms(500)).and(mark(1))) "—what?"]);
}

この例では、レンダー startled が screen.at_mark(Mark(1)) を呼び、表示がダッシュに達した瞬間に表情を変えられます。

安定性: 予定 — マークを超えたテキストとアニメーションの同期：表示される 1 文字ごとに追従するアニメーションや、アニメーションを待つ表示など。まだ設計されていません。

クリックとバックログ

• 表示中のクリックは全文を一度に表示します。ただし click_wait() のポーズは、それ自身のクリックを引き続き待ちます。
• バックログのテキストはポーズや表示演出なしで表示されます。ステップが history を設定していない限り、埋め込んだ値は表示時のまま記録されます。

Enum: TextAlign

pub enum TextAlign {
    Start,
    Center,
    End,
}

テキストの水平方向の揃え方です。

• Kind: — · Builtin: no

Enum: EmphasisStyle

pub enum EmphasisStyle {
    Dots,
    Bold,
    Italic,
}

テキストボックス内で Emphasis::Styled のテキスト（emphasis() によるもの）をどう描くかです。

• Kind: — · Builtin: no

Struct: TextStyle

pub struct TextStyle {
    pub font: Option<FontAsset>,
    pub size: u32,
    pub color: Color,
    pub line_height: Decimal,
    pub letter_spacing: i32,
    pub align: TextAlign,
    pub outline: Option<Outline>,
    pub shadow: Option<Shadow>,
    pub ruby_size: u32,
    pub emphasis: EmphasisStyle,
    pub hanging_indent: bool,
    pub vertical: bool,
}

テキストボックスのスタイルです：メッセージウィンドウ（ui::message）、UI のラベルと text!、画面上のラベルレイヤーに使います。

• Kind: — · Builtin: no

Function: text_style(size, color)

pub const fn text_style(size: u32, color: Color) -> TextStyle

• size u32 — ピクセル単位の文字サイズ。
• color Color — 文字色。
• Returns: TextStyle — フォント None、line_height 1.5、letter_spacing 0、揃え Start、縁取りと影なし、ruby_size = size / 2、強調 Dots、hanging_indent false、vertical false のスタイル。
• Kind: const fn · Builtin: no

TextStyle のビルダー

各ビルダーは、フィールドを 1 つ置き換えたスタイルを返します。Option のフィールドのビルダーは値を Some で包みます。すべて const fn で、Builtin: no です。

pub const fn font(mut self, font: FontAsset) -> TextStyle
pub const fn line_height(mut self, value: Decimal) -> TextStyle
pub const fn letter_spacing(mut self, value: i32) -> TextStyle
pub const fn align(mut self, value: TextAlign) -> TextStyle
pub const fn outline(mut self, value: Outline) -> TextStyle
pub const fn shadow(mut self, value: Shadow) -> TextStyle
pub const fn ruby_size(mut self, value: u32) -> TextStyle
pub const fn emphasis(mut self, value: EmphasisStyle) -> TextStyle
pub const fn hanging_indent(mut self, value: bool) -> TextStyle
pub const fn vertical(mut self, value: bool) -> TextStyle

use std::narrative::text::{Outline, TextStyle, text_style};

const WINDOW_TEXT: TextStyle = text_style(26, WHITE)
    .outline(Outline { color: BLACK, width: 2 })
    .hanging_indent(true);