樣式(style) link

樣式(style)允許訂製可視組件的外觀。修改可視組件樣式特性(property)的值可以實現這一點。例如，改變 background 特性，就可以實現窗口或者按鈕之類背景圖的訂製化。

樣式特性名由兩部分構成，前綴部分指定了特性的使用場景，後半部分是特性本身。例如，按鈕的 hover_background 特性的使用場景是按鈕得到焦點(未被按下)，而按鈕的 idle_background 特性的使用場景是按鈕未得到焦點。(設置 background 特性會同時修改 idle_background 和 hover_background 等background類特性。)

由於Ren’Py擁有超過100中的樣式特性，本節內容只涉及其中很小一部分。除了 background 之外，我們還會使用 color 、 font 、 outlines 和 size 等樣式特性。需要完整的樣式特性列表的話，可以查看樣式特性文件。

使用樣式和樣式繼承 link

每個可視組件都有內建的一個樣式。無論是直接創建還是使用界面系統，某個可視組件被創建後就可以在組件上應用樣式特性，並且樣式生效後更新可視組件的外觀。在下面的樣例中：

image big hello world = Text("Hello, World", size=40)

size 特性將應用於一個文本組件，允許我們修改文本的字號。如此訂製化之後的文本組件會顯示40像素高度的文本。

類似的，當使用screen語言時，每個用戶介面語句都使用相關的樣式特性：

screen big_hello_world:
    text "Hello, World" size 40

單個樣式可以將多個特性組合起來，應用到可視組件上。例如，下面兩個文本組件顯示的內容相同：

image big one = Text("Hello, World", size=40, color="#f00")
image big two = Text("Hello, World", style="big_red")

style big_red:
    size 40
    color "#f00"

每個樣式都有一個特性的集，每個特性集至少包含一種特性。當指定某個樣式應用到可視組件時，(可視組件需要用到的)每個樣式特性都會優先從樣式的特性中嘗試匹配。如果未匹配到，則會從父樣式中再嘗試搜索。如果依然未匹配到，則從父樣式的父樣式中嘗試，以此類推。

每個可視組件都使用一個名為 style 的特性，該特性給定了這個可視組件樣式的父類。

image big hello world = Text("Hello World", style="big")

screen hello_world:
    text "Hello, World" style "big"

當沒有給定 style 特性的情況下，父類會基於可視組件的應用類型進行選擇。父類的選擇可以被 style_prefix 影響，樣式前綴出現在界面語言用戶介面語句的樣式特性中。

當某個樣式被定義位沒有指定父類，就會指定一個預設的父類。如果該樣式名中包含一個下劃線(_)，父類就是把下劃線之前的內容移除後的結果。例如，某個樣式名為 my_button 就繼承自 button 。繼承關係可以使用style語句或者調用某個style對象方法改變。當某種不存在的樣式被使用時，並且樣式名中包含一個下劃線，Ren’Py會使用預設的父類創建一種樣式。

以下劃線開頭的樣式名是預留給Ren’Py使用的。

Ren’Py在起始階段建立的各類樣式，除了style語句或者初始化階段語句塊(block)之外就不應該再修改已命名的樣式。

樣式檢查器 link

當 config.developer 的值為true時，樣式檢查器可用於查看某個可視組件使用的樣式名。

若要啟用樣式檢查器，將滑鼠移動到某個可視組件上，按下鍵盤的shift+I。Ren’Py會在滑鼠位置展現一個可視組件列表，列表中的組件按照在界面被繪製的先後順序排列。(這表示，最後一個可視組件是在繪製在其他組件上層的。)

點擊樣式名可以展示可視組件繼承的父輩類，以及每種父輩類貢獻給最終組件的每一種樣式特性。

定義樣式：style語句 link

更好的定義樣式方法是使用style語句：

style my_text is text:
    size 40
    font "gentium.ttf"

如果某種樣式名不存在，style語句就會創建那種樣式。相反，style語句會修改已存在的樣式。

style語句一關鍵字 style 開頭，後接需要定義的樣式名。style語句第一行後面可以跟0個或多個分句，以及一個可選用的英文冒號(:)。

如果出現了英文冒號，下面必然有一個語句塊(block)。語句塊中每一行都包含一個或多個分句。如果style語句第一行沒有冒號，整個語句就是完整的。

style語句接受使用以下分句：

style-property simple-expression: 聲明的簡單表達式的值，會賦值給樣式特性。
is parent: 設置該樣式的父類。 parent 是一個樣式名。
clear: 在style語句運行前，移除聲明的樣式所有特性。這個功能對繼承自父類的特性值無效。
take style-name: 在style語句運行前，移除聲明的樣式所有特性，並替換為 style-name 樣式的特性。這個功能不會修改樣式的父類。
variant simple-expression: 計算 simple-expression 這個簡單表達式，生成一個字串或者字串列表，詳見界面變種。如果給定的界面變形之一是啟用狀態，style語句會執行，否則會被忽略。
properties simple-expression: 計算 simple-expression 這個簡單表達式，得到一個字典型數據。該欄位能用於將樣式特性名映射到具體的值，而這些值被聲明為向style語句提供特性值。

style語句的樣例如下：

# 創建一個新的樣式，使用默認(default)繼承。
style big_red:
    size 40

# 更新樣式。
style big_red color "#f00"

# 名為label_text的樣式使用big_red的特性，
# 前提是我們使用觸控(touch)系統。

style label_text:
    variant "touch"
    take big_red

style語句通常都在初始化階段運行。如果某個style語句沒有放在初始化語句塊中，其被會自動移動被初始化init 0語句塊中。

定義樣式：Python語句 link

在全局 style 對象中作為作用域存在著一些命名過的樣式。需要創建一種新樣式時，就創建一個Style類的實例，並在 style 對象的某個作用域中聲明該樣式。

init python:
     style.big_red = Style(style.default)

樣式特性可以透過在類似於Style對象作用域的特性中聲明。

init python:
     style.big_red.color = "#f00"
     style.big_red.size = 42

但是樣式特性的值不能透過這種方式讀取，只能被寫入。

class Style(parent) link

parent: 樣式父類。可以是另一個樣式對象，或者一個字串。

clear() link

該函數移除樣式對象的所有樣式特性。對象父輩繼承的值不會變。

等效於樣式語句中的 clear 從句。

set_parent(parent) link

將樣式對象的父類設置為 parent 。

等效於樣式語句中的 is 從句。

take(other) link

使用 other 的所有樣式特性。 other 必須是一個樣式對象。

等效於樣式語句中的 take 從句。

索引化的樣式 link

索引化的樣式是一些輕量級樣式，可基於可視組件的數據訂製化組件的外觀。透過使用一個字串或者整數為某個樣式對象提供索引，可以創建索引化的樣式。如果某個索引化樣式不存在，索引系統會創建一個原來樣式對象的子樣式。

init python:
    style.button["Foo"].background = "#f00"
    style.button["Bar"].background = "#00f"

screen indexed_style_test:
    vbox:
        textbutton "Foo" style style.button["Foo"]
        textbutton "Bar" style style.button["Bar"]

樣式個性化設置 link

Note

GUI環境設定設置 ( GUI的個性化設置 )可能是實現同樣目標的更高方式，因為GUI個性化可以改變某一個參數並用到多個樣式上。

用戶總是有自己調整用於界面各種特性的需求，在樣式方面尤其突出。例如，創作者可能想要讓玩家能自己調整文本的文本外觀、顏色及字體大小。樣式個性化允許這樣的訂製化操作。

樣式個性化可以控制一個或者多個樣式的特性(property)。樣式個性化擁有一個名字及一個或多個可選項。被選中的選項會保存在持久化數據中，第一個可選項會註冊為樣式特性的默認項。

一個可選項會有一個或多個關聯樣式、特性和變數值，並保證選中的選項和給定的特性值會被應用於樣式。Ren’Py首次初始化就會實現這點，並在任何新選項被選中時都會生效。

創作者應該確認每個選項作用於相同的樣式特性集。否則，某些樣式中沒有聲明的變數，會導致不可預料的結果。

下面的例子中，註冊了一個樣式特性，允許用戶選擇大號字體、簡單文本和小一些帶輪廓線的問被。

init python:

    # “text”設置項中的“decorated”會將樣式中的say_dialogue特性代表的字號設置為22。

    renpy.register_style_preference("text", "decorated", style.say_dialogue, "size", 22)

    renpy.register_style_preference("text", "decorated", style.say_dialogue, "outlines", [ (1, "#000", 0, 0) ])

    renpy.register_style_preference("text", "large", style.say_dialogue, "size", 24)

    renpy.register_style_preference("text", "large", style.say_dialogue, "outlines", [ ])

    # 註冊之後“decorated”就會成為“text”設置項中的默認樣式。

下面的代碼定義按鈕，用戶可以點擊按鈕啟用不同的樣式：

textbutton "Decorated" action StylePreference("text", "decorated")
textbutton "Large" action StylePreference("text", "large")

樣式個性化函數如下：

StylePreference(preference, alternative) link

給定樣式特性，將 alternative 設置為被選擇的選項。

preference: 給定樣式個性化名稱的字串。
alternative: 給定選項名稱的字串。

renpy.get_style_preference(preference) link

透過給定了個性化名稱返回對應被選中的選項名稱字串。

preference: 給定樣式個性化名稱的字串。

renpy.register_style_preference(preference, alternative, style, property, value) link

註冊某個選項對應的樣式個性化資訊。

preference

樣式個性化名稱字串。

alternative: 選項名稱字串。
style: 待更新的樣式名。可以是樣式對象，或者樣式名稱的字串。
property: 待更新樣式特性名稱的字串。
value: 賦值給樣式特性的值。

renpy.set_style_preference(preference, alternative) link

將選中的選項設定為樣式個性化。

preference: 樣式個性化名稱的字串。
alternative: 選項名稱的字串。

以下是一個樣例，註冊了一個樣式特性，允許用戶在大號簡單文本和小號帶輪廓線文本之間自由選擇。

init python:
    renpy.register_style_preference("text", "decorated", style.say_dialogue, "outlines", [ (1, "#000", 0, 0) ])
    renpy.register_style_preference("text", "decorated", style.say_dialogue, "size", 22)

    renpy.register_style_preference("text", "large", style.say_dialogue, "outlines", [ ])
    renpy.register_style_preference("text", "large", style.say_dialogue, "size", 24)

下面這段代碼允許用戶使用按鈕進行選擇：

textbutton "Decorated" action StylePreference("text", "decorated")
textbutton "Large" action StylePreference("text", "large")

其他樣式函數 link

style.rebuild() link: 該函數觸發已命名的樣式重建，允許初始化階段之後的樣式變更。

Warning

已命名的樣式不會作為遊戲存檔的一部分被保存。這意味著存檔和讀檔過程的數據不能保持一致。