고급 GUI

이 절에서는 GUI의 고급 사용법에 관한 여러 내용을 다룹니다.

Python 함수

GUI를 지원하는 Python 함수가 몇 가지 있습니다.

gui.button_properties(kind)

버튼의 kind를 받아 해당 버튼의 표준 스타일 속성이 담긴 딕셔너리를 반환합니다. 다음을 설정합니다.

background: 아래 설명에 따릅니다.
padding: gui.kind_borders.padding이 있으면 그 값으로 설정합니다.
xsize: gui.kind_width가 있으면 그 값으로 설정합니다.
ysize: gui.kind_height가 있으면 그 값으로 설정합니다.

kind가 문자열 "nvl_button"이면 gui.nvl_button_background 변수를 찾습니다.

배경은 다음 중 처음으로 존재하는 그림을 배경 이미지로 사용하는 프레임입니다.

gui/button/kind_[prefix_].background.png
gui/button/[prefix_].background.png

gui.kind_borders라는 GUI 변수가 있으면 사용합니다. 없으면 gui.button_borders를 사용합니다. gui.kind_tile이 있으면 테두리를 타일링할지 결정하고, 없으면 gui.button_tile이 타일링을 제어합니다.

[prefix_]의 의미는 스타일 접두사 검색 문서를 참고하세요.

gui.init(width, height, fov=75)

GUI를 초기화합니다.

width: 기본 창의 너비입니다.
height: 기본 창의 높이입니다.
fov: 3D 무대의 시야각입니다.

gui.rebuild()

GUI를 다시 구성합니다.

참고: 매우 느린 함수입니다.

gui.text_properties(kind=None, accent=False)

텍스트 버튼의 kind를 받아 해당 버튼 내부 텍스트의 표준 스타일 속성이 담긴 딕셔너리를 반환합니다. 다음을 설정합니다.

font: gui.kind_text_font가 있으면 그 값으로 설정합니다.
size: gui.kind_text_size가 있으면 그 값으로 설정합니다.
xalign: gui.kind_text_xalign이 있으면 그 값으로 설정합니다.
textalign: gui.kind_text_xalign이 있으면 그 값으로 설정합니다.
layout: gui.kind_text_xalign이 0보다 크고 1보다 작으면 "subtitle"로 설정합니다.

텍스트의 color 스타일 속성을 설정하는 변수도 여러 개 있습니다.

color: gui.kind_text_color가 있으면 그 값으로 설정합니다. 변수가 설정되지 않았고 accent가 True이면 기본 강조색으로 텍스트 색상을 설정합니다.
insensitive_color: gui.kind_text_insensitive_color가 있으면 그 값으로 설정합니다.
idle_color: gui.kind_text_idle_color가 있으면 그 값으로 설정합니다.
hover_color: gui.kind_text_hover_color가 있으면 그 값으로 설정합니다.
selected_color: gui.kind_text_selected_color가 있으면 그 값으로 설정합니다.

그 밖의 모든 텍스트 스타일 속성도 사용할 수 있습니다. kind가 None이 아니면 위치 스타일 속성도 사용할 수 있습니다. 예를 들어 gui.kind_text_outlines는 outlines 스타일 속성을, gui.kind_text_kerning은 kerning을 설정합니다.

gui.variant(f, variant=None)

GUI를 처음 초기화할 때와 다시 구성할 때마다 함수를 호출하게 하는 데코레이터입니다. 다음 형태의 함수 데코레이터로 사용하도록 설계되었습니다.

@gui.variant
def small():
    gui.text_size = 30
    # ...

함수인 f와 변형 이름을 담은 문자열 variant를 전달하여 호출할 수도 있습니다.

gui.button_text_properties(kind=None, accent=False):: gui.text_properties()의 오래된 별칭입니다.

gui.rebuild 자세히 알아보기

gui.rebuild는 Ren'Py의 현재 상태를 반영하도록 GUI를 갱신하는 비교적 느린 함수입니다. 다음 작업을 수행합니다.

gui 네임스페이스의 변수를 정의하는 모든 define 문을 다시 실행합니다.
현재 언어의 모든 translate python 블록을 다시 실행합니다.
모든 style 문을 다시 실행합니다.
시스템의 모든 스타일을 다시 구성합니다.

gui.rebuild는 init python 블록을 다시 실행하지 않습니다. 따라서 다음과

define gui.text_size = persistent.text_size

다음은

init python:
    gui.text_size = persistent.text_size

서로 다릅니다.

default 문, gui 네임스페이스, gui.rebuild

gui 네임스페이스에 적용한 default 문은 의미가 달라집니다. gui 네임스페이스의 변수에 적용하면 define 문과 섞인 순서대로 실행되며, gui.rebuild()를 호출해도 default 문은 다시 실행되지 않습니다.

예를 들어 다음 코드가 있다면

default gui.accent_color = "#c04040"
define gui.hover_color = gui.accent_color

게임을 처음 실행할 때 강조색을 설정한 다음, 마우스를 올렸을 때의 색상을 강조색으로 설정합니다. 이후 두 색상으로 여러 스타일 색상을 설정합니다.

그러나 게임 스크립트 안에 다음 코드가 있다면

$ gui.accent_color = "#4040c0"
$ gui.rebuild()

Ren'Py는 define만 다시 실행합니다. 따라서 마우스를 올렸을 때의 색상을 강조색으로 설정하고 스타일을 갱신합니다. 이를 통해 게임 진행에 따라 GUI의 일부가 달라지게 할 수 있습니다.

실행 중에 GUI 변수를 설정한다면 after_load 레이블에서 gui.rebuild를 호출해야 할 수 있습니다.

label after_load:
    $ gui.rebuild()
    return

이는 default로 설정한 변수에만 적용됩니다. gui 네임스페이스의 모든 변수는 default 또는 define으로 설정해야 합니다.

GUI 환경설정

Ren'Py는 함수 하나와 액션 두 개로 이루어진 GUI 환경설정 시스템도 지원합니다.

gui.SetPreference(name, value, rebuild=True)

name이라는 GUI 환경설정을 value로 설정하는 액션입니다.

rebuild: 기본값인 참이면 gui.rebuild()를 호출하여 변경 사항을 적용합니다. 일반적으로 참이어야 합니다. 다만 gui.SetPreference 액션을 여러 개 실행한다면 마지막 액션을 제외한 나머지에서는 False로 설정해야 합니다.

매우 느린 액션이므로 버튼에 마우스를 올릴 때 사용하는 데는 적합하지 않을 가능성이 높습니다.

gui.TogglePreference(name, a, b, rebuild=True)

name이라는 GUI 환경설정을 a와 b 사이에서 전환하는 액션입니다. 값이 a와 같으면 선택 상태가 됩니다.

rebuild: 기본값인 참이면 gui.rebuild()를 호출하여 변경 사항을 적용합니다. 일반적으로 참이어야 합니다. 다만 gui.SetPreference 액션을 여러 개 실행한다면 마지막 액션을 제외한 나머지에서는 False로 설정해야 합니다.

매우 느린 액션이므로 버튼에 마우스를 올릴 때 사용하는 데는 적합하지 않을 가능성이 높습니다.

gui.preference(name, default=...)

name이라는 GUI 환경설정의 값을 반환합니다.

default: 지정하면 이 값이 GUI 환경설정의 기본값이 됩니다. 해당 환경설정을 처음 사용할 때 기본값을 반드시 지정해야 합니다.

예제

GUI 환경설정 시스템은 변수를 정의할 때 환경설정 이름과 기본값으로 gui.preference()를 호출하여 사용합니다. 예를 들어 GUI 환경설정으로 텍스트 글꼴과 크기를 정의할 수 있습니다.

define gui.text_font = gui.preference("font", "DejaVuSans.ttf")
define gui.text_size = gui.preference("size", 22)

이후 gui.SetPreference와 gui.TogglePreference 액션으로 환경설정 값을 바꿀 수 있습니다. 다음 예제들을 환경설정 스크린에 추가할 수 있습니다.

vbox:
    style_prefix "check"
    label _("설정")
    textbutton _("OpenDyslexic") action gui.TogglePreference("font", "OpenDyslexic-Regular.otf", "DejaVuSans.ttf")

vbox:
    style_prefix "radio"
    label _("글자 크기")
    textbutton _("작게") action gui.SetPreference("size", 20)
    textbutton _("보통") action gui.SetPreference("size", 22)
    textbutton _("크게") action gui.SetPreference("size", 24)