スクリーンと Python link

スクリーン言語同様に、 Ren'Py は python でのスクリーンの定義をサポートします。 python でのスクリーンはスクリーン関数を renpy.define_screen() に与えることで作成され、どんなスクリーンにも使用できます。

スクリーン関数は期待するスコープ変数に対する引数を受け取り、それ以外のキーワード引数は無視するべきです。( それ故その引数の末尾には **kwargs を持つべきです。 ) スクリーンに displayable を追加するためには UI 関数を呼び出します。スクリーン関数はインタラクションが開始するか再開すると呼び出されます。

この再開がユーザーにとってシームレスであることを保証するために、 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)

スクリーン関数 link

以下の関数はスクリーンの定義、表示、非表示をサポートします。

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

プログラム的には call screen ステートメントと等価です。

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

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

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

renpy.define_screen(name, function, modal="False", zorder="0", tag=None, variant=None) link

name は文字列で、これを名前に持つスクリーンを定義します。

function

スクリーンを表示するために呼び出される関数です。関数はそのスクリーンのスコープをキーワード引数として呼び出されます。追加のキーワード引数は無視するべきです。

スクリーンに追加するためには、関数は UI 関数を呼び出すべきです。

modal

作成されるスクリーンがモーダルであるかどうかを決定するために評価される文字列です。モーダルなスクリーンは その下にあるスクリーンが入力イベントを受け取ることを防ぎます。

zorder

評価すると整数になる文字列です。整数はスクリーンが表示される順番を制御します。 大きな zorder を持つスクリーンほど小さな zorder を持つスクリーンの上に表示されます。

tag

このスクリーンに関連づけられるタグです。スクリーンが表示されると、同じタグを持つ他のすべてのスクリーンを置き換えます。タグはデフォルトではスクリーンの名前です。

predict

True ならこのスクリーンは画像を予測のためにロード出来ます。。 False なら出来ません。デフォルトでは True です。

variant

使用するスクリーンの変数の文字列です。

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.get_widget(screen, id, layer=None) link

layer 上の screen から id を持つ ウィジェットを返します。スクリーンが存在しないか、そのスクリーン上にその id を持つウィジェットが存在しなければ None を返します。

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

layer 上の screen にある id のウィジェットのプロパティーを返します。screen が None なら、現在のスクリーンに対するプロパティーを返します。

これはスクリーンのコード内部で使用されます。

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

renpy.hide_screen(tag, layer=None) link

プログラム的に hide screen ステートメントと等価です。

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

renpy.predicting() link

Ren'Py が現在スクリーンを予測していれば True を返します。

renpy.show_screen(_screen_name, *_args, **kwargs) link

プログラム的には show screen ステートメントと等価です。

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

_screen_name

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

_layer

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

_tag

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

_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() を呼び出してください。

renpy.stop_predict_screen(name) link

name という名のスクリーンの予測を停止させます。

renpy.variant(name) link

name が Ren'Py に選択され得るスクリーンバージョンなら True を返します。詳細は スクリーンバージョン を参考にしてください。この関数は python if ステートメントで条件に使用して、選択したスクリーンバージョンに対して適切なスタイルを設定出来ます。

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

UI 関数 link

SL2 の利点により、 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.add
  • ui.bar
  • ui.imagebutton
  • ui.input
  • ui.key
  • ui.label
  • ui.null
  • ui.text
  • ui.textbutton
  • ui.timer
  • ui.vbar
  • ui.hotspot
  • ui.hotbar
  • ui.spritemanager

以下の UI 関数は一つの子を取ります。これらはその子を与えられる必要があり、子がないと、 ui.null() を使用します。

  • ui.button
  • ui.frame
  • ui.transform
  • ui.window
  • ui.drag

以下の UI 関数は複数の子を受け取ります。これらは ui.close() が呼び出されるまでは子を受け付けます。

  • ui.fixed
  • ui.grid
  • ui.hbox
  • ui.side
  • ui.vbox
  • ui.imagemap
  • ui.draggroup

スクリーン言語には存在しない考え方に対応するため、僅かにスクリーン言語のステートメントに対応しない UI 関数もあります。

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

adjustment オブジェクトは bar や viewport によって調整されるvalueを表します。これは値や値の範囲、 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 の値が変更されるとその新しい値を引数に呼び出されます。

ranged

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

change(value) link

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

ui.at(transform) link

次に作成される displayable に適用される変換を指定します。すべての UI 関数が今は at 引数を受け取るため、これはもはや過去の遺物です。

ui.close() link

UI 関数で作成した 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 内部で使用するために存在するのですべての引数はキーワード引数として渡してください。

roll_forward

ロールバック時にこの関数から返される情報です。( None ならロールフォワードは無視されます。) これには通常 renpy.roll_forward_info() 関数の結果が渡されるはずです。

mouse

この関数を実行中のマウスカーソルのスタイルです。

ui.layer(name) link

name と名付けられたレイヤーに displayable を追加します。そのレイヤーは ui.close() で閉じられなければなりません。

ui.screen_id(id_, d) link

その id で screen ステートメントに作成されたかのように displayable d をスクリーンウィジェットid id_ に代入します。

アクション 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 を返します。

periodic(self, st) link

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

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

引数を一つ取ります。

st

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

unhovered(self):

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

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

renpy.is_selected(action) link

action が選択状態なら True を返し、そうでないなら False を返します。

renpy.is_sensitive(action) link

action が有効状態なら True を返し、そうでないなら False を返します。

renpy.run(action) link

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

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

ui.is_selected(action) link

action が選択状態なら True を返し、そうでないなら False を返します。

ui.is_sensitive(action) link

action が有効状態なら True を返し、そうでないなら False を返します。

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") です。

replaces(self, other) link

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

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

periodic(self, st) link

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

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

InputValue link

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

class InputValue link

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

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={}) 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 ひとつ以上の子を取ります。

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

replaces

True で、 displayable が以前の displayable を置き換えるなら、新しい displayable に対する引数としてその displayable は渡されます。

default_keywords

その displayable に与えられるキーワード引数のデフォルトの設定です。

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

add_positional(name) link

name の位置引数を追加します。

add_property(name):

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

add_style_property(name):

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

add_prefix_style_property(prefix, name):

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

add_property_group(group, prefix=''):

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

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

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

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

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

name

これは単語でなくてはいけません。そのユーザー定義スクリーン言語ステートメントの名前になります。

positional

このステートメントが受け取る位置引数の数です。

children

このユーザー定義ステートメントが受け取る子の数です。これは 0, 1 または 0 以上を表す "many" であるべきです。

screen

使用するスクリーンです。未指定では name になります。

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

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

python early:
    renpy.register_sl_statement("titledwindow", positional=1, children=1).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