Menu QML Type

Menú emergente que puede utilizarse como menú contextual o menú emergente. Más...

• Lista de todos los miembros, incluidos los heredados

Propiedades

• 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 (since QtQuick.Controls 6.5)
  • icon.cache : bool (since QtQuick.Controls 6.5)
  • icon.color : color (since QtQuick.Controls 6.5)
  • icon.height : int (since QtQuick.Controls 6.5)
  • icon.name : string (since QtQuick.Controls 6.5)
  • icon.source : url (since QtQuick.Controls 6.5)
  • icon.width : int (since QtQuick.Controls 6.5)
• overlap : real (since QtQuick.Controls 2.3 (Qt 5.10))
• title : string

Métodos

• 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))

Descripción detallada

El menú tiene dos usos principales:

• Menús contextuales; por ejemplo, un menú que se muestra después de hacer clic con el botón derecho del ratón.
• Menús emergentes; por ejemplo, un menú que se muestra tras hacer clic en un botón.

Para los menús contextuales, consulte Context Menus.

Cuando se utiliza como menú emergente, lo más sencillo es especificar la posición indicando las coordenadas x y y deseadas mediante las propiedades respectivas, y llamar a open() para abrir el menú.

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

    Menu {
        id: menu
        y: fileButton.height

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

Si el botón también debe cerrar el menú al pulsarlo, utilice la bandera Popup.CloseOnPressOutsideParent:

    onClicked: menu.visible = !menu.visible

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

Puede crear submenús y declarar objetos Action dentro de Menu:

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" }
    }
}

Los submenús son cascading por defecto en plataformas de escritorio que tienen un cursor de ratón disponible. Los menús no en cascada se muestran de uno en uno y centrados sobre el menú principal.

Normalmente, los elementos de menú se declaran estáticamente como hijos del menú, pero Menu también proporciona API para add, insert, move y remove elementos dinámicamente. Se puede acceder a los elementos de un menú mediante itemAt() o contentChildren.

Aunque MenuItems es el más utilizado con Menu, puede contener cualquier tipo de elemento.

Menús contextuales

Para los menús contextuales, es más fácil utilizar el tipo adjunto ContextMenu, que crea un menú ante un evento específico de la plataforma. Además, los controles de edición de texto como TextField, TextArea, SpinBox y DoubleSpinBox proporcionan sus propios menús contextuales por defecto.

Si no se utiliza ContextMenu, la forma recomendada de abrir el menú es llamar a popup(). A menos que se especifique explícitamente una posición, el menú se posiciona en el cursor del ratón en las plataformas de escritorio que tienen un cursor de ratón disponible, y de lo contrario se centra sobre su elemento padre:

    TapHandler {
        acceptedButtons: Qt.RightButton
        onPressedChanged: {
            if (pressed && Application.styleHints.contextMenuTrigger === Qt.ContextMenuTrigger.Press)
                contextMenu.popup()
        }
        onTapped: {
            if (Application.styleHints.contextMenuTrigger === Qt.ContextMenuTrigger.Release)
                contextMenu.popup()
        }
    }
    TapHandler {
        acceptedDevices: PointerDevice.TouchScreen
        onLongPressed: contextMenu.popup()
    }

    Menu {
        id: contextMenu

        MenuItem {
            text: qsTr("Do stuff")
        }
        MenuItem {
            text: qsTr("Do more stuff")
        }
    }

Ten en cuenta que si estás implementando tu propio menú contextual para los controles de edición de texto, sólo necesitas mostrarlo en las plataformas de escritorio, ya que iOS y Android tienen sus propios menús contextuales nativos:

    TextArea {
        text: qsTr("TextArea")

        // Disable the built-in context menu (since Qt 6.9).
        ContextMenu.menu: null

        TapHandler {
            acceptedButtons: Qt.RightButton
            onPressedChanged: {
                if (pressed === (Application.styleHints.contextMenuTrigger === Qt.ContextMenuTrigger.Press))
                    contextMenu.popup()
            }
        }
    }

    Menu {
        id: contextMenu

        MenuItem {
            text: qsTr("Cut")
            // ...
        }
        MenuItem {
            text: qsTr("Copy")
            // ...
        }
        MenuItem {
            text: qsTr("Paste")
            // ...
        }
    }

Márgenes

Al heredar de Popup, Menu admite margins. Por defecto, todos los estilos incorporados especifican 0 para los márgenes de Menu con el fin de garantizar que el menú se mantenga dentro de los límites de la ventana. Para permitir que un menú salga fuera de la ventana (por ejemplo, para animarlo moviéndose hacia la vista), establezca la propiedad margins en -1.

Generación dinámica de elementos de menú

Puede crear dinámicamente elementos de menú con Instantiator o con la creación dinámica de objetos.

Uso del instanciador

Puede generar dinámicamente elementos de menú con Instantiator. El siguiente código muestra cómo puede implementar un submenú "Archivos recientes", donde los elementos provienen de una lista de archivos almacenados en la configuración:

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()
        }
    }
}

Uso de la creación dinámica de objetos

También puede cargar dinámicamente un componente desde un archivo QML utilizando Qt.createComponent(). Una vez que el componente esté listo, puede llamar a su método createObject() para crear una instancia de ese componente.

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)
            }
        }
    }
}

Tipos de menú

Desde Qt 6.8, un menú ofrece tres implementaciones diferentes, dependiendo de la plataforma. Puedes elegir cuál es la preferida configurando popupType. Esto te permitirá controlar si un menú debe mostrarse como una ventana separada, como un elemento dentro de la ventana padre, o como un menú nativo. Puedes leer más sobre estas opciones en here.

El valor predeterminado de popupType lo decide el estilo. El Estilo macOS, por ejemplo, lo establece en Popup.Native, mientras que el Estilo Imagine utiliza Popup.Window (que es el predeterminado cuando el estilo no establece un tipo de ventana emergente). Si añades personalizaciones a un menú y quieres que se utilicen independientemente del estilo, debes establecer explícitamente que el tipo de ventana emergente sea Popup.Window (o Popup.Item). Otra alternativa es configurar Qt::AA_DontUseNativeMenuWindows application attribute . Esto desactivará los menús contextuales nativos para toda la aplicación, independientemente del estilo.

Que un menú pueda utilizar el tipo preferido depende de la plataforma. Popup.Item es compatible con todas las plataformas, pero Popup.Window normalmente sólo es compatible con las plataformas de escritorio. Además, si el menú está dentro de un native menubar, el menú también será nativo. Y si el menú es un submenú dentro de otro menú, el menú padre (o raíz) decidirá el tipo.

Limitaciones al utilizar menús nativos

Al configurar popupType en Popup.Native existen algunas limitaciones y diferencias en comparación con el uso de Popup.Item y Popup.Window.

Diferencias de la API

Al utilizar menús nativos, sólo se admite un subconjunto de la API de menús en todas las plataformas:

• x
• y
• visible
• opened
• title
• count
• contentData
• contentChildren (los hijos visuales no serán visibles)
• contentModel
• open()
• popup()
• close()
• opened()
• closed()
• aboutToShow()
• aboutToHide()

Además, mostrar una ventana emergente (utilizando, por ejemplo, open() o popup()) será una llamada de bloqueo en algunas plataformas. Esto significa que la llamada no volverá antes de que el menú se cierre de nuevo, lo que puede afectar a la lógica de tu aplicación. Esto es especialmente importante a tener en cuenta si tu aplicación se dirige a múltiples plataformas, y como tal, a veces se ejecuta en plataformas donde los menús nativos no están soportados. En ese caso, el popupType volverá a Popup.Item, por ejemplo, y las llamadas a open() no se bloquearán.

Los elementos como MenuItem seguirán reaccionando a los clics en el elemento de menú nativo correspondiente emitiendo señales, por ejemplo, pero serán sustituidos por su homólogo nativo.

Diferencias de renderizado

Los menús nativos se implementan utilizando las API de menús nativos disponibles en la plataforma. Por lo tanto, esos menús y todo su contenido serán renderizados por la plataforma, y no por QML. Esto significa que no se utilizará delegate para el renderizado. Sin embargo, siempre estará instanciado (pero oculto), de modo que funciones como onCompleted() se ejecuten independientemente de la plataforma y de popupType.

Plataformas compatibles

Los menús nativos son compatibles actualmente con las siguientes plataformas:

• Android
• iOS
• Linux (sólo disponible como menú contextual independiente cuando se ejecuta con el tema de plataforma GTK+)
• macOS
• Windows

Véase también Personalización del menú, MenuItem, Controles de menú, Controles emergentes, Creación dinámica de objetos QML a partir de JavaScript, Popup type, [QML] y popupType.

Documentación de propiedades

cascade : bool [since QtQuick.Controls 2.3 (Qt 5.10)]

Esta propiedad indica si el menú muestra en cascada sus submenús.

El valor por defecto es específico de cada plataforma. Los menús están en cascada por defecto en las plataformas de escritorio que tienen un cursor de ratón disponible. Los menús no en cascada se muestran de uno en uno y centrados sobre el menú padre.

Esta propiedad se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

Véase también overlap.

contentData : list<QtObject> [default]

Esta propiedad contiene la lista de datos de contenido.

La lista contiene todos los objetos que se han declarado en QML como hijos del menú, y también los elementos que se han añadido o insertado dinámicamente mediante los métodos addItem() y insertItem(), respectivamente.

Véase también Item::data y contentChildren.

contentModel : model [read-only]

Esta propiedad contiene el modelo utilizado para mostrar los elementos del menú.

El modelo de contenido se proporciona con fines de visualización. Puede asignarse como modelo a un elemento de contenido que presente el contenido del menú.

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

El modelo permite que los elementos de menú se declaren estáticamente como hijos del menú.

count : int [read-only, since QtQuick.Controls 2.3 (Qt 5.10)]

Esta propiedad contiene el número de elementos.

Esta propiedad se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

currentIndex : int [since QtQuick.Controls 2.3 (Qt 5.10)]

Esta propiedad contiene el índice del elemento resaltado actualmente.

Los elementos del menú pueden resaltarse al pasar el ratón por encima o al navegar con el teclado.

Esta propiedad se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

Ver también MenuItem::highlighted.

delegate : Component [since QtQuick.Controls 2.3 (Qt 5.10)]

Esta propiedad contiene el componente que se utiliza para crear elementos para presentar acciones.

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

Menu no se apropia del delegado.

Esta propiedad se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

Véase también Action.

focus : bool

Esta propiedad indica si la ventana emergente desea ser enfocada.

Cuando la ventana emergente recibe realmente el foco, activeFocus será true. Para más información, consulte Enfoque de teclado en Qt Quick.

El valor por defecto es true.

Véase también activeFocus.

icon group

Estas propiedades fueron introducidas en QtQuick.Controls 6.5.

Ver también AbstractButton::text, AbstractButton::display, e Iconos en Qt Quick Controls.

overlap : real [since QtQuick.Controls 2.3 (Qt 5.10)]

Esta propiedad contiene la cantidad de píxeles en los que el menú se solapa horizontalmente con su menú padre.

Esta propiedad sólo tiene efecto cuando el menú se utiliza como submenú en cascada.

El valor por defecto es específico del estilo.

Esta propiedad se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

Véase también cascade.

title : string

Esta propiedad contiene el título del menú.

El título de un menú se muestra a menudo en el texto de un elemento de menú cuando el menú es un submenú, y en el texto de un botón de herramienta cuando está en una barra de menús.

Documentación del método

[since QtQuick.Controls 2.3 (Qt 5.10)] Action actionAt(int index)

Devuelve la acción en index, o null si el índice no es válido o no hay acción en el índice especificado.

Este método se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

[since QtQuick.Controls 2.3 (Qt 5.10)] void addAction(Action action)

Añade action al final de este menú. El menú no se apropia del nuevo action añadido.

Este método se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

void addItem(Item item)

Añade item al final de la lista de elementos. El menú no se apropia del nuevo elemento item.

Véase también Dynamically Generating Menu Items.

[since QtQuick.Controls 2.3 (Qt 5.10)] void addMenu(Menu menu)

Añade menu como submenú al final de este menú. El menú no toma posesión del recién añadido menu.

Este método se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

[since QtQuick.Controls 2.3 (Qt 5.10)] void dismiss()

Cierra todos los menús de la jerarquía a la que pertenece este menú.

Este método se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

Ver también popup() y Popup::close().

[since QtQuick.Controls 2.3 (Qt 5.10)] void insertAction(int index, Action action)

Inserta action en index. El índice se encuentra dentro de todos los elementos del menú. El menú no se apropia del recién insertado action.

Este método se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

void insertItem(int index, Item item)

Inserta item en index. El menú no se apropia de lo recién insertado item.

Véase también Dynamically Generating Menu Items.

[since QtQuick.Controls 2.3 (Qt 5.10)] void insertMenu(int index, Menu menu)

Inserta menu como submenú en index. El índice se encuentra dentro de todos los elementos del menú. El menú no se apropia del recién insertado menu.

Este método se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

Item itemAt(int index)

Devuelve el elemento en index, o null si no existe.

[since QtQuick.Controls 2.3 (Qt 5.10)] Menu menuAt(int index)

Devuelve el submenú en index, o null si el índice no es válido o no hay submenú en el índice especificado.

Este método se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

void moveItem(int from, int to)

Mueve un elemento from un índice to otro.

Abre el menú en el cursor del ratón en plataformas de escritorio que dispongan de cursor de ratón y, en caso contrario, centra el menú sobre su elemento parent.

El menú puede alinearse opcionalmente con un elemento item. Este elemento se convertirá entonces en current.. Si no se especifica item, currentIndex se establecerá en -1.

Estos métodos se introdujeron en QtQuick.Controls 2.3 (Qt 5.10).

Véase también Popup::open().

Abre el menú en la posición especificada pos en el sistema de coordenadas de las ventanas emergentes, es decir, una coordenada relativa a su elemento parent.

Opcionalmente, el menú puede alinearse con un elemento específico item. Este elemento se convertirá entonces en current. Si no se especifica item, currentIndex se establecerá en -1.

Estos métodos se introdujeron en QtQuick.Controls 2.3 (Qt 5.10).

Véase también Popup::open().

Abre el menú en la posición especificada x, y en el sistema de coordenadas de las ventanas emergentes, es decir, una coordenada relativa a su elemento parent.

El menú puede alinearse opcionalmente con un elemento item. Este elemento se convertirá entonces en current. Si no se especifica item, currentIndex se establecerá en -1.

Estos métodos se introdujeron en QtQuick.Controls 2.3 (Qt 5.10).

Véase también dismiss() y Popup::open().

[since QtQuick.Controls 2.3 (Qt 5.10)] void removeAction(Action action)

Elimina y destruye el action especificado.

Este método se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

[since QtQuick.Controls 2.3 (Qt 5.10)] void removeItem(Item item)

Elimina y destruye el item especificado.

Este método se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

[since QtQuick.Controls 2.3 (Qt 5.10)] void removeMenu(Menu menu)

Elimina y destruye el menu especificado.

Este método se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

[since QtQuick.Controls 2.3 (Qt 5.10)] Action takeAction(int index)

Elimina y devuelve la acción en index. El índice se encuentra dentro de todos los elementos del menú.

Este método se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

[since QtQuick.Controls 2.3 (Qt 5.10)] MenuItem takeItem(int index)

Elimina y devuelve el elemento en index.

Este método se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

[since QtQuick.Controls 2.3 (Qt 5.10)] Menu takeMenu(int index)

Elimina y devuelve el menú en index. El índice se encuentra dentro de todos los elementos del menú.

Este método se introdujo en QtQuick.Controls 2.3 (Qt 5.10).