En esta página

Popup QML Type

Tipo base de controles de interfaz de usuario tipo ventana emergente. Más...

Import Statement: import QtQuick.Controls
Inherits:

QtObject

Inherited By:

Dialog, Drawer, Menu, and ToolTip

Propiedades

Señales

Métodos

Descripción detallada

Popup es el tipo básico de controles de interfaz de usuario tipo ventana emergente. Se puede utilizar con Window o ApplicationWindow.

import QtQuick.Window
import QtQuick.Controls

ApplicationWindow {
    id: window
    width: 400
    height: 400
    visible: true

    Button {
        text: "Open"
        onClicked: popup.open()
    }

    Popup {
        id: popup
        x: 100
        y: 100
        width: 200
        height: 300
        modal: true
        focus: true
        closePolicy: Popup.CloseOnEscape | Popup.CloseOnPressOutsideParent
    }
}

Popup no proporciona un diseño propio, sino que requiere que se posicione su contenido, por ejemplo, creando un RowLayout o un ColumnLayout.

Los elementos declarados como hijos de un Popup se vinculan automáticamente al contentItem del Popup. Los elementos creados dinámicamente deben vincularse explícitamente al contentItem.

El siguiente diagrama ilustra el diseño de una ventana emergente dentro de una ventana:

Ventana emergente que se superpone al contenido

El « implicitWidth » y el « implicitHeight » de una ventana emergente suelen basarse en los tamaños implícitos del fondo y del elemento de contenido, más cualquier margen interior y relleno. Estas propiedades determinan el tamaño que tendrá la ventana emergente cuando no se especifiquen explícitamente « width » o « height ».

La geometría del elemento « contentItem » viene determinada por el relleno (padding). El siguiente ejemplo reserva un relleno de 10 píxeles entre los límites de la ventana emergente y su contenido:

Popup {
    padding: 10

    contentItem: Text {
        text: "Content"
    }
}

El elemento « background » ocupa todo el ancho y la altura de la ventana emergente, a menos que se le hayan asignado márgenes interiores o un tamaño explícito.

Se pueden utilizar insets negativos para que el fondo sea más grande que la ventana emergente. El siguiente ejemplo utiliza insets negativos para colocar una sombra fuera de los límites de la ventana emergente:

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

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

Desde Qt 6.8, algunas ventanas emergentes, como ` Menu`, ofrecen tres implementaciones diferentes, dependiendo de la plataforma. Puedes elegir la que prefieras configurando ` popupType`.

Que una ventana emergente pueda utilizar el tipo preferido depende de la plataforma. Popup.Item es compatible con todas las plataformas, pero Popup.Window y Popup.Native normalmente solo son compatibles con plataformas de escritorio. Además, si una ventana emergente es un Menu dentro de un native menubar, el menú también será nativo. Y si el menú es un submenú dentro de otro menú, el menú principal (o raíz) determinará el tipo.

Mostrar una ventana emergente como un elemento

Al establecer ` popupType ` en ` Popup.Item`, la ventana emergente no se mostrará como una ventana independiente, sino como un elemento dentro de la misma escena que la ventana principal. Este elemento está vinculado al ` overlay` de esa escena y se le aplica un estilo para que parezca una ventana real.

Esta opción resulta especialmente útil en plataformas que no admiten ventanas múltiples. Además, era la única opción disponible antes de Qt 6.8.

Para garantizar que una ventana emergente se muestre por encima de otros elementos de la escena, se recomienda utilizar « ApplicationWindow ». « ApplicationWindow » también ofrece efectos de atenuación del fondo.

Mostrar una ventana emergente como una ventana independiente

Al establecer ` popupType ` en ` Popup.Window`, la ventana emergente se mostrará dentro de un ` window ` de nivel superior configurado con el indicador ` Qt::Popup `. Utilizar una ventana para mostrar una ventana emergente tiene la ventaja de que esta flotará sobre la ventana principal y podrá colocarse fuera de su geometría. Por lo demás, la ventana emergente tendrá el mismo aspecto que al utilizar Popup.Item, es decir, utilizará los mismos delegados y estilos QML que al utilizar Popup.Item.

Nota: Si la plataforma no admite ` Popup.Window`, se utilizará ` Popup.Item ` como alternativa.

Mostrar una ventana emergente nativa

Al establecer popupType en Popup.Native, la ventana emergente se mostrará utilizando una ventana emergente nativa de la plataforma. Esta ventana, y todo su contenido, serán renderizados por la plataforma, y no por QML. Esto significa que los delegados QML asignados a la ventana emergente no se utilizarán para el renderizado. Si, por ejemplo, utilizas esta opción en un « Menu », se implementará mediante las API de menú específicas de la plataforma. Normalmente, esto hará que la ventana emergente tenga un aspecto y un comportamiento más nativos que, por ejemplo, « Popup.Window », pero, al mismo tiempo, se verá afectada por las limitaciones y diferencias de la plataforma en cuanto a apariencia y comportamiento. Dichas limitaciones se documentan con más detalle en las subclases afectadas, como en el caso de Menu.

Nota: Si la plataforma no admite Popup.Native, se utilizará Popup.Window como alternativa.

Si solo se utiliza un elemento dentro de una ventana emergente, esta se redimensionará para adaptarse al tamaño implícito del elemento que contiene. Esto la hace especialmente adecuada para su uso junto con diseños.

Popup {
    ColumnLayout {
        anchors.fill: parent
        CheckBox { text: qsTr("E-mail") }
        CheckBox { text: qsTr("Calendar") }
        CheckBox { text: qsTr("Contacts") }
    }
}

En ocasiones, puede haber dos elementos dentro de la ventana emergente:

Popup {
    SwipeView {
        // ...
    }
    PageIndicator {
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.bottom: parent.bottom
    }
}

En este caso, la ventana emergente no puede calcular un tamaño implícito razonable. Dado que estamos anclando ` PageIndicator ` sobre ` SwipeView`, podemos simplemente establecer el tamaño del contenido en el tamaño implícito de la vista:

Popup {
    contentWidth: view.implicitWidth
    contentHeight: view.implicitHeight

    SwipeView {
        id: view
        // ...
    }
    PageIndicator {
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.bottom: parent.bottom
    }
 }

Nota: Al utilizar popup items, el content item de la ventana emergente pasa a estar anidado en el overlay y no reside dentro del elemento padre de la ventana emergente. Por ello, un scale aplicado al árbol en el que se encuentra la ventana emergente no se aplica a la ventana emergente visual. Para que la ventana emergente de, por ejemplo, un « ComboBox » siga la escala del cuadro combinado, aplica también la misma escala a « overlay »:

Window {
    property double scaleFactor: 2.0

    Scale {
        id: scale
        xScale: scaleFactor
        yScale: scaleFactor
    }
    Item {
        id: scaledContent
        transform: scale

        ComboBox {
            id: combobox
            // ...
        }
    }

    Overlay.overlay.transform: scale
}

Al igual que los elementos de Qt Quick, las coordenadas x y y de la ventana emergente son relativas respecto a su elemento padre. Esto significa que, al abrir una ventana emergente que sea hija de un Button, por ejemplo, la ventana emergente se colocará en relación con el botón.

El siguiente ejemplo utiliza la propiedad Overlay.overlay para situar una ventana emergente en el centro de la ventana, independientemente de la posición del botón que la abre:

Button {
    onClicked: popup.open()

    Popup {
        id: popup

        parent: Overlay.overlay

        x: Math.round((parent.width - width) / 2)
        y: Math.round((parent.height - height) / 2)
        width: 100
        height: 100
    }
}

Otra forma de centrar una ventana emergente en la ventana, independientemente de su elemento padre, es utilizar anchors.centerIn:

ApplicationWindow {
    id: window
    // ...

    Pane {
        // ...

        Popup {
            anchors.centerIn: Overlay.overlay
        }
    }
}

Para garantizar que la ventana emergente se coloque dentro de los límites de la ventana que la contiene, la propiedad ` margins ` puede establecerse en un valor no negativo.

Uso de la superposición

En los casos en los que no se utilice popup windows, Popup establece el padre visual de su contentItem como el overlay de la ventana, con el fin de garantizar que la ventana emergente aparezca por delante de todo lo demás en la escena. Su tarea principal es interceptar eventos para impedir que se envíen a los elementos situados debajo de una ventana emergente modal, y cerrar la ventana emergente según su closePolicy.

En algunos casos, puede resultar útil colocar un elemento delante de una ventana emergente, como un virtual keyboard. Actualmente, esto solo se puede hacer estableciendo el elemento padre del elemento como la superposición y asegurándose de que el elemento se coloque antes que cualquier elemento de la ventana emergente, lo que se garantiza con un valor positivo de z.

Por lo general, no se recomienda utilizar la superposición de esta manera, ya que no fue diseñada para este fin y el comportamiento no será coherente al cambiar el valor de « popupType ».

Popup {
    id: popup
    visible: true
    anchors.centerIn: parent
    margins: 10
    closePolicy: Popup.CloseOnEscape
    ColumnLayout {
        TextField {
            placeholderText: qsTr("Username")
        }
        TextField {
            placeholderText: qsTr("Password")
            echoMode: TextInput.Password
        }
    }
}
InputPanel {
    parent: Overlay.overlay
    width: parent.width
    y: popup.y + popup.topMargin + (window.activeFocusItem?.y ?? 0) + (window.activeFocusItem?.height ?? 0)
    z: 1
}

Una vez finalizada la transición de salida, estas propiedades se restablecerán a los valores que tenían antes de que se iniciara la transición de entrada.

Esto permite que los estilos integrados se animen en función de estas propiedades sin perder ningún valor definido explícitamente.

Gestión de eventos «Atrás»/«Esc»

Por defecto, una ventana emergente se cerrará si:

Para evitar que esto ocurra, puedes:

  • No asigne un ` focus` a la ventana emergente.
  • Establecer el valor de « closePolicy » del menú emergente en un valor que no incluya « Popup.CloseOnEscape ».
  • Gestiona la señal « Keys' escapePressed » en un elemento secundario de la ventana emergente, de modo que reciba el evento antes que la ventana emergente.

Propagación de propiedades

La ventana emergente hereda las fuentes, las paletas y las propiedades asociadas a través de su ventana padre, no de su objeto padre o elemento visual padre:

import QtQuick.Controls.Basic

ApplicationWindow {
    width: 500
    height: 500
    visible: true
    font.pixelSize: 20
    palette.windowText: "steelblue"

    // This will have a pixelSize of 20 and be "steelblue" in color.
    header: Label {
        text: "ApplicationWindow Label"
        leftPadding: 20
        topPadding: 20
    }

    Pane {
        width: 400
        height: 400
        anchors.centerIn: parent
        palette.window: "#edf3f8"
        palette.windowText: "tomato"

        // This will have a pixelSize of 20 and be "tomato" in color.
        Label {
            text: "Pane Label"
        }

        Popup {
            width: 300
            height: 300
            anchors.centerIn: parent
            font.pixelSize: 10
            visible: true

            // This will have a pixelSize of 10 and "steelblue" in color.
            Label {
                text: "Popup Label"
            }

            Popup {
                width: 200
                height: 200
                anchors.centerIn: parent
                visible: true

                // This will have a pixelSize of 20 and be "steelblue" in color.
                Label {
                    text: "Child Popup Label"
                }
            }
        }
    }
}

Diagrama que muestra la herencia de propiedades en ventanas emergentes

Además, las ventanas emergentes no propagan sus propiedades a las ventanas emergentes secundarias. Este comportamiento se basa en Qt Widgets, donde un widget Qt::Popup es una ventana de nivel superior. Las ventanas de nivel superior no propagan sus propiedades a las ventanas secundarias.

Ciertos tipos derivados, como ` ComboBox `, suelen implementarse de tal manera que la ventana emergente se considera una parte integral del control y, como tal, puede heredar elementos como las propiedades asociadas. Por ejemplo, en el estilo Material de ` ComboBox`, la ventana emergente hereda explícitamente el tema y otras propiedades asociadas del propio ` ComboBox `:

popup: T.Popup {
    // ...

    Material.theme: control.Material.theme
    Material.accent: control.Material.accent
    Material.primary: control.Material.primary
}

Por lo tanto, para garantizar que una ventana emergente hija tenga los mismos valores de propiedad que su ventana emergente padre, establece explícitamente dichas propiedades:

Popup {
    id: parentPopup
    // ...

    Popup {
        palette: parentPopup.palette
    }
}

Perfeccionamiento del comportamiento de las ventanas emergentes cerradas

Cuando se cierra una ventana emergente, esta no tiene ninguna ventana asociada, y tampoco la tienen sus elementos hijos. Esto significa que ningún elemento hijo estará polished hasta que se muestre la ventana emergente. Por este motivo, no se puede, por ejemplo, confiar en que una ListView dentro de una Popup cerrada actualice su propiedad count:

import QtQuick
import QtQuick.Controls

ApplicationWindow {
    width: 640
    height: 480
    visible: true

    SomeModel {
        id: someModel
    }

    Button {
        text: view.count
        onClicked: popup.open()
    }

    Popup {
        id: popup
        width: 400
        height: 400
        contentItem: ListView {
            id: view
            model: someModel
            delegate: Label {
                text: display

                required property string display
            }
        }
    }
}

En el ejemplo anterior, el texto del botón no se actualizará cuando se añadan o eliminen filas de someModel después de component completion mientras la ventana emergente esté cerrada.

En su lugar, se puede añadir una propiedad count a SomeModel que se actualice cada vez que se emitan las señales rowsInserted, rowsRemoved y modelReset. El Button puede entonces vincular esta propiedad a su text.

Véase también «Controles emergentes», «Personalización de ventanas emergentes» y « ApplicationWindow ».

Documentación de propiedades

activeFocus : bool [read-only]

Esta propiedad indica si la ventana emergente tiene el foco activo.

Véase también « focus » y «Foco del teclado» en Qt Quick.

anchors.centerIn : Item [since QtQuick.Controls 2.5 (Qt 5.12)]

Los anclajes permiten posicionar un elemento especificando su relación con otros elementos.

Un caso de uso habitual es centrar una ventana emergente dentro de su elemento padre. Una forma de hacerlo es mediante las propiedades x y y. Los anclajes ofrecen un método más cómodo:

Pane {
    // ...

    Popup {
        anchors.centerIn: parent
    }
}

También es posible centrar la ventana emergente en la ventana utilizando Overlay:

ApplicationWindow {
    id: window
    // ...

    Pane {
        // ...

        Popup {
            anchors.centerIn: Overlay.overlay
        }
    }
}

Esto facilita centrar una ventana emergente en la ventana desde cualquier componente.

Nota: Las ventanas emergentes solo se pueden centrar dentro de su elemento padre inmediato o de la superposición de la ventana; si se intenta centrarlas en otros elementos, aparecerá una advertencia.

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

Véase también Popup Positioning, anchors y Using Qt Quick Controls types in property declarations.

availableHeight : real [read-only]

Esta propiedad contiene la altura disponible para el elemento « contentItem » tras restar el relleno vertical del elemento « height » de la ventana emergente.

Véanse también « padding », « topPadding » y « bottomPadding ».

availableWidth : real [read-only]

Esta propiedad contiene el ancho disponible para el elemento « contentItem » tras restar el relleno horizontal del « width » de la ventana emergente.

Véanse también « padding », « leftPadding » y « rightPadding ».

background : Item

Esta propiedad contiene el elemento de fondo.

Nota: Si no se ha especificado un tamaño explícito para el elemento de fondo, este se ajusta automáticamente al tamaño de la ventana emergente. 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 las ventanas emergentes utilizan el tamaño implícito del elemento de fondo para calcular el tamaño implícito de la propia ventana emergente. 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 Personalización deventanas emergentes.

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 Popup Layout y topInset.

bottomMargin : real

Esta propiedad indica la distancia entre el borde inferior de la ventana emergente y el borde inferior de su ventana.

Una ventana emergente con un margen inferior negativo no se desplaza por debajo del borde inferior de la ventana que la contiene. El valor por defecto es « -1 ».

Véase también « margins », « topMargin » y « Popup Layout ».

bottomPadding : real

Esta propiedad define el relleno inferior. A menos que se especifique explícitamente, el valor es igual a « verticalPadding ».

Las propiedades de relleno se utilizan para controlar la geometría de content item.

La ventana emergente utiliza el mismo enfoque para el relleno que Control. Para obtener una explicación visual del sistema de relleno, consulta la sección « Control Layout » de la documentación.

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

clip : bool

Esta propiedad se mantiene independientemente de si el recorte está activado. El valor por defecto es « false ». El recorte solo funciona cuando la ventana emergente no se encuentra en su propia ventana.

closePolicy : enumeration

Esta propiedad determina las circunstancias en las que se cierra la ventana emergente. Los indicadores se pueden combinar para permitir varias formas de cerrar la ventana emergente.

Los valores disponibles son:

ConstanteDescripción
Popup.NoAutoCloseLa ventana emergente solo se cerrará cuando se le indique manualmente que lo haga.
Popup.CloseOnPressOutsideLa ventana emergente se cerrará al hacer clic con el ratón fuera de ella.
Popup.CloseOnPressOutsideParentLa ventana emergente se cerrará al hacer clic con el ratón fuera de su elemento padre.
Popup.CloseOnReleaseOutsideLa ventana emergente se cerrará al soltar el ratón fuera de ella.
Popup.CloseOnReleaseOutsideParentLa ventana emergente se cerrará al soltar el ratón fuera de su elemento padre.
Popup.CloseOnEscapeLa ventana emergente se cerrará cuando se pulse la tecla Esc mientras tenga el foco activo.
Popup.CloseMultipleCuando se utilizan varias ventanas emergentes anidadas, por defecto solo se cierra la ventana emergente situada en la parte superior con cada clic fuera de ella. Cuando la ventana emergente que se está cerrando tiene esta opción activada, también se comprueba la siguiente ventana emergente de la pila: si la posición del clic también estaba fuera de ella, también se cierra. Esta cascada continúa bajando por la pila hasta que se hayan cerrado todas las ventanas emergentes, se alcance una ventana emergente cuyos límites contengan la posición del clic o se cierre una ventana emergente sin el indicador « CloseMultiple ». Debe combinarse con al menos uno de los indicadores « CloseOnPress* » o « CloseOnRelease* ».

El valor por defecto es « Popup.CloseOnEscape | Popup.CloseOnPressOutside ».

Nota: Existe una limitación conocida por la que las políticas « Popup.CloseOnReleaseOutside » y « Popup.CloseOnReleaseOutsideParent » solo funcionan con ventanas emergentes « modal ».

contentChildren : list<Item>

Esta propiedad contiene la lista de elementos hijos de contenido.

La lista contiene todos los elementos que se han declarado en QML como elementos secundarios de la ventana emergente.

Nota: A diferencia de contentData, contentChildren no incluye objetos QML no visuales.

Véase también Item::children y contentData.

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 de la ventana emergente.

Nota: A diferencia de ` contentChildren`, ` contentData ` sí incluye objetos QML no visuales.

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

contentHeight : real

Esta propiedad almacena la altura del contenido. Se utiliza para calcular la altura implícita total de la ventana emergente.

Para obtener más información, consulta Popup Sizing.

Véase también contentWidth.

contentItem : Item

Esta propiedad contiene el elemento de contenido de la ventana emergente.

El elemento de contenido es la representación visual de la ventana emergente. Cuando la ventana emergente se hace visible, el elemento de contenido pasa automáticamente a estar anidado en el « overlay item ».

Nota: El elemento de contenido se redimensiona automáticamente para ajustarse a la « padding » de la ventana emergente.

Nota: La mayoría de las ventanas emergentes utilizan el tamaño implícito del elemento de contenido para calcular el tamaño implícito de la propia ventana emergente. 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 Personalización deventanas emergentes.

contentWidth : real

Esta propiedad almacena el ancho del contenido. Se utiliza para calcular el ancho implícito total de la ventana emergente.

Para obtener más información, consulta Popup Sizing.

Véase también contentHeight.

dim : bool

Esta propiedad determina si la ventana emergente atenúa el fondo.

A menos que se especifique explícitamente, esta propiedad adopta el valor de « modal ». Para volver al valor predeterminado, establece esta propiedad en « undefined ».

Véanse también « modal » y « Overlay.modeless ».

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

Esta propiedad indica si la ventana emergente está activada. El valor por defecto es « true ».

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

Véase también visible y Item::enabled.

enter : Transition

Esta propiedad define la transición que se aplica al elemento emergente cuando este se abre y entra en la pantalla.

El siguiente ejemplo anima la opacidad de la ventana emergente cuando aparece en pantalla:

Popup {
    enter: Transition {
        NumberAnimation { property: "opacity"; from: 0.0; to: 1.0 }
    }
}

Véase también exit.

exit : Transition

Esta propiedad define la transición que se aplica al elemento emergente cuando este se cierra y sale de la pantalla.

El siguiente ejemplo anima la opacidad de la ventana emergente cuando sale de la pantalla:

Popup {
    exit: Transition {
        NumberAnimation { property: "opacity"; from: 1.0; to: 0.0 }
    }
}

Véase también enter.

focus : bool

Esta propiedad indica si la ventana emergente desea recibir el foco.

Cuando la ventana emergente reciba efectivamente el foco, ` activeFocus ` será ` true`. Para obtener más información, consulta «Foco del teclado» en Qt Quick.

El valor predeterminado es false.

Véase también activeFocus.

font : font

Esta propiedad contiene la fuente establecida actualmente para la ventana emergente.

La ventana emergente propaga las propiedades de fuente explícitas a sus elementos hijos. Si se modifica una propiedad específica de la fuente de una ventana emergente, dicha propiedad se propaga a todos los elementos hijos de la ventana emergente, anulando cualquier valor predeterminado del sistema para esa propiedad.

Popup {
    font.family: "Courier"

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

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

Véase también Control::font y ApplicationWindow::font.

height : real

Esta propiedad indica la altura de la ventana emergente.

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 ».

Las propiedades de relleno se utilizan para controlar la geometría del « content item ».

Popup utiliza el mismo enfoque para el relleno que Control. Para obtener una explicación visual del sistema de relleno, consulta la sección « Control Layout » de la documentación.

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

Véase también « padding », « leftPadding », « rightPadding » y « verticalPadding ».

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`.

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`.

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

Véase 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.

El valor se calcula en función de los elementos secundarios del contenido.

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.

El valor se calcula en función de los elementos hijos del contenido.

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

Véase también implicitContentHeight y implicitBackgroundWidth.

implicitHeight : real

Esta propiedad contiene la altura implícita de la ventana emergente.

implicitWidth : real

Esta propiedad contiene el ancho implícito de la ventana emergente.

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 Popup Layout y rightInset.

leftMargin : real

Esta propiedad indica la distancia entre el borde izquierdo de la ventana emergente y el borde izquierdo de la ventana que la contiene.

Una ventana emergente con un margen izquierdo negativo no se desplaza hacia el interior del borde izquierdo de la ventana que la contiene. El valor por defecto es -1.

Véase también « margins », « rightMargin » y « Popup Layout ».

leftPadding : real

Esta propiedad define el relleno a la izquierda. A menos que se especifique explícitamente, el valor es igual a horizontalPadding.

Las propiedades de relleno se utilizan para controlar la geometría del content item.

Popup utiliza el mismo enfoque para el relleno que Control. Para obtener una explicación visual del sistema de relleno, consulta la sección « Control Layout » de la documentación.

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

locale : Locale

Esta propiedad define la configuración regional de la ventana emergente.

Véase también mirrored y LayoutMirroring.

margins : real

Esta propiedad indica la distancia entre los bordes de la ventana emergente y los bordes de la ventana que la contiene.

Una ventana emergente con márgenes negativos no se desplaza dentro de los límites de la ventana que la contiene. El valor por defecto es -1.

Véase también topMargin, leftMargin, rightMargin, bottomMargin y Popup Layout.

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

Esta propiedad indica si la ventana emergente está invertida.

Esta propiedad se proporciona por comodidad. Se considera que una ventana emergente está invertida cuando su dirección de diseño visual es de derecha a izquierda; es decir, cuando se utiliza una configuración regional de derecha a izquierda.

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

Véase también locale y Interfaces de usuario de derecha a izquierda.

Esta propiedad indica si la ventana emergente es modal.

Las ventanas emergentes modales suelen tener un efecto distintivo de atenuación del fondo definido en Overlay.modal y no permiten que los eventos de pulsación o liberación lleguen a los elementos situados debajo de ellas. Por ejemplo, si el usuario hace clic accidentalmente fuera de una ventana emergente, ningún elemento situado debajo de dicha ventana en la ubicación del clic recibirá el evento.

En plataformas de escritorio, es habitual que las ventanas emergentes modales solo se cierren al pulsar la tecla Esc. Para conseguir este comportamiento, establece closePolicy en Popup.CloseOnEscape. Por defecto, closePolicy está establecido en Popup.CloseOnEscape | Popup.CloseOnPressOutside, lo que significa que al hacer clic fuera de una ventana emergente modal, esta se cerrará.

El valor por defecto es false.

Véase también dim.

opacity : real

Esta propiedad define la opacidad de la ventana emergente. La opacidad se especifica como un número comprendido entre 0.0 (totalmente transparente) y 1.0 (totalmente opaco). El valor por defecto es 1.0.

Véase también visible.

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

Esta propiedad indica si la ventana emergente está completamente abierta. Se considera que la ventana emergente está abierta cuando es visible y no se está ejecutando ninguna de las transiciones « enter » ni « exit ».

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

Véase también open(), close() y visible.

padding : real

Esta propiedad establece el relleno predeterminado.

Las propiedades de relleno se utilizan para controlar la geometría de content item.

La ventana emergente utiliza el mismo enfoque para el relleno que Control. Para obtener una explicación visual del sistema de relleno, consulta la sección « Control Layout » de la documentación.

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

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

Esta propiedad contiene la paleta configurada actualmente para la ventana emergente.

La ventana emergente propaga las propiedades explícitas de la paleta a sus elementos secundarios. Si se modifica una propiedad específica de la paleta de una ventana emergente, dicha propiedad se propaga a todos los elementos secundarios de la ventana emergente, anulando cualquier valor predeterminado del sistema para esa propiedad.

Popup {
    palette.text: "red"

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

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

Véase también: Item::palette, Window::palette, ColorGroup, Palette

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

parent : Item

Esta propiedad contiene el elemento principal.

popupType : enumeration [since 6.8]

Esta propiedad determina el tipo de ventana emergente que se prefiere.

Opciones disponibles:

ConstanteDescripción
ItemLa ventana emergente se integrará en la página same scene as the parent, sin utilizar una ventana independiente.
WindowLa ventana emergente se mostrará en una ventana « separate window ». Si la plataforma no admite ventanas múltiples, se utilizará en su lugar « Popup.Item ».
NativeLa ventana emergente será nativa de la plataforma. Si la plataforma no admite ventanas emergentes nativas, se utilizará en su lugar Popup.Window.

Que una ventana emergente pueda utilizar el tipo preferido depende de la plataforma. « Popup.Item » es compatible con todas las plataformas, pero « Popup.Window » y « Popup.Native » normalmente solo son compatibles con plataformas de escritorio. Además, si una ventana emergente es un « Menu » 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) determinará el tipo.

El valor por defecto suele ser « Popup.Item », con algunas excepciones, mencionadas anteriormente. Esto podría cambiar en futuras versiones de Qt, para determinados estilos y plataformas que se beneficien del uso de otros tipos de menús emergentes. Si siempre quieres utilizar menús nativos para todos los estilos en macOS, por ejemplo, puedes hacer lo siguiente:

Menu {
    popupType: Qt.platform.os === "osx" ? Popup.Native : Popup.Window
}

Además, si decides personalizar un menú emergente (por ejemplo, cambiando alguno de los delegados), deberías considerar establecer el tipo de menú emergente también como « Popup.Window ». Esto garantizará que tus cambios sean visibles en todas las plataformas y para todos los estilos. De lo contrario, cuando se utilicen menús nativos, los delegados no se utilizarán para la representación.

Esta propiedad se introdujo en Qt 6.8.

Véase también « Popup type ».

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 Popup Layout y leftInset.

rightMargin : real

Esta propiedad indica la distancia entre el borde derecho de la ventana emergente y el borde derecho de su ventana.

Una ventana emergente con un margen derecho negativo no se desplaza hacia el interior del borde derecho de la ventana que la contiene. El valor por defecto es -1.

Véase también « margins », « leftMargin » y « Popup Layout ».

rightPadding : real

Esta propiedad define el relleno a la derecha. A menos que se especifique explícitamente, el valor es igual a horizontalPadding.

Las propiedades de relleno se utilizan para controlar la geometría de content item.

Popup utiliza el mismo enfoque para el relleno que Control. Para obtener una explicación visual del sistema de relleno, consulta la sección « Control Layout » de la documentación.

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

scale : real

Esta propiedad contiene el factor de escala de la ventana emergente. El valor por defecto es 1.0.

Una escala inferior a 1.0 hace que la ventana emergente se muestre con un tamaño menor, mientras que una escala superior a 1.0 hace que se muestre con un tamaño mayor. No se admiten escalas negativas.

spacing : real [since QtQuick.Controls 2.1 (Qt 5.8)]

Esta propiedad controla el espaciado.

El espaciado resulta útil para ventanas emergentes que contienen varios elementos constitutivos o elementos repetitivos. Por ejemplo, algunos estilos utilizan el espaciado para determinar la distancia entre el encabezado, el contenido y el pie de página de Dialog. Popup no impone el uso del espaciado, por lo que cada estilo puede interpretarlo de forma diferente y algunos pueden ignorarlo por completo.

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

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 Popup Layout y bottomInset.

topMargin : real

Esta propiedad indica la distancia entre el borde superior de la ventana emergente y el borde superior de la ventana que la contiene.

Una ventana emergente con un margen superior negativo no se desplaza hacia el interior del borde superior de la ventana que la contiene. El valor por defecto es -1.

Véase también margins, bottomMargin y Popup Layout.

topPadding : real

Esta propiedad define el relleno superior. A menos que se especifique explícitamente, el valor es igual a « verticalPadding ».

Las propiedades de relleno se utilizan para controlar la geometría de « content item ».

Popup utiliza el mismo enfoque para el relleno que Control. Para obtener una explicación visual del sistema de relleno, consulta la sección « Control Layout » de la documentación.

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

transformOrigin : enumeration

Esta propiedad contiene el punto de origen de las transformaciones en las transiciones de entrada y salida.

Hay nueve orígenes de transformación disponibles, tal y como se muestra en la imagen siguiente. El origen de transformación predeterminado es Popup.Center.

Ventana emergente que muestra los puntos de origen de las transformaciones

Véase también enter, exit y Item::transformOrigin.

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

Esta propiedad controla el relleno vertical. A menos que se especifique explícitamente, el valor es igual a « padding ».

Las propiedades de relleno se utilizan para controlar la geometría del content item.

Popup utiliza el mismo enfoque para el relleno que Control. Para obtener una explicación visual del sistema de relleno, consulta la sección « Control Layout » de la documentación.

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

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

visible : bool

Esta propiedad indica si la ventana emergente está visible. El valor por defecto es false.

Véase también open(), close() y opened.

width : real

Esta propiedad almacena el ancho de la ventana emergente.

x : real

Esta propiedad contiene la coordenada x de la ventana emergente.

Véase también y y z.

y : real

Esta propiedad contiene la coordenada y de la ventana emergente.

Véase también x y z.

z : real

Esta propiedad contiene el valor z de la ventana emergente. El valor z determina el orden de superposición de las ventanas emergentes.

Si dos ventanas emergentes visibles tienen el mismo valor z, la última que se haya abierto aparecerá encima.

Si una ventana emergente no tiene un valor z establecido explícitamente al abrirse y es hija de una ventana emergente ya abierta, se colocará encima de su ventana principal. Esto garantiza que las ventanas secundarias nunca queden ocultas bajo sus ventanas principales.

Si la ventana emergente tiene su propia ventana, el valor z determinará, en su lugar, el orden de superposición de las ventanas.

El valor z predeterminado es 0.

Véase también x y y.

Documentación de Signal

void aboutToHide()

Esta señal se emite cuando la ventana emergente está a punto de ocultarse.

Nota: El controlador correspondiente es ` onAboutToHide`.

Véase también closed().

void aboutToShow()

Esta señal se emite cuando la ventana emergente está a punto de aparecer.

Nota: El controlador correspondiente es onAboutToShow.

Véase también opened().

void closed()

Esta señal se emite cuando se cierra la ventana emergente.

Nota: El controlador correspondiente es onClosed.

Véase también aboutToHide().

void opened()

Esta señal se emite cuando se abre la ventana emergente.

Nota: El controlador correspondiente es onOpened.

Véase también aboutToShow().

Documentación del método

void close()

Cierra la ventana emergente.

Véase también visible.

void forceActiveFocus(enumeration reason = Qt.OtherFocusReason)

Fija el foco en la ventana emergente con el reason especificado.

Este método establece el foco en la ventana emergente y garantiza que todos los objetos FocusScope anteriors de la jerarquía de objetos también reciban focus.

Véase también activeFocus y Qt::FocusReason.

void open()

Abre la ventana emergente.

Véase también visible.

© 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.