Mise en forme des menus et des vues d'éléments

Cette page fait partie du Guide de référence sur le style des widgets. Pour obtenir des explications sur les arborescences d’éléments, les captures d’écran et les tableaux, consultez cette page. Les indicateurs d’état et les membres communs définis par chaque widget sont répertoriés dans la section « Comment un style dessine un widget ».

Les menus

QMenu conserve une liste d’actions et dessine chacune d’elles sous forme d’élément de menu. Lors d’un événement de dessin, il dessine le panneau du menu, puis chaque élément à l’aide de ` CE_MenuItem ` et de ` QStyleOptionMenuItem`, et enfin le cadre. Les éléments de menu ne disposent pas d’élément d’étiquette distinct ; ` CE_MenuItem ` dessine donc la coche, l’icône, le texte, le raccourci et la flèche de sous-menu.

• PE_PanelMenu, l’arrière-plan
• CE_MenuItem, une fois par action (PM_SmallIconSize)
  • PE_IndicatorMenuCheckMark, pour un élément coché. De nombreux styles utilisent plutôt PE_IndicatorCheckBox et PE_IndicatorRadioButton.
  • PE_IndicatorArrowRight ou PE_IndicatorArrowLeft, pour un élément qui ouvre un sous-menu
• CE_MenuScroller (PM_MenuScrollerHeight), lorsque le menu est trop haut pour tenir à l’écran et que SH_Menu_Scrollable est défini
• CE_MenuTearoff (PM_MenuTearoffHeight), pour un menu tear-off
• PE_FrameMenu (PM_MenuPanelWidth), le cadre, avec une QStyleOptionFrame dont l’ lineWidth est PM_MenuPanelWidth
• CE_MenuEmptyArea, pour l’espace non occupé par les éléments ou le cadre

QMenu organise lui-même les éléments, en utilisant PM_MenuHMargin, PM_MenuVMargin, PM_MenuPanelWidth et PM_MenuDesktopFrameWidth. Il consulte également de nombreuses indications de SH_Menu_, telles que SH_Menu_SubMenuPopupDelay, SH_Menu_MouseTracking et SH_Menu_Mask.

QMenu réinitialise l’état après l’appel de ` initFrom()`, de sorte que les éléments ne contiennent que ` State_Enabled`, ` State_Active` et les indicateurs figurant dans ce tableau :

Les membres de ` QStyleOptionMenuItem ` sont :

Pour CE_MenuScroller et CE_MenuTearoff, le menu ne définit que menuItemType, checkType, maxIconWidth et reservedShortcutWidth. CE_MenuEmptyArea définit également menuRect.

Barres de menus

QMenuBar dessine chaque titre de menu avec CE_MenuBarItem et un QStyleOptionMenuItemV2, l’espace après le dernier titre avec CE_MenuBarEmptyArea, et son panneau avec PE_PanelMenuBar et un QStyleOptionFrame. Les menus déroulants sont des QMenu; voir Menus.

• CE_MenuBarItem, une fois par menu (PM_SmallIconSize)
• PE_PanelMenuBar (PM_MenuBarPanelWidth)
• CE_MenuBarEmptyArea

La barre de menus dispose les éléments à l’aide de PM_MenuBarItemSpacing, PM_MenuBarHMargin et PM_MenuBarVMargin, et les redimensionne avec CT_MenuBarItem. Le peintre que QMenuBar transmet pour le panneau est découpé aux quatre bandes de bordure, chacune d’une largeur de PM_MenuBarPanelWidth, de sorte que le panneau ne peut peindre que la bordure. Le peintre pour la zone vide est découpé à l’espace restant après les éléments et la bordure. La barre consulte SH_MenuBar_MouseTracking, SH_MenuBar_AltKeyNavigation et SH_DrawMenuBarSeparator.

Sous macOS, QMenuBar utilise par défaut la barre de menus native et ne dessine rien. Appelez QMenuBar::setNativeMenuBar() pour lui faire appliquer le style.

QMenuBar remplit l’option elle-même plutôt que d’appeler ` initFrom()`. Elle définit ` State_Enabled ` lorsque la barre est activée, ainsi que ces indicateurs sur les éléments :

La barre de menu utilise les membres suivants de l'QStyleOptionMenuItem:

Pour le panneau, la propriété « QStyleOptionFrame::lineWidth » est définie sur « PM_MenuBarPanelWidth » et la propriété « midLineWidth » sur 0.

En-têtes de la vue des éléments

QHeaderView dessine chaque en-tête de section avec ` CE_Header ` et un ` QStyleOptionHeaderV2`. ` QCommonStyle ` le divise en trois parties : l’arrière-plan de la section, le libellé et l’indicateur de tri :

• CE_Header, une fois par section (PM_HeaderMargin)
  • CE_HeaderSection
  • CE_HeaderLabel (SE_HeaderLabel)
  • PE_IndicatorHeaderArrow (SE_HeaderArrow, PM_HeaderMarkSize), pour la section triée
• CE_HeaderEmptyArea, pour l'espace après la dernière section

La vue d’en-tête dimensionne ses sections à l’aide de ` CT_HeaderSection ` et utilise ` PM_HeaderGripMargin ` pour la zone dans laquelle l’utilisateur peut faire glisser la limite d’une section. ` QTableView ` dessine le bouton dans le coin supérieur gauche, à la jonction des deux en-têtes, sous la forme d’un ` CE_Header`. L’indice ` SH_Header_ArrowAlignment ` place l’indicateur de tri.

L'en-tête définit ces indicateurs d'état sur une section :

Les membres de l’ QStyleOptionHeader sont :

QStyleOptionHeaderV2 ajoute « textElideMode », le mode d'élision pour le texte qui ne tient pas, et « isSectionDragTarget », qui est défini sur la section sur laquelle une section glissée est sur le point d'être déposée.

Indicateurs de branches de l’arborescence

QTreeView dessine les indicateurs de branche, c’est-à-dire les lignes et les flèches qui montrent la relation entre les nœuds, à l’aide de ` PE_IndicatorBranch`. Il dessine un indicateur par niveau d’indentation devant chaque élément ; ainsi, un élément profondément imbriqué en comporte plusieurs. L’arborescence dessine également l’arrière-plan de chaque ligne à l’aide de ` PE_PanelItemViewRow ` et indente les niveaux à l’aide de ` PM_TreeViewIndentation`.

Ces deux éléments acceptent un paramètre « QStyleOptionViewItem », ce qui permet à un style de lire également la palette de couleurs, la police et l’indicateur « alternate-row » de la ligne. Le type de branche est codé dans les indicateurs d’état :

Un indicateur ne comportant aucun de ces drapeaux est tracé pour un niveau dont le nœud n’a pas de nœud frère en dessous ; le style ne trace rien à cet endroit.

Éléments de la vue d'élément

Les délégués dessinent les éléments dans les vues d’éléments. Le délégué par défaut de Qt, QStyledItemDelegate, dessine CE_ItemViewItem à l’aide de QStyleOptionViewItem et calcule la taille de l’élément avec CT_ItemViewItem; ainsi, un style contrôle l’apparence des éléments sans délégué associé. QCommonStyle divise l’élément en plusieurs parties : l’arrière-plan, l’indicateur de sélection, la décoration, le texte et le cadre de focus :

• CE_ItemViewItem
  • PE_PanelItemViewItem
  • PE_IndicatorItemViewItemCheck (SE_ItemViewItemCheckIndicator)
  • La décoration, dessinée avec paint() (SE_ItemViewItemDecoration)
  • Le texte, mis en page et dessiné par ` QCommonStyle ` avec élision et retour à la ligne (SE_ItemViewItemText)
  • PE_FrameFocusRect (SE_ItemViewItemFocusRect)

Les vues consultent les indications de vue d’élément telles que SH_ItemView_ShowDecorationSelected, SH_ItemView_ActivateItemOnSingleClick et SH_ItemView_ArrowKeysNavigateIntoChildren. Pour prendre en charge les types de données ou les rôles que QStyledItemDelegate ne gère pas, écrivez un délégué personnalisé ; voir Programmation modèle/vue.

Les indicateurs d’état et les membres de QStyleOptionViewItem sont décrits dans la documentation de la classe ; les plus importants sont State_Selected, State_HasFocus, checkState, decorationPosition, displayAlignment, features, icon, text et viewItemPosition.