界面行為(action)、值(value)和函數 link

Ren’Py帶來了一大堆行為、值和函數，與界面和界面語言協同作用。

行為(action) link

當某個按鈕(包括圖片按鈕、文本按鈕和hotspot按鈕)被啟用、被滑鼠懸停或失去滑鼠懸停狀態時，某個行為(action)就會被喚起。當某個按鈕被選中或者非啟用時，行為(action)就可能已經決定了。

與這些行為一樣，某個行為可以是一個不帶任何入參的函數。當行為被喚起時，對應的函數就會調用。如果那個行為返回某個值，返回的值就會傳到來源交互動作。

需要使用行為的地方也可能出現的是一個行為的列表，列表內的行為會順序運行。

控制行為 link

這些行為用於管理界面，交互結果和流程控制。

Call(label, *args, **kwargs) link: 結束當前語句，並調用某個腳本標籤(label)。入參和關鍵字參數會傳給 renpy.call() 。

Hide(screen=None, transition=None, _layer=None) link

如果名為 screen 的界面已經顯示，則隱藏這個界面。

screen: 若為字串，表示待隱藏界面的名稱。若為None，表示待隱藏界面為當前界面。
transition: 如果非None，隱藏界面時使用轉場(transition)。
_layer: 該項將作為layer參數傳入 renpy.hide_screen()。若該項為None則忽略。

Jump(label) link: 觸發主控流程轉到腳本標籤 label 處。

NullAction(*args, **kwargs) link

不做任何事。

可以用作某個按鈕的“滑鼠懸停/滑鼠離開”事件響應，不執行任何行為。

Return(value=None) link

使用提供的值返回給當前的互動行為，提供的值不可以為None。常用於菜單和imagemap，用來選擇交互行為的返回值。如果使用的是 call screen 語句調用界面，返回值就會放置在 _return 變數中。

如果出現在某個菜單中，值會返回給來源菜單。(這種情況下就需要返回None。)

Show(screen, transition=None, *args, **kwargs) link

觸發另一個界面的顯示。 screen 是給定待顯示的界面名。入參會傳給正在顯示的界面。

如果 transition 非空，則會用作新界面顯示時的轉場效果。

ShowTransient(screen, transition=None, *args, **kwargs) link

顯示一個臨時界面。臨時界面會在當前交互完成後隱藏。入參會傳給當前顯示的界面。

如果 transition 非空，則會用作新界面顯示時的轉場效果。

ToggleScreen(screen, transition=None, *args, **kwargs) link

切換界面的可視性。如果某個界面當前沒有顯示，則會使用提供的入參顯示那個界面。相反，則隱藏那個界面。

如果 transition 非空，則會用作新界面顯示時的轉場效果。

數據行為 link

這些行為設置或者切換數據。

AddToSet(set, value) link

將 value 添加到 set 中。

set: 待添加元素的集合。其可以是一個Python的集合或者列表數據列表。如果是列表的話，新增的值會追加到列表結尾。
value: 待添加或追加的值。

RemoveFromSet(set, value) link

將 value 從 set 中移除。

set: 待移除元素的集合，可以是一個集(set)或者列表(list)型數據。
value: 待移除的元素。

SetDict(dict, key, value) link: 將字典型數據 dict 中鍵值 key 對應的值設置為 value 。

SetField(object, field, value) link: 將某個對象的欄位(field)設置為給定的值。 object 是目標對象， field 是待設置的欄位名稱的字串， value 是需要設置成的值。

SetLocalVariable(name, value) link

將指定的變數 name 設置為當前本地上下文中的值 value。

只有在某個界面(screen)被另一個場景(scene)使用的情況，才會用到該函數。其提供了一種方法，可以設置界面使用變數的值。在其他需要修改變數值的情況下，推薦使用 SetScreenVariable() ，那可以快取更多的界面數據。

該函數能賦值的變數僅限當前上下文中創建——其他地方創建的變數不能通過該函數進行設置和傳遞。

SetScreenVariable(name, value) link: 將與當前界面關聯的變數 name 值設置為 value 。

SetVariable(variable, value) link: 將變數 variable 設置為 value 。

ToggleDict(dict, key, true_value=None, false_value=None) link

切換 dict 中鍵 key 的值。“切換”的意思是，當對應的行為執行後，原布爾值取反。

true_value: 如果非None，這就是我們使用的True值。
false_value: 如果非None，這就是我們使用的False值。

ToggleField(object, field, true_value=None, false_value=None) link

切換 object 上 field 的值。“切換”的意思是，當對應的行為執行後，原欄位(field)上所有布爾值取反。

true_value: 如果非None，這就是我們使用的True值。
false_value: 如果非None，這就是我們使用的False值。

ToggleLocalVariable(name, true_value=None, false_value=None) link

切換當前本地上下文中 name 的值。

只有在某個界面(screen)被另一個場景(scene)使用的情況，才會用到該函數。其提供了一種方法，可以設置界面使用變數的值。在其他需要修改變數值的情況下，推薦使用 ToggleScreenVariable() ，那可以快取更多的界面數據。

該函數能賦值的變數僅限當前上下文中創建——其他地方創建的變數不能通過該函數進行設置和傳遞。

true_value: 如果非None，這就是我們使用的True值。
false_value: 如果非None，這就是我們使用的False值。

ToggleScreenVariable(name, true_value=None, false_value=None) link

切換當前界面變數 name 的值。

true_value: 如果非None，這就是我們使用的True值。
false_value: 如果非None，這就是我們使用的False值。

ToggleSetMembership(set, value) link

切換集 set 中 value 的成員。如果對應的值在集裡不存在，會添加那個值到集合中。否則，就會移動那個值。

帶有這個行為的按鈕會被標記為被選中(selected)狀態，僅當那個值存在於集 set 中。

set: 待添加或移除成員的集合。其可以是一個集(set)或列表(list)。如果是列表，就會在列表中結尾添加新元素。
value: 需要添加的值。

ToggleVariable(variable, true_value=None, false_value=None) link

切換 variable 。

true_value: 如果非None，這就是我們使用的True值。
false_value: 如果非None，這就是我們使用的False值。

菜單行為 link

以下行為(action)會喚起菜單，或者主要用在主選單和遊戲菜單中。

MainMenu(confirm=True) link

觸發Ren’Py回到主選單。

confirm: 若為True，觸發Ren’Py詢問用戶是否希望返回主選單，而不是直接返回。

Quit(confirm=None) link

退出遊戲。

confirm: 若為True，提示用戶是否希望退出，而不是直接退出。若為None，僅當用戶不處於主選單時才詢問。

ShowMenu(screen=None, *args, **kwargs) link

如果不在遊戲菜單中的話，就進入遊戲菜單。如果已經處於遊戲菜單，就顯示某個界面或跳轉到某個腳本標籤(label)。

screen 通常是某個界面的名稱，使用界面機制顯示。如果界面不存在，就會在 screen 後面加上“_screen”，並跳轉到對應的腳本標籤(label)處。

ShowMenu(“load”)
ShowMenu(“save”)
ShowMenu(“preferences”)

也可以用來顯示用戶自訂的菜單界面。例如，創作者定義了一個名為“state”的界面，可以把“state”界面顯示為遊戲菜單的一部分，使用如下語句：

ShowMenu(“stats”)

不帶入參的ShowMenu語句默認進入遊戲菜單。

額外的入參和關鍵字參數會傳給對應的界面。

Start(label='start') link

讓Ren’Py從菜單上下文跳轉到目標名的腳本標籤(label)處。主要用處是從主選單開始新遊戲。通常的用法如下：

Start() - 從start腳本標籤(label)處開始。
Start(“foo”) - 從“foo”腳本標籤(label)處開始。

文件行為 link

這些行為會處理文件的保存、讀取和刪除。其中很多都是用 name 和 page 入參。

name: 待保存內容的檔案名。其可以是一個字串或者一個整數。與 page 一起創建檔案名。
page: 行為實際執行的頁面(page)。其值是“auto”、“quick”或者一個正整數。若為None，page的值會根據持久化頁面編號自動確定。

如果設置了 config.file_slotname_callback，則會使用該配置項並轉為一個存檔槽位名稱。

FileAction(name, page=None, **kwargs) link

對文件“進行正確操作”。這意味著在load界面顯示時進行文件讀取操作，相反在save界面顯示時進行文件保存操作。

name: 存檔或讀檔時，槽位的名稱。如果為None，一個未被使用的槽位(基於當前時間的巨大數字)就會被使用。
page: 存檔或讀檔時使用的頁面編號(page)。若為None，就使用當前頁面。

其他關鍵字入參會傳給FileLoad或者FileSave。

FileDelete(name, confirm=True, page=None) link

刪除文件。

name: 要刪除的存檔槽名稱。
confirm: 若為True，刪除文件前提示用戶確認。
page: 存檔或讀檔時使用的頁面編號(page)。若為None，就使用當前頁面。

FileLoad(name, confirm=True, page=None, newest=True) link

讀取文件。

name: 讀取的槽位名稱。若為None，an unused slot the file will not be loadable。
confirm: 如果為True且當前不在主選單，在讀取文件前提是用戶確認。
page: 文件讀取的頁面編號。如果為None，就是用當前頁面。
newest: 如果為True，按鈕會被選中，前提是其為最新的文件。
cycle: 忽略。
slot: 若為True，使用 name 參數，而忽略 page 參數。

FilePage(page) link: 將文件頁面設置為 page ，其可以是“auto”、“quick”或一個整數。

FilePageNext(max=None, wrap=False) link

前往下一個文件頁面(page)。

max: 若該值存在，應該是整數，給定了我們前往的文件最大頁面編號。
wrap: 若為True，我們可以從文件最後的頁面前往第一頁面，前提是設置了頁面最大編號。
auto: 若此參數和 warp 都為True，將會把玩家帶往自動存檔頁。
quick: 若此參數和 warp 都為True，將會把玩家帶往快速存檔頁。

FilePagePrevious(max=None, wrap=False) link

前往上一個文件頁面，前提是上一個頁面存在的話。

max: 若該值存在，應該是整數，給定了我們前往的文件最大頁面編號。需要啟用wrap。
wrap: 若為True，我們可以從文件第一頁面前往最後的頁面，前提是設置了頁面最大編號。
auto: 若此參數和 warp 都為True，將會把玩家帶往自動存檔頁。
quick: 若此參數和 warp 都為True，將會把玩家帶往快速存檔頁。

FileSave(name, confirm=True, newest=True, page=None, cycle=False) link

保存文件。

帶槽位的按鈕被選中，如果其被標記為最新存檔文件。

name: 待存檔的槽位名。如果為None，一個未被使用的槽位(基於當前時間的巨大數字)就會被使用。
confirm: 若為True，覆蓋文件前提示用戶確認。
newest: 忽略。
page: 槽位所在頁面名稱。若為None，使用當前頁面。
cycle: 如果為True，在提供的頁面上存檔會循環使用而並不會顯示給用戶看。config.quicksave_slots 配置了循環使用的槽位。
slot: 若為True，使用 name 參數，而忽略 page 參數。

FileTakeScreenshot(*args, **kwargs) link: 當遊戲存檔時，截取螢幕快照並使用。通常使用存檔界面顯示之前的界面截圖，用作存檔的快照。

QuickLoad(confirm=True) link

快速讀檔。

confirm: 若為True，且目前不在主選單界面，讀檔前提是用戶確認。

QuickSave(message='Quick save complete.', newest=False) link

快速存檔。

message: 當快速存檔完成時向用戶顯示的一條資訊。
newest: 設置為True用於標記快速存檔為最新的存檔。

同步行為 link

DownloadSync() link: 該行為會從Ren’Py同步伺服器端下載數據並同步。

UploadSync() link: 該行為會將最後存檔文件上傳到Ren’Py同步伺服器端。

音訊行為 link

關於音訊通道(channel)的概念和工作機制，大多數資訊都可以在音訊中找到解釋。

PauseAudio(channel, value=True) link

音訊通道 channel 設置暫停標識(flag)。

如果 value 為True，通道channel會暫停。相反，通道channel會從暫停恢復。如果值為“toggle”，暫停標識會進行切換，即布爾值進行“邏輯非”操作。

Play(channel, file, selected=None, **kwargs) link

在指定通道(channel)播放一個音訊檔案。

channel: 播放使用的通道(channel)。
file: 播放的文件。
selected: 若為True，當文件在通道上播放時，使用這個行為的按鈕會被標記為“被選中”。若為False，這個行為不會觸發按鈕啟動播放。若為None，當通道是一個音樂(music)通道時按鈕會被標記為“被選中”。

其他關鍵字參數會被傳給 renpy.music.play()。

Queue(channel, file, **kwargs) link

在給定的通道上將音訊檔案隊列化。

channel: 播放使用的通道(channel)。
file: 播放的文件。

其他關鍵字參數會被傳給 renpy.music.queue()。

SetMixer(mixer, volume) link

將 mixer 的音量設定為 value 。

mixer: 需要調整音量的混合器(mixer)。這個字串通常是“main”、“music”、“sfx”或“voice”。混合器的資訊詳見音量。
value: 調整的目標音量值。是一個位於0.0至1.0閉區間內的數值。

SetMute(mixer, mute) link

將一個或多個混合器設置為靜音狀態。當混合器靜音時，與混合器關聯的音訊通道會停止播放音訊。

mixer: 給出單個混合器名稱的字串，或一個混合器列表名稱的字串列表。混合器名稱通常是“music”、“sfx”或“voice”。
mute: 若為True則靜音混合器，若為False則取消混合器靜音。

Stop(channel, **kwargs) link

停用某個音訊通道。

channel: 停用的音訊通道名。

關鍵字參數會傳給 :func:renpy.music.stop()。

ToggleMute(mixer) link

切換混合器的靜音狀態。

mixer: 單個混合器名稱的字串，或一個混合器列表名稱的字串列表。混合器名稱通常是“music”、“sfx”或“voice”。

獲取焦點行為 link

CaptureFocus(name='default') link

若某個可視組件獲得焦點並執行該行為，將儲存一塊包含可視組件的矩形區域，並根據入參 name 命名。該矩形區域可通過 GetFocusRect() 或 nearrect 組件的 focus 特性訪問。若沒有可視組件獲得焦點，上次捕獲的矩形區域將從儲存區移除。

name: 獲得焦點矩形區域儲存名稱。其應是一個字串。如果設置為“tooltip”則比較特殊，當提示消息改變時，將執行自動捕獲。

ClearFocus(name='default') link: 使用 CaptureFocus() 函數清除儲存的矩形區域焦點。

GetFocusRect(name='default') link

若指定名稱的矩形區域在儲存區中(無論是使用 CaptureFocus() 捕獲還是tooltip自動捕獲)，返回一個(x, y, h, w)形式的矩形。否則返回None。

name: 獲得焦點矩形區域檢索名稱。其應是一個字串。如果設置為“tooltip”則比較特殊，當提示消息改變時，將執行自動捕獲。

ToggleFocus(name='default') link

若焦點矩形區域存在則清除，否則捕獲。

name: 獲得焦點矩形區域儲存名稱。其應是一個字串。如果設置為“tooltip”則比較特殊，當提示消息改變時，將執行自動捕獲。

其他行為 link

這些是其他地方找不到的一些行為。

Confirm(prompt, yes, no=None, confirm_selected=False) link

提示用戶進行確認的一種行為。如果用戶點擊了“是”，將執行 yes 行為。否則，執行 no 行為。

prompt: 向用戶顯示的提示內容。
confirm_selected: 若為True，當yes行為被選中後，提示 prompt 依然會顯示。若為False，也是預設值， yes 行為選中後提示就不再顯示。

這個行為的可用性和可選擇性與 yes 行為相匹配。

DisableAllInputValues() link: 禁用所有活動的輸入項。如果存在默認輸入項的話，它將重新獲得焦點。否則，任何輸入項都不會獲得焦點。

Function(callable, *args, **kwargs) link

這個行為會使用 args 和 kwargs 調用 callable 。

callable: 可調用的對象。該項假設遇到兩個相等的可調用對象，調用任意一個都是相同的。
args: 傳給 callable` 的固定位置入參。
kwargs: 傳給 callable 的關鍵字入參。

這個行為使用一個可選的 _update_screens 關鍵字參數，而且這個參數預設為True。參數為True時，函數返回後，互動行動會重新開始，各界面會更新。

如果函數返回一個非空值，互動行為會停止並返回那個值。(使用call screen語句得到的返回值放置在 _return 變數中。)

創作者可以從 Action 派生自己的子類，並替代此Function函數。這樣就可以自己命名行為，並判斷對應組件是否選中和可啟用的。

Help(help=None) link

顯示幫助。

如果定義過一個名為 help 的界面，使用 ShowMenu() 就可以顯示那個界面，並且 help 參數會被省略。

help

用於提供幫助的字串。其被用於以下兩種情況：

如果存在一個對應名稱的文本標籤(label)，對應的標籤會在新的上下文中被調用。
否則，內嵌某個給定檔案名稱，並使用web瀏覽器打開。

若 help 為None， config.help() 配置項會被用作預設值。

HideInterface(*args, **kwargs) link: 隱藏用戶介面，直到出現用戶點擊事件。

If(expression, true=None, false=None) link: 根據 expression 的結果選擇使用 true 或 false 的行為。這個函數用在基於某個表達式的結果選擇執行行為。注意入參的預設值None，也可以用作一個行為，禁用某個按鈕。

InvertSelected(action) link: 該行為將提供行為的選項狀態反轉，可以應用在別的方法上。

MouseMove(x, y, duration=0) link

將滑鼠指針移動到坐標 x, y 。如果設備沒有滑鼠指針，或者_preferences.mouse_move的值是False，那什麼都不會發生。

duration: 移動滑鼠指針行為消耗的時間，單位為秒。這個時間段內，滑鼠可能不會響應用戶操作。

Notify(message) link: 使用 renpy.notify() 函數顯示 message 內容。

OpenURL(url) link: 在web瀏覽器中打開 url 。

QueueEvent(event, up=False) link: 使用 renpy.queue_event() 將給定的事件消息加入到事件隊列中。

RestartStatement(*args, **kwargs) link

這個行為會觸發Ren’Py回滾到當前語句之前，並再次執行當前語句。可以用在某些持久化變數改變後影響語句顯示效果的情況。

在菜單語境運行的話，等到用戶退出並回到上一層語境時才會執行回滾行為。

RollForward(*args, **kwargs) link: 這個行為觸發前滾，前提是前滾可行。否則，該行為是禁用狀態。

Rollback(*args, **kwargs) link

這個行為觸發回滾，前提是回滾可行。否則，不會發生任何事。

入參將傳給 :func:renpy.rollback() 函數，除非參數 force 是預設值“menu”。

RollbackToIdentifier(identifier) link: 這個行為觸發回滾至某個標識符(identifier)。回滾標識符會作為HistoryEntry對象的一部分返回。

Screenshot(*args, **kwargs) link: 螢幕截圖。

Scroll(id, direction, amount='step') link

id: 當前界面中條(bar)、視口(viewport)或vpgrid的id。
direction: 如果是vbar，“increase”或“decrease”二選一；如果是視口或vpgrid，“horizontal increase”、“vertical increase”、“horizontal decrease”或“vertical decrease”，四選一。
amount: 滾動數量。可以使用像質數，也可以寫“step”或“page”。
delay: 若非零，表示延遲時間值。

SelectedIf(expression) link

這個行為允許某個表達式控制一個按鈕是否被標記為選中狀態。其應被用作包含一個或多個行為的列表的一部分。例如：

# 如果mars_flag為True時，按鈕會被選中
textbutton "Marsopolis":
    action [ SelectedIf(SetVariable("mars_flag", True)), SetVariable("on_mars", True) ]

點擊按鈕後，在SeletedIf內部的行為會被正常執行。

SensitiveIf(expression) link

這個行為允許某個表達式控制一個按鈕是否被標記為可用狀態。其應被用作包含一個或多個行為的列表的一部分。例如：

# 如果mars_flag為True時，按鈕是可用的
textbutton "Marsopolis":
    action [ SensitiveIf(SetVariable("mars_flag", True)), SetVariable("on_mars", True) ]

點擊按鈕後，在SensitiveIf內部的行為會被正常執行。

Skip(fast=False, confirm=False) link

觸發遊戲開始使用跳過(skipping)。如果遊戲處於菜單語境下，這個行為導致回到遊戲界面。否則，這個行為啟用跳過(skipping)。

fast: 若該值為True，直接跳到下一個菜單選項。
confirm: 若該值為True，在使用跳過(skipping)前需要用戶確認。

With(transition) link: 觸發 transition 生效。

還有一些行為記錄在文件的其他頁面，比如 Language、Replay、EndReplay、 gui.SetPreference、gui.TogglePreference、 StylePreference 和 voice actions。

可以通過 Action 類創建新的行為。

條(bar)值 link

條值與條(bar)一同使用，設置條(bar)的值，且允許條(bar)調整某個潛在特性。可以通過創建 BarValue 類的子類創建一個新的條值。所有的BarValue類都有關鍵字 step ，也可以接受關鍵字 force_step ，具體情況詳見 ui.adjustment() 。

AnimatedValue(value=0.0, range=1.0, delay=1.0, old_value=None) link

將某個值序列化，使用 delay 秒的時間將 old_value 的值轉為 value 的值。

value: value值自身，是一個數值。
range: value值的範圍，是一個數值。
delay: 序列化value值的時間，單位為秒。預設值是1.0。
old_value: 舊的value值。若為None，我們使用AnimatedValue想要替換的value值。否則，其會初始化為 value 的值。

AudioPositionValue(channel='music', update_interval=0.1) link

顯示在 channel 通道播放音訊檔案播放位置的值。

update_interval: 值的更新頻率，單位為秒。

DictValue(dict, key, range, max_is_zero=False, style='bar', offset=0, step=None, action=None, force_step=False) link

允許用戶使用字典型數據的鍵調整對應的值。

dict: 字典。
key: 鍵。
range: 調整的數值範圍。
max_is_zero: 若為True，當鍵對應的值為0時，條(bar)值範圍會調整為從1到0，所有其他值都會被降低到1。同樣的，當條(bar)被設置成最大值時，鍵的值將設置為0。
style: 創建的條(bar)的樣式。
offset: 添加到條值的一個偏移量。
step: 調整條(bar)值的步進大小。若為空，預設為條(bar)的十分之一。
action: 若非None，當欄位改變時，將調用指定行為(action)。

FieldValue(object, field, range, max_is_zero=False, style='bar', offset=0, step=None, action=None, force_step=False) link

允許用戶調整某個對象上欄位(field)的條(bar)值。

object

調整的對象。

field

欄位(filed)名稱的字串。

range

可調整的範圍。

max_is_zero

若為True，當鍵對應的值為0時，條(bar)值範圍會調整為從1到0，所有其他值都會被降低到1。同樣的，當條(bar)被設置成最大值時，欄位(filed)的值將設置為0。

這偏向於某些內部使用。

style

創建的條(bar)的樣式。

offset

添加到條值的一個偏移量。

step

調整條(bar)值的步進大小。若為空，預設為條(bar)的十分之一。

action

若非None，當欄位改變時，將調用指定行為(action)。

MixerValue(mixer) link

音訊混合器的值。

mixer: 待調整的混合器名。通常是“music”、“sfx”或“voice”，創作者也可以創建新的混合器。

ScreenVariableValue(variable, range, max_is_zero=False, style='bar', offset=0, step=None, action=None, force_step=False) link

用於調整界面變數值的條(bar)值。

variable

一個字串，給出了待調整的變數名。

range

可調整的範圍。

max_is_zero

若為True，當鍵對應的值為0時，條(bar)值範圍會調整為從1到0，所有其他值都會被降低到1。同樣的，當條(bar)被設置成最大值時，variable的值將設置為0。

這偏向於某些內部使用。

style

創建的條(bar)的樣式。

offset

添加到條值的一個偏移量。

step

調整條(bar)值的步進大小。若為空，預設為條(bar)的十分之一。

action

若非None，當欄位改變時，將調用指定行為(action)。

StaticValue(value=0.0, range=1.0) link

這個行為允許某個值被指定為靜態。

value: 值自身，一個數值。
range: 數值範圍。

VariableValue(variable, range, max_is_zero=False, style='bar', offset=0, step=None, action=None, force_step=False) link

允許用戶調整默認儲存區變數值的條(bar)值。

variable

一個字串，給出了待調整的變數名。

range

可調整的範圍。

max_is_zero

若為True，當鍵對應的值為0時，條(bar)值範圍會調整為從1到0，所有其他值都會被降低到1。同樣的，當條(bar)被設置成最大值時，variable的值將設置為0。

這偏向於某些內部使用。

style

創建的條(bar)的樣式。

offset

添加到條值的一個偏移量。

step

調整條(bar)值的步進大小。若為空，預設為條(bar)的十分之一。

action

若非None，當欄位改變時，將調用指定行為(action)。

XScrollValue(viewport) link: 根據給定的id，在當前界面水平滾動視口(viewport)的可調整值。視口(viewport)必須在條(bar)值出現前定義。

YScrollValue(viewport) link: 根據給定的id，在當前界面垂直滾動視口(viewport)的可調整值。視口(viewport)必須在條(bar)值出現前定義。

輸入(input)值 link

輸入(input)值與文本輸入一起使用，用於設置默認文本、接受改變文本、響應確認鍵、決定文本是否可編輯。要創建新的輸入(input)值，可以使用 InputValue 類的子類。

Ren’Py定義的輸入(input)值繼承自InputValue類，這意味著所有輸入值均含有Enable()、Disable()和Toggle()方法，分別執行啟用(enable)、禁用(disable)和切換編輯(toggle edit)行為。可以參考 DisableAllInputValues() 行為。

DictInputValue(dict, key, default=True, returnable=False) link

將字典 dict 中鍵 key 的值更新的輸入(input)值。

default: 若為True，默認情況下輸入可以被編輯。
returnable: 若為True，當用戶按下確認鍵，輸入的值就會被返回。

FieldInputValue(object, field, default=True, returnable=False) link

一個更新某個對象上欄位(field)值的輸入值。

field: 欄位(filed)名稱的字串。
default: 若為True，輸入預設是可以被編輯的。
returnable: 若為True，當用戶按下確認鍵，輸入的值就會被返回。

FilePageNameInputValue(pattern='Page {}', auto='Automatic saves', quick='Quick saves', page=None, default=False) link

一個輸入值用於更新文件頁面(page)名。

pattern: 用於頁面(page)的默認名。使用Python風格的替換，例如花括號{}裡的內容可以替換為頁面(page)的編號。
auto: 自動保存頁面(page)的名稱。
quick: 快速保存頁面(page)的名稱。
page: 若該參數存在，給出了要顯示的頁面(page)編號。通常該值設定為None，表示當前頁面。
default: 若為True，該輸入默認可以被編輯。

ScreenVariableInputValue(variable, default=True, returnable=False) link

一個更新變數的輸入(input)值。

variable: 待更新變數名，一個字串。
default: 若為True，該輸入默認可以被編輯。
returnable: 若為True，當用戶按下確認鍵，輸入的值就會被返回。

VariableInputValue(variable, default=True, returnable=False) link

一個更新變數的輸入(input)值。

variable: 待更新變數名，一個字串。
default: 若為True，該輸入默認可以被編輯。
returnable: 若為True，當用戶按下確認鍵，輸入的值就會被返回。

函數和類 link

這些函數和類在界面方面很有用。

環境設定(preference) link

所有環境設定都可以基於上面給出的行為Action和值Value來定義。這需要一些Ren’Py方面的知識，才能選擇正確的環境設定並運用。環境設定構造器(constructor)讓這件事變得簡單，通過創建一個行為或值，就能基於名稱應用在預設的環境設定界面上。

Preference(name, value=None, range=None) link

其從某項環境設定構造了合適的行為或者值。環境設定名稱應該是在變准菜單中出現的名稱，值應該是選項名、“toggle”輪詢選項、一個指定的值，或者按鈕的名稱。

可以與按鈕和熱區一起使用的行為如下：

Preference(“display”, “fullscreen”) - 全螢幕模式顯示。
Preference(“display”, “window”) - 窗口模式顯示，1倍大小。
Preference(“display”, 2.0) - 窗口模式顯示，2倍大小。
Preference(“display”, “any window”) - 用前一種窗口尺寸顯示。
Preference(“display”, “toggle”) - 切換顯示模式。
Preference(“transitions”, “all”) - 顯示所有轉場(transition)效果。
Preference(“transitions”, “none”) - 不顯示轉場(transition)效果。
Preference(“transitions”, “toggle”) - 切換轉場(transition)效果。
Preference(“video sprites”, “show”) - 顯示所有影片精靈(sprite)。
Preference(“video sprites”, “hide”) - 可能的話，將影片精靈(sprite)降格為圖片顯示。
Preference(“video sprites”, “toggle”) - 切換圖像降格行為。
Preference(“show empty window”, “show”) - 允許“window show”和“window auto”語句在say語句之外顯示一個空窗口。
Preference(“show empty window”, “hide”) - 不允許“window show”和“window auto”語句在say語句之外顯示一個空窗口。
Preference(“show empty window”, “toggle”) - 切換上面兩種情況。
Preference(“text speed”, 0) - 文本立刻顯示。
Preference(“text speed”, 142) - 設置文本顯示速度為每秒142字元。
Preference(“joystick”) - 顯示joystick環境設定。
Preference(“skip”, “seen”) - 只跳過看過的資訊。
Preference(“skip”, “all”) - 跳過所有資訊，無論是否看過。
Preference(“skip”, “toggle”) - 切換上面兩種情況。
Preference(“begin skipping”) - 開始跳過(skipping)。
Preference(“after choices”, “skip”) - 在選項後跳過。
Preference(“after choices”, “stop”) - 在選項後停止跳過。
Preference(“after choices”, “toggle”) - 切換上面兩種情況。
Preference(“auto-forward time”, 0) - 將自動前進的時間設定為無限。
Preference(“auto-forward time”, 10) - 設置自動前進時間(單位為每秒250個字元)。
Preference(“auto-forward”, “enable”) - 啟用自動前進模式。
Preference(“auto-forward”, “disable”) - 禁用自動前進模式。
Preference(“auto-forward”, “toggle”) - 切換自動前進模式。
Preference(“auto-forward after click”, “enable”) - 在一次點擊後維持自動前進模式。
Preference(“auto-forward after click”, “disable”) - 在一次點擊後禁用自動前進模式。
Preference(“auto-forward after click”, “toggle”) - 切換上面兩種情況。
Preference(“automatic move”, “enable”) - 啟用自動滑鼠模式。
Preference(“automatic move”, “disable”) - 禁用自動滑鼠模式。
Preference(“automatic move”, “toggle”) - 切換自動滑鼠模式。
Preference(“wait for voice”, “enable”) - 自動前進時，等待當前語音播放完畢。
Preference(“wait for voice”, “disable”) - 自動前進時，不等待當前語音播放完畢。
Preference(“wait for voice”, “toggle”) - 切換語音等待模式。
Preference(“voice sustain”, “enable”) - 當前互動行為中維持語音。
Preference(“voice sustain”, “disable”) - 當前互動行為中不維持語音。
Preference(“voice sustain”, “toggle”) - 切換語音維持模式。
Preference(“music mute”, “enable”) - 音樂混合器靜音。
Preference(“music mute”, “disable”) - 取消音樂混合器靜音。
Preference(“music mute”, “toggle”) - 切換音樂靜音狀態。
Preference(“sound mute”, “enable”) - 音效混合器靜音。
Preference(“sound mute”, “disable”) - 取消音效混合器靜音。
Preference(“sound mute”, “toggle”) - 切換音效靜音狀態。
Preference(“voice mute”, “enable”) - 語音混合器靜音。
Preference(“voice mute”, “disable”) - 取消語音混合器靜音。
Preference(“voice mute”, “toggle”) - 切換語音靜音狀態。
Preference(“mixer <mixer> mute”, “enable”) - 將指定的混合器靜音。
Preference(“mixer <mixer> mute”, “disable”) - 取消指定的混合器靜音。
Preference(“mixer <mixer> mute”, “toggle”) - 切換指定的混合器靜音狀態。
Preference(“all mute”, “enable”) - 所有混合器靜音。
Preference(“all mute”, “disable”) - 取消所有混合器靜音。
Preference(“all mute”, “toggle”) - 切換所有混合器靜音狀態。
Preference(“main volume”, 0.5) - 設置對所有音訊通道的調整值。
Preference(“music volume”, 0.5) - 設置音樂音量。
Preference(“sound volume”, 0.5) - 設置音效音量。
Preference(“voice volume”, 0.5) - 設置語音音量。
Preference(“mixer <mixer> volume”, 0.5) - 設置指定混合器音量。
Preference(“emphasize audio”, “enable”) - 加強在config.emphasize_audio_channels中定義的音訊通道。
Preference(“emphasize audio”, “disable”) - 取消加強在config.emphasize_audio_channels中定義的音訊通道。
Preference(“emphasize audio”, “toggle”) - 切換音訊加強狀態。
Preference(“self voicing”, “enable”) - 啟用自動語音。
Preference(“self voicing”, “disable”) - 禁用自動語音。
Preference(“self voicing”, “toggle”) - 切換自動語音模式。
Preference(“clipboard voicing”, “enable”) - 啟用剪貼板語音。
Preference(“clipboard voicing”, “disable”) - 禁用剪貼板語音。
Preference(“clipboard voicing”, “toggle”) - 切換剪貼板語音狀態。
Preference(“debug voicing”, “enable”) - 啟用自動語音debug。
Preference(“debug voicing”, “disable”) - 禁用自動語音debug。
Preference(“debug voicing”, “toggle”) - 切換自動語音debug狀態。
Preference(“rollback side”, “left”) - 觸摸螢幕左側觸發回滾。
Preference(“rollback side”, “right”) - 觸摸螢幕右側觸發回滾。
Preference(“rollback side”, “disable”) - 觸摸螢幕不觸發回滾。
Preference(“gl powersave”, True) - 使用省電模式降低幀率。
Preference(“gl powersave”, False) - 不使用省電模式降低幀率。
Preference(“gl powersave”, “auto”) - 使用電池情況下自動啟用省電模式。
Preference(“gl framerate”, None) - 運行時顯示幀率。
Preference(“gl framerate”, 60) - 在給定的幀率下運行。
Preference(“gl tearing”, True) - (設備性能不足時)拖慢而不是跳幀。
Preference(“gl tearing”, False) - (設備性能不足時)跳幀而不是拖慢。
Preference(“font transform”, “opendyslexic”) - 將字體轉為opendyslexic(譯者註：為閱讀障礙人群設計的字體)的配置項。
Preference(“font transform”, “dejavusans”) - 將字體轉為deja vu sans的配置項。
Preference(“font transform”, None) - 禁用字體轉換。
Preference(“font size”, 1.0) - 字號縮放因子配置項。
Preference(“font line spacing”, 1.0) - 字體行距縮放因子配置項。
Preference(“system cursor”, “enable”) - 使用系統貫標，忽略 config.mouse。
Preference(“system cursor”, “disable”) - 使用config.mouse的游標。
Preference(“system cursor”, “toggle”) - 切換系統游標。
Preference(“high contrast text”, “enable”) - 啟用黑背景白文字。
Preference(“high contrast text”, “disable”) - 禁用高對比文本。
Preference(“high contrast text”, “toggle”) - 切換高對比文本。
Preference(“audio when minimized”, “enable”) - 窗口最小化後保持聲音播放。
Preference(“audio when minimized”, “disable”) - 窗口最小化後停止聲音播放。
Preference(“audio when minimized”, “toggle”) - 切換窗口最小化後的聲音播放設置。
Preference(“audio when unfocused”, “enable”) - 窗口失去焦點後保持聲音播放。
Preference(“audio when unfocused”, “disable”) - 窗口失去焦點後停止聲音播放。
Preference(“audio when unfocused”, “toggle”) - 切換窗口失去焦點後的聲音播放設置。
Preference(“web cache preload”, “enable”) - 啟用web快取預載入。
Preference(“web cache preload”, “disable”) - 禁用web快取預載入，並刪除預載入的數據。
Preference(“web cache preload”, “toggle”) - 切換web快取預載入設置。
Preference(“voice after game menu”, “enable”) - 進入遊戲設置菜單界面時繼續播放聲音。
Preference(“voice after game menu”, “disable”) - 進入遊戲設置菜單界面時停止播放聲音。
Preference(“voice after game menu”, “toggle”) - 切換進入遊戲設置菜單界面時的播放聲音設定。

可以與條(bar)一起使用的值如下：

Preference(“text speed”)
Preference(“auto-forward time”)
Preference(“main volume”)
Preference(“music volume”)
Preference(“sound volume”)
Preference(“voice volume”)
Preference(“mixer <mixer> volume”)
Preference(“self voicing volume drop”)
Preference(“font size”)
Preference(“font line spacing”)

range 參數可以指定某個條(bar)的數值範圍。例如，“text speed”的預設值是200cps。“auto-forward time”的預設值是每段文本30秒。(這些是最大值，而不是預設值。)

可以被按鈕使用的行為包括： * Preference(“renderer menu”) - 顯示渲染器(renderer)菜單。 * Preference(“accessibility menu”) - 顯示數據(accessibility)讀寫菜單

上面的界面是內部定義的，無法訂製化。

GetCharacterVolume(voice_tag) link: 該函數根據關聯的語音標籤(tag)，返回一個介於0.0到1.0之間的數值，表示對應 voice 聲道最大音量的一個比例。

遊戲手把 link

這些函數和行為跟遊戲手把一起工作。

GamepadCalibrate() link: 調用手把校正的行為。

GamepadExists(developer=True) link

檢測手把是否存在的函數。存在返回True，不存在返回False。

developer: 強制該函數返回True，config.developer必須配置為True。

文件函數 link

這些函數返回關於文件的有用資訊。它們使用相同的默認頁面(page)相關的文件行為。

FileCurrentPage() link: 將當前文件頁面(page)以字串返回。

FileCurrentScreenshot(empty=None, **properties) link

一個螢幕幕截圖的可顯示控制項。其將保存你在當前文件中，前提是進入了菜單或使用 FileTakeScreenshot() 採集了螢幕截圖。

如果沒有當前螢幕截圖，對應的位置上顯示 empty 的圖像。(如果 empty 是空值None，預設為 Null() 。)

FileJson(name, key=None, empty=None, missing=None, page=None, slot=False) link

根據 name 參數讀取對應的Json數據。

如果存檔槽位是空的，則返回 empty 。

如果存檔槽位不是空的，並且 key 為None，返回包含Json數據的整個目錄

如果 key 不為None，則返回json[key]，前提是 key 在存檔json對象中有定義。如果存檔存在但不包含 key ，就返回 missing 。如果存檔槽位為空，則返回 empty 。

使用 config.save_json_callbacks() 註冊的回調函數可以用於在存檔槽位中添加Json。

FileLoadable(name, page=None) link: 該函數在文件可載入的情況下返回True，否則返回False。

FileNewest(name, page=None) link: 如果文件是最新版本返回True，否則返回False。

FilePageName(auto='a', quick='q') link: 以字串形式返回當前文件頁面(page)名稱。如果是一個普通頁面(page)，該函數返回頁面編號。否則，返回 auto 或 quick 。

FileSaveName(name, empty='', page=None) link: 返回文件保存時生效的存檔名，如果文件不存在則返回 empty 。

FileScreenshot(name, empty=None, page=None) link

返回給定那個文件相關的螢幕截圖。如果文件不能載入，返回 empty ，前提 empty 的值不是None。在文件不能載入且 empty 為空的情況下，一個空的可視組件會被創建。

返回值是一個可顯示對象。

FileSlotName(slot, slots_per_page, auto='a', quick='q', format='%s%d') link

返回編號後的槽位名。前提是普通頁面(page)下的槽位都按順序從1開始編號，並且頁面也從1開始編號。當槽位編號為2，每個頁面槽位數(slots_per_page)為10，其他變數都是預設值的情況下：

顯示第一頁面時，返回“2”。
顯示第二頁面時，返回“12”。
顯示自動頁面時，返回“a2”。
顯示快速存檔頁面時，返回“q2”。

slot: 接入的槽位編號。
slots_per_page: 每頁槽位數量。
auto: 自動存檔頁面的前綴。
quick: 快速存檔頁面的前綴。
format: 格式程式碼。包含兩部分：一個頁面前綴字串，一個槽位編號整數。

FileTime(name, format='%b %d, %H:%M', empty='', page=None) link

返回文件保存時間，格式根據 format 顯示。如果未找到文件，返回 empty 。

返回值是一個字串。

FileUsedSlots(page=None, highest_first=True) link

返回頁面上所有可用的經過編號的文件列表。

page: 待掃描的頁面名。若為None，就使用當前頁面。
highest_first: 若為True，列表內文件按編號從大到小排序。否則，列表內文件按編號從小到大排序。

頭像函數 link

該函數返回使用的頭像。

SideImage() link: 返回與當前發言角色相關的頭像。如果頭像不存在則返回一個空的可視組件。

Tooltips link

所有可視組件上可用的 tooltip 特性和GetTooltip函數都可以讀寫tooltip。當可視組件獲得焦點時，GetTooltip函數會返回這個組件的tooltip特性的值。

提醒一下，傳入 tooltip 特性的值需要支持是否相等的判斷。

這裡是一個樣例：

screen tooltip_example():
    vbox:
        textbutton "北":
            action Return("n")
            tooltip "去約見北極熊。"

        textbutton "南":
            action Return("s")
            tooltip "前往熱帶。"

        textbutton "東":
            action Return("e")
            tooltip "我們可以擁抱黎明。"

        textbutton "西":
            action Return("w")
            tooltip "去欣賞最美的日落。"

        $ tooltip = GetTooltip()

        if tooltip:
            text "[tooltip]"

可視組件 nearrect 可用於顯示“跳出視窗型”tooltip，並且可以獲取一個特殊的“tooltip”焦點名，會將最後獲取焦點的位置設定為tooltip對象：

screen tooltip_example2():
    frame:

        padding (20, 20)
        align (.5, .3)

        has vbox

        textbutton "北":
            action Return("n")
            tooltip "去約見北極熊。"

        textbutton "南":
            action Return("s")
            tooltip "前往熱帶。"

        textbutton "東":
            action Return("e")
            tooltip "我們可以擁抱黎明。"

        textbutton "西":
            action Return("w")
            tooltip "去欣賞最美的日落。"

    # 這是界面上最後顯示的內容。

    $ tooltip = GetTooltip()

    if tooltip:

        nearrect:
            focus "tooltip"
            prefer_top True

            frame:
                xalign 0.5
                text tooltip

GetTooltip(screen=None) link

返回當前獲得焦點的可視組件的tooltip，如果可視組件未獲得焦點則返回None。

screen: 如果非空，這個參數應該是某個界面的名稱或者標籤(tag)。如果獲得焦點的可視組件是界面的一部分，則該函數隻返回tooltip。

傳統方法 link

Warning

這種傳統方法已被廢棄，並使用上面說的方法替代。不過你可能會在一些老版本的項目中見到它。

當按鈕處於指針懸停狀態時，tooltip類會改變界面。

class Tooltip(default) link

當滑鼠指針懸停在某個區域上時，一個tooltip對象可以用於提示對應界面的功能。

tooltip對象有一個 value 欄位，當tooltip對象被創建時會通過構造器傳入 default 作為預設值。當透過tooltip創建的某個按鈕行為被使用時，value欄位就會根據關聯的行為改變對應值。

Action(value) link: 將按鈕的hovered特性對應的行為返回。當按鈕處於指針懸停狀態時，tooltip的value欄位會被設置為 value 。當按鈕失去焦點時，tooltip的value欄位會恢復為預設值。

在某個界面使用tooltip時，常用做法是在default語句中創建tooltip對象。tooltip的值和行為的方法可以在界面中使用。使用時可以按任何順序——在行為執行前就可以使用tooltip的值。

tooltip可以使用任何類型的值。在下面的樣例中，我們使用text語句在界面中顯示字串，使用add語句添加可視組件也是可行的。還可以設計更多複雜的行為。

screen tooltip_test:

    default tt = Tooltip("沒有選擇任何按鈕。")

    frame:
        xfill True

        has vbox

        textbutton "One.":
            action Return(1)
            hovered tt.Action("The loneliest number.")

        textbutton "Two.":
            action Return(2)
            hovered tt.Action("Is what it takes.")

        textbutton "Three.":
            action Return(3)
            hovered tt.Action("A crowd.")

        text tt.value