En esta página

Estilo de los menús y las vistas de elementos

Esta página forma parte de la Referencia de estilos de widgets. Para obtener una explicación sobre los árboles de elementos, las capturas de pantalla y las tablas, consulta esa página. Los indicadores de estado y los miembros comunes que establece cada widget se enumeran en «Cómo dibuja un estilo un widget».

QMenu mantiene una lista de acciones y dibuja cada una de ellas como un elemento de menú. En un evento de pintura, dibuja el panel del menú, a continuación cada elemento con un « CE_MenuItem » y un « QStyleOptionMenuItem », y por último el marco. Los elementos de menú no tienen un elemento de etiqueta independiente, por lo que « CE_MenuItem » dibuja la marca de verificación, el icono, el texto, el atajo y la flecha del submenú.

  • PE_PanelMenu, el fondo
  • CE_MenuItem, una vez por acción (PM_SmallIconSize)
    • PE_IndicatorMenuCheckMark, para un elemento marcado. Muchos estilos utilizan en su lugar PE_IndicatorCheckBox y PE_IndicatorRadioButton.
    • PE_IndicatorArrowRight o PE_IndicatorArrowLeft, para un elemento que abre un submenú
  • CE_MenuScroller (PM_MenuScrollerHeight), cuando el menú es demasiado alto para la pantalla y SH_Menu_Scrollable está activado
  • CE_MenuTearoff (PM_MenuTearoffHeight), para un menú tear-off
  • PE_FrameMenu (PM_MenuPanelWidth), el marco, con un QStyleOptionFrame cuyo lineWidth es PM_MenuPanelWidth
  • CE_MenuEmptyArea, para el espacio no ocupado por elementos o por el marco

QMenu se encarga de distribuir los elementos por sí mismo, utilizando PM_MenuHMargin, PM_MenuVMargin, PM_MenuPanelWidth y PM_MenuDesktopFrameWidth. También consulta numerosas sugerencias de SH_Menu_, como SH_Menu_SubMenuPopupDelay, SH_Menu_MouseTracking y SH_Menu_Mask.

Menú con un elemento con icono, un elemento marcado, un elemento de submenú, un elemento desactivado y un elemento sin formato, todos ellos con contorno

QMenu restablece el estado tras llamar a ` initFrom()`, de modo que los elementos solo contienen ` State_Enabled`, ` State_Active` y los indicadores de esta tabla:

EstadoSe establece cuando
State_SelectedEl elemento está resaltado y no es un separador.
State_SunkenEl elemento está pulsado.
State_DownArrowEl elemento es un control de desplazamiento que desplaza el menú hacia abajo.
State_EnabledLa acción está habilitada. Las acciones deshabilitadas desactivan este indicador incluso cuando el menú está habilitado.

Los miembros de ` QStyleOptionMenuItem ` son:

MiembroDescripción
menuItemTypeUn valor de « MenuItemType »: un elemento normal, el elemento predeterminado, un separador, un submenú, un elemento desplazable, un elemento desprendible, un margen o un área vacía.
checkTypeUn valor de « CheckType »: no marcable, exclusivo o no exclusivo.
checkedIndica si el elemento está marcado.
menuHasCheckableItemsIndica si al menos un elemento del menú es seleccionable, de modo que el estilo pueda reservar espacio para las marcas de selección.
menuRectEl rectángulo que abarca todo el menú.
textEl texto del elemento. Un carácter de tabulación separa el texto del atajo.
iconEl icono del elemento.
maxIconWidthEl ancho del icono más ancho del menú.
reservedShortcutWidthEl ancho reservado para la columna de accesos directos.
fontLa fuente del texto del elemento.

En el caso de CE_MenuScroller y CE_MenuTearoff, el menú solo establece menuItemType, checkType, maxIconWidth y reservedShortcutWidth. CE_MenuEmptyArea también establece menuRect.

QMenuBar dibuja cada título de menú con « CE_MenuBarItem » y « QStyleOptionMenuItemV2 », el espacio tras el último título con « CE_MenuBarEmptyArea », y su panel con « PE_PanelMenuBar » y « QStyleOptionFrame ». Los menús desplegables son « QMenu»; véase Menús.

  • CE_MenuBarItem, una vez por menú (PM_SmallIconSize)
  • PE_PanelMenuBar (PM_MenuBarPanelWidth)
  • CE_MenuBarEmptyArea

La barra de menús distribuye los elementos con PM_MenuBarItemSpacing, PM_MenuBarHMargin y PM_MenuBarVMargin, y ajusta su tamaño con CT_MenuBarItem. El «painter» que QMenuBar pasa al panel se recorta a las cuatro franjas del borde, cada una de PM_MenuBarPanelWidth de ancho, de modo que el panel solo puede dibujar el borde. El «painter» del área vacía se recorta al espacio que dejan los elementos y el borde. La barra consulta SH_MenuBar_MouseTracking, SH_MenuBar_AltKeyNavigation y SH_DrawMenuBarSeparator.

En macOS, QMenuBar utiliza la barra de menús nativa por defecto y no dibuja nada. Llama a QMenuBar::setNativeMenuBar() para que utilice el estilo.

Barra de menús con los menús «Archivo», «Edición», «Ver» y «Ayuda», con cada elemento y el espacio en blanco resaltados

QMenuBar rellena la propia opción en lugar de llamar a initFrom(). Establece State_Enabled cuando la barra está habilitada, y estos indicadores en los elementos:

EstadoSe establece cuando
State_SelectedEl elemento está resaltado.
State_SunkenEl menú del elemento está abierto.
State_HasFocusLa barra de menús tiene el foco o contiene un elemento activo.
State_MouseOverEl ratón se encuentra sobre el elemento.

La barra de menús utiliza estos miembros de ` QStyleOptionMenuItem`:

MiembroDescripción
menuRectEl rectángulo de toda la barra de menús.
textEl título del menú.
iconEl icono del menú. Son pocos los estilos que lo dibujan.

Para el panel, « QStyleOptionFrame::lineWidth » se establece en « PM_MenuBarPanelWidth » y « midLineWidth » en 0.

Encabezados de la vista de elementos

QHeaderView dibuja cada sección de encabezado con « CE_Header » y « QStyleOptionHeaderV2 ». « QCommonStyle » lo divide en el fondo de la sección, la etiqueta y el indicador de ordenación:

  • CE_Header, una vez por sección (PM_HeaderMargin)
    • CE_HeaderSection
    • CE_HeaderLabel (SE_HeaderLabel)
    • PE_IndicatorHeaderArrow (SE_HeaderArrow, PM_HeaderMarkSize), para la sección ordenada
  • CE_HeaderEmptyArea, para el espacio tras la última sección

La vista de encabezado ajusta el tamaño de sus secciones con ` CT_HeaderSection ` y utiliza ` PM_HeaderGripMargin ` para el área en la que el usuario puede arrastrar el límite de una sección. ` QTableView ` dibuja el botón en la esquina superior izquierda, donde se unen los dos encabezados, como un ` CE_Header`. La sugerencia ` SH_Header_ArrowAlignment ` coloca el indicador de ordenación.

Tabla con las secciones de encabezado «Nombre», «Tamaño» y «Modificado», en la que se muestran con contorno las secciones, las etiquetas y el indicador de ordenación

El encabezado establece estos indicadores de estado en una sección:

EstadoSe establece cuando
State_RaisedSiempre. El encabezado lo establece para todas las secciones.
State_HorizontalSe trata de la cabecera horizontal situada encima de la vista.
State_SunkenSe pulsa la sección, o bien la sección está seleccionada y la opción « highlightSections » está activada.
State_OnSe selecciona un elemento de la sección y la opción « highlightSections » está activada.
State_MouseOverEl ratón se encuentra sobre la sección. Configurar solo cuando « sectionsClickable » esté activado.

Los miembros de « QStyleOptionHeader » son:

MiembroDescripción
sectionEl índice lógico de la sección.
textoEl texto de la sección.
textAlignmentLa alineación del texto de la sección.
iconoEl icono de la sección.
iconAlignmentLa alineación del icono en la sección.
posiciónUn valor de « SectionPosition »: la posición de la sección con respecto a las demás secciones.
selectedPositionUn valor de « SelectedPosition »: la posición de la sección seleccionada con respecto a esta.
sortIndicatorUn valor de ` SortIndicator `: ningún indicador o la dirección de la flecha de ordenación.
orientationIndica si se trata del encabezado horizontal situado encima de la vista o del encabezado vertical situado junto a ella.

QStyleOptionHeaderV2 Añade « textElideMode », el modo de elisión para el texto que no cabe, y « isSectionDragTarget », que se establece en la sección sobre la que se va a soltar una sección arrastrada.

Indicadores de ramas del árbol

QTreeView dibuja los indicadores de rama, las líneas y flechas que muestran la relación entre los nodos, con ` PE_IndicatorBranch`. Dibuja un indicador por cada nivel de sangría delante de cada elemento, por lo que un elemento profundamente anidado tiene varios. El árbol también dibuja el fondo de cada fila con ` PE_PanelItemViewRow ` y sangra los niveles mediante ` PM_TreeViewIndentation`.

Ambos elementos aceptan un ` QStyleOptionViewItem`, por lo que un estilo también puede leer la paleta de colores, la fuente y el indicador de filas alternas de la fila. El tipo de rama se codifica en los indicadores de estado:

EstadoSe establece cuando
State_ItemEl indicador pertenece al elemento de esta fila, en lugar de a un antecesor. Dibuja aquí el conector horizontal.
State_ChildrenEl elemento tiene elementos secundarios, por lo que el indicador muestra una flecha de expansión o colapso.
State_OpenEl elemento está expandido.
State_SiblingEl nodo de este nivel tiene un elemento hermano por debajo, por lo que una línea vertical continúa hacia abajo.

Se dibuja un indicador sin ninguna de estas marcas para un nivel cuyo nodo no tiene ningún nodo hermano por debajo; el estilo no dibuja nada en ese lugar.

Vista en árbol con carpetas desplegadas y contraídas, en la que las celdas indicadoras de las ramas aparecen resaltadas y etiquetadas con sus banderas de estado

Elementos de la vista de elementos

Los delegados se encargan de dibujar los elementos en las vistas de elementos. El delegado predeterminado de Qt, ` QStyledItemDelegate`, dibuja ` CE_ItemViewItem ` con ` QStyleOptionViewItem ` y calcula el tamaño del elemento con ` CT_ItemViewItem`, por lo que un estilo controla el aspecto de los elementos sin necesidad de un delegado asociado. ` QCommonStyle ` divide el elemento en el fondo, el indicador de selección, la decoración, el texto y el marco de foco:

  • CE_ItemViewItem
    • PE_PanelItemViewItem
    • PE_IndicatorItemViewItemCheck (SE_ItemViewItemCheckIndicator)
    • La decoración, dibujada con paint() (SE_ItemViewItemDecoration)
    • El texto, maquetado y dibujado mediante ` QCommonStyle ` con elisión y ajuste al ancho (SE_ItemViewItemText)
    • PE_FrameFocusRect (SE_ItemViewItemFocusRect)

Las vistas consultan sugerencias de vista de elementos como SH_ItemView_ShowDecorationSelected, SH_ItemView_ActivateItemOnSingleClick y SH_ItemView_ArrowKeysNavigateIntoChildren. Para admitir tipos de datos o roles que QStyledItemDelegate no gestiona, escribe un delegado personalizado; consulta Programación de modelo/vista.

Los indicadores de estado y los miembros de QStyleOptionViewItem se describen en la documentación de la clase; los más importantes son State_Selected, State_HasFocus, checkState, decorationPosition, displayAlignment, features, icon, text y viewItemPosition.

Véase también «Referencia de estilos de widgets», «Estilos de botones y widgets de entrada», «Estilos de contenedores y ventanas» y QStyledItemDelegate.

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