ComboBox QML Type

Botón combinado y lista emergente para seleccionar opciones. Más...

• Lista de todos los miembros, incluidos los heredados

Propiedades

• acceptableInput : bool (since QtQuick.Controls 2.2 (Qt 5.9))
• count : int
• currentIndex : int
• currentText : string
• currentValue : var (since QtQuick.Controls 2.14 (Qt 5.14))
• delegate : Component
• delegateModel : model
• displayText : string
• down : bool (since QtQuick.Controls 2.2 (Qt 5.9))
• editText : string (since QtQuick.Controls 2.2 (Qt 5.9))
• editable : bool (since QtQuick.Controls 2.2 (Qt 5.9))
• flat : bool (since QtQuick.Controls 2.1 (Qt 5.8))
• highlightedIndex : int
• implicitContentWidthPolicy : enumeration (since QtQuick.Controls 6.0 (Qt 6.0))
• implicitIndicatorHeight : real (since QtQuick.Controls 2.5 (Qt 5.12))
• implicitIndicatorWidth : real (since QtQuick.Controls 2.5 (Qt 5.12))
• indicator : Item
• inputMethodComposing : bool (since QtQuick.Controls 2.2 (Qt 5.9))
• inputMethodHints : flags (since QtQuick.Controls 2.2 (Qt 5.9))
• model : model
• popup : Popup
• pressed : bool
• selectTextByMouse : bool (since QtQuick.Controls 2.15 (Qt 5.15))
• textRole : string
• validator : Validator (since QtQuick.Controls 2.2 (Qt 5.9))
• valueRole : string (since QtQuick.Controls 2.14 (Qt 5.14))

Señales

• void accepted() (since QtQuick.Controls 2.2 (Qt 5.9))
• void activated(int index)
• void highlighted(int index)

Métodos

• void decrementCurrentIndex()
• int find(string text, enumeration flags)
• void incrementCurrentIndex()
• int indexOfValue(object value) (since QtQuick.Controls 2.14 (Qt 5.14))
• void selectAll() (since QtQuick.Controls 2.2 (Qt 5.9))
• string textAt(int index)
• var valueAt(int index) (since QtQuick.Controls 2.14 (Qt 5.14))

Descripción detallada

ComboBox es una combinación de botón y lista emergente. Proporciona un medio para presentar una lista de opciones al usuario de forma que ocupe el mínimo espacio en pantalla.

ComboBox se rellena con un modelo de datos. El modelo de datos suele ser un array JavaScript, un ListModel o un entero, pero también se admiten otros tipos de modelos de datos.

ComboBox {
    model: ["First", "Second", "Third"]
}

ComboBox editable

ComboBox se puede hacer editable. Un cuadro combinado editable autocompleta su texto basándose en lo que está disponible en el modelo.

El siguiente ejemplo demuestra cómo añadir contenido a un cuadro combinado editable reaccionando a la señal accepted.

ComboBox {
    editable: true
    model: ListModel {
        id: model
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    onAccepted: {
        if (find(editText) === -1)
            model.append({text: editText})
    }
}

Ventana emergente de ComboBox

Por defecto, al hacer clic fuera de la ventana emergente de ComboBox se cerrará, y el evento se propagará a los elementos inferiores en el orden de apilamiento. Para evitar que el popup se cierre, configura su closePolicy:

    popup.closePolicy: Popup.CloseOnEscape

Para evitar la propagación del evento, establezca su propiedad modal a true:

    popup.modal: true

Funciones del Modelo ComboBox

ComboBox es capaz de visualizar modelos de datos estándar que proporcionan el rol modelData:

• modelos que sólo tienen un rol
• modelos que no tienen roles con nombre (JavaScript array, integer)

Cuando se utilizan modelos que tienen varios roles con nombre, ComboBox debe configurarse para utilizar un text role específico para sus instancias display text y delegate. Si desea utilizar un rol del elemento del modelo que corresponda al rol de texto, configure valueRole. La propiedad currentValue y el método indexOfValue() pueden utilizarse entonces para obtener información sobre esos valores.

Por ejemplo:

ApplicationWindow {
    width: 640
    height: 480
    visible: true

    // Used as an example of a backend - this would usually be
    // e.g. a C++ type exposed to QML.
    QtObject {
        id: backend
        property int modifier
    }

    ComboBox {
        model: [
            { value: Qt.NoModifier, text: qsTr("No modifier") },
            { value: Qt.ShiftModifier, text: qsTr("Shift") },
            { value: Qt.ControlModifier, text: qsTr("Control") }
        ]
        textRole: "text"
        valueRole: "value"
        // Set currentValue to the value stored in the backend.
        currentValue: backend.modifier
        // When an item is selected, update the backend.
        onActivated: backend.modifier = currentValue
    }
}

Ver también Personalización de ComboBox, Controles de Entrada y Gestión de Foco en Qt Quick Controls.

Documentación de propiedades

acceptableInput : bool [read-only, since QtQuick.Controls 2.2 (Qt 5.9)]

Esta propiedad indica si el cuadro combinado contiene texto aceptable en el campo de texto editable.

Si se ha establecido un validador, el valor es true sólo si el texto actual es aceptable para el validador como cadena final (no como cadena intermedia).

Esta propiedad se introdujo en QtQuick.Controls 2.2 (Qt 5.9).

Véase también validator y accepted.

count : int [read-only]

Esta propiedad contiene el número de elementos del cuadro combinado.

currentIndex : int

Esta propiedad contiene el índice del elemento actual del cuadro combinado.

El valor por defecto es -1 cuando count es 0, y 0 en caso contrario.

Véase también activated(), currentText, y highlightedIndex.

currentText : string [read-only]

Esta propiedad contiene el texto del elemento actual del cuadro combinado.

Véase también currentIndex, displayText, textRole, y editText.

currentValue : var [since QtQuick.Controls 2.14 (Qt 5.14)]

Esta propiedad contiene el valor del elemento actual del cuadro combinado. Al establecer esta propiedad, currentIndex mostrará el elemento con el valor correspondiente o -1 si no se encuentra. Establecer tanto currentIndex como currentValue declarativamente resultará en un comportamiento indefinido. No es posible establecer esta propiedad con un valor que no sea único.

Para ver un ejemplo de cómo utilizar esta propiedad, consulte ComboBox Model Roles.

Esta propiedad se introdujo en QtQuick.Controls 2.14 (Qt 5.14).

Véase también currentIndex, currentText, y valueRole.

delegate : Component

Esta propiedad contiene un delegado que presenta un elemento en la ventana emergente del cuadro combinado.

Se recomienda utilizar ItemDelegate (o cualquier otro derivado de AbstractButton ) como delegado. Esto asegura que la interacción funcione como se espera, y la ventana emergente se cerrará automáticamente cuando sea apropiado. Cuando se utilizan otros tipos como delegado, la ventana emergente debe cerrarse manualmente. Por ejemplo, si se utiliza MouseArea:

delegate: Rectangle {
    // ...
    MouseArea {
        // ...
        onClicked: comboBox.popup.close()
    }
}

Desde Qt 6.11, ComboBox no se apropia del delegado.

Véase también ItemDelegate y Personalización de ComboBox.

delegateModel : model [read-only]

Esta propiedad contiene el modelo que proporciona instancias delegadas para el cuadro combinado.

Normalmente se asigna a un ListView en el contentItem del popup.

Véase también Personalización de ComboBox.

displayText : string

Esta propiedad contiene el texto que se muestra en el botón del cuadro combinado.

Por defecto, el texto mostrado presenta la selección actual. Es decir, sigue al texto del elemento actual. Sin embargo, el texto mostrado por defecto puede ser reemplazado por un valor personalizado.

ComboBox {
    currentIndex: 1
    displayText: "Size: " + currentText
    model: ["S", "M", "L"]
}

Véase también currentText y textRole.

down : bool [since QtQuick.Controls 2.2 (Qt 5.9)]

Esta propiedad indica si el botón del cuadro combinado está visualmente hacia abajo.

A menos que se establezca explícitamente, esta propiedad es true cuando pressed o popup.visible es true. Para volver al valor por defecto, establezca esta propiedad a undefined.

Esta propiedad se introdujo en QtQuick.Controls 2.2 (Qt 5.9).

Véase también pressed y popup.

editText : string [since QtQuick.Controls 2.2 (Qt 5.9)]

Esta propiedad contiene el texto del campo de texto de un cuadro combinado editable.

Esta propiedad se introdujo en QtQuick.Controls 2.2 (Qt 5.9).

Véase también editable, currentText, y displayText.

editable : bool [since QtQuick.Controls 2.2 (Qt 5.9)]

Esta propiedad indica si el cuadro combinado es editable.

El valor por defecto es false.

Esta propiedad se introdujo en QtQuick.Controls 2.2 (Qt 5.9).

Véase también validator.

flat : bool [since QtQuick.Controls 2.1 (Qt 5.8)]

Esta propiedad indica si el botón del cuadro combinado es plano.

Un botón de cuadro combinado plano no dibuja un fondo a menos que se interactúe con él. En comparación con los cuadros combinados normales, los cuadros combinados planos tienen un aspecto que los hace destacar menos del resto de la interfaz de usuario. Por ejemplo, cuando se coloca un cuadro combinado en una barra de herramientas, puede ser deseable hacer que el cuadro combinado sea plano para que combine mejor con el aspecto plano de los botones de herramientas.

El valor por defecto es false.

Esta propiedad se introdujo en QtQuick.Controls 2.1 (Qt 5.8).

highlightedIndex : int [read-only]

Esta propiedad contiene el índice del elemento resaltado en la lista emergente del cuadro combinado.

Cuando se activa un elemento resaltado, la ventana emergente se cierra, currentIndex se establece en highlightedIndex, y el valor de esta propiedad se restablece en -1, puesto que ya no hay ningún elemento resaltado.

Véase también highlighted() y currentIndex.

implicitContentWidthPolicy : enumeration [since QtQuick.Controls 6.0 (Qt 6.0)]

Esta propiedad controla cómo se calcula la implicitContentWidth de ComboBox.

Cuando la anchura de ComboBox no es suficiente para mostrar el texto, éste se omite. Dependiendo de qué partes del texto se elidan, esto puede dificultar la selección de un elemento para el usuario final. Una forma eficaz de asegurarse de que ComboBox es lo suficientemente ancha para evitar que el texto se omita es establecer una anchura que se sepa que es lo suficientemente grande:

width: 300
implicitContentWidthPolicy: ComboBox.ContentItemImplicitWidth

Sin embargo, a menudo no es posible saber si un valor codificado será o no lo suficientemente grande, ya que el tamaño del texto depende de muchos factores, como la familia de fuentes, el tamaño de la fuente, las traducciones, etc.

implicitContentWidthPolicy proporciona una forma sencilla de controlar cómo se calcula el implicitContentWidth, lo que a su vez afecta a implicitWidth de ComboBox y garantiza que el texto no se elidirá.

Los valores disponibles son

El valor por defecto es ContentItemImplicitWidth.

Como esta propiedad sólo afecta al implicitWidth del ComboBox, establecer un width explícito todavía puede dar lugar a eliding.

Esta propiedad se introdujo en QtQuick.Controls 6.0 (Qt 6.0).

implicitIndicatorHeight : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

Esta propiedad contiene la altura del indicador implícito.

El valor es igual a indicator ? indicator.implicitHeight : 0.

Se utiliza normalmente, junto con implicitContentHeight y implicitBackgroundHeight, para calcular el implicitHeight.

Esta propiedad se introdujo en QtQuick.Controls 2.5 (Qt 5.12).

Véase también implicitIndicatorWidth.

implicitIndicatorWidth : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

Esta propiedad contiene el ancho implícito del indicador.

El valor es igual a indicator ? indicator.implicitWidth : 0.

Se utiliza normalmente, junto con implicitContentWidth y implicitBackgroundWidth, para calcular el implicitWidth.

Esta propiedad se introdujo en QtQuick.Controls 2.5 (Qt 5.12).

Véase también implicitIndicatorHeight.

indicator : Item

Esta propiedad contiene el elemento indicador de caída.

Véase también Personalizar ComboBox.

inputMethodComposing : bool [read-only, since QtQuick.Controls 2.2 (Qt 5.9)]

Esta propiedad indica si un cuadro combinado editable tiene texto parcial introducido por un método de entrada.

Mientras se está componiendo, un método de entrada puede depender de eventos de ratón o tecla del cuadro combinado para editar o confirmar el texto parcial. Esta propiedad puede utilizarse para determinar cuándo desactivar los manejadores de eventos que puedan interferir con el correcto funcionamiento de un método de entrada.

Esta propiedad se introdujo en QtQuick.Controls 2.2 (Qt 5.9).

inputMethodHints : flags [since QtQuick.Controls 2.2 (Qt 5.9)]

Proporciona sugerencias al método de entrada sobre el contenido esperado del cuadro combinado y cómo debe funcionar.

El valor por defecto es Qt.ImhNoPredictiveText.

El valor es una combinación de bits de los indicadores o Qt.ImhNone si no hay ningún indicador.

Los indicadores que alteran el comportamiento son:

• Qt.ImhHiddenText - Los caracteres deben estar ocultos, como se suele utilizar al introducir contraseñas.
• Qt.ImhSensitiveData - El texto tecleado no debe ser almacenado por el método de entrada activo en ningún almacenamiento persistente como el diccionario predictivo del usuario.
• Qt.ImhNoAutoUppercase - El método de entrada no debería intentar cambiar automáticamente a mayúsculas cuando termina una frase.
• Qt.ImhPreferNumbers - Se prefieren los números (pero no son obligatorios).
• Qt.ImhPreferUppercase - Se prefieren las mayúsculas (pero no son obligatorias).
• Qt.ImhPreferLowercase - Se prefieren las minúsculas (pero no son obligatorias).
• Qt.ImhNoPredictiveText - No utilizar texto predictivo (es decir, búsqueda en diccionario) mientras se escribe.
• Qt.ImhDate - El editor de texto funciona como un campo de fecha.
• Qt.ImhTime - El editor de texto funciona como un campo de tiempo.

Las banderas que restringen la entrada (banderas exclusivas) son:

• Qt.ImhDigitsOnly - Sólo se permiten dígitos.
• Qt.ImhFormattedNumbersOnly - Sólo se permite la entrada de números. Esto incluye el punto decimal y el signo menos.
• Qt.ImhUppercaseOnly - Sólo se permite la introducción de letras mayúsculas.
• Qt.ImhLowercaseOnly - Sólo se permite la entrada de letras minúsculas.
• Qt.ImhDialableCharactersOnly - Sólo se permiten caracteres adecuados para la marcación telefónica.
• Qt.ImhEmailCharactersOnly - Sólo se permiten caracteres adecuados para direcciones de correo electrónico.
• Qt.ImhUrlCharactersOnly - Sólo se permiten caracteres adecuados para URLs.

Máscaras:

• Qt.ImhExclusiveInputMask - Esta máscara devuelve un valor distinto de cero si se utiliza alguno de los indicadores exclusivos.

Esta propiedad se introdujo en QtQuick.Controls 2.2 (Qt 5.9).

model : model

Esta propiedad contiene el modelo que proporciona los datos para el cuadro combinado.

ComboBox {
    textRole: "key"
    model: ListModel {
        ListElement { key: "First"; value: 123 }
        ListElement { key: "Second"; value: 456 }
        ListElement { key: "Third"; value: 789 }
    }
}

Véase también textRole y Modelos de datos.

popup : Popup

Esta propiedad contiene la ventana emergente.

La ventana emergente puede abrirse o cerrarse manualmente, si es necesario:

onSpecialEvent: comboBox.popup.close()

Véase también Personalizar ComboBox.

pressed : bool [read-only]

Esta propiedad indica si el botón del cuadro combinado está pulsado físicamente. Un botón puede ser presionado por eventos táctiles o de teclado.

Véase también down.

selectTextByMouse : bool [since QtQuick.Controls 2.15 (Qt 5.15)]

Esta propiedad mantiene si el campo de texto de un ComboBox editable puede ser seleccionado con el ratón.

El valor por defecto es false.

Esta propiedad se introdujo en QtQuick.Controls 2.15 (Qt 5.15).

textRole : string

Esta propiedad contiene el rol del modelo utilizado para rellenar el cuadro combinado.

Cuando el modelo tiene múltiples roles, textRole puede establecerse para determinar qué rol debe mostrarse.

Véase también model, currentText, displayText, y ComboBox Model Roles.

validator : Validator [since QtQuick.Controls 2.2 (Qt 5.9)]

Esta propiedad contiene un validador de texto de entrada para un cuadro combinado editable.

Cuando se establece un validador, el campo de texto sólo aceptará entradas que dejen la propiedad text en un estado intermedio. La señal accepted sólo se emitirá si el texto está en un estado aceptable cuando se pulse la tecla Return o Enter.

Los validadores actualmente soportados son IntValidator, DoubleValidator, y RegularExpressionValidator. A continuación se muestra un ejemplo de uso de validadores, que permite la introducción de enteros entre 0 y 10 en el campo de texto:

ComboBox {
    model: 10
    editable: true
    validator: IntValidator {
        top: 9
        bottom: 0
    }
}

Esta propiedad se introdujo en QtQuick.Controls 2.2 (Qt 5.9).

Véase también acceptableInput, accepted, y editable.

valueRole : string [since QtQuick.Controls 2.14 (Qt 5.14)]

Esta propiedad contiene el rol del modelo utilizado para almacenar el valor asociado a cada elemento del modelo.

Para ver un ejemplo de cómo utilizar esta propiedad, consulte ComboBox Model Roles.

Esta propiedad se introdujo en QtQuick.Controls 2.14 (Qt 5.14).

Ver también model y currentValue.

Documentación de Señales

[since QtQuick.Controls 2.2 (Qt 5.9)] void accepted()

Esta señal se emite cuando se pulsa la tecla Return o Enter en un cuadro combinado editable.

Puede manejar esta señal para, por ejemplo, añadir al modelo el elemento recién introducido:

ComboBox {
    editable: true
    model: ListModel {
        id: model
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    onAccepted: {
        if (find(editText) === -1)
            model.append({text: editText})
    }
}

Antes de que se emita la señal, se comprueba si la cadena existe en el modelo. En caso afirmativo, se asigna a currentIndex su índice y a currentText la propia cadena.

Después de que se haya emitido la señal, y si la primera comprobación ha fallado (es decir, el elemento no existía), se realizará otra comprobación para ver si el elemento fue añadido por el controlador de la señal. En caso afirmativo, currentIndex y currentText se actualizan en consecuencia. En caso contrario, se establecerán en -1 y "", respectivamente.

Esta señal se introdujo en QtQuick.Controls 2.2 (Qt 5.9).

void activated(int index)

Esta señal se emite cuando el elemento en index es activado por el usuario.

Un elemento se activa cuando se selecciona mientras la ventana emergente está abierta, provocando el cierre de la ventana emergente (y el cambio de currentIndex ), o mientras la ventana emergente está cerrada y se navega por el cuadro combinado mediante el teclado, provocando el cambio de currentIndex. La propiedad currentIndex se establece en index.

Véase también currentIndex.

void highlighted(int index)

Esta señal se emite cuando el usuario resalta el elemento en index en la lista emergente.

La señal de resaltado sólo se emite cuando la ventana emergente está abierta y un elemento está resaltado, pero no necesariamente activated.

Véase también highlightedIndex.

Documentación del método

void decrementCurrentIndex()

Disminuye el índice actual del cuadro combinado, o el índice resaltado si la lista emergente está visible.

Véase también currentIndex y highlightedIndex.

int find(string text, enumeration flags)

Devuelve el índice del text especificado , o -1 si no se encuentra ninguna coincidencia.

La forma en que se realiza la búsqueda viene definida por la coincidencia especificada flags. Por defecto, el cuadro combinado distingue entre mayúsculas y minúsculas (Qt.MatchExactly). Los demás tipos de coincidencia no distinguen entre mayúsculas y minúsculas a menos que también se especifique el indicador Qt.MatchCaseSensitive.

Por ejemplo:

ComboBox {
    model: ListModel {
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    Component.onCompleted: currentIndex = find("Coconut")
}

Véase también textRole.

void incrementCurrentIndex()

Incrementa el índice actual del cuadro combinado, o el índice resaltado si la lista emergente está visible.

Véase también currentIndex y highlightedIndex.

[since QtQuick.Controls 2.14 (Qt 5.14)] int indexOfValue(object value)

Devuelve el índice del value especificado, o -1 si no se encuentra ninguna coincidencia.

Para ver un ejemplo de cómo utilizar este método, consulte ComboBox Model Roles.

Este método se introdujo en QtQuick.Controls 2.14 (Qt 5.14).

Véase también find(), currentValue, currentIndex, valueRole, y valueAt.

[since QtQuick.Controls 2.2 (Qt 5.9)] void selectAll()

Selecciona todo el texto del campo de texto editable del cuadro combinado.

Este método se introdujo en QtQuick.Controls 2.2 (Qt 5.9).

Véase también editText.

string textAt(int index)

Devuelve el texto para el index especificado , o una cadena vacía si el índice está fuera de los límites.

Por ejemplo:

ComboBox {
    model: ListModel {
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    onActivated: (index) => { print(textAt(index)) }
}

Véase también textRole.

[since QtQuick.Controls 2.14 (Qt 5.14)] var valueAt(int index)

Devuelve el valor en la posición index del cuadro combinado.

Este método se introdujo en QtQuick.Controls 2.14 (Qt 5.14).

Véase también indexOfValue.