Módulo 4: Contenedores — Organizando el Lienzo

Aprende a agrupar y organizar widgets usando contenedores

---

Objetivos de Aprendizaje

Al finalizar este módulo serás capaz de:

Comprender qué son los contenedores y por qué son esenciales
Usar Group Box para agrupar widgets relacionados
Crear interfaces con pestañas usando Tab Widget
Implementar navegación por páginas con Stacked Widget
Manejar contenido extenso con Scroll Area
Usar Frame y Widget como contenedores básicos
Implementar Tool Box para paneles colapsables
Crear interfaces con múltiples documentos (MDI Area)
Integrar contenido web con WebEngine View
Usar Dock Widgets para paneles acoplables

---

4.1 ¿Qué son los Contenedores?

Los contenedores son widgets que pueden contener otros widgets dentro. Son como las carpetas de tu proyecto de diseño: te ayudan a organizar, agrupar y estructurar.

🎨 ANALOGÍA DEL DISEÑO

Si los widgets son como los elementos individuales de tu diseño (textos, botones, imágenes), los contenedores son como los grupos de capas en Photoshop o los frames en Figma. Te permiten organizar elementos relacionados juntos y aplicar propiedades al grupo completo.

¿Por qué usar contenedores?

Razón	Descripción	Ejemplo
-------	-------------	---------
Organización visual	Agrupar elementos relacionados	"Datos Personales", "Dirección"
Jerarquía	Crear niveles de información	Pestañas con contenido diferente
Reutilización	Crear componentes reutilizables	Un formulario de contacto que se usa en varias ventanas
Estilos	Aplicar estilos a un grupo completo	Fondo oscuro para toda una sección
Layouts	Organizar widgets hijos automáticamente	Layout vertical dentro de un Group Box

---

4.2 Group Box

El Group Box es un marco con título que agrupa widgets relacionados. Es perfecto para secciones de un formulario.

Características

Marco visible con borde y título
Los widgets dentro se organizan con layouts
Se puede habilitar/deshabilitar todo el grupo con un checkbox (propiedad checkable)

Propiedades clave

Propiedad	Descripción	Ejemplo
-----------	-------------	---------
title	El título del Group Box	"Datos Personales"
checkable	Si tiene un checkbox para activar/desactivar el grupo	`true` / `false`
checked	Si el checkbox está marcado	`true`
flat	Si el borde es plano (sin relieve)	`false`
alignment	Alineación del título	`AlignHCenter`

Cómo usar un Group Box

Arrastra un Group Box al área de trabajo
Cambia su propiedad title a algo como "Datos Personales"
Arrastra widgets DENTRO del Group Box
Aplica un layout al Group Box (clic derecho > Lay Out > Lay Out Vertically)
En el Object Inspector verás que los widgets aparecen como hijos del Group Box

┌─ Group Box: "Datos Personales" ─────────────────┐
│                                                   │
│  Label: "Nombre:"    Line Edit: [____________]    │
│  Label: "Email:"     Line Edit: [____________]    │
│  Label: "Teléfono:"  Line Edit: [____________]    │
│                                                   │
└───────────────────────────────────────────────────┘

📸 [PLACEHOLDER PARA IMAGEN]: Captura de pantalla de un Group Box con varios widgets dentro, mostrando el Object Inspector con la jerarquía.

---

4.3 Tab Widget (Pestañas)

El Tab Widget crea una interfaz con pestañas, como las pestañas de un navegador o las secciones de preferencias de una aplicación.

Características

Cada pestaña es una "página" independiente
Solo una pestaña visible a la vez
Cada pestaña puede tener su propio conjunto de widgets y layouts

Propiedades clave

Propiedad	Descripción	Ejemplo
-----------	-------------	---------
currentIndex	Índice de la pestaña activa (0 = primera)	`0`
tabPosition	Posición de las pestañas	`North`, `South`, `East`, `West`
tabShape	Forma de las pestañas	`Rounded`, `Triangular`
documentMode	Modo documento (sin borde alrededor)	`true` / `false`
tabsClosable	Mostrar botón de cerrar en cada pestaña	`false`
movable	Si las pestañas se pueden reordenar arrastrando	`false`

Cómo agregar/eliminar pestañas

Haz clic derecho en las pestañas del Tab Widget
Selecciona "Insert Page" para agregar una nueva pestaña
Selecciona "Delete Page" para eliminar la pestaña actual
Haz doble clic en el texto de la pestaña para renombrarla

🎨 ANALOGÍA DEL DISEÑO

Un Tab Widget es como tener varios artboards en Figma pero que el usuario puede cambiar entre ellos con un clic. Cada pestaña es un artboard diferente con su propio contenido.

Ejemplo de uso

┌─────────────────────────────────────────────┐
│ [General] [Apariencia] [Avanzado]           │
├─────────────────────────────────────────────┤
│                                             │
│  Contenido de la pestaña "General":         │
│  - Campo de nombre                          │
│  - Campo de email                           │
│  - Selector de idioma                        │
│                                             │
└─────────────────────────────────────────────┘

---

4.4 Stacked Widget (Páginas Apiladas)

El Stacked Widget es similar al Tab Widget pero sin pestañas visibles. Solo muestra una página a la vez. Es ideal para asistentes (wizards) o interfaces con navegación lateral.

Características

Múltiples páginas pero sin indicadores visuales de navegación
La página visible se controla con la propiedad currentIndex
Se usa comúnmente con botones de navegación "Anterior" / "Siguiente"

Propiedades clave

Propiedad	Descripción	Ejemplo
-----------	-------------	---------
currentIndex	Índice de la página visible (0 = primera)	`0`
count	Número total de páginas (solo lectura)	`3`

Cómo agregar/eliminar páginas

Haz clic derecho en el Stacked Widget
Selecciona "Insert Page" para agregar una nueva página
Selecciona "Delete Page" para eliminar la página actual

🎨 ANALOGÍA DEL DISEÑO

Un Stacked Widget es como una presentación de diapositivas: solo ves una diapositiva a la vez, pero puedes avanzar y retroceder entre ellas. El Tab Widget sería la misma presentación pero con índices visibles en la parte superior.

Ejemplo: Wizard de 3 pasos

┌─────────────────────────────────────────────┐
│         ASISTENTE DE CONFIGURACIÓN          │
├─────────────────────────────────────────────┤
│                                             │
│  [Página 1: Bienvenida]                     │
│  "Bienvenido al asistente de configuración" │
│  [Siguiente >]                              │
│                                             │
│  ↓ (al hacer clic en "Siguiente")           │
│                                             │
│  [Página 2: Datos]                          │
│  "Ingresa tus datos personales"             │
│  [< Anterior]    [Siguiente >]              │
│                                             │
│  ↓ (al hacer clic en "Siguiente")           │
│                                             │
│  [Página 3: Finalizar]                      │
│  "¡Configuración completada!"               │
│  [< Anterior]    [Finalizar]                │
│                                             │
└─────────────────────────────────────────────┘

💡 CONSEJO: Para controlar qué página se muestra sin código, puedes usar Signals y Slots. Conecta un botón "Siguiente" al Stacked Widget con un slot personalizado, o usa un Spin Box oculto para cambiar el currentIndex.

---

4.5 Scroll Area

El Scroll Area crea un área con barras de desplazamiento. Es esencial cuando tienes más contenido del que cabe en la ventana.

Características

Contiene un widget interno donde colocas tus elementos
Las barras de scroll aparecen automáticamente cuando el contenido excede el tamaño visible
Puedes desactivar las barras horizontal o vertical

Propiedades clave

Propiedad	Descripción	Ejemplo
-----------	-------------	---------
widgetResizable	Si el widget interno se redimensiona automáticamente	`true`
horizontalScrollBarPolicy	Política de barra horizontal	`ScrollBarAsNeeded`, `ScrollBarAlwaysOff`, `ScrollBarAlwaysOn`
verticalScrollBarPolicy	Política de barra vertical	`ScrollBarAsNeeded`, `ScrollBarAlwaysOff`, `ScrollBarAlwaysOn`

Cómo usar un Scroll Area

Arrastra un Scroll Area al área de trabajo
Dentro del Scroll Area hay un widget contenedor (llamado scrollAreaWidgetContents)
Coloca tus widgets dentro de scrollAreaWidgetContents
Aplica un layout al widget contenedor interno
Las barras de scroll aparecerán automáticamente cuando sea necesario

💡 CONSEJO: Usa Scroll Area cuando diseñes formularios largos, galerías de imágenes, o cualquier contenido que pueda crecer más allá del tamaño de la ventana. Siempre aplica un layout al widget interno del Scroll Area.

---

4.6 Frame

Un Frame es un contenedor con borde decorativo. Puedes personalizar su estilo de borde, sombra y forma.

Propiedades clave

Propiedad	Descripción	Valores
-----------	-------------	---------
frameShape	Forma del borde	`Box`, `Panel`, `StyledPanel`, `HLine`, `VLine`, `WinPanel`, `NoFrame`
frameShadow	Sombra del borde	`Plain`, `Raised`, `Sunken`
lineWidth	Grosor del borde exterior	`1` (por defecto)
midLineWidth	Grosor del borde medio	`0` (por defecto)
midFrameShape	Forma del borde medio	Depende de frameShape

Ejemplos de uso

Estilo	frameShape	frameShadow	Uso
--------	-----------	-------------	-----
Caja con relieve	`Box`	`Raised`	Tarjeta destacada
Panel hundido	`StyledPanel`	`Sunken`	Área de contenido
Línea horizontal	`HLine`	`Sunken`	Separador
Sin borde	`NoFrame`	`Plain`	Contenedor invisible

---

4.7 Widget (Contenedor Básico)

El Widget es el contenedor más básico. Sin bordes, sin título, sin decoración.

🎨 ANALOGÍA DEL DISEÑO

Un Widget contenedor es como un
en HTML o un Frame vacío en Figma: un contenedor invisible que agrupa elementos para aplicarles un layout o estilos comunes.

Cuándo usar un Widget contenedor

Cuando necesitas agrupar widgets pero no quieres un borde visible (usa Frame si quieres borde)
Como contenedor intermedio para crear layouts complejos
Para aplicar un styleSheet a un grupo de widgets sin afectar al resto

---

4.8 Tool Box

El Tool Box es un contenedor tipo acordeón: las secciones se expanden y colapsan. Ideal para paneles laterales con muchas opciones.

Características

Múltiples secciones apiladas verticalmente
Solo una sección expandida a la vez
Al hacer clic en el título de una sección, se expande y las demás se colapsan

Propiedades clave

Propiedad	Descripción
-----------	-------------
currentIndex	Índice de la sección expandida
iconSize	Tamaño de los iconos de las secciones

Cómo agregar secciones

Haz clic derecho en el Tool Box
Selecciona "Insert Page" para agregar una sección
Haz doble clic en el título de la sección para renombrarla

🎨 ANALOGÍA DEL DISEÑO

El Tool Box es como los paneles colapsables de Photoshop (Color, Capas, Propiedades): haces clic en el título para expandir o colapsar cada sección.

---

4.9 MDI Area

El MDI (Multiple Document Interface) Area permite tener múltiples ventanas dentro de una ventana principal.

Características

Cada "sub-ventana" puede moverse, redimensionarse, minimizarse
Modo cascada o modo mosaico para organizar las sub-ventanas
Similar a tener múltiples documentos abiertos en Photoshop

Propiedades clave

Propiedad	Descripción
-----------	-------------
viewMode	`SubWindowView` (ventanas flotantes) o `TabbedView` (pestañas)
documentMode	Modo documento

🎨 ANALOGÍA DEL DISEÑO

El MDI Area es como tener múltiples imágenes abiertas en Photoshop, cada una en su ventana interna que puedes mover, redimensionar y organizar.

---

4.10 WebEngine View

El WebEngine View es un navegador web completo embebido en tu aplicación.

Características

Carga páginas web, HTML local, o contenido dinámico
Soporta HTML, CSS, JavaScript completo
Perfecto para mostrar documentación, ayuda online, o contenido web

Propiedades clave

Propiedad	Descripción	Ejemplo
-----------	-------------	---------
url	La dirección web a cargar	`https://ejemplo.com`

💡 CONSEJO: Si ya sabes diseñar para web (HTML/CSS), puedes crear tu diseño en HTML y mostrarlo dentro de tu aplicación PySide6 usando WebEngine View. Es un puente perfecto entre el diseño web y las aplicaciones de escritorio.

---

4.11 Dock Widget

Los Dock Widgets son paneles que el usuario puede mover, acoplar y hacer flotantes. Solo están disponibles dentro de un Main Window.

Características

Se pueden acoplar a los 4 lados del Main Window
Se pueden hacer flotantes (ventana independiente)
Se pueden cerrar y volver a abrir desde el menú
Similar a los paneles de Photoshop

Propiedades clave

Propiedad	Descripción	Valores
-----------	-------------	---------
windowTitle	Título del panel	"Capas", "Propiedades"
features	Características del dock	`DockWidgetClosable`, `DockWidgetMovable`, `DockWidgetFloatable`, `AllDockWidgetFeatures`, `NoDockWidgetFeatures`
allowedAreas	Dónde se puede acoplar	`LeftDockWidgetArea`, `RightDockWidgetArea`, `TopDockWidgetArea`, `BottomDockWidgetArea`, `AllDockWidgetAreas`

🎨 ANALOGÍA DEL DISEÑO

Los Dock Widgets son exactamente como los paneles de Photoshop (Capas, Color, Propiedades) que puedes mover, acoplar a los lados, o hacer flotantes.

---

4.12 Comparación de Contenedores

Contenedor	Borde visible	Título	Múltiples "páginas"	Uso principal
------------	--------------	--------	---------------------	---------------
Group Box	Sí	Sí	No	Agrupar campos relacionados
Tab Widget	Sí	Sí (pestañas)	Sí	Configuración por categorías
Stacked Widget	No	No	Sí	Wizards, navegación por páginas
Scroll Area	Opcional	No	No	Contenido que excede la ventana
Frame	Sí (personalizable)	No	No	Contenedor decorativo
Widget	No	No	No	Contenedor invisible
Tool Box	Sí (acordeón)	Sí (secciones)	Sí (colapsable)	Paneles laterales
MDI Area	Sí	Sí (sub-ventanas)	Sí (flotantes)	Múltiples documentos
Dock Widget	Sí	Sí	No	Paneles acoplables
WebEngine View	No	No	No	Contenido web

---

Ejercicio Práctico del Módulo

🏋️ EJERCICIO 4: Ventana de Configuración con Pestañas

Objetivo: Crear una ventana de configuración profesional con múltiples pestañas y contenedores.

Pasos:

1. Crea un Dialog sin botones de 550x450 píxeles

2. Cambia el windowTitle a "Configuración"

3. Cambia el fondo: styleSheet: background-color: #1a1a2e;

4. Agrega un Tab Widget que ocupe casi toda la ventana

5. Crea 3 pestañas: "General", "Apariencia", "Cuentas"

6. En la pestaña "General":

- Agrega un Group Box titulado "Información Personal"

- Dentro del Group Box, agrega un Layout Vertical con:

- Label "Nombre:" + Line Edit

- Label "Email:" + Line Edit

- Label "Idioma:" + Combo Box (Español, Inglés, Francés)

7. En la pestaña "Apariencia":

- Agrega un Group Box titulado "Tema Visual"

- Dentro: Label "Tema:" + Combo Box (Oscuro, Claro, Automático)

- Agrega otro Group Box titulado "Tipografía"

- Dentro: Label "Tamaño:" + Slider (min: 10, max: 24)

- Agrega un Frame como vista previa con un Label dentro que diga "Vista previa del texto"

8. En la pestaña "Cuentas":

- Agrega un List Widget con cuentas de ejemplo:

- "juan@email.com"

- "maria@email.com"

- "carlos@email.com"

- Agrega un Push Button "Agregar cuenta" debajo

9. Aplica layouts a cada pestaña y contenedor

10. Renombra todos los widgets con nombres descriptivos

11. Guarda como configuracion.ui

12. Presiona Ctrl+R para ver la vista previa

Resultado esperado: Una ventana de configuración con 3 pestañas, cada una con Group Boxes organizados, campos de entrada y una lista de cuentas.

---

Recursos Adicionales

Recurso	Descripción
---------	-------------
[Qt Container Widgets](https://doc.qt.io/qt-6/qtwidgets-index.html#container-classes)	Documentación oficial de contenedores
[QMdiArea Documentation](https://doc.qt.io/qt-6/qmdiarea.html)	Documentación de MDI Area
[QDockWidget Documentation](https://doc.qt.io/qt-6/qdockwidget.html)	Documentación de Dock Widgets

---

Evaluación de Comprensión

¿Cuál es la diferencia entre un Group Box y un Frame?
¿Cuándo usarías un Tab Widget y cuándo un Stacked Widget?
¿Qué contenedor usarías para un formulario que puede ser más alto que la ventana?
¿Qué propiedad del Group Box permite activar/desactivar todos los widgets dentro de él?
¿Qué contenedor es similar a los paneles de Photoshop que puedes mover y acoplar?
¿Cómo agregas una nueva pestaña a un Tab Widget?
¿Qué propiedad del Stacked Widget controla qué página se muestra?
¿Cuál es la diferencia entre un Widget contenedor y un Frame?
¿Qué contenedor usarías para crear un asistente paso a paso (wizard)?
¿Para qué sirve el WebEngine View?

---

Módulo anterior: ← [Módulo 3: Widgets Básicos](02-widgets-basicos.md)

Siguiente módulo: → [Módulo 5: Layouts](04-layouts.md)

📝 Evaluación de Comprensión

Escribe tus respuestas y luego presiona el botón para comparar con las respuestas correctas.

1. ¿Cuál es la diferencia entre un Group Box y un Frame?

✅ Respuesta Correcta

Group Box tiene un marco visible con título y puede tener un checkbox para activar/desactivar todo el grupo. Frame es un contenedor con borde decorativo personalizable pero sin título ni checkbox.

2. ¿Cuándo usarías un Tab Widget y cuándo un Stacked Widget?

✅ Respuesta Correcta

Tab Widget cuando quieres pestañas visibles que el usuario puede cambiar directamente (como configuración por categorías). Stacked Widget cuando quieres navegación por páginas sin indicadores visibles (como wizards con botones Anterior/Siguiente).

3. ¿Qué contenedor usarías para un formulario que puede ser más alto que la ventana?

✅ Respuesta Correcta

Scroll Area, porque crea barras de desplazamiento automáticas cuando el contenido excede el tamaño visible.

4. ¿Qué propiedad del Group Box permite activar/desactivar todos los widgets dentro de él?

✅ Respuesta Correcta

La propiedad 'checkable' (junto con 'checked').

5. ¿Qué contenedor es similar a los paneles de Photoshop que puedes mover y acoplar?

✅ Respuesta Correcta

Dock Widget.

6. ¿Cómo agregas una nueva pestaña a un Tab Widget?

✅ Respuesta Correcta

Haciendo clic derecho en las pestañas del Tab Widget y seleccionando 'Insert Page'.

7. ¿Qué propiedad del Stacked Widget controla qué página se muestra?

✅ Respuesta Correcta

La propiedad 'currentIndex'.

8. ¿Cuál es la diferencia entre un Widget contenedor y un Frame?

✅ Respuesta Correcta

Widget es un contenedor básico invisible sin bordes ni decoración. Frame es un contenedor con borde decorativo personalizable (frameShape, frameShadow, lineWidth).

9. ¿Qué contenedor usarías para crear un asistente paso a paso (wizard)?

✅ Respuesta Correcta

Stacked Widget, porque permite navegar entre páginas sin pestañas visibles, ideal para wizards con botones Anterior/Siguiente.

10. ¿Para qué sirve el WebEngine View?

✅ Respuesta Correcta

Es un navegador web completo embebido en la aplicación. Permite cargar páginas web, HTML local o contenido dinámico. Es útil para mostrar documentación, ayuda online o contenido web dentro de la aplicación.

Módulo 4: Contenedores

---

Objetivo

Crear una ventana de configuración profesional con múltiples pestañas y contenedores.

---

Instrucciones

Crea un Dialog sin botones de 550x450 píxeles
windowTitle: "Configuración"
Fondo: styleSheet: background-color: #1a1a2e;
Agrega un Tab Widget que ocupe casi toda la ventana
Crea 3 pestañas: "General", "Apariencia", "Cuentas"

Pestaña "General":

Group Box "Información Personal"
Layout Vertical con:
Label "Nombre:" + Line Edit
Label "Email:" + Line Edit
Label "Idioma:" + Combo Box (Español, Inglés, Francés)

Pestaña "Apariencia":

Group Box "Tema Visual"
Label "Tema:" + Combo Box (Oscuro, Claro, Automático)
Group Box "Tipografía"
Label "Tamaño:" + Slider (min: 10, max: 24)
Frame como vista previa con Label "Vista previa del texto"

Pestaña "Cuentas":

List Widget con cuentas de ejemplo:
"juan@email.com"
"maria@email.com"
"carlos@email.com"
Push Button "Agregar cuenta" debajo

Aplica layouts a cada pestaña y contenedor
Renombra todos los widgets
Guarda como configuracion.ui
Presiona Ctrl+R para verificar

---

Resultado Esperado

Una ventana de configuración con 3 pestañas, cada una con Group Boxes organizados, campos de entrada y una lista de cuentas.

---

Checklist

[ ] Dialog de 550x450 con fondo oscuro
[ ] Tab Widget con 3 pestañas
[ ] Pestaña General con Group Box y 3 campos
[ ] Pestaña Apariencia con 2 Group Boxes y Frame de vista previa
[ ] Pestaña Cuentas con List Widget y botón
[ ] Layouts aplicados a todos los contenedores
[ ] Todos los widgets renombrados

Anterior: Módulo 3 Siguiente: Módulo 5

Módulo 4: Contenedores — Organizando el Lienzo

Objetivos de Aprendizaje

4.1 ¿Qué son los Contenedores?

¿Por qué usar contenedores?

4.2 Group Box

Características

Propiedades clave

Cómo usar un Group Box

4.3 Tab Widget (Pestañas)

Características

Propiedades clave

Cómo agregar/eliminar pestañas

Ejemplo de uso

4.4 Stacked Widget (Páginas Apiladas)

Características

Propiedades clave

Cómo agregar/eliminar páginas

Ejemplo: Wizard de 3 pasos

4.5 Scroll Area

Características

Propiedades clave

Cómo usar un Scroll Area

4.6 Frame

Propiedades clave

Ejemplos de uso

4.7 Widget (Contenedor Básico)

Cuándo usar un Widget contenedor

4.8 Tool Box

Características

Propiedades clave

Cómo agregar secciones

4.9 MDI Area

Características

Propiedades clave

4.10 WebEngine View

Características

Propiedades clave

4.11 Dock Widget

Características

Propiedades clave

4.12 Comparación de Contenedores

Ejercicio Práctico del Módulo

Recursos Adicionales

Evaluación de Comprensión

Ejercicio 4: Ventana de Configuración con Pestañas

Objetivo

Instrucciones

Pestaña "General":

Pestaña "Apariencia":

Pestaña "Cuentas":

Resultado Esperado

Checklist