Window QML Type

새로운 최상위 창을 생성합니다. 더 보기...

• 상속된 멤버를 포함한 모든 멤버 목록

속성

• active : bool
• activeFocusItem : Item
• color : color
• contentItem : Item
• contentOrientation : Qt::ScreenOrientation
• data : list<QtObject>
• flags : Qt::WindowFlags
• height : int
• maximumHeight : int
• maximumWidth : int
• minimumHeight : int
• minimumWidth : int
• modality : Qt::WindowModality
• opacity : real
• palette : Palette (since 6.0)
• screen : Screen
• title : string
• transientParent : QWindow
• visibility : QWindow::Visibility
• visible : bool
• width : int
• x : int
• y : int

연관 속성

• active : bool
• activeFocusItem : Item
• contentItem : Item
• height : int
• visibility : QWindow::Visibility
• width : int
• window : Window

신호

• afterAnimating()
• closing(CloseEvent close)
• devicePixelRatioChanged()
• frameSwapped()
• sceneGraphError(SceneGraphError error, QString message)

방법

• void alert(int msec)
• void close()
• void hide()
• void lower()
• void raise()
• void requestActivate()
• void show()
• void showFullScreen()
• void showMaximized()
• void showMinimized()
• void showNormal()
• void startSystemMove() (since 6.8)
• void startSystemResize(Qt::Edges edges) (since 6.8)

상세 설명

Window 객체는 Qt Quick 장면용 새로운 최상위 창을 생성합니다. 이 객체는 QtQuick 그래픽 유형과 함께 사용할 수 있도록 창을 자동으로 설정합니다.

Window는 Item 내부나 다른 Window 내부에서 선언될 수 있으며, 이 경우 내부 Window는 자동으로 외부 Window에 대해 “일시적(transient for)” 상태가 되며, 외부 Window를 transientParent 로 갖게 됩니다. 대부분의 플랫폼에서는 이 경우 내부 창이 외부 창을 중심으로 정렬되어 표시되며, flags 에 따라 플랫폼별로 다른 동작이 나타날 수도 있습니다. 중첩된 창을 애플리케이션의 대화 상자로 사용할 예정이라면, flags 를 Qt.Dialog 로 설정해야 합니다. 일부 창 관리자는 이 플래그가 없으면 중앙 정렬 기능을 제공하지 않기 때문입니다.

최상위 ` QtObject` 내부에 여러 개의 창을 선언할 수도 있으며, 이 경우 창들 간에는 일시적인 관계가 형성되지 않습니다.

또는 x 및 y 을 설정하거나 바인딩하여 Window를 화면의 특정 위치에 명시적으로 배치할 수도 있습니다.

사용자가 창을 닫으려고 하면 closing 신호가 발생합니다. 창을 닫아도 안전한 경우(예: 저장되지 않은 변경 사항이 더 이상 없는 경우)를 제외하고 close.accepted = false 를 설정하는 onClosing 핸들러를 작성하여 창이 계속 열려 있도록 강제할 수 있습니다(예: 사용자에게 변경 사항을 저장할지 묻기 위해).

onClosing: (close) => {
    if (document.changed) {
        close.accepted = false
        confirmExitPopup.open()
    }
}

// The confirmExitPopup allows user to save or discard the document,
// or to cancel the closing.

스타일 지정

Qt Quick 의 모든 시각적 유형과 마찬가지로, Window도 palettes 를 지원합니다. 그러나 Text 와 같은 유형의 경우와 마찬가지로, Window는 기본적으로 팔레트를 사용하지 않습니다. 예를 들어, 운영 체제의 테마가 변경될 때 창의 배경색을 변경하려면 color 을 설정해야 합니다:

Window {
    visible: true

    // here we use the Window.active and Window.palette ordinary properties
    color: active ? palette.active.window : palette.inactive.window

    Text {
        anchors.centerIn: parent
        // here we use the Window.active attached property and the Item.palette property
        color: Window.active ? palette.active.windowText : palette.inactive.windowText
        text: Window.active ? "active" : "inactive"
    }
}

자동 스타일을 적용하려면 Window 대신 ApplicationWindow (및 Label)를 사용해야 합니다: Qt Quick Controls 에서 제공하는 `xml-ph-0000@deepl.internal`(및 `xml-ph-0001@deepl.internal`)를 사용하여 자동 스타일링을 적용하십시오.

속성 설명서

active : bool [read-only]

창의 활성 상태.

Window {
    visible: true

    // here we use the Window.active and Window.palette ordinary properties
    color: active ? palette.active.window : palette.inactive.window
}

requestActivate()도 참조하십시오 .

activeFocusItem : Item [read-only]

현재 포커스가 설정된 항목이거나, 포커스가 설정된 항목이 없는 경우 ` null `입니다.

color : color

창의 배경색입니다.

이 속성을 설정하는 것이 별도의 Rectangle을 사용하는 것보다 더 효율적입니다.

contentItem : Item [read-only]

씬의 보이지 않는 루트 아이템입니다.

contentOrientation : Qt::ScreenOrientation

이는 창 관리자가 해당 창과 관련하여 팝업, 대화상자, 상태 표시줄 또는 이와 유사한 추가 콘텐츠를 표시해야 할 경우를 대비한 힌트입니다.

권장되는 방향은 Screen.orientation 이지만, 애플리케이션이 가능한 모든 방향을 지원할 필요는 없으므로 현재 화면 방향을 무시하도록 선택할 수도 있습니다.

창의 방향과 콘텐츠 방향의 차이에 따라 콘텐츠를 회전할 각도가 결정됩니다.

기본값은 Qt::PrimaryOrientation 입니다.

Screen도 참조하십시오 .

data : list<QtObject> [default]

데이터 속성을 사용하면 하나의 Window 내에서 시각적 자식 요소, 리소스 및 다른 Window를 자유롭게 혼합할 수 있습니다.

데이터 목록에 다른 창을 할당하면, 중첩된 창은 외부의 창에 대해 “일시적(transient for)” 상태가 됩니다.

데이터 목록에 ' Item '을 할당하면, 해당 항목은 Window의 ' contentItem'의 자식이 되어 창 내부에 표시됩니다. 항목의 부모는 Window의 ' contentItem'가 되며, 이는 해당 Window 내의 항목 소유권 트리의 루트입니다.

다른 객체 유형을 할당하면 리소스로 추가됩니다.

data 속성은 Window의 기본 속성이므로 모든 자식 항목이 자동으로 이 속성에 할당되므로, 일반적으로 이 속성을 참조할 필요는 없습니다.

QWindow::transientParent()도 참조하십시오 .

flags : Qt::WindowFlags

창의 창 플래그.

창 플래그는 윈도우 시스템에서 창의 외관을 제어하며, 대화 상자, 팝업, 일반 창 중 어느 유형인지, 제목 표시줄을 포함할지 여부 등을 결정합니다.

요청한 플래그를 적용할 수 없는 경우, 이 속성에서 읽어온 플래그가 설정한 플래그와 다를 수 있습니다.

import QtQuick

Window {
    id: mainWindow
    title: "Main Window"
    color: "#456"
    property real defaultSpacing: 10

    property Splash splash: Splash {
        onTimeout: mainWindow.show()
    }

    component Splash: Window {
        id: splash

        // a splash screen has no titlebar
        flags: Qt.SplashScreen
        // the transparent color lets background behind the image edges show through
        color: "transparent"
        modality: Qt.ApplicationModal // in case another application window is showing
        title: "Splash Window" // for the taskbar/dock, task switcher etc.
        visible: true

        // here we use the Screen attached property to center the splash window
        x: (Screen.width - splashImage.width) / 2
        y: (Screen.height - splashImage.height) / 2
        width: splashImage.width
        height: splashImage.height

        property int timeoutInterval: 2000
        signal timeout

        Image {
            id: splashImage
            source: "images/qt-logo.png"
        }

        TapHandler {
            onTapped: splash.timeout()
        }

        Timer {
            interval: splash.timeoutInterval; running: true; repeat: false
            onTriggered: {
                splash.visible = false
                splash.timeout()
            }
        }
    }
}

Qt::WindowFlags 및 Qt Quick 예제 - 창 및 화면을참조하십시오 .

창의 위치와 크기를 정의합니다.

(x, y) 위치는 창이 하나뿐인 경우 Screen 을 기준으로 하며, 여러 개의 화면이 있는 경우에는 가상 데스크톱을 기준으로 합니다.

Window { x: 100; y: 100; width: 100; height: 100 }

창의 최대 크기를 정의합니다.

이는 지정된 너비와 높이를 초과하여 창 크기가 조정되지 않도록 창 관리자에게 전달하는 힌트입니다.

창의 최소 크기를 정의합니다.

이는 지정된 너비와 높이 이하로 창 크기가 조정되지 않도록 창 관리자에게 전달하는 힌트입니다.

modality : Qt::WindowModality

창의 모달성.

모달 창은 다른 창이 입력 이벤트를 수신하지 못하도록 차단합니다. 가능한 값으로는 Qt.NonModal(기본값), Qt.WindowModal 및 Qt.ApplicationModal이 있습니다.

opacity : real

창의 불투명도.

창 관리 시스템이 창 불투명도를 지원하는 경우, 이를 사용하여 창을 서서히 나타나게 하거나 사라지게 하거나, 반투명하게 만들 수 있습니다.

값이 1.0 이상이면 완전히 불투명하게 처리되고, 0.0 이하이면 완전히 투명하게 처리됩니다. 그 사이의 값은 이 두 극단 사이의 다양한 반투명도를 나타냅니다.

기본값은 1.0입니다.

palette : Palette [since 6.0]

이 속성은 창에 현재 설정된 팔레트를 저장합니다.

기본 팔레트는 시스템 환경에 따라 달라집니다. ` QGuiApplication `는 모든 애플리케이션 창의 기본값으로 사용되는 시스템/테마 팔레트를 관리합니다. 또한 QML을 로드하기 전에 ` QGuiApplication::setPalette()`에 사용자 정의 팔레트를 전달하여 창의 기본 팔레트를 설정할 수도 있습니다.

Window는 명시적인 팔레트 속성을 자식 항목 및 컨트롤로 전파하며, 해당 속성에 대한 시스템 기본값을 재정의합니다.

import QtQuick
import QtQuick.Controls

Window {
    visible: true

    // here we use the Window.active and Window.palette ordinary properties
    color: active ? palette.active.window : palette.inactive.window

    // colors that are not customized here come from SystemPalette
    palette.active.window: "peachpuff"
    palette.windowText: "brown"

    Text {
        anchors.centerIn: parent
        // here we use the Window.active attached property and the Item.palette property
        color: Window.active ? palette.active.windowText : palette.inactive.windowText
        text: Window.active ? "active" : "inactive"
    }

    Button {
        text: "Button"
        anchors {
            bottom: parent.bottom
            bottomMargin: 6
            horizontalCenter: parent.horizontalCenter
        }
    }
}

이 속성은 Qt 6.0에서 도입되었습니다.

Item::palette, Popup::palette, ColorGroup 및 SystemPalette도 참조하십시오 .

screen : Screen

창이 연결된 화면입니다.

창을 표시하기 전에 이 속성을 지정하면, 명시적인 창 위치가 설정되어 있지 않은 한 해당 화면에 창이 표시됩니다. 이 값은 ` Application.screens ` 배열의 요소여야 합니다.

QWindow::setScreen(), QWindow::screen(), QScreen 및 Application도 참조하십시오 .

title : string

윈도우 시스템에서 윈도우의 제목.

창 제목은 사용 중인 윈도우 시스템과 창 플래그에 따라 창 장식의 제목 영역에 표시될 수 있습니다. 또한 윈도우 시스템이 작업 전환기 등 다른 상황에서 해당 창을 식별하는 데 사용될 수도 있습니다.

transientParent : QWindow

이 창이 일시적인 팝업으로 표시되는 창.

이는 창 관리자에게 이 창이 일시적인 부모 창을 대신하는 대화 상자나 팝업임을 알리는 힌트입니다. 일반적으로 이는 일시적인 창이 처음 표시될 때 일시적인 부모 창 중앙에 배치되고, 부모 창을 최소화하면 일시적인 창도 함께 최소화되는 등의 동작을 의미하지만, 결과는 플랫폼마다 다소 차이가 있을 수 있습니다.

default property 을 사용하거나 전용 속성을 통해 Item 또는 다른 Window 내부에 Window를 선언하면, transientParent 속성이 명시적으로 설정되지 않은 한, 해당 Window를 포함하는 창과의 일시적 부모 관계가 자동으로 설정됩니다. 이는 Qt.createComponent 또는 Qt.createQmlObject 를 통해 Window 항목을 생성할 때도, parent 인자로 Item 또는 Window가 전달되는 한 적용됩니다.

일시적 상위 요소가 있는 Window는, 설령 ` visible ` 속성이 ` true`로 설정되어 있더라도, 해당 일시적 상위 요소가 표시될 때까지 표시되지 않습니다. 이는 앞서 설명한 자동 일시적 상위 관계에도 적용됩니다. 특히, 창을 포함하는 요소가 Item인 경우, 해당 창은 시각적 부모 계층 구조를 통해 포함하는 항목이 씬에 추가될 때까지 표시되지 않습니다. transientParent를 null 로 설정하면 이 동작을 무시할 수 있습니다:

Window {
    // visible is false by default
    Window {
        transientParent: null
        visible: true
    }
}

창이 기본적으로 일시적 상위 요소의 중앙에 위치하도록 하려면, 창 관리자에 따라 Window::flags 속성을 적절한 Qt::WindowType (예: Qt::Dialog)로 설정해야 할 수도 있습니다.

parent()도 참조하십시오 .

visibility : QWindow::Visibility

창의 화면 점유 상태.

가시성은 창이 창 관리 시스템에서 정상, 최소화, 최대화, 전체 화면 또는 숨김 상태로 표시되어야 하는지를 나타냅니다.

가시성을 ` AutomaticVisibility `로 설정한다는 것은 창에 기본 가시 상태를 부여하는 것을 의미하며, 이는 플랫폼에 따라 ` FullScreen ` 또는 ` Windowed `일 수 있습니다. 그러나 가시성 속성을 읽을 때는 항상 실제 상태가 반환되며, ` AutomaticVisibility`는 절대 반환되지 않습니다.

창이 visible 상태가 아닐 때, 그 가시성은 Hidden 입니다. 가시성을 Hidden 로 설정하는 것은 visible 을 false 로 설정하는 것과 같습니다.

기본값은 Hidden

import QtQuick
import QtQuick.Controls

Window {
    id: win
    flags: Qt.Window | Qt.WindowFullscreenButtonHint
    visibility: fullscreenButton.checked ? Window.FullScreen : Window.Windowed

    Button {
        id: fullscreenButton
        anchors {
            right: parent.right
            top: parent.top
            margins: 6
        }
        width: height
        checkable: true
        Binding on checked { value: win.visibility === Window.FullScreen }
        text: "⛶"
        ToolTip.visible: hovered
        ToolTip.delay: Qt.styleHints.mousePressAndHoldInterval
        ToolTip.text: win.visibility === Window.FullScreen ? qsTr("restore") : qsTr("fill screen")
    }
}

visible 및 Qt Quick 의 ‘예제 - 창 및 화면’항목도 참조하십시오 .

visible : bool

창이 화면에 표시되는지 여부.

visible을 false로 설정하는 것은 visibility 를 Hidden 로 설정하는 것과 같습니다.

visibility 로 설정하여 재정의하지 않는 한, 기본값은 false 입니다.

visibility도 참조하십시오 .

부속 속성 설명서

Window.active : bool [read-only attached]

이 첨부 속성은 창이 활성화되어 있는지 여부를 나타냅니다. Window 첨부 속성은 모든 Item에 연결할 수 있습니다.

다음은 레이블을 변경하여 해당 레이블이 표시된 창의 활성 상태를 나타내는 예시입니다:

import QtQuick

Text {
    text: Window.active ? "active" : "inactive"
}

Window.activeFocusItem : Item [read-only attached]

이 첨부 속성은 현재 포커스가 설정된 항목을 보관하며, 포커스가 설정된 항목이 없는 경우에는 ` null `를 보관합니다. Window 첨부 속성은 모든 Item에 연결할 수 있습니다.

Window.contentItem : Item [read-only attached]

이 부착 속성은 씬의 보이지 않는 루트 아이템을 보유하거나, 해당 아이템이 창에 속해 있지 않은 경우 ‘ null ’를 보유합니다. ‘Window’ 부착 속성은 어떤 아이템이든 부착할 수 있습니다.

이러한 부착 속성은 항목의 창 크기를 저장합니다. Window 부착 속성은 모든 항목에 부착할 수 있습니다.

Window.visibility : QWindow::Visibility [read-only attached]

이 부착 속성은 창 관리 시스템에서 해당 창이 현재 정상 상태, 최소화, 최대화, 전체 화면 또는 숨김 상태로 표시되어 있는지 여부와 관계없이 유지됩니다. ` Window ` 부착 속성은 모든 `Item`에 적용할 수 있습니다. 해당 항목이 어떤 창에도 표시되지 않는 경우, 값은 ` Hidden`이 됩니다.

visible 및 visibility항목도 참조하십시오 .

Window.window : Window [attached]

이 첨부 속성은 항목의 창을 보관합니다. Window 첨부 속성은 모든 항목에 첨부할 수 있습니다.

신호 문서

afterAnimating()

이 신호는 렌더 스레드에 장면 그래프의 동기화를 수행하도록 요청하기 전에 GUI 스레드에서 발생합니다.

onAfterAnimating을 구현하여 각 애니메이션 단계가 끝난 후 추가 처리를 수행할 수 있습니다.

closing(CloseEvent close)

사용자가 창을 닫으려고 할 때 이 신호가 발생합니다.

이 신호에는 ` close ` 매개변수가 포함됩니다. ` close.accepted ` 속성은 기본적으로 `true`로 설정되어 있어 창을 닫을 수 있도록 허용되지만, 창을 닫기 전에 다른 작업을 수행해야 하는 경우 ` onClosing ` 핸들러를 구현하고 ` close.accepted = false `를 설정할 수 있습니다.

devicePixelRatioChanged()

frameSwapped()

이 신호는 프레임이 표시를 위해 큐에 추가되었을 때 발생합니다. 수직 동기화(vsync)가 활성화된 경우, 지속적으로 애니메이션이 재생되는 장면에서는 이 신호가 vsync 간격당 최대 한 번 발생합니다.

sceneGraphError(SceneGraphError error, QString message)

이 신호는 씬 그래프 초기화 중에 error 가 발생했을 때 발송됩니다.

onSceneGraphError(error, message)를 구현하여 그래픽 컨텍스트 생성 실패와 같은 오류를 사용자 정의 방식으로 처리할 수 있습니다. 이 신호에 핸들러가 연결되어 있지 않으면 Quick은 message 를 출력하거나 메시지 상자를 표시한 후 애플리케이션을 종료합니다.

메서드 문서

void alert(int msec)

msec 밀리초 동안 알림을 표시합니다. msec 가 0 (기본값)인 경우, 창이 다시 활성화될 때까지 알림이 무기한으로 표시됩니다.

경고 상태에서는 창이 깜빡이거나 작업 표시줄 항목을 튀게 하는 등의 방식으로 사용자의 주의를 요구함을 나타냅니다.

void close()

창을 닫습니다.

이 메서드가 호출되거나 사용자가 제목 표시줄의 버튼을 통해 창을 닫으려고 시도하면, ` closing ` 신호가 발생합니다. 핸들러가 없거나 핸들러가 닫기 권한을 취소하지 않으면, 창은 이후 닫힙니다. ` QGuiApplication::quitOnLastWindowClosed ` 속성이 ` true`이고 열려 있는 다른 창이 없는 경우, 애플리케이션이 종료됩니다.

void hide()

창을 숨깁니다.

visible 을 false 로 설정하거나, visibility 을 Hidden 로 설정하는 것과 동일합니다.

show()도 참조하십시오 .

void lower()

윈도우 시스템에서 해당 창을 아래로 내립니다.

해당 창이 다른 창들 아래에 표시되도록 하도록 요청합니다.

void raise()

윈도우 시스템에서 해당 창을 위로 올립니다.

해당 창이 다른 창들 위에 표시되도록 최상단 위치로 올릴 것을 요청합니다.

void requestActivate()

창이 활성화되도록, 즉 키보드 포커스를 받도록 요청합니다.

void show()

창을 표시합니다.

이는 창 유형 및 플래그에 대한 플랫폼의 기본 동작에 따라 showFullScreen(), showMaximized() 또는 showNormal()를 호출하는 것과 동일합니다.

showFullScreen(), showMaximized(), showNormal(), hide() 및 QQuickItem::flags()도 참조하십시오 .

void showFullScreen()

창을 전체 화면으로 표시합니다.

visibility 를 FullScreen 로 설정하는 것과 동일합니다.

void showMaximized()

창을 최대화 상태로 표시합니다.

visibility 을 Maximized 로 설정하는 것과 동일합니다.

void showMinimized()

창을 최소화 상태로 표시합니다.

visibility 를 Minimized 로 설정하는 것과 동일합니다.

void showNormal()

창을 일반적인 상태로 표시합니다. 즉, 최대화, 최소화 또는 전체 화면 상태가 아닙니다.

visibility 를 Windowed 로 설정하는 것과 동일합니다.

[since 6.8] void startSystemMove()

시스템별 이동 작업을 시작합니다.

플랫폼 지원을 활용하여 창에 대한 대화형 이동 작업을 시작합니다. 마우스 버튼이 해제될 때까지 창은 마우스 커서를 따라갑니다.

setPosition 대신 이 메서드를 사용하십시오. 이 메서드를 사용하면 윈도우 관리자가 스냅, 타일링 및 관련 애니메이션을 처리할 수 있습니다. Wayland에서는 setPosition 가 지원되지 않으므로, 이 방법이 애플리케이션이 창의 위치를 제어할 수 있는 유일한 방법입니다.

이 메서드는 Qt 6.8에서 도입되었습니다.

[since 6.8] void startSystemResize(Qt::Edges edges)

시스템별 크기 조정 작업을 시작합니다.

플랫폼 지원을 활용하여 창에 대한 대화형 크기 조정 작업을 시작합니다. 지정된 가장자리는 드래그하는 동안 마우스 커서를 따라갑니다.

setGeometry 대신 이 메서드를 사용하십시오. 이 메서드를 사용하면 창 관리자가 화면 가장자리로 크기를 조정할 때 스냅 및 크기 조정 애니메이션을 처리할 수 있습니다.

edges 단일 가장자리이거나 인접한 두 가장자리의 조합(모서리)이어야 합니다. 그 외의 값은 허용되지 않습니다.

이 메서드는 Qt 6.8에서 도입되었습니다.