QML
← 전체 컴포넌트

Ribbon

앱의 명령을 탭과 그룹으로 묶는 리본 메뉴입니다. 주요 작업 버튼과 작은 버튼 열을 함께 배치할 수 있습니다.

import Syidax.Core.Ribbon

지원 QML 타입

타입정의 / 역할
탭·선택·접힘 상태를 관리하고 명령 이벤트를 모으는 리본의 최상위 컨테이너입니다.
명령 그룹들을 담는 리본 탭이며 tabId로 식별하고 title을 탭 제목으로 표시합니다.
탭 안에서 명령들을 가로로 묶으며 제목과 선택적 상세 열기 버튼을 제공합니다.
명령을 세로로 쌓고 폭을 맞추며 그룹 안에서 묶음 전체를 가운데 배치합니다.
아이콘·이미지를 표시하고 Action·체크 상태·이벤트 식별용 commandId를 지원하는 명령 버튼입니다.
명령 사이에 직접 배치하는 가로·세로 구분선입니다.

예제로 보기

미리보기는 Qt 실행 화면의 이미지입니다. 아래 버튼으로 결과를 전환하세요.

01 큰 버튼과 세로 묶음

큰 버튼은 그룹에 직접 넣고, 작은 버튼 묶음은 SyRibbonColumn에 넣습니다.

Qt 실행 화면 · 이미지
큰 버튼과 세로 묶음 · 미리보기
기본 실행 화면
QML 코드
import QtQuick
import QtQuick.Controls as Controls
import Syidax.Core

SyRibbon {
    width: 520
    SyRibbonTab {
        tabId: "home"; title: "홈"
        SyRibbonGroup {
            title: "클립보드"
            SyRibbonButton { text: "붙여넣기"; imageSource: Icons.ribbonPaste }
            SyRibbonColumn {
                SyRibbonButton { text: "잘라내기"; icon.source: Icons.ribbonCut }
                SyRibbonButton { text: "복사"; icon.source: Icons.ribbonCopy }
                SyRibbonButton { text: "서식 복사"; icon.source: Icons.ribbonFormatPainter }
            }
        }
        SyRibbonGroup {
            title: "삽입"
            SyRibbonButton { text: "그림"; imageSource: Icons.ribbonPicture }
            SyRibbonButton { text: "표"; imageSource: Icons.ribbonTable }
        }
    }
}

02 이미지 크기와 컬러 아이콘

컬러 아이콘의 색은 유지되며, imageWidth·imageHeight로 이미지 크기를 조절합니다.

Qt 실행 화면 · 이미지
이미지 크기와 컬러 아이콘 · 미리보기
기본 실행 화면
QML 코드
import QtQuick
import QtQuick.Controls as Controls
import Syidax.Core

SyRibbon {
    width: 520
    SyRibbonTab {
        tabId: "insert"; title: "삽입"
        SyRibbonGroup {
            title: "이미지"
            SyRibbonButton {
                text: "그림"
                imageSource: Icons.ribbonPicture
                imageWidth: 40; imageHeight: 32
                imageFillMode: Image.PreserveAspectFit
            }
            SyRibbonButton { text: "저장"; icon.source: Icons.ribbonSave }
            SyRibbonColumn {
                SyRibbonButton { text: "메모"; icon.source: Icons.ribbonComment }
                SyRibbonButton { text: "링크"; icon.source: Icons.ribbonLink }
            }
        }
    }
}

03 켜기·끄기와 단일 선택

굵게는 독립적으로 켜고 끄며, 정렬은 한 항목만 선택됩니다.

Qt 실행 화면 · 이미지
켜기·끄기와 단일 선택 · 굵게 · 왼쪽
QML 코드
import QtQuick
import QtQuick.Controls as Controls
import Syidax.Core

Column {
    width: 520; spacing: 12
    SyRibbon {
        width: parent.width
        SyRibbonTab {
            tabId: "format"; title: "서식"
            SyRibbonGroup {
                title: "글자"
                SyRibbonColumn {
                    SyRibbonButton { id: bold; text: "굵게"; icon.source: Icons.ribbonBold; checkable: true; checked: true }
                    SyRibbonButton { text: "기울임"; icon.source: Icons.ribbonItalic; checkable: true }
                }
            }
            SyRibbonGroup {
                title: "정렬"
                Row {
                    SyRibbonButton { id: left; text: "왼쪽"; icon.source: Icons.ribbonAlignLeft; checkable: true; autoExclusive: true; checked: true }
                    SyRibbonButton { id: center; text: "가운데"; icon.source: Icons.ribbonAlignCenter; checkable: true; autoExclusive: true }
                }
            }
        }
    }
    Text {
        text: (bold.checked ? "굵게 켜짐" : "굵게 꺼짐") + " · " + (left.checked ? "왼쪽 정렬" : "가운데 정렬")
        color: Theme.semantic.textDefault; font.family: Theme.fontFamily
    }
}

04 탭 전환과 접기

보기 탭으로 전환한 뒤 명령 영역만 접습니다. 탭은 계속 표시됩니다.

Qt 실행 화면 · 이미지
탭 전환과 접기 · 홈
QML 코드
import QtQuick
import QtQuick.Controls as Controls
import Syidax.Core

Column {
    width: 520; spacing: 12
    Row {
        spacing: 8
        SyButton { text: "보기 탭"; onClicked: ribbon.selectTab("view", "example") }
        SyButton { text: ribbon.collapsed ? "펼치기" : "접기"; onClicked: ribbon.setCollapsed(!ribbon.collapsed, "example") }
    }
    SyRibbon {
        id: ribbon; width: parent.width
        SyRibbonTab {
            tabId: "home"; title: "홈"
            SyRibbonGroup { title: "파일"; SyRibbonButton { text: "저장"; icon.source: Icons.ribbonSave } }
        }
        SyRibbonTab {
            tabId: "view"; title: "보기"
            SyRibbonGroup { title: "표시"; SyRibbonButton { text: "눈금선"; icon.source: Icons.ribbonGrid; checkable: true; checked: true } }
        }
    }
    Text {
        text: "currentTab: " + ribbon.currentTab + " · collapsed: " + ribbon.collapsed
        color: Theme.semantic.textDefault; font.family: Theme.fontFamily
    }
}

05 하나의 Action으로 연결

일반 버튼·리본·Ctrl+S가 같은 저장 동작과 활성 상태를 공유합니다.

Qt 실행 화면 · 이미지
하나의 Action으로 연결 · 준비
QML 코드
import QtQuick
import QtQuick.Controls as Controls
import Syidax.Core

Column {
    id: demo; width: 520; spacing: 12
    property int saves: 0
    Controls.Action {
        id: saveAction; text: "저장"; shortcut: "Ctrl+S"
        icon.source: Icons.ribbonSave
        onTriggered: demo.saves += 1
    }
    Row {
        spacing: 8
        SyButton { id: toolbarSave; action: saveAction }
        SyButton { text: "활성 상태 전환"; onClicked: saveAction.enabled = !saveAction.enabled }
    }
    SyRibbon {
        width: parent.width
        SyRibbonTab {
            tabId: "home"; title: "홈"
            SyRibbonGroup { title: "파일"; SyRibbonButton { id: ribbonSave; commandId: "save"; action: saveAction } }
        }
    }
    Text {
        text: "저장 횟수: " + demo.saves + " · enabled: " + saveAction.enabled
        color: Theme.semantic.textDefault; font.family: Theme.fontFamily
    }
}

06 명령·그룹 이벤트 확인

저장 버튼은 명령·탭·그룹 ID를 전달합니다. 그룹의 더보기 버튼은 별도 이벤트를 보냅니다.

Qt 실행 화면 · 이미지
명령·그룹 이벤트 확인 · 준비
QML 코드
import QtQuick
import QtQuick.Controls as Controls
import Syidax.Core

Column {
    id: demo; width: 520; spacing: 12
    property string result: "저장 또는 그룹의 더보기를 누르세요."
    SyRibbon {
        width: parent.width
        onCommandTriggered: detail => demo.result = "commandTriggered\n" + JSON.stringify({commandId: detail.commandId, tabId: detail.tabId, groupId: detail.groupId})
        onGroupRequested: detail => demo.result = "groupRequested\n" + JSON.stringify(detail)
        SyRibbonTab {
            tabId: "home"; title: "홈"
            SyRibbonGroup {
                id: fileGroup; groupId: "file"; title: "파일"; launcherVisible: true
                SyRibbonButton { id: save; commandId: "save"; text: "저장"; icon.source: Icons.ribbonSave }
            }
        }
    }
    Rectangle {
        width: parent.width; height: eventText.implicitHeight + 24
        color: Theme.semantic.backgroundBold; radius: 6
        Text {
            id: eventText; x: 12; y: 12; width: parent.width - 24
            text: demo.result; wrapMode: Text.WrapAnywhere
            color: Theme.semantic.textDefault; font.family: Theme.monoFontFamily
        }
    }
}

API 77

항목을 가리키거나 선택하면 QML 예제와 복사 버튼이 나타납니다.

SyRibbon · 속성

이름타입 / 기본값설명
list · []기본 콘텐츠이며 SyRibbonTab 자식을 선언합니다.
string · ""선택한 tabId입니다. 사용할 수 없는 값은 첫 사용 가능 탭으로 바뀝니다.
var · read-only선언 순서대로 등록된 SyRibbonTab 목록입니다.
read-only · null선택한 탭과 인덱스이며 사용 가능한 탭이 없으면 null / -1입니다.
read-only · -1선택한 탭과 인덱스이며 사용 가능한 탭이 없으면 null / -1입니다.
bool · false탭 헤더는 남기고 명령 영역을 접습니다.
bool · true접기·펼치기 버튼의 표시 여부이며 collapsed 상태와 별개입니다.
bool · false리본의 사용자 조작을 막습니다.
string · "Ribbon"리본의 접근성 이름입니다.
string · "Collapse ribbon"접기·펼치기 컨트롤의 접근성 이름이며 앱 언어에 맞게 지정합니다.
string · "Expand ribbon"접기·펼치기 컨트롤의 접근성 이름이며 앱 언어에 맞게 지정합니다.
int · 160 ms전환 시간입니다. 동작 줄이기 설정에서는 전환을 생략합니다.
color · Theme.semantic.backgroundDefault리본의 배경색과 테두리색입니다.
color · Theme.semantic.borderSubtle리본의 배경색과 테두리색입니다.

SyRibbonTab · 속성

이름타입 / 기본값설명
list · []이 탭에 속하는 그룹을 선언하는 기본 콘텐츠입니다.
string · ""리본 안에서 중복되지 않는 비어 있지 않은 식별자입니다.
string · ""탭 헤더에 표시하는 제목입니다.
bool · true탭 헤더의 표시와 탭 선택 가능 여부를 제어합니다.
bool · false헤더는 남기되 탭을 선택할 수 없게 합니다.
real · 6그룹 바깥 여백과 그룹 사이 간격입니다.
real · 0그룹 바깥 여백과 그룹 사이 간격입니다.
bool · read-only현재 선택된 탭인지 나타내며 실제 visible은 선택 상태를 따릅니다.
real · read-only같은 탭의 그룹들이 함께 사용하는 명령 영역 높이입니다.

SyRibbonGroup · 속성

이름타입 / 기본값설명
list · []버튼·컬럼·사용자 컨트롤을 선언 순서대로 가로 배치하는 기본 콘텐츠입니다.
string · ""이벤트에서 사용할 그룹 식별자와 명령 아래에 표시할 제목입니다.
string · ""이벤트에서 사용할 그룹 식별자와 명령 아래에 표시할 제목입니다.
bool · automatic그룹 끝 구분선이며 마지막으로 보이는 그룹에서는 자동으로 숨깁니다.
bool · false그룹 제목 옆에 작은 상세 열기 버튼을 표시합니다.
string · title상세 열기 버튼의 접근성 이름입니다.
real · 4선언한 명령 항목 사이의 가로 간격입니다.
real · read-only콘텐츠 자체 높이와 같은 탭의 다른 그룹에 맞춘 명령 영역 높이입니다.
real · read-only콘텐츠 자체 높이와 같은 탭의 다른 그룹에 맞춘 명령 영역 높이입니다.

SyRibbonColumn · 속성

이름타입 / 기본값설명
list · []세로로 쌓을 명령들을 선언하는 기본 콘텐츠입니다.
real · 0보이는 명령 사이의 세로 간격이며 숨긴 명령은 공간을 차지하지 않습니다.

SyRibbonButton · 속성

이름타입 / 기본값설명
string · ""명령 이벤트에 포함되는 식별자입니다.
Qt Quick Button properties라벨·아이콘·공용 Action입니다. Action의 텍스트·아이콘·활성·체크 상태도 공유합니다.
Qt Quick Button properties라벨·아이콘·공용 Action입니다. Action의 텍스트·아이콘·활성·체크 상태도 공유합니다.
Qt Quick Button properties라벨·아이콘·공용 Action입니다. Action의 텍스트·아이콘·활성·체크 상태도 공유합니다.
bool · false토글 사용·현재 체크 상태·같은 부모의 항목 중 하나만 선택하도록 설정합니다.
bool · false토글 사용·현재 체크 상태·같은 부모의 항목 중 하나만 선택하도록 설정합니다.
bool · false토글 사용·현재 체크 상태·같은 부모의 항목 중 하나만 선택하도록 설정합니다.
bool · false포인터·키보드·trigger() 조작을 막습니다.
string · ""포인터를 올렸을 때의 도움말입니다. 비어 있으면 잘린 라벨의 전체 문구를 사용합니다.
url · ""icon.source보다 우선하는 이미지 URL이며 원본 색상을 유지합니다.
real · 28 (vertical) / 16 (horizontal)이미지 영역 크기입니다. 0은 해당 크기를 숨기며 기본값은 배치 방향에 따라 결정됩니다.
real · 28 (vertical) / 16 (horizontal)이미지 영역 크기입니다. 0은 해당 크기를 숨기며 기본값은 배치 방향에 따라 결정됩니다.
Image.FillMode · Image.PreserveAspectFit이미지 영역 안에서 비율 유지·잘라 채우기·늘리기 방식을 정합니다.
size · Qt.size(0, 0)원본 이미지의 디코딩 크기 요청값이며 0은 원본 기본값을 사용합니다.
bool · true이미지 비동기 로딩과 캐시 사용 옵션입니다.
bool · true이미지 비동기 로딩과 캐시 사용 옵션입니다.
int · read-onlyQML Image가 제공하는 이미지 로딩 상태와 진행률입니다.
real · read-onlyQML Image가 제공하는 이미지 로딩 상태와 진행률입니다.

SyRibbonSeparator · 속성

이름타입 / 기본값설명
string · "vertical""vertical" 또는 "horizontal" 방향의 구분선입니다.
real · 72구분선의 긴 방향 길이입니다.
color · Theme.semantic.borderSubtle구분선 색상입니다.

메서드

타입메서드반환값 / 동작
SyRibbon사용 가능한 탭이면 true, 없거나 숨김·비활성인 탭 또는 비활성 리본이면 false입니다. source 기본값은 "api"입니다.
SyRibboncollapsed를 설정하며 반환값은 없습니다. source 기본값은 "api"입니다.
SyRibbonButton클릭과 같은 체크·Action·클릭 순서를 실행합니다. 숨김·비활성이면 false, 실행하면 true입니다.
SyRibbonGrouplaunchRequested와 리본의 groupRequested를 발생시킵니다. 숨김·비활성이면 실행하지 않으며 반환값은 없습니다.

시그널

타입 / 시그널전달값발생 시점
{ tabId, previousTabId, index, source }활성 탭이 바뀐 뒤 한 번 발생합니다. 초기화나 같은 값 재설정에는 발생하지 않습니다.
{ collapsed, source }접힘 상태가 바뀐 뒤 한 번 발생하며 초기값이나 같은 상태에는 발생하지 않습니다.
{ commandId, tabId, groupId, text, checked, source }리본 명령 실행 시 발생합니다. 공유 Action은 리본에서 한 번만 전달합니다.
{ commandId, tabId, groupId, text, checked, source }명령의 체크 상태가 바뀔 때 발생하고 source는 "state"입니다. 명령 실행과는 별개입니다.
{ ...commandDetail, kind, value }pressed·released·canceled·hovered·focused 변화를 전달합니다.
{ tabId, groupId }그룹에서 상세 화면 열기를 요청할 때 발생합니다.
{ commandId, tabId, groupId, text, checked, source }이 버튼의 개별 명령 실행 이벤트입니다.
{ commandId, tabId, groupId, text, checked, source }초기화 이후 이 버튼의 체크 상태 변경이며 source는 "state"입니다.
{ ...commandDetail, kind, value }이 버튼의 누름·놓음·취소·hover·포커스 이벤트입니다.
{ tabId, groupId }이 그룹의 상세 열기 이벤트이며 launcherVisible로 버튼을 표시합니다.

배치와 상태 규칙

항목동작
SyRibbon 안에 탭을, 탭 안에 그룹을, 그룹 안에 버튼이나 컬럼을 선언합니다. 그룹은 선언 순서대로 가로 배치합니다.
그룹에 직접 놓은 이미지·아이콘 버튼은 아래에 라벨을, 컬럼 안의 버튼은 아이콘 옆에 라벨을 둡니다. 버튼별 크기 옵션이나 자동 재배치는 없습니다.
SyRibbonColumn은 버튼 폭을 맞추고 묶음을 가운데 배치합니다. 두 개는 두 줄, 네 개는 네 줄이며 일반 QML Column과 사용자 Row도 지원합니다.
그룹끼리 명령 높이를 공유합니다. 버튼은 실제 아이콘·라벨을 함께 가운데 배치하며 빈 두 번째 줄은 예약하지 않습니다. 긴 가로형 라벨은 200px에서 줄이고 hover로 전체를 보여줍니다.
선택된 탭을 제거·숨김·비활성화하면 첫 사용 가능 탭으로 이동하고, 없으면 선택을 비웁니다. 탭 표시에는 페이지 visible 대신 tabVisible을 사용합니다.
탭은 좌우 방향키·Home·End, 명령 버튼은 Space로 조작합니다. 넘치는 내용은 가로 스크롤되며 포커스한 명령은 보이도록 이동합니다.
Theme.reducedMotion이면 전환을 생략합니다. Icons.ribbon*는 icon.source에서도 원본 컬러를 유지하고 단색 기호만 테마 색상을 사용합니다.
구조화된 리본 시그널과 함께 QML 기본 속성 변경 시그널도 사용할 수 있습니다.