QML
← 전체 컴포넌트

Progress Circular

원형 표시로 작업의 완료 비율을 보여 줍니다.

import Syidax.Core.ProgressCircular

지원 QML 타입

타입정의 / 역할
선택적으로 수치를 표시하는 원형 진행률 표시기입니다.

예제로 보기

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

01 기본 구성

SyProgressCircular는 위에서부터 시계 방향으로 percent(0 … 100)만큼 채워지는 고리이며 가운데에 반올림한 퍼센트가 놓입니다.

Qt 실행 화면 · 이미지
기본 구성 · 기본
기본 실행 화면
QML 코드
import QtQuick
import Syidax.Core

Item {
    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    id: story

    property QtObject settings: QtObject {
        id: storyArgs
        property real percent: 65
        property string size: "medium"
        property string status: "default"
        property bool hideText: false
        property bool indeterminate: false
    }

    

    SyProgressCircular {
        percent: storyArgs.percent
        size: storyArgs.size
        status: storyArgs.status
        hideText: storyArgs.hideText
        indeterminate: storyArgs.indeterminate
    }

}

02 size

size는 지름을 정합니다: "small" 56 px, "medium" 92 px(기본), "large" 128 px.

Qt 실행 화면 · 이미지
size · 기본
기본 실행 화면
QML 코드
import QtQuick
import Syidax.Core

pragma ComponentBehavior: Bound

Item {
    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    id: story
    readonly property var sizes: ["small", "medium", "large"]

    Row {
        spacing: 24
        Repeater {
            model: story.sizes
            delegate: Column {
                id: cell
                required property string modelData
                spacing: 8
                SyProgressCircular { anchors.horizontalCenter: parent.horizontalCenter; percent: 65; size: cell.modelData }
                Text { anchors.horizontalCenter: parent.horizontalCenter; text: cell.modelData; font.family: Theme.fontFamily; font.pixelSize: 11; color: Theme.semantic.textSubtle }
            }
        }
    }
}

03 status

status는 채움 색과 가운데에 놓일 것을 정합니다: "default"(진행 중)는 퍼센트를 보여 주고, "error"는 고리를 오류 색으로 칠하며 숫자 대신 ✕ 글리프를, "complete"는 성공 색과 ✓ 글리프를 보여 줍니다.

Qt 실행 화면 · 이미지
status · 기본
기본 실행 화면
QML 코드
import QtQuick
import Syidax.Core

pragma ComponentBehavior: Bound

Item {
    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    id: story
    readonly property var statuses: ["default", "error", "complete"]

    Row {
        spacing: 24
        Repeater {
            model: story.statuses
            delegate: Column {
                id: cell
                required property string modelData
                spacing: 8
                SyProgressCircular { anchors.horizontalCenter: parent.horizontalCenter; percent: cell.modelData === "complete" ? 100 : 65; status: cell.modelData }
                Text { anchors.horizontalCenter: parent.horizontalCenter; text: cell.modelData; font.family: Theme.fontFamily; font.pixelSize: 11; color: Theme.semantic.textSubtle }
            }
        }
    }
}

04 segment

segment는 채움을 이어지는 색 호로 그립니다.

Qt 실행 화면 · 이미지
segment · 기본
기본 실행 화면
QML 코드
import QtQuick
import Syidax.Core

Item {
    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height

    SyProgressCircular {
        percent: 85
        segment: [{ percent: 30, status: "error" }, { percent: 70, status: "complete" }, { percent: 85 }]
    }
}

05 indeterminate

indeterminate: true는 길이를 모르는 작업용입니다: 숫자(또는 글리프)와 구간 호가 숨겨지고, 고리의 40 %인 144° 호가 현재 status 색으로 1초에 한 바퀴 돕니다.

Qt 실행 화면 · 이미지
indeterminate · 기본
QML 코드
import QtQuick
import Syidax.Core

Item {
    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    property QtObject settings: QtObject {
        id: storyArgs
        property bool indeterminate: true
    }

    

    SyProgressCircular { size: "small"; percent: 40; indeterminate: storyArgs.indeterminate }
}

06 changed · getValue

changed(percent)는 클램프된 값이 바뀔 때마다 — 변화마다 한 번, 클램프된 수로 — 발생합니다: percent를 150으로 두면 100을 보고하고, 두 번째 150은 value가 움직이지 않았으므로 아무것도 보고하지 않습니다.

Qt 실행 화면 · 이미지
changed · getValue · 기본
QML 코드
import QtQuick
import Syidax.Core

Item {
    component EventLog: Rectangle {
        id: logBox
        property var lines: []
        implicitWidth: 440
        implicitHeight: Math.max(56, logText.implicitHeight + 24)
        radius: 4; color: Theme.semantic.backgroundBold
        function log(value) { lines = lines.slice(-3).concat([String(value)]) }
        Text {
            id: logText; x: 12; y: 12; width: parent.width - 24
            text: logBox.lines.length ? logBox.lines.join("\n") : "컨트롤을 조작하면 이벤트 결과가 표시됩니다."
            wrapMode: Text.Wrap; color: Theme.semantic.textDefault
            font.family: Theme.monoFontFamily; font.pixelSize: 12
        }
    }

    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    // Focused Gallery routes: keep only the selected API and its prerequisites.
    id: featureStory

    Column {
        spacing: 12
        Row {
            spacing: 16
            SyProgressCircular {
                id: upload
                size: "small"
                onChanged: (percent) => { if (true) { output.log(("changed: %1%").arg(percent)) } }
            }
            Column {
                anchors.verticalCenter: parent.verticalCenter
                spacing: 8
            SyButton { id: exampleControl1;  visible: true; text: "upload.getValue()"; size: "small"; onClicked: output.log("getValue() → " + upload.getValue()) }
                Row {
                    spacing: 8
                    SyButton { id: exampleControl2;  text: "upload.percent += 25"; variant: "secondary"; size: "small"; onClicked: upload.percent += 25 }
                    SyButton { id: exampleControl3;  text: "upload.percent = 0"; variant: "secondary"; size: "small"; onClicked: upload.percent = 0 }
                }
                Text {
                    text: "upload.getValue() === " + upload.getValue()
                    font.family: Theme.monoFontFamily
                    font.pixelSize: 12
                    color: Theme.semantic.textSubtle
                }
            }
        }
        EventLog { id: output }
    }
}

07 완료된 원형 진행률

percent · status 설정을 적용한 완료된 원형 진행률 예제입니다.

Qt 실행 화면 · 이미지
완료된 원형 진행률 · 실행 결과
기본 실행 화면
QML 코드
import QtQuick
import Syidax.Core

Item {
    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    id: story

    property QtObject settings: QtObject {
        id: storyArgs
        property real percent: 100
        property string size: "medium"
        property string status: "complete"
        property bool hideText: false
        property bool indeterminate: false
    }

    

    SyProgressCircular {
        percent: storyArgs.percent
        size: storyArgs.size
        status: storyArgs.status
        hideText: storyArgs.hideText
        indeterminate: storyArgs.indeterminate
    }

}

08 완료 시점을 모르는 진행률

indeterminate 설정을 적용한 완료 시점을 모르는 진행률 예제입니다.

Qt 실행 화면 · 이미지
완료 시점을 모르는 진행률 · 실행 결과
기본 실행 화면
QML 코드
import QtQuick
import Syidax.Core

Item {
    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    id: story

    property QtObject settings: QtObject {
        id: storyArgs
        property real percent: 65
        property string size: "medium"
        property string status: "default"
        property bool hideText: false
        property bool indeterminate: true
    }

    

    SyProgressCircular {
        percent: storyArgs.percent
        size: storyArgs.size
        status: storyArgs.status
        hideText: storyArgs.hideText
        indeterminate: storyArgs.indeterminate
    }

}

API 32

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

속성

속성타입기본값설명
real0진행률. 0 … 100으로 클램프되어 value가 됩니다.
var (list 또는 string)[]누적 지점 [{ percent, status }, …] 또는 같은 내용의 JSON 문자열. 오름차순 정렬되어 이어지는 호로 그려지며 percent가 0보다 크면 거기서 잘립니다(0이면 지점들이 채움을 정함).
string"default""default" · "error" · "complete" — 고리 색과 가운데 글리프.
boolfalse숫자와 상태 글리프를 숨깁니다.
string"medium""small" 56 · "medium" 92 · "large" 128 px — 지름. 선 두께와 글자가 함께 커집니다.
string""접근성 이름(비어 있으면 "Progress"). 시각적 툴팁은 없습니다.
boolfalse채움 대신 도는 40 % 호. 숫자, 글리프, 구간 호를 숨깁니다.
real (읽기 전용)—클램프된 퍼센트.
real (읽기 전용)—현재 size의 기하.
real (읽기 전용)—현재 size의 기하.
real (읽기 전용)—현재 size의 기하.
real (읽기 전용)—현재 size의 숫자 글꼴 크기와 글리프 상자.
real (읽기 전용)—현재 size의 숫자 글꼴 크기와 글리프 상자.
color (읽기 전용)—status의 고리 색.
var (읽기 전용)—파싱된 구간 { percent, status }와 퍼센트 단위의 호 { start, sweep, status }.
var (읽기 전용)—파싱된 구간 { percent, status }와 퍼센트 단위의 호 { start, sweep, status }.

메서드

메서드설명
클램프된 퍼센트(real, 0 … 100)를 반환합니다 — value와 같습니다. 인자 없음, 어느 상태에서나 동작합니다.
상태 이름("default" · "error" · "complete")의 고리 색을 반환합니다. 구간 호에 쓰입니다.

시그널

시그널인자발생 시점
percent: real — 클램프된 값, 0 … 100value가 바뀔 때마다. percent가 움직여도 클램프된 값이 그대로면 발생하지 않고, status · size · segment · indeterminate에도 발생하지 않습니다.

동작

항목동작 / 조건
클램프된 퍼센트.
진행률. 0 … 100으로 클램프되어 value가 됩니다.
value가 바뀔 때마다. percent가 움직여도 클램프된 값이 그대로면 발생하지 않고, status · size · segment · indeterminate에도 발생하지 않습니다.
"default" · "error" · "complete" — 고리 색과 가운데 글리프.
숫자와 상태 글리프를 숨깁니다.
채움 대신 도는 40 % 호. 숫자, 글리프, 구간 호를 숨깁니다.
누적 지점 [{ percent, status }, …] 또는 같은 내용의 JSON 문자열. 오름차순 정렬되어 이어지는 호로 그려지며 percent가 0보다 크면 거기서 잘립니다(0이면 지점들이 채움을 정함).
"small" 56 · "medium" 92 · "large" 128 px — 지름. 선 두께와 글자가 함께 커집니다.
접근성 이름(비어 있으면 "Progress"). 시각적 툴팁은 없습니다.

키보드

항목동작 / 조건
진행률. 0 … 100으로 클램프되어 value가 됩니다.
"default" · "error" · "complete" — 고리 색과 가운데 글리프.
value가 바뀔 때마다. percent가 움직여도 클램프된 값이 그대로면 발생하지 않고, status · size · segment · indeterminate에도 발생하지 않습니다.
클램프된 퍼센트(real, 0 … 100)를 반환합니다 — value와 같습니다. 인자 없음, 어느 상태에서나 동작합니다.