함수와 이벤트 안내

이 페이지는 BoAYo SDK 0.2.0의 함수와 이벤트를 현재 코드 기준으로 설명합니다. 앱은 창 이미지를 만들고, SDK는 Bosio 창 관리자 연결·아래 캡션·창별 이벤트를 처리합니다. 런처 패널은 앱 창과 별개의 UI입니다.

연결하고 창 만들기·닫기

from boayo_sdk import BoayoSDK

with BoayoSDK("my-app") as sdk:
    window = sdk.create_window("My App")
    window.present(draw_content)
    while sdk.windows:
        for event in sdk.poll_events():
            handle(event)

create_window()의 모든 인자

window = sdk.create_window(
    title, *, azimuth=None, elevation=None,
    width_deg=38, height_deg=28,
    width=400, height=300, accent=ACCENT,
)

캡션을 드래그하면 창이 차지하는 구면 각도는 바뀌지만, 처음 만든 RGB 그림 영역의 픽셀 크기는 그대로입니다. 앱이 다른 크기의 이미지를 만들어 보내면 SDK가 기존 내용 영역에 맞춰 넣습니다.

창 객체로 내용을 그리기

def draw_content(canvas, content):
    canvas.text("HELLO", content.x + 20, content.y + 20,
                INK, scale=3, bold=True)
    canvas.rounded_rect(content.x + 20, content.y + 70,
                        120, 50, 12, ACCENT)

window.present(draw_content)

앱에서는 BoayoApplicationWindow(...)를 직접 만들지 않고 sdk.create_window()를 사용하세요. window.handle_event(raw), window.apply_gaze_drag(azimuth, elevation), window.cancel_drag()는 캡션 클릭과 창 밖 드래그를 SDK가 처리할 때 사용하는 함수입니다. 앱에서 직접 호출하면 SDK가 돌려주는 이벤트와 실제 창 상태가 어긋날 수 있습니다.

각 present()는 화면을 다시 만들어 제출합니다. 콜백은 content.x/y를 더해 내용 영역 안에 그려야 합니다. SDK 표면은 RGB24이므로 픽셀별 알파 투명도가 없습니다.

BoayoWindowState 필드

sdk.window_state(window)와 window.state의 내용은 같습니다. 포커스 값은 sdk.poll_events()로 새 이벤트를 읽은 뒤 갱신됩니다. SDK를 거치지 않고 Bosio에서 창 위치·크기를 직접 바꾸면 SDK의 창 상태에는 자동으로 반영되지 않습니다.

BoayoEvent와 이벤트 종류

sdk.poll_events()는 BoayoEvent 목록을 반환합니다. 모든 이벤트에 window_id와 type이 있으며, 나머지 필드인 x, y, pressed, button, focused, state는 이벤트 종류에 따라 값이 있거나 None입니다.

내용 영역에서 받은 x/y는 캡션을 제외한 내용 영역의 왼쪽 위가 (0, 0)인 픽셀 좌표입니다. 값은 실수이며 오른쪽과 아래쪽으로 증가합니다. pointer_button.pressed는 눌렀을 때 True, 놓았을 때 False이고 왼쪽 버튼 이름은 "left"입니다. 포인터 이동 이벤트의 pressed와 내용 입력 이벤트의 state는 None입니다.

focus 이벤트의 event.focused와 event.state.focused는 같습니다. 크기 조절 중 변화가 여러 번 있어도 sdk.poll_events()를 한 번 호출할 때 창별로 최종 크기 한 번만 resize를 돌려줍니다. 드래그가 창 밖으로 이어지면 현재 포인터 위치를 이용해 계속 계산합니다. RGB 이미지의 픽셀 크기가 바뀌는 것은 아닙니다.

여러 창에서 이벤트 처리하기

with BoayoSDK("multi-view") as sdk:
    main = sdk.create_window("Main")
    tools = sdk.create_window("Tools", azimuth=20, elevation=0)
    main.present(draw_main)
    tools.present(draw_tools)

    while sdk.windows:
        for event in sdk.poll_events():
            if event.type == "resize":
                print(event.window_id, event.state.width_deg)
            elif event.type == "focus":
                print(event.window_id, event.focused)
            elif event.type == "pointer_button" and event.pressed:
                print(event.window_id, event.x, event.y)

한 SDK 연결에서 앱의 모든 창 이벤트를 읽으므로 window_id로 창을 구분하세요. 이미지가 바뀌지 않는 앱도 sdk.poll_events()를 주기적으로 호출해야 캡션 조작과 닫기에 반응합니다.

BoayoSurface 그리기 함수

window.present(draw_content) 콜백의 canvas는 RGB24 이미지를 그리는 BoayoSurface입니다. 색은 각 채널이 0~255인 (R, G, B) 튜플이고 좌표는 창 이미지 전체의 픽셀 단위입니다.

canvas.pixels는 직접 수정할 수 있는 uint8 NumPy RGB 배열입니다. 다른 도구에서 만든 이미지를 내용 영역에 복사할 때 사용할 수 있습니다. 캡션까지 덮어쓰지 않도록 content 좌표를 확인하세요.

INK, MUTED, PANEL, WHITE, ACCENT는 SDK가 제공하는 RGB 색상값입니다. 내장 글꼴은 한글을 지원하지 않습니다. 한글이나 더 선명한 글씨가 필요하면 다른 도구로 RGB 이미지를 만든 뒤 present_rgb()로 보내세요.

오류와 현재 한계

• Bosio에 연결하기 전에 create_window(), 연결을 닫은 뒤 poll_events()를 호출하면 RuntimeError가 납니다.
• 다른 앱이 만들었거나 이미 닫힌 창을 window_state() 또는 destroy_window()에 넘기면 ValueError가 납니다.
• 그림 영역이 240×170픽셀보다 작으면 캡션을 그릴 수 없습니다. present_rgb()에는 3채널 RGB 배열과 contain 또는 stretch를 지정해야 합니다.
• Bosio와의 연결이 끊기면 클라이언트 오류가 발생합니다. 보드에서는 창 관리자와 BoAYo 서비스 상태를 확인하세요.
• 구면 각도 크기를 조절해도 앱 이미지의 픽셀 해상도는 자동으로 높아지지 않습니다. 현재 RGB24에는 픽셀별 투명도도 없습니다.