QML
← 전체 컴포넌트

Slider

손잡이를 움직여 숫자나 범위를 선택하는 슬라이더입니다. 음량 조절이나 가격 범위 설정 등에 사용합니다.

import Syidax.Core.Slider

지원 QML 타입

타입정의 / 역할
트랙의 손잡이를 움직여 숫자나 숫자 범위를 선택합니다.

예제로 보기

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

01 기본 구성

SySlider는 레일과 손잡이가 있는 폼 필드입니다.

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

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

    property QtObject settings: QtObject {
        id: storyArgs
        property string label: "볼륨"
        property real value: 40
        property real min: 0
        property real max: 100
        property real step: 1
        property string showTooltip: "default"
        property string tooltipPlacement: "top"
        property bool reverse: false
        property bool hideTrackFill: false
        property bool disabled: false
        property bool readonly: false
    }

    

    SySlider {
        width: 320
        label: storyArgs.label
        value: storyArgs.value
        min: storyArgs.min
        max: storyArgs.max
        step: storyArgs.step
        showTooltip: storyArgs.showTooltip
        tooltipPlacement: storyArgs.tooltipPlacement
        reverse: storyArgs.reverse
        hideTrackFill: storyArgs.hideTrackFill
        disabled: storyArgs.disabled
        readonly: storyArgs.readonly
        onValueChanged: if (storyArgs.value !== value) storyArgs.value = value
    }

}

02 range · rangeValue

range: true는 손잡이 둘을 보입니다.

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

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

    Column {
        spacing: 16
        SySlider {
            id: price
            width: 320
            label: "가격 범위"
            range: true; rangeValue: [20, 80]; showTooltip: "always"
        }
        Text { text: price.lo + " – " + price.hi; font.family: Theme.monoFontFamily; font.pixelSize: 12; color: Theme.semantic.textSubtle }
    }
}

03 marks · snapToMarks · hideMarks

marks는 { 값: "라벨" } 객체이며 QML에서는 ({ 25: "25%" })처럼 괄호로 감싸 씁니다.

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

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

    property QtObject settings: QtObject {
        id: storyArgs
        property bool snapToMarks: true
        property bool hideMarks: false
    }

    

    SySlider { id: featureTarget0;
        width: 320
        label: "밝기"
        value: 50
        marks: ({ 0: "0%", 25: "25%", 50: "50%", 75: "75%", 100: "100%" })
        snapToMarks: storyArgs.snapToMarks
        hideMarks: storyArgs.hideMarks
    }
}

04 showTooltip · tooltipPlacement

showTooltip은 값 말풍선이 손잡이 옆에 언제 보일지 정합니다: "default"는 그 손잡이에 호버하거나 드래그하는 동안, "always"는 항상, "never"는 숨깁니다.

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

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

    property QtObject settings: QtObject {
        id: storyArgs
        property string showTooltip: "always"
        property string tooltipPlacement: "top"
    }

    

    Item {
        width: 360
        height: 80
        SySlider { id: featureTarget0; x: 20; y: 32; width: 320; value: 60; showTooltip: storyArgs.showTooltip; tooltipPlacement: storyArgs.tooltipPlacement }
    }
}

05 vertical · length

vertical: true는 레일을 세웁니다: min이 아래에 오고 값이 위로 커집니다(reverse면 반대).

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

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

    Row {
        spacing: 48
        SySlider { id: featureTarget0; vertical: true; length: 160; value: 30 }
        SySlider { id: featureTarget1; vertical: true; length: 160; value: 70; marks: ({ 50: "half" }); showTooltip: "always"; tooltipPlacement: "right" }
    }
}

06 disabled · readonly · reverse · hideTrackFill

disabled는 비활성 톤으로 그리고 포인터와 Tab 포커스를 무시합니다.

Qt 실행 화면 · 이미지
disabled · readonly · reverse · hideTrackFill · 기본
기본 실행 화면
QML 코드
import QtQuick
import Syidax.Core

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

    Column {
        spacing: 16
        SySlider { label: "비활성";  id: featureTarget0; visible: true; width: 320; value: 40; disabled: true }
        SySlider { label: "읽기 전용";  id: featureTarget1; visible: true; width: 320; value: 40; readonly: true }
        SySlider { label: "역방향";  id: featureTarget2; visible: true; width: 320; value: 40; reverse: true }
        SySlider { label: "트랙 채우기 없음";  id: featureTarget3; visible: true; width: 320; value: 40; hideTrackFill: true }
    }
}

07 changed

changed(detail)는 슬라이더의 유일한 시그널입니다.

Qt 실행 화면 · 이미지
changed · 기본
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

    

    Column {
        spacing: 16
        SySlider { id: exampleControl1; 
            width: 320
            label: "볼륨"; value: 30; step: 5
            onChanged: (detail) => output.log(("value: %1").arg(detail.value))
        }
        SySlider {
            width: 320
            label: "가격 범위"; range: true; rangeValue: [20, 80]
            onChanged: (detail) => output.log(("range: %1 – %2").arg(detail.min).arg(detail.max))
        }
        EventLog { id: output }
    }
}

08 getValue

getValue()는 단일 모드에서 현재 숫자(min … max로 잘림)를, range 모드에서 { min, max }를 돌려줍니다.

Qt 실행 화면 · 이미지
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

    Column {
        spacing: 16
        SySlider { id: volume; width: 320; label: "볼륨"; value: 30 }
        SySlider { id: price; width: 320; label: "가격 범위"; range: true; rangeValue: [20, 80] }
        Row {
            spacing: 8
            SyButton { id: exampleControl1;  text: "volume.getValue()"; variant: "secondary"; size: "small"; onClicked: output.log("getValue() → " + JSON.stringify(volume.getValue())) }
            SyButton { id: exampleControl2;  text: "price.getValue()"; variant: "secondary"; size: "small"; onClicked: output.log("getValue() → " + JSON.stringify(price.getValue())) }
            SyButton { id: exampleControl3;  text: "volume.setFocus()"; variant: "secondary"; size: "small"; onClicked: volume.setFocus() }
        }
        EventLog { id: output }
    }
}

API 87

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

속성

항목동작 / 조건
SySlider 자체 속성:

속성

속성타입기본값설명
var(숫자)0단일 모드의 값. min … max로 잘려 그려지며, 사용자 이동은 step에 스냅되고 코드 대입은 스냅되지 않습니다. 생성 뒤의 모든 변경이 changed를 발생시킵니다.
real0눈금의 양 끝.
real100눈금의 양 끝.
real1사용자 이동이 스냅되는 격자(min에서 세고 step의 소수 자릿수로 반올림). 0이면 격자가 없고 키는 1씩 움직입니다.
boolfalserangeValue 위의 손잡이 둘. changed와 getValue()가 { min, max }로 바뀌고 value는 무시됩니다.
list[]range 모드의 [low, high]. 빈 목록은 [min, max]. 코드로 설정해도 changed가 발생합니다.
object({}){ 값: "라벨" } — 눈금 안의 항목마다 점과 라벨. min과 max는 항상 라벨이 붙습니다.
boolfalse점과 라벨을 숨깁니다. 눈금 스냅은 그대로 동작합니다.
boolfalse사용자 이동이 step 격자 대신 가장 가까운 눈금에 닿습니다.
string"default"default(호버·드래그 중) · always · never.
string"top"손잡이의 top · bottom · left · right.
boolfalse레일이 length px 위로 세워지고 눈금은 오른쪽에 놓입니다.
real160vertical일 때의 레일 길이. 가로에서는 무시되고 너비가 결정합니다.
boolfalsemax가 왼쪽 / 아래. 채움은 max 쪽 끝에서 시작합니다.
boolfalse레일에 채워진 부분이 없습니다.
boolfalse사용자 입력에 손잡이가 움직이지 않음. 보통 톤.
string"single"키가 움직일 손잡이: single · min · max. 누름이 자동으로 설정합니다. 키로 먼저 다루는 range 슬라이더에는 min / max를 직접 설정하십시오.
real(읽기 전용)—range 모드의 잘린 낮은 / 높은 값(그 밖에는 min / max).
real(읽기 전용)—range 모드의 잘린 낮은 / 높은 값(그 밖에는 min / max).
real(읽기 전용)—눈금으로 잘린 value.
var(읽기 전용)—소속 폼이 제출하는 값: current, range 모드에서는 { min, max }.
bool(읽기 전용)—레일에 키보드 포커스가 있는지.
bool(읽기 전용)—!disabled && !readonly.

속성

항목동작 / 조건
필드 프레임(SyFieldFrame)에서 상속:

속성

속성타입기본값설명
string""레일 위의 제목. required가 별표를 더합니다.
string""SyForm.values()의 키.
string"medium"여기서는 제목 글자 크기만 바꿉니다(12 / 14 / 16 px).
boolfalse비활성 톤. 포인터와 Tab을 무시하고 폼이 필드를 건너뜁니다.
boolfalse별표만 그립니다 — 슬라이더는 항상 유효합니다.
string""레일 아래 도움말
string""사용자 오류 문구(슬라이더는 항상 유효하므로 보이지 않음).
real240앱이 너비를 정하지 않을 때의 너비.
booltrue제목 줄과 제목·레일·메시지 사이 간격.
real작은 간격제목 줄과 제목·레일·메시지 사이 간격.
읽기 전용—슬라이더에서는 항상 true · false · "".
읽기 전용—슬라이더에서는 항상 true · false · "".
읽기 전용—슬라이더에서는 항상 true · false · "".

메서드

메서드설명
단일 모드에서 current(숫자), range 모드에서 { min, max }를 돌려줍니다.
레일에 키보드 포커스를 줌(키가 activeThumb을 움직임)
거둠.
value를 생성 시점 값으로 되돌리고 touched / submitted 플래그를 지웁니다. rangeValue는 되돌리지 않습니다.
항상 true를 돌려줍니다(유효성 규칙 없음).
항상 true를 돌려줍니다(유효성 규칙 없음).
항상 ""를 돌려줍니다.
사용자 오류 플래그를 켜고 끕니다. 슬라이더에서는 보이는 효과가 없습니다.
사용자 오류 플래그를 켜고 끕니다. 슬라이더에서는 보이는 효과가 없습니다.

시그널

시그널인자시점
detail: { value }(단일) 또는 { min, max }(range)생성 뒤 value / rangeValue가 바뀔 때마다 — 포인터, 키, 코드. 값은 잘려 있습니다. 초기값에는 발생하지 않고, disabled / readonly 동안 사용자 입력은 막힙니다.
detail필드 베이스에 선언만 되어 있고 슬라이더는 발생시키지 않습니다. hasFocus를 쓰십시오.
detail필드 베이스에 선언만 되어 있고 슬라이더는 발생시키지 않습니다. hasFocus를 쓰십시오.

동작

항목동작 / 조건
단일 모드의 값. min … max로 잘려 그려지며, 사용자 이동은 step에 스냅되고 코드 대입은 스냅되지 않습니다. 생성 뒤의 모든 변경이 changed를 발생시킵니다.
value는 min … max로 잘려 그려집니다(current가 그 잘린 숫자). 사용자 이동은 min에서 센 step 격자에 스냅되고 step의 소수 자릿수로 반올림됩니다. 레일에 포커스가 있으면(반응 가능할 때 Tab이 닿고, 누르면 생기며, setFocus()도 줌): Left / Down이 한 step 내리고, Right / Up이 한 step 올리며, PageDown / PageUp이 열 step, Home이 min, End가 max로 옮깁니다. range 모드에서는 키가 activeThumb을 움직입니다: 누름이 움직인 손잡이로 설정하고, Home / End는 다른 손잡이에서 멈춥니다(높은 손잡이는 lo, 낮은 손잡이는 hi). activeThumb은 "single"로 시작하는데 이것은 range 손잡이를 가리키지 않으므로, 클릭 전에 키로 움직여야 하는 range 슬라이더에는 직접 "min"이나 "max"를 설정하십시오. rangeValue: [low, high]가 두 손잡이의 위치이고 빈 목록은 [min, max]를 뜻합니다. changed는 { min, max }를 전달하고 getValue()와 폼 값도 같은 객체입니다. range 모드에서 value는 쓰이지 않습니다. min … max 밖의 항목은 버려지고, min과 max는 라벨을 주지 않아도 숫자가 라벨인 점을 항상 얻습니다. name이 SyForm.values()의 키가 됩니다: 단일 모드에서는 숫자, range 모드에서는 { min, max }(formValue).
value는 min … max로 잘려 그려집니다(current가 그 잘린 숫자). 레일에 포커스가 있으면(반응 가능할 때 Tab이 닿고, 누르면 생기며, setFocus()도 줌): Left / Down이 한 step 내리고, Right / Up이 한 step 올리며, PageDown / PageUp이 열 step, Home이 min, End가 max로 옮깁니다. range 모드에서는 키가 activeThumb을 움직입니다: 누름이 움직인 손잡이로 설정하고, Home / End는 다른 손잡이에서 멈춥니다(높은 손잡이는 lo, 낮은 손잡이는 hi). activeThumb은 "single"로 시작하는데 이것은 range 손잡이를 가리키지 않으므로, 클릭 전에 키로 움직여야 하는 range 슬라이더에는 직접 "min"이나 "max"를 설정하십시오. rangeValue: [low, high]가 두 손잡이의 위치이고 빈 목록은 [min, max]를 뜻합니다. changed는 { min, max }를 전달하고 getValue()와 폼 값도 같은 객체입니다. range 모드에서 value는 쓰이지 않습니다. min … max 밖의 항목은 버려지고, min과 max는 라벨을 주지 않아도 숫자가 라벨인 점을 항상 얻습니다. reverse는 max를 먼저(왼쪽, 세로면 아래) 놓고, hideTrackFill은 시작점(또는 낮은 손잡이)과 손잡이 사이의 채움을 없앱니다. name이 SyForm.values()의 키가 됩니다: 단일 모드에서는 숫자, range 모드에서는 { min, max }(formValue).
눈금으로 잘린 value.
사용자 이동이 스냅되는 격자(min에서 세고 step의 소수 자릿수로 반올림). 0이면 격자가 없고 키는 1씩 움직입니다.
생성 뒤 value / rangeValue가 바뀔 때마다 — 포인터, 키, 코드. 값은 잘려 있습니다. 초기값에는 발생하지 않고, disabled / readonly 동안 사용자 입력은 막힙니다.
레일을 누르면 가장 가까운 손잡이(단일 모드에서는 유일한 손잡이)가 포인터로 뛰고 레일에 포커스가 갑니다. 드래그는 놓을 때까지 포인터를 따릅니다. "default" 모드에서는 손잡이에 호버하면 툴팁이 보이고, 레일에 호버하면 호버 톤으로 바뀝니다.
레일에 포커스가 있으면(반응 가능할 때 Tab이 닿고, 누르면 생기며, setFocus()도 줌): Left / Down이 한 step 내리고, Right / Up이 한 step 올리며, PageDown / PageUp이 열 step, Home이 min, End가 max로 옮깁니다. range 모드에서는 키가 activeThumb을 움직입니다: 누름이 움직인 손잡이로 설정하고, Home / End는 다른 손잡이에서 멈춥니다(높은 손잡이는 lo, 낮은 손잡이는 hi).
키가 움직일 손잡이: single · min · max. 누름이 자동으로 설정합니다. 키로 먼저 다루는 range 슬라이더에는 min / max를 직접 설정하십시오.
레일에 포커스가 있으면(반응 가능할 때 Tab이 닿고, 누르면 생기며, setFocus()도 줌): Left / Down이 한 step 내리고, Right / Up이 한 step 올리며, PageDown / PageUp이 열 step, Home이 min, End가 max로 옮깁니다. range 모드에서는 키가 activeThumb을 움직입니다: 누름이 움직인 손잡이로 설정하고, Home / End는 다른 손잡이에서 멈춥니다(높은 손잡이는 lo, 낮은 손잡이는 hi). lo와 hi는 항상 잘린 쌍입니다.
레일에 포커스가 있으면(반응 가능할 때 Tab이 닿고, 누르면 생기며, setFocus()도 줌): Left / Down이 한 step 내리고, Right / Up이 한 step 올리며, PageDown / PageUp이 열 step, Home이 min, End가 max로 옮깁니다. range 모드에서는 키가 activeThumb을 움직입니다: 누름이 움직인 손잡이로 설정하고, Home / End는 다른 손잡이에서 멈춥니다(높은 손잡이는 lo, 낮은 손잡이는 hi). lo와 hi는 항상 잘린 쌍입니다. 손잡이는 서로를 넘지 않습니다: 낮은 손잡이를 높은 손잡이 너머로 끌면 hi에 멈추고, 반대도 같습니다.
range 모드의 [low, high]. 빈 목록은 [min, max]. 코드로 설정해도 changed가 발생합니다.
단일 모드에서 current(숫자), range 모드에서 { min, max }를 돌려줍니다.
비활성 톤. 포인터와 Tab을 무시하고 폼이 필드를 건너뜁니다.
사용자 입력에 손잡이가 움직이지 않음. 보통 톤.
focused / blured는 필드 베이스에 있지만 슬라이더는 발생시키지 않습니다 — hasFocus를 읽으십시오.
focused / blured는 필드 베이스에 있지만 슬라이더는 발생시키지 않습니다 — hasFocus를 읽으십시오.
레일에 키보드 포커스가 있는지.
{ 값: "라벨" } — 눈금 안의 항목마다 점과 라벨. min과 max는 항상 라벨이 붙습니다.
사용자 이동이 step 격자 대신 가장 가까운 눈금에 닿습니다.
점과 라벨을 숨깁니다. 눈금 스냅은 그대로 동작합니다.
default(호버·드래그 중) · always · never.
손잡이의 top · bottom · left · right.
가로: 레일이 필드 너비 — 앱이 width를 정하지 않으면 preferredWidth 240 — 에 걸치고, 필드 높이는 14 px에 눈금이 보이면 24 px, 툴팁 여백을 더한 값입니다.
앱이 너비를 정하지 않을 때의 너비.
레일 위의 제목. required가 별표를 더합니다.
label은 위, message는 아래에 놓이며 다른 필드와 같습니다.
vertical일 때의 레일 길이. 가로에서는 무시되고 너비가 결정합니다.
max가 왼쪽 / 아래. 채움은 max 쪽 끝에서 시작합니다.
레일에 채워진 부분이 없습니다.
SyForm.values()의 키.
name이 SyForm.values()의 키가 됩니다: 단일 모드에서는 숫자, range 모드에서는 { min, max }(formValue).
소속 폼이 제출하는 값: current, range 모드에서는 { min, max }.
슬라이더에는 유효성 규칙이 없습니다: checkValidity() / reportValidity()는 true, getStatus()는 ""를 돌려주고, required는 제목의 별표만 그립니다.
슬라이더에는 유효성 규칙이 없습니다: checkValidity() / reportValidity()는 true, getStatus()는 ""를 돌려주고, required는 제목의 별표만 그립니다.
항상 ""를 돌려줍니다.
별표만 그립니다 — 슬라이더는 항상 유효합니다.