スクリーンと Python link

スクリーン関数 link

次の関数はスクリーンに関連する様々な処理をサポートします。

renpy.call_screen(_screen_name, *args, _with_none=True, _mode='screen', **kwargs) link

プログラム的には call screen ステートメントに相当します。

これはスクリーンとして _screen_name を表示し、インタラクションを実行します。スクリーンはインタラクションが終わると非表示になり、インタラクションの結果が返されます。

_ で始まらない位置引数、キーワード引数はスクリーンに渡されます。

キーワード引数 _with_none が False なら「 with None 」はインタラクションの終わりに実行されません。

キーワード引数 _mode があれば、それがこのインタラクションのモードになり、そうでなければ "screen" モードになります。

renpy.current_screen() link

現在更新または描画、処理中のスクリーンに対する情報を返します。

返されたオブジェクトのドキュメントに記載されたフィールドは get_screen() を参照してください。

renpy.get_adjustment(bar_value) link

指定の bar_value, BarValue から、使用している ui.adjustment() を返します。 adjustment には以下の定義された属性があります。:

value link: バーの現在の値です。

range link: バーの現在の範囲です。

renpy.get_displayable(screen, id, layer=None, base=False) link: layer 上の screen から id を持つウィジェットを返します。スクリーンが存在しないか、そのスクリーン上にその id を持つウィジェットが存在しなければ None を返します。

renpy.get_displayable_properties(id, screen=None, layer=None) link

layer 上の screen にある id のウィジェットのプロパティーを返します。screen が None なら、現在のスクリーンに対するプロパティーを返します。これは python やスクリーン内のプロパティーコードから使用出来ます。

これはそのウィジェットのプロパティーを持つ辞書を返すので、そこから各プロパティーを所得出来ることに注意してください。

renpy.get_screen(name, layer=None) link

与えられた name を持つ layer 上のスクリーンの情報を返します。 name は画像タグとして解釈され、なければスクリーンの名前と解釈されます。そのスクリーンが表示されていなければ None が返されます。

name は name のリストでもかまいません、その場合表示されている最初のスクリーンが返されます。

この関数を使用してスクリーンが表示されているかチェック出来ます。例

if renpy.get_screen("say"):
    text "The say screen is showing."
else:
    text "The say screen is hidden."

この関数から返されたオブジェクトはフィールドのうち、次のフィールドを記載します :

layer link: スクリーンを表示するためのレイヤーです。

name link: 表示するスクリーンの名前です。

zorder link: スクリーンが表示される zorder です。

警告

他の同様の関数と同様に、この関数が返すオブジェクトは、関数が呼び出されてからの短期的な使用を意図しています。このオブジェクトのセーブデータへの保存やロールバックへの参加は推奨されません。

renpy.get_screen_variable(name, *, screen=None, layer=None) link

スクリーンのスコープ内の変数の値を返します。

name: 返す変数の名前です。
screen: 変数を返すスクリーンの名前です。 None なら現在のスクリーンが使用されます(現在のスクリーンはスクリーンの更新時とスクリーン内で実行されるアクション内でのみ定義されます)。
layer: screen が None でなければスクリーンを探すためのレイヤーです。

renpy.hide_screen(tag, layer=None, immediately=False) link

プログラム的に hide screen ステートメントに相当します。

layer 上の tag を持つスクリーンを非表示にします。

immediately が True の場合、その screen はすぐに非表示になり、 on hide イベントは発生しません。

renpy.set_focus(screen, id, layer='screens') link

screen 中の id を持つ displayable にフォーカスを試みます。これはその Displayable が見つからなければ失敗し、そのウィンドウはフォーカスされないか、他のものにフォーカスします。

この呼び出しが処理されると僅かでもマウスが移動するとフォーカスは変化します。

renpy.set_screen_variable(name, value, *, screen=None, layer=None) link

あるスクリーンのスコープにある変数の値を設定します。これは変数の値を即座には更新しないことに注意してください。 renpy.restart_interaction() を呼び出してアップデートしてください。

name: 設定する変数名です。最適化が他の変数に対する変更を見えなくすることがあるため、これは Default ステートメントで作成された変数であるべきです。
value: 変数を設定する値です。
screen: 変数を返すスクリーンの名前です。 None なら現在のスクリーンが使用されます(現在のスクリーンはスクリーンの更新時とスクリーン内で実行されるアクション内でのみ定義されます)。
layer: screen が None でなければスクリーンを探すためのレイヤーです。

renpy.show_screen(_screen_name, *args, _layer=None, _zorder=None, _tag=None, _widget_properties={}, _transient=False, **kwargs) link

プログラム的には show screen ステートメントに相当します。

その名前のスクリーンを表示します。これは以下のキーワード引数を受け取ります。 :

_screen_name

表示するスクリーンの名前です。

_layer

スクリーンを表示するレイヤーです。これは Show Screen ステートメントの onlayer 節に相当します。

_zorder

スクリーンを表示する zorder です。指定されなければそのスクリーンのデフォルトの zorder になります。それもなければ 0 になります。

_tag

表示するスクリーンのタグになります。指定されなければそのスクリーンのデフォルトのタグです。それもなければデフォルトでそのスクリーンの名前になります。

これは Show Screen ステートメントの as 節に相当します。

_widget_properties

ウィジェットの id をキーとする辞書であり、その値はプロパティー名をキーにその値を値とする辞書です。その id のウィジェットがスクリーンによって表示されると、指定したプロパティーがそこに追加されます。

_transient

True ならスクリーンは現在のインタラクションが終わると自動的に非表示になります。

アンダースコア (_) で始まらない位置引数とキーワード引数はそのスクリーンに渡されます。

renpy.start_predict_screen(_screen_name, *args, **kwargs) link

_screen_name という名のスクリーンを指定された引数で表示したときの予測を Ren'Py に開始させます。これは _screen_name の以前の予測を置き換えます。スクリーンの予測を停止するためには renpy.stop_predict_screen() を呼び出してください。

予測は通常のゲームプレイ中ずっと発生します。予測の完了を待つには、 predict 引数に renpy.pause() を使用してください。

renpy.stop_predict_screen(name) link: name という名のスクリーンの予測を停止させます。

renpy.variant(name) link

name が現在 Ren'Py に実行されているスクリーン variant なら True を返します。詳細はスクリーン variant を参考にしてください。この関数を if ステートメントで条件に使用して、選択したスクリーン variant に対して振る舞いを変更出来ます。

name はスクリーン variant のリストでもかまいません、その場合この関数はそのどのスクリーン variant が選択されても True を返します。

class ui.adjustment(range=1, value=0, step=None, page=None, changed=None, adjustable=None, ranged=None, force_step=False, raw_changed=None) link

adjustment オブジェクトは bar や viewport によって調整される値を表します。これは値や値の範囲、 step と page での値の調整法についての情報を含みます。

以下のパラメーターは adjustment オブジェクトのフィールドやプロパティーに対応します。 :

range

adjustment の範囲で、数字です。

value

adjustment の値で、数字です。

step

adjustment の一つの step のサイズで、数字です。 None ならデフォルトでは page が設定されていればその10分の1で、そうでなければ range の10分の1です。

これはマウスホイールで viewport をスクロールするときに使用されます。

page

adjustment の page あたりのサイズです。 None ならこれは viewport により自動的に設定されます。もし設定されなければ、デフォルトで range の10分の1です。

スクロールバーをクリックすると使用されます。

以下のパラメーターは adjustment の動作を制御します。

adjustable

True ならこの adjustment はbar から変更できます。 False なら出来ません。

デフォルトでは changed 関数が与えられているか adjustment が viewport に関連づけられていれば変更可能で、そうでなければ出来ません。

changed

この関数は adjustment の値が変更されるとその新しい値を引数に呼び出されます。

raw_changed

この関数は、 adjustment の値が変更されたときに呼び出されます。 changed とは異なり、この関数は生の値を引数に呼び出されますが、これは範囲外である可能性があります。これは、 adjustment と新しい値の 2 つの引数で呼び出されます。

ranged

この関数は adjustment の range が viewport によって設定されると adjustment オブジェクトを引数に呼び出されます。

レイアウトの過程でこの関数は複数回呼び出されます。

force_step

adjustment が viewport や bar に対応する draggable で変更され、かつこれが True ならばドラッグが次のステップに達したときのみ値が変更されます。 adjustment が viewport や bar に対応する draggable で変更され、かつこれが "release" ならば、 draggable の解放時、値は最も近いステップに丸められます。 False ならばこの adjustment はステップの値を無視します。

change(value) link: adjustment の値を value に変更し、その adjustment を使用しているすべての bar や viewport が更新されます。

ui.interact(*, roll_forward=None, mouse='default') link

ユーザーとのインタラクションを起し、その結果を返します。これは Ren'Py にスクリーンを再描画させ入力イベントの処理を開始します。 displayable がイベントに対して値を返すと、その値は ui.interact から返され、インタラクションは終了します。

この関数は滅多に直接呼び出されません。 say ステートメントや menu, with pause, call screen ステートメント含む Ren'Py の一部、 renpy.input() などの多くの関数から通常呼び出されます。しかし必要なら直接呼び出せます。

インタラクション終了時、 transient レイヤーと transient が True として表示されたすべてのスクリーンはそのシーンリストから除去されます。

以下の引数はドキュメントに記載されています。ドキュメントに記載されていない引数は Ren'Py 内部で使用するために存在するのですべての引数はキーワード引数として渡してください。

roll_forward: ロールバック時にこの関数から返される情報です( None ならロールフォワードは無視されます)。これには通常 renpy.roll_forward_info() 関数の結果が渡されるはずです。
mouse: この関数を実行中のマウスカーソルのスタイルです。

アクション link

スクリーン言語で作成された displayable の多くは引数としてアクションを受け取ります。アクションは以下の三つのうちいずれかです。 :

引数を受け取らない呼び出し可能な ( 関数や bound method のような ) python オブジェクト
Action クラスを継承するクラスのオブジェクト
他のアクションのリスト

Action クラスを継承する利点はボタンが有効か、選択されているかを設定するメソッドを上書き可能なことです。

class Action link

新しいアクションを定義するためにはこのクラスを継承してください。アクションの動作を変更するためにはこのクラスのメソッドを上書きしてください。

__call__(self) link

これはアクションがアクティベートされると呼び出されるメソッドです。多くの場合 None でない値を返すと、現在のインタラクションが終了します。

このメソッドはデフォルトでは NotImplemented の例外を出す ( Ren'Py にエラーを報告させる ) ため、上書きする必要があります。

get_sensitive(self) link

これはこのアクションに関連づけられたボタンが有効かどうかを決定するために呼び出されます。ボタンが有効なら True を返すべきです。

これが False を返しても __call__ は実行されることに注意してください。

デフォルトでは True を返します。

get_selected(self) link

これはボタンが選択された状態でレンダリングされるべきなら True を返し、そうでないなら False を返すべきです。

デフォルトでは False を返します。

get_tooltip(self) link

特定のツールチップが代入されていなければこのボタンのデフォルトのツールチップを所得します。ツールチップの値またはツールチップが分からなければ None を返します。

デフォルトでは None を返します。

periodic(self, st) link

このメソッドは各インタラクションが開始されると一旦呼び出され、その後も継続的に呼び出されます。数字を返すとその秒数が経過すると、そうでないならすぐに呼び出されます。

これの主な使用法は get_selected や get_sensitive の値が変更されたら renpy.restart_interaction() を呼び出すことです。

引数を一つ受け取ります。

st: このアクションに関連づけられたスクリーンか displayable が最初に表示されてからの秒数です。

unhovered(self) link: アクションがボタン ( または同様なオブジェクト ) への hovered パラメーターとして使用されると、このメソッドはそのオブジェクトがフォーカスを失うと呼び出されます。

alt link: このアクションを使用するボタンに:propref:alt プロパティーが設定されていなければ、そのボタンに対して読み上げられるテキストとなります。これはそのクラスやそのコンストラクターの文字列、文字列を返す python プロパティーにできます。

pythonからアクションを実行するには renpy.run() を使用してください。

renpy.is_selected(action) link: 提供された action や action のリストが選択状態なら True を返し、そうでないなら False を返します。

renpy.is_sensitive(action) link: 提供された action や action のリストが選択可能状態なら True を返し、そうでないなら False を返します。

renpy.run(action) link

アクションまたはアクションのリストを実行します。単体のアクションは引数なしで呼び出され、アクションのリストはこの関数で順番に実行されます。 None は無視されます。

最後のアクションの結果の値を返します。

BarValue link

bar, vbar または hotbar 作成時に BarValue オブジェクトは value 引数に提供されます。 BarValue オブジェクトのメソッドは adjustment やスタイルを得るために呼び出されます。

class BarValue link

新しい BarValue を定義するためには、このクラスを継承してそのメソッドを上書きしてください。

get_adjustment(self) link

このメソッドは bar の adjustment オブジェクトを得るために呼び出されます。 ui.adjustment() で adjustment を作成し、作成されたオブジェクトを返します。

このメソッドはデフォルトでは NotImplemented の例外を出す ( Ren'Py にエラーを報告させる ) ため、上書きする必要があります。

get_style(self) link

これはこの値を使用する bar のスタイルを決定するために使用されます。二つのスタイル名か、 style オブジェクトのタプルを返すべきです。第一要素は bar に、第二要素は vbar に使用されます。 :

これはデフォルトで ("bar", "vbar") です。

get_tooltip(self) link

特定のツールチップが代入されていなければこのボタンのデフォルトのツールチップを所得します。ツールチップの値またはツールチップが分からなければ None を返します。

デフォルトでは None を返します。

replaces(self, other) link

これはスクリーンが更新される時のように、 BarValue が他の BarValue を置き換えるときに呼び出され、 other からこの BarValue に更新するために使用されます。 get_adjustment より前に、呼び出されます。

other は self と同じ型である必要はありません。

periodic(self, st) link

このメソッドは各インタラクションの開始時に一度呼び出され、秒数の数字を返すとその時間が経過した後に、そうでなければすぐに再び呼び出されます。これは get_adjustment の後に呼び出されます。

AnimatedValue() のように時間につれて bar の値を更新するために使用されます。このためには、 get_adjustment で adjustment を保持し、 periodic で adjustment の changed メソッドを呼び出すべきです。

alt link: この BarValue を使用するボタンに:propref:alt プロパティーが設定されていなければ、そのバーに対して読み上げられるテキストとなります。これはそのクラスやそのコンストラクターの文字列、文字列を返す python プロパティーにできます。

InputValue link

input 作成時に、 InputValue オブジェクトは value プロパティーとして提供されます。 InputValue オブジェクトのメソッドはテキストの設定と所得、編集可能かどうか、エンターキーが押されたときの処理を決定するために呼び出されます。

class InputValue link

新しい InputValue を定義するためには、このクラスを継承してそのメソッドを上書きしてください。

editable link: True でないならば、入力欄を無効化します。

default link: Trueなら、input はデフォルトで編集可能な状態です(スクリーン表示時に、キャレットが与えられます)。

get_text(self) link: 入力されたテキストを返します。これは実装されなければいけません。

set_text(self, s) link: 入力されたテキストが変更されると、新しいテキストで呼び出されます。これは実装されなければいけません。

enter(self) link: ユーザーがエンターを押すと呼び出されます。これが None 以外を返すと、その値がインタラクションから返されます。これは renpy.IgnoreEvent() イベントを投げて押下を無視させられます。そうでなければ、他の displayable にエンターキーの押下が伝達されます。

以下のアクションは InputValue で利用可能なメソッドです。 :

Enable() link: テキストを編集可能にするアクションを返します。

Disable() link: テキストを編集不能にするアクションを返します。

Toggle() link: テキストが編集可能かをトグルするアクションを返します。

ユーザー定義スクリーン言語ステートメント link

Ren'Py はユーザー定義スクリーン言語ステートメントをサポートしています。ユーザー定義スクリーン言語ステートメントはスクリーン言語の use ステートメントに対するラッパーです。位置引数はそのまま位置引数になり、プロパティーはキーワード引数になり、ステートメントがブロックを受け取ると、use ステートメント同様に処理します。例えば次のユーザー定義スクリーン言語ステートメントは

titledwindow "Test Window":
    icon "icon.png"

    text "This is a test."

こうなります。

use titledwindow("Test Window", icon="icon.png"):
    text "This is a test."

ユーザー定義スクリーン言語ステートメントは python early ブロックで登録されなければなりません。また、そのユーザー定義ステートメントがあるファイル名はそれを使用するどのファイルよりも先に読み込まれなけれなければなりません。Ren'Py はファイルをパスのユニコード順に読み込むので、ユーザー定義ステートメントを登録するファイル名の先頭に 01 や小さい数を付けるとよいです。

ユーザー定義スクリーン言語ステートメント renpy.register_sl_statement 関数で登録されます。 :

class renpy.register_sl_displayable(name, displayable, style, nchildren=0, scope=False, *, replaces=False, default_keywords={}, default_properties=True, unique=False) link

displayable を作成するユーザー定義のスクリーン言語ステートメントを登録します。

name

スクリーン言語ステートメントの名前でと Ren'Py のキーワードを含む文字列です。このキーワードは新しいステートメントを導入するために使用されます。

displayable

これは関数で、呼び出されると displayable オブジェクトを返します。すべての位置引数、プロパティーとスタイルプロパティーはこの関数へ引数として渡されます。その他のキーワード引数も以下のようにこの関数へ渡されます。

これは displayable を返すべきです。複数の displayable を返すと最も外側の displayable の _main 属性が "main" displayable に設定され、子はこれに追加されます。

style

この displayable のスタイルのベース名です。スタイルプロパティーが指定されないと、これにスタイル接頭辞を追加します。結果のスタイルが displayable 関数に style キーワード引数として渡されます。

nchildren

この displayable の子の数で、次のうちのひとつです。 :

0: displayable は子を受け取りません。
1: displayable はひとつ子を受け取ります。ひとつ以上の子が与えられると、子は Fixed に配置されます。
"many": displayable ひとつ以上の子を受け取ります。

unique

関数が他のどこからも参照されない Displayable を返すなら True にするべきです。

以下の引数はキーワード引数を使って渡されるべきです。

replaces: True で、 displayable が以前の displayable を置き換えるなら、新しい displayable に対するパラメーターとしてその displayable は渡されます。
default_keywords: その displayable に与えられるキーワード引数のデフォルトの設定です。
default_properties: True なら ui と position プロパティーがデフォルトで追加されます。

以下のメソッドを呼び出して、追加する位置引数とプロパティーを指定出来るオブジェクトを返します。それらの各メソッドは同様に呼び出せるオブジェクトを返し、メソッドをひとつなぎに出来ます。

add_positional(name) link: name の位置引数を追加します。

add_property(name) link: name のプロパティーを追加します。プロパティーはキーワード引数として渡されます。

add_style_property(name) link: name で終り、さまざまなスタイルプロパティー接頭辞を接頭辞にするプロパティーの一群を追加します。例えば ("size") で呼び出されると、size, idle_size, hover_size などを定義します。

add_prefix_style_property(prefix, name) link: prefix とスタイルプロパティーの接頭辞、 name で構成された名前を持つプロパティーの一群を追加します。例えば prefix が text_ name が size で呼び出されると、これは text_size, text_idle_size, text_hover_size などを作成します。

add_property_group(group, prefix='') link

prefix を接頭辞に持つプロパティーのグループを追加します。 Group は次の文字列のうちの一つです。 :

"bar"
"box"
"button"
"position"
"text"
"window"

これらはスタイルのプロパティーのグループに対応します。グループは "ui" にも出来、その場合共通のUIプロパティーを追加します。

copy_properties(name) link: name スクリーンステートメントに渡せるすべてのスタイルと位置引数、キーワード引数を追加します。

class renpy.register_sl_statement(name, children='many', screen=None) link

Ren'Py にユーザー定義のスクリーン言語ステートメントを登録します。

name: これは単語でなくてはいけません。そのユーザー定義スクリーン言語ステートメントの名前になります。
children: このユーザー定義ステートメントが受け取る子の数です。これは 0, 1 または 0 以上を表す "many" であるべきです。
screen: 使用するスクリーンです。未指定では name になります。

追加する位置引数とプロパティーを指定出来るオブジェクトを返します。このオブジェクトは renpy.register_sl_displayable が返すオブジェクト同様に add_ メソッドを持ちます。

ユーザー定義スクリーン言語ステートメントの例として、上記で指定した titlewindow ステートメントの実装を示します。先ず、 01custom.rpy のような初期に読み込まれるファイルの python early ブロックでステートメントは登録されなければなりません。以下のように登録します。

python early:
    renpy.register_sl_statement("titledwindow", children=1).add_positional("title").add_property("icon").add_property("pos")

次にユーザー定義ステートメントを実装するスクリーンを定義します。このスクリーンはどのファイルでも定義出来ます。そのようなスクリーンの 1 例です。

screen titledwindow(title, icon=None, pos=(0, 0)):
    drag:
        pos pos

        frame:
            background "#00000080"

            has vbox

            hbox:
                if icon is not None:
                    add icon

                text title

            null height 15

            transclude

add_property_group のような大きなプロパティ―グループを使用するなら、 **properties シンタックスを使用してどこかに properties キーワードを使うとよいです。例

screen titledwindow(title, icon=None, **properties):
    frame:
        # When background not in properties it will use it as default value.
        background "#00000080"

        properties properties

        has vbox

        hbox:
            if icon is not None:
                add icon

            text title

        null height 15

        transclude