Control QML Type
Tipo base abstracto que proporciona funcionalidades comunes a todos los controles. Más...
| Import Statement: | import QtQuick.Controls |
| Inherits: | |
| Inherited By: | 52 typesAbstractButton, BusyIndicator, Button, CheckBox, CheckDelegate, ComboBox, Container, DayOfWeekRow, DelayButton, Dial, DialogButtonBox, DoubleSpinBox, Frame, GroupBox, HorizontalHeaderViewDelegate, ItemDelegate, MenuBar, MenuBarItem, MenuItem, MenuSeparator, MonthGrid, Page, PageIndicator, Pane, ProgressBar, RadioButton, RadioDelegate, RangeSlider, RoundButton, ScrollBar, ScrollIndicator, ScrollView, SearchField, SelectionRectangle, Slider, SpinBox, SplitView, StackView, SwipeDelegate, SwipeView, Switch, SwitchDelegate, TabBar, TabButton, TableViewDelegate, ToolBar, ToolButton, ToolSeparator, TreeViewDelegate, Tumbler, VerticalHeaderViewDelegate, and WeekNumberColumn |
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
El control es el tipo básico de los controles de la interfaz de usuario. Recibe eventos de entrada del sistema de ventanas y dibuja una representación de sí mismo en la pantalla.
Diseño del control
El siguiente diagrama ilustra la disposición de un control típico:

El « implicitWidth » y el « implicitHeight » de un control suelen basarse en los tamaños implícitos del fondo y del elemento de contenido, más cualquier «insets» y «paddings». Estas propiedades determinan el tamaño que tendrá el control cuando no se especifiquen explícitamente « width » o « height ».
La geometría del elemento contentItem viene determinada por el relleno. El siguiente ejemplo reserva un relleno de 10 píxeles entre los límites del control y su contenido:
El elemento « background » ocupa todo el ancho y la altura del control, a menos que se le hayan asignado márgenes interiores o un tamaño explícito. Los márgenes de fondo son útiles para ampliar el área táctil o 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 como para que el usuario pueda interactuar con él. Los márgenes afectan al tamaño del control y, por lo tanto, influirán, por ejemplo, en el espacio que ocupan en un diseño.
Se pueden utilizar márgenes negativos para que el fondo sea más grande que el control. El siguiente ejemplo utiliza márgenes negativos 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"
}
}Gestión de eventos
Todos los controles, excepto los indicadores no interactivos, impiden que los clics y los toques lleguen a los elementos situados debajo de ellos. Por ejemplo, la llamada console.log() del ejemplo siguiente nunca se ejecutará al hacer clic en el Pane, ya que el MouseArea se encuentra debajo de él en la escena:
MouseArea {
anchors.fill: parent
onClicked: console.log("MouseArea was clicked")
Pane {
anchors.fill: parent
}
}Los controles consumen los eventos de la rueda si ` wheelEnabled ` es ` true`.
Véase también ApplicationWindow, Container y Using Qt Quick Controls types in property declarations.
Documentación de propiedades
availableHeight : real [read-only]
Esta propiedad contiene la altura disponible para el elemento « contentItem » tras restar el relleno vertical del elemento « height » del control.
Véase también Control Layout, padding, topPadding y bottomPadding.
availableWidth : real [read-only]
Esta propiedad contiene el ancho disponible para el elemento « contentItem » tras restar el relleno horizontal del elemento « 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"
}
}Nota: Si no se ha especificado un tamaño explícito para el elemento de fondo, este adopta automáticamente el tamaño del control. En la mayoría de los casos, no es necesario especificar el ancho ni la altura de un elemento de fondo.
Nota: La mayoría de los controles utilizan el tamaño implícito del elemento de fondo para calcular el tamaño implícito del propio control. Si sustituyes el elemento de fondo por uno personalizado, también debes considerar la posibilidad de proporcionarle un tamaño implícito adecuado (a menos que se trate de un elemento como Image, que tiene su propio tamaño implícito).
Véase también Control Layout.
bottomInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]
Esta propiedad define el margen inferior del 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 define el relleno inferior. A menos que se especifique 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
}
}Nota: El elemento de contenido se coloca y se redimensiona automáticamente para ajustarse al área de contenido ( padding ) del control. No se respetan los enlaces a las propiedades x, y, width y height del elemento de contenido.
Nota: La mayoría de los controles utilizan el tamaño implícito del elemento de contenido para calcular el tamaño implícito del propio control. Si sustituyes el elemento de contenido por uno personalizado, también debes considerar la posibilidad de proporcionarle un tamaño implícito adecuado (a menos que se trate de un elemento como Text, que tiene su propio tamaño implícito).
Véase también Control Layout y padding.
focusReason : enumeration
Esta propiedad contiene el motivo del último cambio de foco.
Qt modifica el valor de esta propiedad cada vez que se transfiere el foco, por lo que nunca deberías tener que establecerla tú mismo.
Nota: Esta propiedad no indica si el elemento tiene un « active focus », sino el motivo por el que el elemento ha ganado o perdido el foco.
| Constante | Descripción |
|---|---|
Qt.MouseFocusReason | Se ha producido una acción del ratón. |
Qt.TabFocusReason | Se ha pulsado la tecla Tab. |
Qt.BacktabFocusReason | Se ha producido un «Backtab». La entrada para esto puede incluir las teclas Mayús o Control; p. ej., Mayús+Tab. |
Qt.ActiveWindowFocusReason | El sistema de ventanas ha activado o desactivado esta ventana. |
Qt.PopupFocusReason | La aplicación ha abierto o cerrado una ventana emergente que ha capturado o liberado el foco del teclado. |
Qt.ShortcutFocusReason | El usuario ha escrito el atajo asociado a una etiqueta |
Qt.MenuBarFocusReason | La barra de menús ha obtenido el foco. |
Qt.OtherFocusReason | Otra razón, normalmente específica de la aplicación. |
Véase también Item::activeFocus y visualFocus.
font : font
Esta propiedad contiene la fuente configurada actualmente para el control.
Esta propiedad describe la fuente solicitada por el control. El estilo del control utiliza esta fuente al representar componentes estándar, y está disponible para garantizar que los controles personalizados mantengan la coherencia con la apariencia nativa de la plataforma. Es habitual que diferentes plataformas, o diferentes estilos, definan fuentes distintas para una aplicación.
La fuente predeterminada depende del entorno del sistema. ApplicationWindow mantiene una fuente del sistema o del tema que sirve como predeterminada para todos los controles. También puede haber fuentes predeterminadas especiales para determinados tipos de controles. Asimismo, puedes establecer la fuente predeterminada para los controles de una de estas formas:
- pasando una fuente personalizada a ` QGuiApplication::setFont()` antes de cargar el QML; o
- especificando las fuentes en el archivo qtquickcontrols2.conf.
Por último, la fuente se compara con la base de datos de fuentes de Qt para encontrar la que mejor se ajuste.
El control propaga las propiedades de fuente explícitas del control padre a los hijos. Si se modifica una propiedad específica de la fuente de un control, dicha propiedad se propaga a todos los controles hijos, 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 consultar la lista completa de propiedades de fuente disponibles, consulta la documentación de « font QML Value Type ».
horizontalPadding : real [since QtQuick.Controls 2.5 (Qt 5.12)]
Esta propiedad define el relleno horizontal. A menos que se especifique 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 de paso del cursor. El valor por defecto es « Application.styleHints.useHoverEffects ».
Al establecer esta propiedad, el valor se propaga a todos los controles secundarios que no tengan « hoverEnabled » establecido explícitamente.
También puede activar o desactivar los efectos al pasar el cursor por todas las aplicaciones de 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 cursor se encuentra sobre el control.
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.
Normalmente se utiliza, 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 define el ancho implícito del fondo.
El valor es igual a background ? background.implicitWidth : 0.
Normalmente se utiliza, junto con ` implicitContentWidth`, para calcular la ` implicitWidth`:
Control {
implicitWidth: Math.max(implicitBackgroundWidth + leftInset + rightInset,
implicitContentWidth + leftPadding + rightPadding)
}Esta propiedad se introdujo en QtQuick.Controls 2.5 (Qt 5.12).
Véanse 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.
En el caso de 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 en función de los elementos hijos del contenido.
Normalmente se utiliza, junto con ` implicitBackgroundHeight`, para calcular el ` 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 « implicitContentWidth » y « implicitBackgroundHeight ».
implicitContentWidth : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]
Esta propiedad contiene el ancho implícito del contenido.
En el caso de 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 en función de los elementos hijos del contenido.
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).
Véase también « implicitContentHeight » y « implicitBackgroundWidth ».
leftInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]
Esta propiedad define el margen izquierdo del 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 define el relleno a la izquierda. A menos que se especifique explícitamente, el valor es igual a « horizontalPadding ».
Véase también Control Layout, padding, rightPadding, horizontalPadding y availableWidth.
locale : Locale
Esta propiedad almacena la configuración regional del control.
Contiene propiedades específicas de la configuración regional para dar formato a datos y números. A menos que se haya establecido una configuración regional especial, se trata de la configuración regional del control padre o de la configuración regional predeterminada.
El control propaga la configuración regional del control padre a los controles hijos. Si se cambia la configuración regional del control, esta se propaga a todos los controles hijos, sustituyendo la configuración regional predeterminada del sistema.
Véase también mirrored.
mirrored : bool [read-only]
Esta propiedad indica si el control está invertido.
Esta propiedad se proporciona por comodidad. Se considera que un control está invertido cuando su dirección de 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.
Véase también « LayoutMirroring » e «Interfaces de usuario de derecha a izquierda».
padding : real
Esta propiedad establece el relleno predeterminado.
El relleno añade un espacio entre cada borde del elemento de contenido y el elemento de fondo, lo que controla de forma efectiva el tamaño del elemento de contenido. Para especificar un valor de relleno para un borde concreto del control, configura la propiedad correspondiente:
Nota: Los distintos estilos pueden especificar el relleno predeterminado para ciertos controles de diferentes maneras, y estas formas pueden cambiar con el tiempo a medida que evolucionan las directrices de diseño en las que se basa el estilo. Para garantizar que estos cambios no afecten a los valores de relleno que hayas especificado, es mejor utilizar las propiedades más específicas disponibles. Por ejemplo, en lugar de establecer la propiedad de relleno:
padding: 0configura cada propiedad específica en su lugar:
leftPadding: 0
rightPadding: 0
topPadding: 0
bottomPadding: 0Véase también Control Layout, availableWidth, availableHeight, topPadding, leftPadding, rightPadding y bottomPadding.
rightInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]
Esta propiedad establece el margen derecho del 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 establece el relleno adecuado. A menos que se especifique explícitamente, el valor es igual a horizontalPadding.
Véase también Control Layout, padding, leftPadding, horizontalPadding y availableWidth.
spacing : real
Esta propiedad define el espaciado.
El espaciado resulta útil para controles que contienen elementos constitutivos múltiples o repetitivos. Por ejemplo, algunos estilos utilizan el espaciado para determinar la distancia entre el texto y el indicador de CheckBox. Control no impone el uso del espaciado, 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 define el margen superior del 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 define el relleno superior. A menos que se especifique 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 define el relleno vertical. A menos que se especifique 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 el foco visual. Esta propiedad tiene el valor « true » cuando el control tiene el foco activo y el motivo del foco es « Qt.TabFocusReason », « Qt.BacktabFocusReason » o « Qt.ShortcutFocusReason ».
En general, para visualizar el foco de teclado, se prefiere esta propiedad a « Item::activeFocus ». Esto garantiza que el foco de teclado solo se visualice al interactuar con las teclas, y no al interactuar mediante el tacto o el ratón.
Véase también focusReason y Item::activeFocus.
wheelEnabled : bool
Esta propiedad determina si el control gestiona los eventos de la rueda de ratón. El valor por defecto es false.
Nota: Hay que tenercuidado al habilitar los eventos de rueda para controles dentro de elementos desplazables, como Flickable, ya que el control consumirá los eventos y, por lo tanto, interrumpirá el desplazamiento del Flickable.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.