Control QML Type

Tipo base abstracto que proporciona funcionalidad común a todos los controles. Más...

• Lista de todos los miembros, incluidos los heredados

Propiedades

• availableHeight : real
• availableWidth : real
• background : Item
• bottomInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
• bottomPadding : real
• contentItem : Item
• focusReason : enumeration
• font : font
• horizontalPadding : real (since QtQuick.Controls 2.5 (Qt 5.12))
• hoverEnabled : bool
• hovered : bool
• implicitBackgroundHeight : real (since QtQuick.Controls 2.5 (Qt 5.12))
• implicitBackgroundWidth : real (since QtQuick.Controls 2.5 (Qt 5.12))
• implicitContentHeight : real (since QtQuick.Controls 2.5 (Qt 5.12))
• implicitContentWidth : real (since QtQuick.Controls 2.5 (Qt 5.12))
• leftInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
• leftPadding : real
• locale : Locale
• mirrored : bool
• padding : real
• rightInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
• rightPadding : real
• spacing : real
• topInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
• topPadding : real
• verticalPadding : real (since QtQuick.Controls 2.5 (Qt 5.12))
• visualFocus : bool
• wheelEnabled : bool

Descripción detallada

Control es el tipo base de los controles de interfaz de usuario. Recibe eventos de entrada del sistema de ventanas, y pinta una representación de sí mismo en la pantalla.

Disposición del control

El siguiente diagrama ilustra la disposición de un control típico:

Las direcciones implicitWidth y implicitHeight de un control se basan normalmente en los tamaños implícitos del fondo y del elemento de contenido más cualquier inserto y relleno. Estas propiedades determinan el tamaño del control cuando no se especifica explícitamente width o height.

La geometría de contentItem viene determinada por el relleno. El siguiente ejemplo reserva 10px de relleno entre los límites del control y su contenido:

Control {
    padding: 10

    contentItem: Text {
        text: "Content"
    }
}

El elemento background ocupa toda la anchura y altura del control, a menos que se le hayan asignado inserciones o un tamaño explícito. Las inserciones de fondo son útiles para extender el área táctil/interactiva de un control sin afectar a su tamaño visual. Esto se utiliza a menudo en dispositivos táctiles para garantizar que un control no sea demasiado pequeño para que el usuario pueda interactuar con él. Las inserciones afectan al tamaño del control y, por tanto, al espacio que ocupan en un diseño, por ejemplo.

Las inserciones negativas pueden utilizarse para que el fondo sea mayor que el control. El siguiente ejemplo utiliza inserciones negativas para colocar una sombra fuera de los límites del control:

Control {
    topInset: -2
    leftInset: -2
    rightInset: -6
    bottomInset: -6

    background: BorderImage {
        source: ":/images/shadowed-background.png"
    }
}

Manejo de Eventos

Todos los controles, excepto los indicadores no interactivos, no permiten que los clics y toques se transmitan a los elementos situados debajo de ellos. Por ejemplo, la llamada console.log() en el ejemplo de abajo nunca será ejecutada cuando se haga click en el Panel, porque el MouseArea está debajo de él en la escena:

MouseArea {
    anchors.fill: parent
    onClicked: console.log("MouseArea was clicked")

    Pane {
        anchors.fill: parent
    }
}

Los eventos de rueda son consumidos por los controles si wheelEnabled es true.

Ver también ApplicationWindow, Container, y Using Qt Quick Controls types in property declarations.

Documentación de Propiedades

availableHeight : real [read-only]

Esta propiedad mantiene la altura disponible para el contentItem después de deducir el relleno vertical del height del control.

Véase también Control Layout, padding, topPadding, y bottomPadding.

availableWidth : real [read-only]

Esta propiedad mantiene el ancho disponible en contentItem después de deducir el relleno horizontal de width del control.

Véase también Control Layout, padding, leftPadding, y rightPadding.

background : Item

Esta propiedad contiene el elemento de fondo.

Button {
    id: control
    text: qsTr("Button")
    background: Rectangle {
        implicitWidth: 100
        implicitHeight: 40
        opacity: enabled ? 1 : 0.3
        color: control.down ? "#d0d0d0" : "#e0e0e0"
    }
}

Véase también Control Layout.

bottomInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

Esta propiedad contiene la inserción inferior para el fondo.

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

Véase también Control Layout y topInset.

bottomPadding : real

Esta propiedad contiene el relleno inferior. A menos que se establezca explícitamente, el valor es igual a verticalPadding.

Véase también Control Layout, padding, topPadding, verticalPadding, y availableHeight.

contentItem : Item

Esta propiedad contiene el elemento de contenido visual.

Button {
    id: control
    text: qsTr("Button")
    contentItem: Label {
        text: control.text
        verticalAlignment: Text.AlignVCenter
    }
}

Véase también Control Layout y padding.

focusReason : enumeration

Esta propiedad contiene la razón del último cambio de foco.

El valor de esta propiedad es modificado por Qt cada vez que se transfiere el foco, y nunca deberías tener que establecer esta propiedad tú mismo.

Véase también Item::activeFocus y visualFocus.

font : font

Esta propiedad contiene la fuente actualmente establecida para el control.

Esta propiedad describe la fuente solicitada por el control. La fuente es utilizada por el estilo del control cuando renderiza componentes estándar, y está disponible como un medio para asegurar que los controles personalizados puedan mantener la consistencia con la apariencia nativa de la plataforma. Es común que diferentes plataformas, o diferentes estilos, definan diferentes fuentes para una aplicación.

La fuente predeterminada depende del entorno del sistema. ApplicationWindow mantiene una fuente de sistema/tema que sirve como predeterminada para todos los controles. También puede haber fuentes especiales por defecto para ciertos tipos de controles. También puede establecer el tipo de letra por defecto para los controles, ya sea:

• pasando una fuente personalizada a QGuiApplication::setFont(), antes de cargar el QML; o bien
• especificando las fuentes en el archivo qtquickcontrols2.conf.

Finalmente, la fuente se compara con la base de datos de fuentes de Qt para encontrar la más adecuada.

Control propaga las propiedades explícitas de las fuentes de padres a hijos. Si cambia una propiedad específica en la fuente de un control, esa propiedad se propaga a todos los hijos del control, anulando cualquier valor predeterminado del sistema para esa propiedad.

Page {
    font.family: "Courier"

    Column {
        Label {
            text: qsTr("This will use Courier...")
        }

        Switch {
            text: qsTr("... and so will this")
        }
    }
}

Para obtener la lista completa de propiedades de fuente disponibles, consulte la documentación de font QML Value Type.

horizontalPadding : real [since QtQuick.Controls 2.5 (Qt 5.12)]

Esta propiedad contiene el relleno horizontal. A menos que se establezca explícitamente, el valor es igual a padding.

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

Véase también Control Layout, padding, leftPadding, rightPadding, y verticalPadding.

hoverEnabled : bool

Esta propiedad determina si el control acepta eventos hover. El valor por defecto es Application.styleHints.useHoverEffects.

Establecer esta propiedad propaga el valor a todos los controles hijo que no tengan hoverEnabled explícitamente establecido.

También puede activar o desactivar los efectos hover para todas las aplicaciones Qt Quick Controls configurando la variable de entorno QT_QUICK_CONTROLS_HOVER_ENABLED.

Véase también hovered.

hovered : bool [read-only]

Esta propiedad indica si el control está sobrevolado.

Véase también hoverEnabled.

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

Esta propiedad contiene la altura implícita del fondo.

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

Se utiliza normalmente, junto con implicitContentHeight, para calcular la implicitHeight:

Control {
    implicitHeight: Math.max(implicitBackgroundHeight + topInset + bottomInset,
                             implicitContentHeight + topPadding + bottomPadding)
}

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

Véase también implicitBackgroundWidth y implicitContentHeight.

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

Esta propiedad contiene el ancho implícito del fondo.

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

Se utiliza normalmente, junto con implicitContentWidth, para calcular el implicitWidth:

Control {
    implicitWidth: Math.max(implicitBackgroundWidth + leftInset + rightInset,
                            implicitContentWidth + leftPadding + rightPadding)
}

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

Ver también implicitBackgroundHeight y implicitContentWidth.

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

Esta propiedad contiene la altura implícita del contenido.

Para los controles básicos, el valor es igual a contentItem ? contentItem.implicitHeight : 0. Para los tipos que heredan de Container o Pane, el valor se calcula basándose en el contenido hijo.

Normalmente se utiliza, junto con implicitBackgroundHeight, para calcular la altura implicitHeight:

Control {
    implicitHeight: Math.max(implicitBackgroundHeight + topInset + bottomInset,
                             implicitContentHeight + topPadding + bottomPadding)
}

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

Ver también implicitContentWidth y implicitBackgroundHeight.

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

Esta propiedad contiene el ancho implícito del contenido.

Para los controles básicos, el valor es igual a contentItem ? contentItem.implicitWidth : 0. Para los tipos que heredan de Container o Pane, el valor se calcula basándose en el contenido hijo.

Normalmente se utiliza, junto con implicitBackgroundWidth, para calcular el implicitWidth:

Control {
    implicitWidth: Math.max(implicitBackgroundWidth + leftInset + rightInset,
                            implicitContentWidth + leftPadding + rightPadding)
}

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

Ver también implicitContentHeight y implicitBackgroundWidth.

leftInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

Esta propiedad contiene la inserción izquierda para el fondo.

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

Véase también Control Layout y rightInset.

leftPadding : real

Esta propiedad contiene el relleno izquierdo. A menos que se establezca explícitamente, el valor es igual a horizontalPadding.

Véase también Control Layout, padding, rightPadding, horizontalPadding, y availableWidth.

locale : Locale

Esta propiedad contiene la configuración regional del control.

Contiene propiedades específicas de localización para formatear datos y números. A menos que se haya establecido una configuración regional especial, ésta es la configuración regional del padre o la configuración regional por defecto.

El control propaga la configuración regional del padre a los hijos. Si cambia la configuración regional del control, ésta se propagará a todos los controles hijos, anulando la configuración regional por defecto del sistema.

Véase también mirrored.

mirrored : bool [read-only]

Esta propiedad indica si el control está reflejado.

Esta propiedad se proporciona por conveniencia. Un control se considera reflejado cuando la dirección de su diseño visual es de derecha a izquierda; es decir, cuando LayoutMirroring.enabled es true.

A partir de Qt 6.2, la propiedad locale ya no afecta a esta propiedad.

Ver también LayoutMirroring e Interfaces de usuario de derecha a izquierda.

padding : real

Esta propiedad contiene el relleno por defecto.

El relleno añade un espacio entre cada borde del elemento de contenido y el elemento de fondo, controlando eficazmente el tamaño del elemento de contenido. Para especificar un valor de relleno para un borde específico del control, establezca su propiedad correspondiente:

• leftPadding
• rightPadding
• topPadding
• bottomPadding

padding: 0

establezca en su lugar cada propiedad específica:

leftPadding: 0
rightPadding: 0
topPadding: 0
bottomPadding: 0

Véase también Control Layout, availableWidth, availableHeight, topPadding, leftPadding, rightPadding, y bottomPadding.

rightInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

Esta propiedad contiene la inserción derecha para el fondo.

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

Véase también Control Layout y leftInset.

rightPadding : real

Esta propiedad contiene el relleno derecho. A menos que se establezca explícitamente, el valor es igual a horizontalPadding.

Véase también Control Layout, padding, leftPadding, horizontalPadding, y availableWidth.

spacing : real

Esta propiedad contiene el espaciado.

El espaciado es útil para los controles que tienen bloques de construcción múltiples o repetitivos. Por ejemplo, algunos estilos utilizan el espaciado para determinar la distancia entre el texto y el indicador de CheckBox. El espaciado no es impuesto por Control, por lo que cada estilo puede interpretarlo de forma diferente, y algunos pueden ignorarlo por completo.

topInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

Esta propiedad contiene la inserción superior para el fondo.

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

Véase también Control Layout y bottomInset.

topPadding : real

Esta propiedad contiene el relleno superior. A menos que se establezca explícitamente, el valor es igual a verticalPadding.

Véase también Control Layout, padding, bottomPadding, verticalPadding, y availableHeight.

verticalPadding : real [since QtQuick.Controls 2.5 (Qt 5.12)]

Esta propiedad contiene el relleno vertical. A menos que se establezca explícitamente, el valor es igual a padding.

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

Véase también Control Layout, padding, topPadding, bottomPadding, y horizontalPadding.

visualFocus : bool [read-only]

Esta propiedad indica si el control tiene foco visual. Esta propiedad es true cuando el control tiene foco activo y la razón de foco es Qt.TabFocusReason, Qt.BacktabFocusReason, o Qt.ShortcutFocusReason.

En general, para visualizar el foco de tecla, esta propiedad es preferible a Item::activeFocus. Esto asegura que el foco de tecla sólo se visualiza cuando se interactúa con las teclas - no cuando se interactúa a través del tacto o el ratón.

Véase también focusReason y Item::activeFocus.

wheelEnabled : bool

Esta propiedad determina si el control maneja eventos de rueda. El valor por defecto es false.