Stylisation des boutons et des widgets de saisie
Cette page fait partie de la Référence sur le style des widgets. Pour une explication des arborescences d'éléments, des captures d'écran et des 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 boutons
QPushButton dessine un élément de contrôle unique, CE_PushButton, avec un QStyleOptionButton. QCommonStyle le divise en trois parties : le biseau, le libellé et le cadre de focus :
CE_PushButtonCE_PushButtonBevel(PM_ButtonDefaultIndicator,PM_MenuButtonIndicator)PE_FrameDefaultButton, pour le bouton par défautPE_PanelButtonCommandPE_IndicatorArrowDown, pour un bouton avec un menu
CE_PushButtonLabel(SE_PushButtonContents,PM_ButtonShiftHorizontal,PM_ButtonShiftVertical,PM_ButtonIconSize)PE_FrameFocusRect(SE_PushButtonFocusRect)
Le bouton calcule son indication de taille à l’aide de CT_PushButton et PM_ButtonMargin. Les limites des éléments varient selon les styles. Dans QCommonStyle, PE_FrameDefaultButton récupère l’intégralité du rectangle biseauté, tout comme PE_PanelButtonCommand, sauf sur un bouton à valeur par défaut automatique, où le panneau se rétrécit de PM_ButtonDefaultIndicator de chaque côté.
QPushButton définit les indicateurs d’état suivants :
| État | Activé lorsque |
|---|---|
State_Sunken | Le bouton est enfoncé ou son menu est affiché. |
State_On | Le bouton est coché. |
State_Raised | Le bouton n'est ni à plat ni enfoncé. |
Les autres membres de l'QStyleOptionButton e sont :
| Membre | Description |
|---|---|
| caractéristiques | Indicateurs de l'énumération « QStyleOptionButton::ButtonFeature » qui décrivent le bouton : plat, par défaut, par défaut automatique, avec un menu ou un bouton de lien de commande. |
| icône | L'QIcon du bouton, le cas échéant. |
| iconSize | La taille de l'icône. |
| text | Texte du bouton. |
Les cases à cocher et les boutons radio
QCheckBox et QRadioButton ont des structures identiques. Les deux utilisent QStyleOptionButton et dessinent un élément de contrôle, CE_CheckBox ou CE_RadioButton. QCommonStyle dessine l’indicateur, l’étiquette et le cadre de sélection :
CE_CheckBoxPE_IndicatorCheckBox(SE_CheckBoxIndicator,PM_IndicatorWidth,PM_IndicatorHeight)CE_CheckBoxLabel(SE_CheckBoxContents,PM_CheckBoxLabelSpacing)PE_FrameFocusRect(SE_CheckBoxFocusRect)
CE_RadioButtonPE_IndicatorRadioButton(SE_RadioButtonIndicator,PM_ExclusiveIndicatorWidth,PM_ExclusiveIndicatorHeight)CE_RadioButtonLabel(SE_RadioButtonContents,PM_RadioButtonLabelSpacing)PE_FrameFocusRect(SE_RadioButtonFocusRect)
Les indications de taille utilisent CT_CheckBox et CT_RadioButton. Le guide « Styling a Checkbox: A Walkthrough » retrace le processus de dessin d’une case à cocher à travers le code du widget et celui de QCommonStyle.
Les boutons définissent les indicateurs d’état suivants :
| État | Activé lorsque |
|---|---|
State_Sunken | Le bouton est enfoncé. La zone cliquable correspond à SE_CheckBoxClickRect ou SE_RadioButtonClickRect, ce qui, dans QCommonStyle, recouvre à la fois le libellé et l’indicateur. |
State_NoChange | La case à cocher est partiellement cochée (case à cocher à trois états). |
State_On | Le bouton est coché. |
State_Off | Le bouton n’est pas coché. |
Les autres éléments de QStyleOptionButton sont répertoriés sous Boutons poussoirs.
Boutons d’outils
QToolButton dessine un contrôle complexe, CC_ToolButton, avec un QStyleOptionToolButton. Il comporte deux sous-contrôles : le bouton lui-même et, pour un bouton doté d’ a menu button, l’indicateur de menu.
CC_ToolButtonSC_ToolButtonPE_PanelButtonTool(PM_DefaultFrameWidth)PE_FrameFocusRectCE_ToolButtonLabel(PM_ButtonShiftHorizontal,PM_ButtonShiftVertical)
SC_ToolButtonMenu(PM_MenuButtonIndicator)PE_IndicatorButtonDropDownPE_IndicatorArrowDown
Pour les fenêtres contextuelles de instant et delayed, il n’y a pas de sous-contrôle de menu ; par conséquent, QCommonStyle affiche à la place PE_IndicatorArrowDown dans le coin du rectangle du bouton. L’indicateur de taille utilise CT_ToolButton, et le bouton consulte SH_ToolButton_PopupDelay et SH_ToolButtonStyle. Les boutons d’outils d’une barre d’outils reprennent la taille de leur icône depuis la barre d’outils. Les boutons autonomes utilisent PM_ButtonIconSize.
QToolButton définit les indicateurs d’état suivants :
| État | Activé lorsque |
|---|---|
State_AutoRaise | La propriété « autoRaise » est définie. |
State_Raised | Le bouton n’est ni coché ni enfoncé. La méthode ` QCommonStyle ` désactive ensuite cet indicateur si la propriété ` State_AutoRaise ` est définie et que la souris ne se trouve pas au-dessus du bouton. |
State_Sunken | Le bouton est enfoncé ou son menu est affiché. |
State_On | Le bouton est cochable et coché. |
Les autres membres de ` QStyleOptionToolButton ` sont :
| Membre | Description |
|---|---|
| arrowType | Valeur de l'Qt::ArrowType qui indique la direction de la flèche dessinée à la place d'une icône, le cas échéant. |
| features | Indicateurs de l'énumération « QStyleOptionToolButton::ToolButtonFeature » : indique si le bouton affiche une flèche, comporte un bouton de menu ou dispose d'une fenêtre contextuelle à ouverture différée. |
| font | QFont de l'étiquette du bouton. |
| icon | L'QIcon du bouton. |
| iconSize | La taille de l'icône. |
| pos | La position du bouton, telle qu'elle est fournie par la fonction ` QWidget::pos()`. |
| text | Le texte du bouton. |
| toolButtonStyle | Une valeur de type « Qt::ToolButtonStyle » qui détermine si le bouton affiche l’icône, le texte ou les deux. |
Listes déroulantes
QComboBox dessine le bouton et l’étiquette à l’aide de ` CC_ComboBox ` et ` CE_ComboBoxLabel`, tous deux avec un ` QStyleOptionComboBox`. ` QCommonStyle ` omet le texte de l’étiquette pour une liste déroulante modifiable, où l’enfant ` QLineEdit ` se charge de l’afficher. La liste contextuelle est une vue d’élément dessinée par un délégué, mais le style contrôle sa taille et sa position à l’aide de SC_ComboBoxListBoxPopup. Pour une zone modifiable, le style détermine l’emplacement de la zone de saisie à l’aide de SC_ComboBoxEditField; le champ lui-même est un élément enfant de type QLineEdit.
CC_ComboBox(PM_ComboBoxFrameWidth)SC_ComboBoxFrameSC_ComboBoxArrow(PE_IndicatorArrowDown)SC_ComboBoxEditFieldSC_ComboBoxListBoxPopup, pour le positionnement de la fenêtre contextuelle
CE_ComboBoxLabel(SC_ComboBoxEditField)
L'indicateur de taille utilise CT_ComboBox. Les indicateurs de style tels que SH_ComboBox_Popup, SH_ComboBox_PopupFrameStyle et SH_ComboBox_UseNativePopup déterminent l'apparence et le comportement de la fenêtre contextuelle.
QComboBox définit les indicateurs d'état suivants :
| État | Activé lorsque |
|---|---|
State_Selected | La zone n'est pas modifiable et a le focus. |
State_Sunken | SC_ComboBoxArrow est active. |
State_On | La liste déroulante est visible. |
Les autres membres de l'QStyleOptionComboBox e sont :
| Membre | Description |
|---|---|
| currentIcon | L'icône de l'élément actuel. |
| currentText | Le texte de l'élément actuel. |
| editable | Indique si la liste déroulante est modifiable. |
| frame | Indique si la liste déroulante possède un cadre. |
| iconSize | Taille de l'icône de l'élément actuel. |
| popupRect | Le rectangle englobant de la liste contextuelle. |
| textAlignment | L'alignement du texte dans l'étiquette. |
Boîtes de sélection
QSpinBox, QDoubleSpinBox et QDateTimeEdit dessinent CC_SpinBox à l'aide d'un QStyleOptionSpinBox. Le champ d'édition est un enfant de type QLineEdit dont le style renvoie la géométrie pour SC_SpinBoxEditField.
CC_SpinBox(PM_SpinBoxFrameWidth)SC_SpinBoxFrameSC_SpinBoxUpPE_PanelButtonBevelPE_IndicatorSpinUpouPE_IndicatorSpinPlus, selon buttonSymbols
SC_SpinBoxDownPE_PanelButtonBevelPE_IndicatorSpinDownouPE_IndicatorSpinMinus
SC_SpinBoxEditField
Un style n’est pas obligé de dessiner les panneaux du bouton avec PE_PanelButtonBevel. L’indication de taille utilise CT_SpinBox, et le widget consulte des indications telles que SH_SpinBox_ButtonsInsideFrame, SH_SpinBox_StepModifier et SH_SpinControls_DisableOnBounds.
La zone de saisie à molette active cet indicateur d’état :
| État | Activé lorsque |
|---|---|
State_Sunken | le sous-contrôle « SC_SpinBoxUp » ou « SC_SpinBoxDown » est actionné. |
Les autres éléments de QStyleOptionSpinBox sont :
| Élément | Description |
|---|---|
| frame | Indique si la zone de saisie à rouleau affiche un cadre. |
| buttonSymbols | Valeur de type « QAbstractSpinBox::ButtonSymbols » permettant de sélectionner les symboles affichés sur les boutons : flèches, signes plus et moins, ou aucun. |
| stepEnabled | QAbstractSpinBox::StepEnabled Indicateurs précisant quels boutons permettent de modifier la valeur par incréments. Un bouton ne permettant pas de modifier la valeur par incréments est affiché comme désactivé. |
Curseurs
QSlider affiche une CC_Slider avec une QStyleOptionSlider. Il calcule sa taille indicative à partir de PM_SliderThickness et CT_Slider, et sa taille minimale indicative à partir de PM_SliderLength.
CC_Slider(PM_SliderLength,PM_SliderControlThickness,PM_SliderTickmarkOffset,PM_SliderSpaceAvailable)SC_SliderGrooveSC_SliderHandleSC_SliderTickmarks
QCommonStyle ne dessine que les repères ; la rainure et la poignée dépendent toujours du style. Les styles ne sont pas tenus de renvoyer un rectangle pour SC_SliderTickmarks. Fusion renvoie un rectangle vide et dessine les repères sous la poignée, dans la zone indiquée sur la capture d’écran. Le widget consulte SH_Slider_AbsoluteSetButtons, SH_Slider_PageSetButtons et SH_Slider_SnapToValue.
QDial utilise la même option et dessine CC_Dial avec les sous-contrôles SC_DialGroove, SC_DialHandle et SC_DialTickmarks.
QSlider définit les indicateurs d'état suivants :
| État | Activé lorsque |
|---|---|
State_Horizontal | Le curseur est horizontal. |
State_Sunken | Un sous-contrôle quelconque est enfoncé, y compris la rainure. activeSubControls indique lequel. |
QStyleOptionSlider gère tous les « QAbstractSlider». Ses membres sont :
| Membre | Description |
|---|---|
| orientation | Une valeur d'Qt::Orientation: verticale ou horizontale. |
| minimum | La valeur minimale. |
| maximum | La valeur maximale. |
| tickPosition | Valeur de type « QSlider::TickPosition » indiquant l'emplacement des graduations. |
| tickInterval | Distance entre les graduations, exprimée en valeurs du curseur. |
| upsideDown | Direction dans laquelle la valeur augmente. Tous les curseurs abstraits utilisent ce membre à la place de ` QStyleOption::direction`. |
| sliderPosition | La position du curseur, exprimée en valeur de curseur. Elle est égale à ` sliderValue ` lorsque ` tracking ` est activé ; sinon, la valeur n'est mise à jour que lorsque le curseur est relâché. |
| sliderValue | La valeur actuelle. |
| singleStep | Quantité de variation de la valeur en une seule étape, par exemple lors de l'appui sur une touche fléchée. |
| pageStep | Valeur de variation de la valeur lors d’un pas de page, par exemple un clic dans la rainure. |
| notchTarget | Distance souhaitée entre les crans, en pixels. Utilisée par QDial. |
| dialWrapping | Indique si le cadran effectue une boucle. Utilisé par QDial. |
| keyboardModifiers | Les touches de modification qui étaient enfoncées lors du dernier événement de souris, pour les styles où les touches de modification modifient le comportement du glissement. |
Barres de défilement
QScrollBar dessine CC_ScrollBar avec un QStyleOptionSlider. Lorsque l'utilisateur fait glisser le curseur, la barre ramène la valeur à sa position initiale si le pointeur s'éloigne de plus de PM_MaximumDragDistance en dehors de la barre.
CC_ScrollBar(PM_ScrollBarExtent,PM_ScrollBarSliderMin)SC_ScrollBarGrooveSC_ScrollBarSubLine(CE_ScrollBarSubLine)SC_ScrollBarAddLine(CE_ScrollBarAddLine)SC_ScrollBarSubPage(CE_ScrollBarSubPage)SC_ScrollBarAddPage(CE_ScrollBarAddPage)SC_ScrollBarFirst(CE_ScrollBarFirst)SC_ScrollBarLast(CE_ScrollBarLast)SC_ScrollBarSlider(CE_ScrollBarSlider)PE_FrameFocusRect
QCommonStyle dessine chaque sous-contrôle avec l’élément de contrôle du même nom. Certains styles dessinent les indicateurs de ligne avec PE_IndicatorArrowUp et les autres primitives de flèche, ainsi que les zones de page avec PE_PanelButtonBevel; cela dépend du style utilisé. SC_ScrollBarFirst et SC_ScrollBarLast sont des boutons facultatifs qui permettent d’accéder aux extrémités ; la plupart des styles renvoient un rectangle vide pour ceux-ci. L’indication de taille utilise CT_ScrollBar, et les indications de comportement incluent SH_ScrollBar_LeftClickAbsolutePosition, SH_ScrollBar_ContextMenu et SH_ScrollBar_Transient.
QScrollBar définit les indicateurs d’état suivants :
| État | Activé lorsque |
|---|---|
State_Horizontal | La barre de défilement est horizontale. |
State_Sunken | Un sous-contrôle est enfoncé et le pointeur ne l'a pas quitté. |
State_On | La barre est une barre de défilement temporaire actuellement affichée. |
Les membres de l'QStyleOptionSlider e sont répertoriés sous « Sliders ». Les propriétés sliderPosition, sliderValue, pageStep et upsideDown déterminent la taille et la position de la poignée.
Barres de progression
QProgressBar dessine un élément de contrôle, CE_ProgressBar, avec un QStyleOptionProgressBar. QCommonStyle le divise en trois parties : la rainure, le contenu et l’étiquette :
CE_ProgressBarCE_ProgressBarGroove(SE_ProgressBarGroove)CE_ProgressBarContents(SE_ProgressBarContents,PM_ProgressBarChunkWidth)CE_ProgressBarLabel(SE_ProgressBarLabel)
Les styles qui affichent le contenu sous forme d’une rangée de blocs utilisent PE_IndicatorProgressChunk. Dans QCommonStyle et Fusion, le cadre, le contenu et l’étiquette occupent tous la barre entière ; l’étiquette est du texte centré superposé au contenu, son rectangle ne constitue donc pas une zone distincte. L'indication de taille utilise CT_ProgressBar. Un indicateur d'activité, c’est-à-dire une barre dont les valeurs minimale et maximale sont toutes deux égales à zéro, est animé par le style.
QProgressBar définit cet indicateur d’état :
| État | Activé lorsque |
|---|---|
State_Horizontal | La barre est horizontale. |
Les autres membres de l'QStyleOptionProgressBar sont :
| Membre | Description |
|---|---|
| minimum | La valeur minimale. |
| maximum | La valeur maximale. |
| progression | La valeur actuelle. |
| text | Le texte de l'étiquette. |
| textAlignment | L'alignement du texte dans l'étiquette. |
| textVisible | Indique si l'étiquette est affichée. |
| invertedAppearance | Indique si la barre se remplit à partir de l’extrémité opposée, par exemple de droite à gauche pour une barre horizontale. |
| bottomToTop | Indique si le libellé d’une barre verticale est pivoté pour se lire de bas en haut. |
Voir également Référence sur les styles de widgets, Personnalisation des conteneurs et des fenêtres, et Personnalisation des menus et des vues d'éléments.
© 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.
