スクリーン言語同様に Ren'Py は python でのスクリーンの定義をサポートします。 python でのスクリーンはスクリーン関数を renpy.define_screen() に与えて作成され、どんなスクリーンにも使用できます。
スクリーン関数は期待するスコープ変数に対する引数を受け取り、それ以外のキーワード引数は無視するべきです( それ故その引数の末尾には **kwargs を持つべきです)。UI 関数を呼び出してスクリーンに displayable を追加します。スクリーン関数はインタラクションが開始するか再開すると呼び出されます。
この再開がユーザーにとってシームレスであると保証するには UI 関数へのすべての呼び出しが id 引数をサポートすることが重要です。スクリーンは再生成されるため、 Ren'Py は同じ id を持つ以前の displayable の内容で各 displayable を更新します。 id はスクリーン言語によって自動的に生成されますが、直接 ui 関数を使用するときは手動で指定する必要があります。
警告
注意: UI 関数は非推奨です。
python スクリーンの例を示します
init python:
def say_screen(who, what, **kwargs):
ui.window(id="window")
ui.vbox(id="say_vbox")
ui.text(who, id="who")
ui.text(what, id="what")
ui.close()
renpy.define_screen("say", say_screen)
以下の関数はスクリーンの定義、表示、非表示をサポートします。
renpy.call_screen(_screen_name, *args, **kwargs) linkプログラム的には call screen ステートメントと等価です。
これはスクリーンとして _screen_name を表示し、インタラクションを実行します。スクリーンはインタラクションが終わると非表示になり、インタラクションの結果が返されます。
_ で始まらない位置引数、キーワード引数はスクリーンに渡されます。
キーワード引数 _with_none が False なら「 with None 」はインタラクションの終わりに実行されません。
kwargs に _mode キーワード引数があれば、それがこのインタラクションのモードになり、そうでなければ "screen" モードになります。
renpy.define_screen(name, function, modal="False", zorder="0", tag=None, variant=None) linkname は文字列で、これを名前に持つスクリーンを定義します。
スクリーンを表示するために呼び出される関数です。関数はそのスクリーンのスコープをキーワード引数として呼び出されます。追加のキーワード引数は無視するべきです。
スクリーンに追加するためには、関数は UI 関数を呼び出すべきです。
作成されるスクリーンがモーダルであるかどうかを決定するために評価される文字列です。モーダルなスクリーンは その下にあるスクリーンが入力イベントを受け取ることを防ぎます。
評価すると整数になる文字列です。整数はスクリーンが表示される順番を制御します。 大きな zorder を持つスクリーンほど小さな zorder を持つスクリーンの上に表示されます。
このスクリーンに関連づけられるタグです。スクリーンが表示されると、同じタグを持つ他のすべてのスクリーンを置き換えます。タグはデフォルトではスクリーンの名前です。
True ならこのスクリーンは画像を予測のためにロード出来ます。 False なら出来ません。デフォルトでは True です。
使用するスクリーンバージョンの文字列です。
renpy.get_displayable(screen, id, layer=None, base=False) linklayer 上の screen から id を持つ ウィジェットを返します。スクリーンが存在しないか、そのスクリーン上にその id を持つウィジェットが存在しなければ None を返します。
renpy.get_displayable_properties(id, screen=None, layer=None) linklayer 上の screen にある id のウィジェットのプロパティーを返します。screen が None なら、現在のスクリーンに対するプロパティーを返します。これは python やスクリーン内のプロパティーコードから使用出来ます。
これはそのウィジェットのプロパティーを持つ辞書を返すので、そこから各プロパティーを所得出来ることに注意してください。
renpy.get_screen(name, layer=None) link与えられた name を持つレイヤー上の ScreenDisplayable を返します。name は画像タグと解釈され、なければスクリーンの名前と解釈されます。そのスクリーンが表示されていなければ None が返されます。
name は name のリストでもかまいません、その場合表示されている最初のスクリーンが返されます。
この関数を使用してスクリーンが表示されているかチェック出来ます。例
if renpy.get_screen("say"):
text "The say screen is showing."
else:
text "The say screen is hidden."
renpy.hide_screen(tag, layer=None) linkプログラム的に hide screen ステートメントと等価です。
layer 上の tag を持つスクリーンを非表示にします。
renpy.predicting() linkRen'Py が現在スクリーンを予測していれば True を返します。
renpy.set_focus(screen, id, layer=u'screens') linkscreen 中の id を持つ displayable にフォーカスを試みます。これはその Displayable が見つからなければ失敗し、そのウィンドウはフォーカスされないか、他のものにフォーカスします。
この呼び出しが処理されると僅かでもマウスが移動するとフォーカスは変化します。
renpy.show_screen(_screen_name, *_args, **kwargs) linkプログラム的には show screen ステートメントと等価です。
その名前のスクリーンを表示します。これは以下のキーワード引数を取ります。 :
表示するスクリーンの名前です。
スクリーンを表示するためのレイヤーです。
スクリーンに表示する zorder です。指定されなければそのスクリーンのデフォルトの zorder です。それもなければ 0 になります。
表示するスクリーンのタグです。指定されなければそのスクリーンのデフォルトのタグです。それもなければデフォルトでそのスクリーンの名前になります。
ウィジェットの id からプロパティーの名前を得る辞書、つまりプロパティーを値に持つ辞書です。その id のウィジェットがスクリーンに表示されると、指定したプロパティーがそこに追加されます。
True ならスクリーンは現在のインタラクションが終わると自動的に非表示になります。
アンダースコア (_) で始まらない位置引数とキーワード引数はそのスクリーンに渡されます。
renpy.start_predict_screen(_screen_name, *args, **kwargs) link_screen_name という名のスクリーンを指定された引数で表示したときの予測を Ren'Py に開始させます。これは _screen_name の以前の予測を置き換えます。スクリーンの予測を停止するためには renpy.stop_predict_screen() を呼び出してください。
renpy.stop_predict_screen(name) linkname という名のスクリーンの予測を停止させます。
renpy.variant(name) linkname が Ren'Py に選択され得るスクリーンバージョンなら True を返します。詳細は スクリーンバージョン を参考にしてください。この関数を python if ステートメントで条件に使用して、選択したスクリーンバージョンに対して適切なスタイルを設定出来ます。
name はスクリーンバージョンのリストでもかまいません、その場合この関数はそのどのスクリーンバージョンが選択されても True を返します。
注釈
Ren'Py の実装が変更され、 displayable を作成する UI 関数は現在スクリーン言語による実装よりかなり遅くなりえます。
UI 関数はスクリーン言語と等価な python です。各スクリーン言語のステートメントに対して、同じ名前の UI 関数があります。例えば ui.text は text ステートメントに対応し、 ui.add は add ステートメントに対応します。
スクリーン言語のパラメーターや引数と python の引数には簡単な対応関係があります。スクリーン言語のパラメーターは位置引数に、プロパティーはキーワード引数になります。例えば、スクリーン言語のステートメントではこれが
text "Hello, World" size 40 xalign 0.5
こうなります。
ui.text("Hello, World", size=40, xalign=0.5)
( 実際には id 引数が追加されるべきです。 )
UI 関数にはそれらが取る子の数に対応した三つのグループがあります。
以下の UI 関数は子を受け取りません。
以下の UI 関数は一つの子を取ります。これらはその子を与えられる必要があり、子がないと、 ui.null() を使用します。
以下の UI 関数は複数の子を受け取ります。これらは ui.close() が呼び出されるまでは子を受け付けます。
スクリーン言語には存在しない考え方に対応するため、僅かにスクリーン言語のステートメントに対応しない UI 関数もあります。
ui.adjustment(range=1, value=0, step=None, page=None, changed=None, adjustable=None, ranged=None, force_step=False) linkadjustment オブジェクトは bar や viewport によって調整される値を表します。これは値や値の範囲、 step と page での値の調整法についての情報を含みます。
以下のパラメーターは adjustment オブジェクトのフィールドやプロパティーに対応します。 :
adjustment の範囲で,数字です。
adjustment の値で、数字です。
adjustment の一つの step のサイズで、数字です。 None ならデフォルトでは page が設定されていればその10分の1で、そうでなければ range の10分の1です。
これはマウスホイールで viewport をスクロールするときに使用されます。
adjustment の page あたりのサイズです。 None ならこれは viewport により自動的に設定されます。もし設定されなければ、デフォルトで range の10分の1です。
スクロールバーをクリックすると使用されます。
以下のパラメーターは adjustment の動作を制御するします。
True ならこの adjustment はbar から変更できます。 False なら出来ません。
デフォルトでは changed 関数が与えられているか adjustment が viewport に関連づけられていれば変更可能で、さもなければ出来ません。
この関数は adjustment の値が変更されるとその新しい値を引数に呼び出されます。
この関数は adjustment の range が viewport によって設定されると adjustment オブジェクトを引数に呼び出されます。
レイアウトの過程でこの関数は複数回呼び出されます。
adjustment が viewport や bar に対応する draggable で変更され、かつこれが True ならばドラッグが次のステップに達したときのみ値が変更されます。 adjustment が viewport や bar に対応する draggable で変更され、かつこれが "release" ならば、 draggable の解放時、値は最も近いステップに丸められます。 False ならばこの adjustment はステップの値を無視します。
change(value) linkadjustment の値を value に変更し、その adjustment を使用しているすべての bar や viewport が更新されます。
ui.at(transform) link次に作成される displayable に適用される transform を指定します。すべての UI 関数が今は at 引数を受け取るため、これはもはや過去の遺物です。
ui.close() linkUI 関数で作成した displayable を 閉じます。 displayable を閉じるとき、 displayable が何も開かれていなけらば新しい displayable をその親か、レイヤーに追加します。
ui.detached() link次の displayable をその先の displayable やコンテナに追加しません。これは ui 関数の結果を変数に代入したいなら使用してください。
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 内部で使用するために存在するのですべての引数はキーワード引数として渡してください。
ロールバック時にこの関数から返される情報です( None ならロールフォワードは無視されます)。これには通常 renpy.roll_forward_info() 関数の結果が渡されるはずです。
この関数を実行中のマウスカーソルのスタイルです。
ui.layer(name) linkname と名付けられたレイヤーに displayable を追加します。そのレイヤーは ui.close() で閉じられなければなりません。
ui.screen_id(id_, d) linkその id で screen ステートメントに作成されたかのように displayable d をスクリーンウィジェットid id_ に代入します。
スクリーン言語で作成された displayable の多くは引数としてアクションを取ります。アクションは以下の三つのうちいずれかです。 :
引数を取らない呼び出し可能な ( 関数や bound method のような ) python オブジェクト
Action クラスを継承するクラスのオブジェクト
他のアクションのリスト
Action クラスを継承する利点はボタンが有効か、選択されているかを設定するメソッドを上書き可能なことです。
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() を呼び出すことです。
引数を一つ取ります。
このアクションに関連づけられたスクリーンか displayable が最初に表示されてからの秒数です。
unhovered(self) linkアクションがボタン ( または同様なオブジェクト ) への hovered パラメーターとして使用されると、このメソッドはそのオブジェクトがフォーカスを失うと呼び出されます。
pythonからアクションを実行するには renpy.run() を使用してください。
renpy.is_selected(action) linkaction が選択状態なら True を返し、そうでないなら False を返します。
renpy.is_sensitive(action) linkaction が有効状態なら True を返し、そうでないなら False を返します。
renpy.run(action) linkアクションまたはアクションのリストを実行します。単体のアクションは引数なしで呼び出され、アクションのリストはこの関数で順番に実行されます。 None は無視されます。
最後のアクションの結果の値を返します。
bar, vbar または hotbar 作成時に BarValue オブジェクトは value 引数に提供されます。 BarValue オブジェクトのメソッドは adjustment やスタイルを得るために呼び出されます。
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 メソッドを呼び出すべきです。
input 作成時に、 InputValue オブジェクトは value プロパティーとして提供されます。 InputValue オブジェクトのメソッドは テキストの設定と所得、編集可能かどうか、エンターキーが押されたときの処理を決定するために呼び出されます。
InputValue link新しい InputValue を定義するためには、このクラスを継承してそのメソッドを上書きしてください。
default linkTrueなら、input はデフォルトで編集可能な状態です(スクリーン表示時に、キャレットが与えられます)。
get_text(self) link入力されたテキストを返します。これは実装されなければいけません。
set_text(self, s) link入力されたテキストが変更されると、新しいテキストで呼び出されます。これは実装されなければいけません。
enter(self) linkユーザーがエンターを押すと呼び出されます。これが None 以外を返すと、その値がインタラクションから返されます。これは renpy.IgnoreEvent() でイベントを投げて押下を無視します。そうでなければ、他の displayable にエンターキーの押下が伝達されます。
以下のアクションは InputValue で利用可能なメソッドです。 :
Enable() linkテキストを編集可能にするアクションを返します。
Disable() linkテキストを編集不能にするアクションを返します。
Toggle() 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 関数で登録されます。 :
renpy.register_sl_displayable(name, displayable, style, nchildren=0, scope=False, replaces=False, default_keywords={}, default_properties=True) linkdisplayable を作成するユーザー定義のスクリーン言語ステートメントを登録します。
スクリーン言語ステートメントの名前でと Ren'Py のキーワードを含む文字列です。このキーワードは新しいステートメントを導入するために使用されます。
これは関数で、呼び出されると displayable オブジェクトを返します。すべての位置引数、プロパティーとスタイルプロパティーはこの関数へ引数として渡されます。その他のキーワード引数も以下のようにこの関数へ渡されます。
これは displayable を返すべきです。 複数の displayable を返すと最も外側の displayable の _main 属性が "main" displayable に設定され、子はこれに追加されます。
この displayable のスタイルのベース名です。 スタイルプロパティーが指定されないと、これにスタイル接頭辞を追加します。結果のスタイルが displayable 関数に style キーワード引数として渡されます。
この displayable の子の数で、次のうちのひとつです。 :
displayable は子を取りません。
displayable はひとつ子を取ります。ひとつ以上の子が与えられると、子は Fixed に配置されます。
displayable ひとつ以上の子を取ります。
以下の引数はキーワード引数を使って渡されるべきです。
True で、 displayable が以前の displayable を置き換えるなら、新しい displayable に対する引数としてその displayable は渡されます。
その displayable に与えられるキーワード引数のデフォルトの設定です。
True なら ui と position プロパティーがデフォルトで追加されます。
以下のメソッドを呼び出して、追加する位置引数とプロパティーを指定出来るオブジェクトを返します。それらの各メソッドは同様に呼び出せるオブジェクトを返し、メソッドをひとつなぎに出来ます。
add_positional(name) linkname の位置引数を追加します。
add_property(name) linkname のプロパティーを追加します。プロパティーはキーワード引数として渡されます。
add_style_property(name) linkname で終り、さまざまなスタイルプロパティー接頭辞を接頭辞にするプロパティーの一群を追加します。例えば ("size") で呼び出されると、size, idle_size, hover_size などを定義します。
add_prefix_style_property(prefix, name) linkprefix とスタイルプロパティーの接頭辞、 name で構成された名前を持つプロパティーの一群を追加します。例えば prefix が text_ name が size で呼び出されると、これは text_size, text_idle_size, text_hover_size などを作成します。
add_property_group(group, prefix='') linkprefix を接頭辞に持つプロパティーのグループを追加します。 Group は次の文字列のうちの一つです。 :
これらは スタイルのプロパティー のグループに対応します。グループは "ui" にも出来、その場合 ユーザーインターフェイス共通のプロパティー を追加します。
renpy.register_sl_statement(name, children=u'many', screen=None) linkRen'Py にユーザー定義のスクリーン言語ステートメントを登録します。
これは単語でなくてはいけません。そのユーザー定義スクリーン言語ステートメントの名前になります。
このユーザー定義ステートメントが受け取る子の数です。これは 0, 1 または 0 以上を表す "many" であるべきです。
使用するスクリーンです。未指定では 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