Menu QML Type

컨텍스트 메뉴 또는 팝업 메뉴로 사용할 수 있는 메뉴 팝업입니다. 더 보기...

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

속성

• cascade : bool (since QtQuick.Controls 2.3 (Qt 5.10))
• contentData : list<QtObject>
• contentModel : model
• count : int (since QtQuick.Controls 2.3 (Qt 5.10))
• currentIndex : int (since QtQuick.Controls 2.3 (Qt 5.10))
• delegate : Component (since QtQuick.Controls 2.3 (Qt 5.10))
• focus : bool
• icon
  • icon.cache : bool
  • icon.color : color
  • icon.height : int
  • icon.name : string
  • icon.source : url
  • icon.width : int
• overlap : real (since QtQuick.Controls 2.3 (Qt 5.10))
• title : string

방법

• Action actionAt(int index) (since QtQuick.Controls 2.3 (Qt 5.10))
• void addAction(Action action) (since QtQuick.Controls 2.3 (Qt 5.10))
• void addItem(Item item)
• void addMenu(Menu menu) (since QtQuick.Controls 2.3 (Qt 5.10))
• void dismiss() (since QtQuick.Controls 2.3 (Qt 5.10))
• void insertAction(int index, Action action) (since QtQuick.Controls 2.3 (Qt 5.10))
• void insertItem(int index, Item item)
• void insertMenu(int index, Menu menu) (since QtQuick.Controls 2.3 (Qt 5.10))
• Item itemAt(int index)
• Menu menuAt(int index) (since QtQuick.Controls 2.3 (Qt 5.10))
• void moveItem(int from, int to)
• void popup(MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void popup(Item parent, MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void popup(point pos, MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void popup(Item parent, point pos, MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void popup(real x, real y, MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void popup(Item parent, real x, real y, MenuItem item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void removeAction(Action action) (since QtQuick.Controls 2.3 (Qt 5.10))
• void removeItem(Item item) (since QtQuick.Controls 2.3 (Qt 5.10))
• void removeMenu(Menu menu) (since QtQuick.Controls 2.3 (Qt 5.10))
• Action takeAction(int index) (since QtQuick.Controls 2.3 (Qt 5.10))
• MenuItem takeItem(int index) (since QtQuick.Controls 2.3 (Qt 5.10))
• Menu takeMenu(int index) (since QtQuick.Controls 2.3 (Qt 5.10))

자세한 설명

메뉴에는 두 가지 주요 사용 사례가 있습니다:

• 컨텍스트 메뉴; 예를 들어 마우스 오른쪽 버튼 클릭 후 표시되는 메뉴
• 팝업 메뉴; 예를 들어 버튼을 클릭한 후 표시되는 메뉴

컨텍스트 메뉴로 사용하는 경우 메뉴를 여는 권장 방법은 popup()를 호출하는 것입니다. 위치를 명시적으로 지정하지 않는 한 메뉴는 마우스 커서를 사용할 수 있는 데스크톱 플랫폼에서는 마우스 커서 위치에, 그렇지 않은 경우에는 상위 항목의 중앙에 위치합니다.

MouseArea {
    anchors.fill: parent
    acceptedButtons: Qt.LeftButton | Qt.RightButton
    onClicked: {
        if (mouse.button === Qt.RightButton)
            contextMenu.popup()
    }
    onPressAndHold: {
        if (mouse.source === Qt.MouseEventNotSynthesized)
            contextMenu.popup()
    }

    Menu {
        id: contextMenu
        MenuItem { text: "Cut" }
        MenuItem { text: "Copy" }
        MenuItem { text: "Paste" }
    }
}

팝업 메뉴로 사용하는 경우 해당 속성을 사용하여 원하는 x 및 y 좌표를 지정하여 위치를 지정하고 open()를 호출하여 메뉴를 여는 것이 가장 쉽습니다.

Button {
    id: fileButton
    text: "File"
    onClicked: menu.open()

    Menu {
        id: menu
        y: fileButton.height

        MenuItem {
            text: "New..."
        }
        MenuItem {
            text: "Open..."
        }
        MenuItem {
            text: "Save"
        }
    }
}

버튼을 클릭했을 때 메뉴도 닫아야 하는 경우에는 Popup.CloseOnPressOutsideParent 플래그를 사용합니다:

onClicked: menu.visible = !menu.visible

Menu {
    // ...
    closePolicy: Popup.CloseOnEscape | Popup.CloseOnPressOutsideParent

QtQuick.Controls 2.3(Qt 5.10) 이후부터는 하위 메뉴를 만들고 메뉴 안에 Action 객체를 선언할 수도 있습니다:

Menu {
    Action { text: "Cut" }
    Action { text: "Copy" }
    Action { text: "Paste" }

    MenuSeparator { }

    Menu {
        title: "Find/Replace"
        Action { text: "Find Next" }
        Action { text: "Find Previous" }
        Action { text: "Replace" }
    }
}

하위 메뉴는 마우스 커서를 사용할 수 있는 데스크톱 플랫폼에서 기본적으로 cascading 입니다. 비계단식 메뉴는 한 번에 한 메뉴씩 표시되며 상위 메뉴의 중앙에 표시됩니다.

일반적으로 메뉴 항목은 메뉴의 하위 항목으로 정적으로 선언되지만 메뉴는 add, insert, move 및 remove 항목에 대한 API도 동적으로 제공합니다. 메뉴의 항목은 itemAt() 또는 contentChildren 을 사용하여 액세스할 수 있습니다.

MenuItems 이 가장 일반적으로 Menu와 함께 사용되지만 모든 유형의 항목을 포함할 수 있습니다.

여백

팝업에서 상속되었으므로 Menu는 margins 을 지원합니다. 기본적으로 모든 기본 제공 스타일은 메뉴가 창 범위 내에 유지되도록 메뉴의 여백에 0 을 지정합니다. 메뉴가 창 밖으로 나가도록 허용하려면(예: 보기로 이동하는 애니메이션을 적용하려면) 여백 속성을 -1 으로 설정합니다.

메뉴 항목 동적으로 생성하기

Instantiator 또는 동적 객체 생성을 사용하여 메뉴 항목을 동적으로 생성할 수 있습니다.

인스턴티베이터 사용

Instantiator 를 사용하여 메뉴 항목을 동적으로 생성할 수 있습니다. 다음 코드는 설정에 저장된 파일 목록에서 항목을 가져오는 '최근 파일' 하위 메뉴를 구현하는 방법을 보여줍니다:

Menu {
    title: qsTr("File")

    Menu {
        id: recentFilesMenu
        title: qsTr("Recent Files")
        enabled: recentFilesInstantiator.count > 0

        Instantiator {
            id: recentFilesInstantiator
            model: settings.recentFiles
            delegate: MenuItem {
                text: settings.displayableFilePath(modelData)
                onTriggered: loadFile(modelData)
            }

            onObjectAdded: (index, object) => recentFilesMenu.insertItem(index, object)
            onObjectRemoved: (index, object) => recentFilesMenu.removeItem(object)
        }

        MenuSeparator {}

        MenuItem {
            text: qsTr("Clear Recent Files")
            onTriggered: settings.clearRecentFiles()
        }
    }
}

동적 개체 생성 사용

Qt.createComponent()를 사용하여 QML 파일에서 컴포넌트를 동적으로 로드할 수도 있습니다. 컴포넌트가 준비되면 해당 컴포넌트의 createObject() 메서드를 호출하여 해당 컴포넌트의 인스턴스를 만들 수 있습니다.

Row {
    anchors.centerIn: parent

    Component {
        id: menuItemComponent

        MenuItem {}
    }

    Button {
        id: button
        text: "Menu"
        onClicked: menu.open()
        Menu {
            id: menu
        }
    }

    Button {
        text: "Add item"
        onClicked: {
            onClicked: {
                let menuItem = menuItemComponent.createObject(
                    menu.contentItem, { text: qsTr("New item") })
                menu.addItem(menuItem)
            }
        }
    }
}

메뉴 유형

Qt 6.8부터 메뉴는 플랫폼에 따라 세 가지 다른 구현을 제공합니다. popupType 을 설정하여 어느 것을 선호할지 선택할 수 있습니다. 이를 통해 메뉴를 별도의 창으로 표시할지, 부모 창 안의 항목으로 표시할지, 기본 메뉴로 표시할지 제어할 수 있습니다. 이러한 옵션에 대한 자세한 내용은 here 에서 확인할 수 있습니다.

기본값 popupType 은 스타일에 따라 결정됩니다. 예를 들어 macOS 스타일은 Popup.Native 로 설정하는 반면 Imagine 스타일은 Popup.Window (스타일에서 팝업 유형을 설정하지 않은 경우 기본값)을 사용합니다. 메뉴에 사용자 정의 항목을 추가하고 스타일에 관계없이 해당 항목을 사용하려면 팝업 유형을 Popup.Window (또는 Popup.Item)로 명시적으로 설정해야 합니다. 또 다른 대안은 Qt::AA_DontUseNativeMenuWindows application attribute 으로 설정하는 것입니다. 이렇게 하면 스타일에 관계없이 전체 애플리케이션에 대한 기본 컨텍스트 메뉴가 비활성화됩니다.

기본값 popupType 은 스타일에 따라 결정됩니다. 예를 들어 macOS 스타일은 Popup.Native 로 설정하고 Imagine 스타일은 Popup.Window (스타일에서 팝업 유형을 설정하지 않은 경우 기본값)을 사용합니다. 메뉴에 사용자 지정을 추가하고 스타일에 관계없이 사용하려면 팝업 유형을 Popup.Window (또는 Popup.Item)로 명시적으로 설정해야 합니다.

메뉴에서 선호하는 유형을 사용할 수 있는지 여부는 플랫폼에 따라 다릅니다. Popup.Item 는 모든 플랫폼에서 지원되지만 Popup.Window 은 일반적으로 데스크톱 플랫폼에서만 지원됩니다. 또한 메뉴가 native menubar 안에 있는 경우 메뉴도 네이티브가 됩니다. 메뉴가 다른 메뉴 내부의 하위 메뉴인 경우 상위(또는 루트) 메뉴에 따라 유형이 결정됩니다.

기본 메뉴 사용 시 제한 사항

popupType 을 Popup.Native 으로 설정하면 Popup.Item 및 Popup.Window 을 사용할 때와 비교하여 몇 가지 제한 사항과 차이점이 있습니다.

API 차이점

네이티브 메뉴를 사용하는 경우 모든 플랫폼에서 메뉴 API의 하위 집합만 지원됩니다:

• x
• y
• visible
• opened
• title
• count
• contentData
• contentChildren (시각적 자식은 표시되지 않음)
• contentModel
• open()
• popup()
• close()
• opened()
• closed()
• aboutToShow()
• aboutToHide()

또한 open() 또는 popup()와 같은 팝업을 표시하면 일부 플랫폼에서는 차단 호출이 될 수 있습니다. 즉, 메뉴가 다시 닫히기 전에는 호출이 반환되지 않으므로 애플리케이션의 로직에 영향을 줄 수 있습니다. 애플리케이션이 여러 플랫폼을 대상으로 하는 경우, 즉 기본 메뉴가 지원되지 않는 플랫폼에서 실행되는 경우 특히 이 점을 고려해야 합니다. 이 경우 예를 들어 팝업 유형은 Popup.Item 로 돌아가며 open() 호출은 차단되지 않습니다.

예를 들어 MenuItem 같은 항목은 여전히 해당 기본 메뉴 항목의 클릭에 신호를 보내 반응하지만 해당 기본 메뉴 항목으로 대체됩니다.

렌더링 차이점

네이티브 메뉴는 플랫폼에서 사용 가능한 네이티브 메뉴 API를 사용하여 구현됩니다. 따라서 이러한 메뉴와 모든 콘텐츠는 QML이 아닌 플랫폼에 의해 렌더링됩니다. 즉, delegate 은 렌더링에 사용되지 않습니다. 그러나 항상 인스턴스화되지만 숨겨져 있으므로 onCompleted()와 같은 함수는 플랫폼에 관계없이 실행되고 popupType.

지원되는 플랫폼

네이티브 메뉴는 현재 다음 플랫폼에서 지원됩니다:

• Android
• iOS
• Linux(GTK+ 플랫폼 테마로 실행할 때 독립형 컨텍스트 메뉴로만 사용 가능)
• macOS
• Windows

메뉴 사용자 정의, MenuItem, 메뉴 컨트롤, 팝업 컨트롤, 자바스크립트에서 동적 QML 객체 생성, Popup type, [QML] 및 popupType 을참조하세요 .

프로퍼티 문서

Menu {
    id: menu
    contentItem: ListView {
        model: menu.contentModel
    }
}

Menu {
    Action { text: "Cut" }
    Action { text: "Copy" }
    Action { text: "Paste" }
}

메서드 문서