QMLQT QUICK · C++ · PYTHON
QML 컴포넌트, 공통 디자인 토큰과 직접 실행할 수 있는 예제로 데스크톱 화면을 만드세요.
QML Core는 별도 제품입니다. C++와 Python에서 같은 QML 화면을 사용합니다.
QML CORE
56개 컴포넌트 중 56개
START WITH A WORKING APP
SDK 압축을 풀고 플러그인 버전과 호환되는 Qt 키트로 빌드하세요.
cmake -S examples/cmake-app -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=C:/Qt/6.12.0/msvc2022_64 -DCMAKE_MSVC_DEBUG_INFORMATION_FORMAT=Embedded -DCMAKE_POLICY_DEFAULT_CMP0141=NEW
cmake --build build
build/syidax-example --license your.license.json --example workbench순수 QML 버전을 사용하고 Python 바인딩을 명시적으로 선택하세요.
python -m venv .venv
.venv/Scripts/python -m pip install -r examples/python-app/requirements-pyside6.txt
.venv/Scripts/python examples/python-app/main.py --binding pyside6 --license your.license.json --example records--diagnose --json으로 Qt 버전, import 경로, 폰트, 실행 상태와 라이선스를 점검하세요. 라이선스 토큰은 출력하지 않습니다.
Gallery 평가 앱을 지금 사용할 수 있습니다. 유료 SDK 판매와 다운로드는 준비 중입니다. 위 설치 예제는 SDK 출시 후 사용하는 방법입니다.
아래 버전에서 네이티브 창과 예제의 기본 실행을 검사했습니다. Qt 6.8은 소스 최소 기준이며 모든 Qt 버전의 검증을 뜻하지 않습니다. Gallery는 software 렌더러를 사용합니다.
실행 중인 Windows 앱을 단계별로 캡처했습니다. 재생·일시 정지로 각 상태를 살펴보세요.
TRY IT YOURSELF
Windows 앱에서 예제를 실행하고 속성을 살펴보며 밝은 테마와 어두운 테마를 전환하세요. Gallery는 평가용이며 상업용 SDK는 별도 제품입니다.
Gallery 다운로드 · Windows x64$24.99 / 월
$249.99 / 년 · 개발자 1명 기준
Chart와 동일한 정규 단가입니다. 첫 구매·추가 좌석·갱신에 같은 가격이 적용됩니다.
문서, 실행 가능한 예제와 진단 도구를 제공합니다. 개별 기술 지원, 온보딩, SLA는 제공하지 않습니다.
구매 및 라이선스 조건 보기 →--qml 경로가 Syidax 폴더를 포함하는지 확인하세요. Python에서는 qml-pure를 사용합니다. 소스 저장소가 아닌 압축 해제한 SDK를 기준으로 실행하세요.
QML Core 인증서를 다시 다운로드한 뒤 --license로 전달하세요. Web Core·Chart·Grid 인증서는 QML을 활성화하지 않습니다. 월간 만료 시 사용이 종료되며, 연간은 이용 기간 내 출시 버전에 한해 보유 권한이 적용됩니다.
플러그인 빌드의 Qt 버전과 아키텍처를 확인하세요. 서로 다른 Python Qt 바인딩을 혼용하지 마세요. qml-pure로 플러그인 ABI 의존성을 피할 수 있습니다.
PDF는 별도 QtQuick.Pdf 모듈이 필요합니다. 이 모듈이 없어도 나머지 Core 컴포넌트는 사용 가능합니다. 아이콘 팩 등록과 리소스 경로는 SDK의 ICON-PACKS 문서를 확인하세요.
예제는 사용자 앱 데이터 폴더에만 저장합니다. 권한과 디스크 공간을 확인하세요. 잘못된 JSON은 백업한 뒤 초기 데이터로 복구됩니다. 저장 실패 시 입력 값이 유지됩니다.
입력한 내용에 맞는 후보를 제안하는 텍스트 필드입니다. 후보를 선택하거나 값을 직접 입력할 수 있습니다.
import Syidax.Core.Autocomplete
| 타입 | 정의 / 역할 |
|---|---|
| 입력한 글자에 맞는 추천 목록을 보여주는 텍스트 필드입니다. |
미리보기는 Qt 실행 화면의 이미지입니다. 아래 버튼으로 결과를 전환하세요.
SyAutocomplete는 제안이 있는 텍스트 필드입니다.
import QtQuick
import Syidax.Core
Item {
implicitWidth: Math.max(360, childrenRect.width)
implicitHeight: childrenRect.height
id: story
readonly property var cities: ["Seoul", "Busan", "Incheon", "Daegu", "Daejeon", "Gwangju", "Suwon", "Ulsan", "Sejong"]
property QtObject settings: QtObject {
id: storyArgs
property string placeholder: "도시"
property string trigger: "focus"
property int min: 0
property bool caseSensitive: false
property bool highlightMatches: true
property int debounceTime: 0
property string size: "medium"
property string status: "default"
property bool disabled: false
property bool readonly: false
property bool required: false
property bool loading: false
}
SyAutocomplete { id: exampleControl1;
source: story.cities
placeholder: storyArgs.placeholder
trigger: storyArgs.trigger
min: storyArgs.min
caseSensitive: storyArgs.caseSensitive
highlightMatches: storyArgs.highlightMatches
debounceTime: storyArgs.debounceTime
size: storyArgs.size
status: storyArgs.status
disabled: storyArgs.disabled
readonly: storyArgs.readonly
required: storyArgs.required
loading: storyArgs.loading
}
}focus는 입력란에 포커스를 주면 목록을 표시합니다. input은 두 글자 이상 입력하면 일치하는 항목을 표시합니다.
import QtQuick
import Syidax.Core
Item {
width: 550; height: 300
readonly property var cities: ["Seoul", "Busan", "Incheon", "Daegu", "Daejeon", "Gwangju"]
id: sample
Row {
x: 20; y: 20; spacing: 30
SyAutocomplete { id: focusCity; width: 240; source: sample.cities; placeholder: "trigger: focus" }
SyAutocomplete { id: inputCity; width: 240; source: sample.cities; trigger: "input"; min: 2; placeholder: "trigger: input, min: 2" }
}
}highlightMatches: true는 각 제안 안에서 입력한 글자가 처음 나오는 부분을 굵게 그려 사용자가 왜 그 행이 맞았는지 보게 합니다.
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: story
readonly property var cities: ["Seoul", "Busan", "Incheon", "Daegu", "Daejeon", "Sejong"]
property QtObject settings: QtObject {
id: storyArgs
property bool highlightMatches: true
property bool caseSensitive: false
}
SyAutocomplete { id: featureTarget0; source: story.cities; value: "Se"; highlightMatches: storyArgs.highlightMatches; caseSensitive: storyArgs.caseSensitive }
}disabled는 비활성 톤으로 그립니다.
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: story
readonly property var cities: ["Seoul", "Busan"]
Column {
spacing: 12
SyAutocomplete { id: featureTarget0; visible: true; source: story.cities; value: "Seoul"; disabled: true }
SyAutocomplete { id: featureTarget1; visible: true; source: story.cities; value: "Seoul"; readonly: true }
SyAutocomplete { id: featureTarget2; visible: true; source: story.cities; value: "Seoul"; status: "error" }
SyAutocomplete { id: featureTarget3; visible: true; source: story.cities; loading: true; placeholder: "옵션 불러오는 중…" }
}
}changed(detail)는 생성 뒤 value가 바뀔 때마다 발생합니다: 키 입력마다, 제안을 고를 때(고르기가 먼저 value를 씀), 코드가 value를 대입할 때.
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: story
readonly property var cities: ["Seoul", "Busan", "Incheon", "Daegu", "Daejeon"]
Column {
spacing: 12
SyAutocomplete { id: exampleControl1;
source: story.cities
onChanged: (detail) => { if (true) { output.log(("changed: %1 (valid: %2)").arg(detail.value).arg(detail.isValid)) } }
onSelected: (detail) => { if (true) { output.log(("selected: %1").arg(detail.value)) } }
}
EventLog { id: output }
}
}setFocus()는 필드에 포커스를 주고(trigger: "focus"면 목록이 열림), setBlur()는 포커스를 거두고 목록을 닫습니다.
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: story
readonly property var cities: ["Seoul", "Busan", "Incheon"]
Column {
spacing: 12
Item {
width: 560; height: 280
SyAutocomplete {
x: 24; y: 24
id: city; source: story.cities; required: true }
}
Flow {
objectName: "exampleCommands"
width: 560
spacing: 8
SyButton { id: exampleControl1; visible: true; text: "city.setFocus()"; variant: "secondary"; size: "small"; onClicked: city.setFocus() }
SyButton { id: exampleControl2; visible: true; text: "city.setBlur()"; variant: "secondary"; size: "small"; onClicked: city.setBlur() }
SyButton { id: exampleControl3; visible: true; text: "city.checkValidity()"; variant: "secondary"; size: "small"; onClicked: output.log("checkValidity() → " + city.checkValidity()) }
SyButton { id: exampleControl4; visible: true; text: "city.reportValidity()"; variant: "secondary"; size: "small"; onClicked: output.log("reportValidity() → " + city.reportValidity()) }
SyButton { id: exampleControl5; visible: true; text: "city.getValidStatus()"; variant: "secondary"; size: "small"; onClicked: output.log("getValidStatus() → " + JSON.stringify(city.getValidStatus())) }
SyButton { id: exampleControl6; visible: true; text: "city.setCustomError()"; variant: "secondary"; size: "small"; onClicked: city.setCustomError() }
SyButton { id: exampleControl7; visible: true; text: "city.clearCustomError()"; variant: "secondary"; size: "small"; onClicked: city.clearCustomError() }
}
EventLog { id: output }
}
}caseSensitive · trigger · min 설정을 적용한 대소문자 구분 검색 예제입니다.
import QtQuick
import Syidax.Core
Item {
implicitWidth: Math.max(360, childrenRect.width)
implicitHeight: childrenRect.height
id: story
readonly property var cities: ["Seoul", "Busan", "Incheon", "Daegu", "Daejeon", "Gwangju", "Suwon", "Ulsan", "Sejong"]
property QtObject settings: QtObject {
id: storyArgs
property string placeholder: "도시"
property string trigger: "input"
property int min: 1
property bool caseSensitive: true
property bool highlightMatches: true
property int debounceTime: 0
property string size: "medium"
property string status: "default"
property bool disabled: false
property bool readonly: false
property bool required: false
property bool loading: false
}
SyAutocomplete { id: exampleControl1;
source: story.cities
placeholder: storyArgs.placeholder
trigger: storyArgs.trigger
min: storyArgs.min
caseSensitive: storyArgs.caseSensitive
highlightMatches: storyArgs.highlightMatches
debounceTime: storyArgs.debounceTime
size: storyArgs.size
status: storyArgs.status
disabled: storyArgs.disabled
readonly: storyArgs.readonly
required: storyArgs.required
loading: storyArgs.loading
}
}trigger · min · debounceTime 설정을 적용한 입력 후 지연 검색 예제입니다.
import QtQuick
import Syidax.Core
Item {
implicitWidth: Math.max(360, childrenRect.width)
implicitHeight: childrenRect.height
id: story
readonly property var cities: ["Seoul", "Busan", "Incheon", "Daegu", "Daejeon", "Gwangju", "Suwon", "Ulsan", "Sejong"]
property QtObject settings: QtObject {
id: storyArgs
property string placeholder: "도시"
property string trigger: "input"
property int min: 2
property bool caseSensitive: false
property bool highlightMatches: true
property int debounceTime: 300
property string size: "medium"
property string status: "default"
property bool disabled: false
property bool readonly: false
property bool required: false
property bool loading: false
}
SyAutocomplete { id: exampleControl1;
source: story.cities
placeholder: storyArgs.placeholder
trigger: storyArgs.trigger
min: storyArgs.min
caseSensitive: storyArgs.caseSensitive
highlightMatches: storyArgs.highlightMatches
debounceTime: storyArgs.debounceTime
size: storyArgs.size
status: storyArgs.status
disabled: storyArgs.disabled
readonly: storyArgs.readonly
required: storyArgs.required
loading: storyArgs.loading
}
}검증 전·오류 표시·초기화 결과를 비교합니다.
import QtQuick
import Syidax.Core
Column {
width: 440; spacing: 12
SyAutocomplete {
id: field; width: parent.width; name: "selection"; required: true
label: "필수 입력"; source: ["Seoul", "Busan", "Incheon"]
error: "계속하려면 이 항목을 입력하세요."
}
Row {
spacing: 8
SyButton { id: check; text: "검증"; onClicked: field.reportValidity() }
SyButton { id: reset; text: "초기화"; onClicked: field.reset() }
}
Text { text: "상태: " + (field.invalid ? "오류" : "입력 준비"); color: Theme.semantic.textDefault }
}업무 규칙에 맞는 오류를 표시하고 초기화합니다.
import QtQuick
import Syidax.Core
Column {
width: 440; spacing: 12
SyAutocomplete {
id: field; width: parent.width; name: "selection"; required: true
label: "필수 입력"; source: ["Seoul", "Busan", "Incheon"]
value: "Seoul"
error: "현재 사용할 수 없는 선택입니다. 다른 값을 선택하세요."
}
Row {
spacing: 8
SyButton { id: check; text: "오류 표시"; onClicked: field.setCustomError() }
SyButton { id: reset; text: "초기화"; onClicked: field.reset() }
}
Text { text: "상태: " + (field.invalid ? "오류" : "입력 준비"); color: Theme.semantic.textDefault }
}항목을 가리키거나 선택하면 QML 예제와 복사 버튼이 나타납니다.
| 속성 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| string | "" | 글자. 코드로 쓸 수 있습니다(changed 발생). | |
| list | [] | 제안 문자열들. 바꾸면 다시 걸러집니다. | |
| string | "focus" | focus: 포커스에 목록 · input: 입력한 뒤에만 목록. | |
| int | 0 | 목록이 보이고 걸러지기 위해 필요한 글자 수. | |
| bool | false | 대소문자를 구분해 매칭(과 강조). | |
| bool | false | 각 제안의 일치 부분을 굵게. | |
| int | 0 | 마지막 키 입력 뒤 거르기 전에 기다릴 밀리초(0 = 즉시). | |
| bool | false | 제안 대신 스피너 행. | |
| string | "" | 글자가 비어 있는 동안 보입니다. | |
| string | "default" | default · warning · error · success — 외형이지 유효성이 아닙니다. | |
| bool | false | 편집 불가, 목록 없음, 읽기는 가능. | |
| int | -1 | filteredList에서 강조된 행. | |
| list | [] | 지금 보이는 제안들. | |
| bool | false | 사용자가 입력한 뒤 true(trigger: "input"이 기다리는 것). | |
| bool(읽기 전용) | — | 목록이 보이는 중인지. | |
| string(읽기 전용) | — | 문자열로서의 value. | |
| bool(읽기 전용) | — | 필드에 포커스가 있는지 | |
| bool(읽기 전용) | — | 포인터가 상자 위에 있는지. | |
| string | "" | 프레임의 제목, 폼 키, 도움말, 사용자 오류 문구. | |
| string | "" | 프레임의 제목, 폼 키, 도움말, 사용자 오류 문구. | |
| string | "" | 프레임의 제목, 폼 키, 도움말, 사용자 오류 문구. | |
| string | "" | 프레임의 제목, 폼 키, 도움말, 사용자 오류 문구. | |
| string | "medium" | small · medium · large — 상자 높이 24 / 32 / 40 px. | |
| bool | false | 비활성 톤과 반응 없음 | |
| bool | false | 빈 글자는 valueMissing. | |
| 읽기 전용 | — | 유효성: "" · valueMissing · custom. invalid는 touched 되거나 report 된 뒤. | |
| 읽기 전용 | — | invalid는 touched 되거나 report 된 뒤. | |
| 읽기 전용 | — | 유효성: "" · valueMissing · custom. invalid는 touched 되거나 report 된 뒤. | |
| real | 240 | 앱이 너비를 정하지 않을 때의 너비. |
| 메서드 | 설명 |
|---|---|
필드에 포커스를 줍니다. trigger: "focus"면 목록이 열립니다. | |
| 포커스를 거두고 목록을 닫습니다. | |
상태가 ""인지 돌려줍니다(조용히). | |
| 같지만 오류 줄을 드러냅니다. | |
"", "valueMissing" 또는 "custom"(둘은 같습니다). | |
"", "valueMissing" 또는 "custom"(둘은 같습니다). | |
custom 상태를 강제(하고 필드를 touched로 표시) · 해제. | |
custom 상태를 강제(하고 필드를 touched로 표시) · 해제. | |
| 생성 시점 값을 되돌리고 touched / submitted / custom 플래그를 지웁니다. |
| 시그널 | 인자 | 시점 |
|---|---|---|
detail: { value, isValid, status } | 생성 뒤 value가 바뀜 — 입력, 선택, 코드. 초기값에는 없음. | |
detail: { value, isValid, status } | 클릭이나 강조된 행의 Enter로 제안을 고름(changed 다음). | |
detail: { value, isValid, status } | 필드가 포커스를 얻음. | |
detail: { value, isValid, status } | 필드가 포커스를 잃음. 이제 필드는 touched이고 목록은 닫힙니다. |
| 항목 | 동작 / 조건 |
|---|---|
| 대소문자를 구분해 매칭(과 강조). | |
| 제안 문자열들. 바꾸면 다시 걸러집니다. | |
| 각 제안의 일치 부분을 굵게. | |
focus: 포커스에 목록 · input: 입력한 뒤에만 목록. | |
trigger: "focus"(기본값): 필드에 포커스가 있고 글자가 min자 이상일 때마다(min: 0 → 포커스 즉시). | |
| 목록이 보이고 걸러지기 위해 필요한 글자 수. | |
마지막 키 입력 뒤 거르기 전에 기다릴 밀리초(0 = 즉시). | |
| 포커스를 거두고 목록을 닫습니다. | |
| 목록이 보이는 중인지. | |
| 지금 보이는 제안들. | |
filteredList에서 강조된 행. | |
글자. 코드로 쓸 수 있습니다(changed 발생). | |
클릭이나 강조된 행의 Enter로 제안을 고름(changed 다음). | |
생성 뒤 value가 바뀜 — 입력, 선택, 코드. 초기값에는 없음. | |
목록이 닫혀 있거나 강조된 행이 없을 때 Enter는 필드가 선언된 SyForm(있다면)을 제출합니다. 키패드 Enter도 Return과 같이 동작합니다. | |
disabled: 비활성 톤, 포커스 없음, 목록 없음. | |
| 편집 불가, 목록 없음, 읽기는 가능. | |
default · warning · error · success — 외형이지 유효성이 아닙니다. | |
status는 외형을 더합니다 — 프레임과 글자에 default, warning, error, success 톤 — 유효성은 건드리지 않습니다. 오류 줄(기본 문구 또는 error)은 필드가 블러된(touched) 뒤나 reportValidity() 뒤에 보입니다. | |
| 제안 대신 스피너 행. | |
required인데 글자가 비면 valueMissing, setCustomError()면 custom, disabled나 readonly면 항상 "". | |
required인데 글자가 비면 valueMissing, setCustomError()면 custom, disabled나 readonly면 항상 "". | |
| 같지만 오류 줄을 드러냅니다. | |
small · medium · large — 상자 높이 24 / 32 / 40 px. | |
상자는 size 높이(small 24 · medium 32 · large 40 px)이고, 너비는 앱이 width를 정하지 않으면 preferredWidth 240입니다. | |
| 앱이 너비를 정하지 않을 때의 너비. |
| 항목 | 동작 / 조건 |
|---|---|
| 키보드: Tab과 Shift+Tab으로 필드에 진입하고 이동합니다. 숨김·비활성 필드는 건너뜁니다. 열린 선택기는 Escape로 닫을 수 있습니다. Textarea의 Tab은 들여쓰기 대신 포커스를 이동하며 Modal 안에서는 포커스 경계를 유지합니다. |