Styling Buttons and Input Widgets

The style elements, states, and options of push buttons, checkboxes, radio buttons, tool buttons, combo boxes, spin boxes, sliders, scroll bars, and progress bars.

This page is part of the Widget Style Reference . For an explanation of the element trees, screenshots, and tables, see that page. The common state flags and members that every widget sets are listed in How a Style Draws a Widget .

Push buttons

QPushButton draws a single control element, CE_PushButton, with a QStyleOptionButton . QCommonStyle splits it into the bevel, the label, and the focus frame:

• CE_PushButton

  • CE_PushButtonBevel (PM_ButtonDefaultIndicator, PM_MenuButtonIndicator)

    • PE_FrameDefaultButton, for the default button

    • PE_PanelButtonCommand

    • PE_IndicatorArrowDown, for a button with a menu

  • CE_PushButtonLabel (SE_PushButtonContents, PM_ButtonShiftHorizontal, PM_ButtonShiftVertical, PM_ButtonIconSize)

  • PE_FrameFocusRect (SE_PushButtonFocusRect)

The button calculates its size hint with CT_PushButton and PM_ButtonMargin. Element bounds vary between styles. In QCommonStyle , PE_FrameDefaultButton gets the whole bevel rectangle, and so does PE_PanelButtonCommand, except on an auto-default button, where the panel shrinks by PM_ButtonDefaultIndicator on each side.

QPushButton sets these state flags:

State	Set when
State_Sunken	The button is pressed, or its menu is shown.
State_On	The button is checked.
State_Raised	The button isn’t flat and isn’t pressed.

The other members of QStyleOptionButton are:

Member	Description
features	Flags of the ButtonFeature enum that describe the button: flat, default, auto-default, with a menu, or a command link button.
icon	The button’s QIcon, if any.
iconSize	The size of the icon.
text	The button text.

Checkboxes and radio buttons

QCheckBox and QRadioButton have identical structures. Both use QStyleOptionButton and draw one control element, CE_CheckBox or CE_RadioButton. QCommonStyle draws the indicator, the label, and the focus frame:

• CE_CheckBox

  • PE_IndicatorCheckBox (SE_CheckBoxIndicator, PM_IndicatorWidth, PM_IndicatorHeight)

  • CE_CheckBoxLabel (SE_CheckBoxContents, PM_CheckBoxLabelSpacing)

  • PE_FrameFocusRect (SE_CheckBoxFocusRect)

• CE_RadioButton

  • PE_IndicatorRadioButton (SE_RadioButtonIndicator, PM_ExclusiveIndicatorWidth, PM_ExclusiveIndicatorHeight)

  • CE_RadioButtonLabel (SE_RadioButtonContents, PM_RadioButtonLabelSpacing)

  • PE_FrameFocusRect (SE_RadioButtonFocusRect)

The size hints use CT_CheckBox and CT_RadioButton. Styling a Checkbox: A Walkthrough traces the drawing of a checkbox through the widget and QCommonStyle code.

The buttons set these state flags:

State	Set when
State_Sunken	The button is pressed. The clickable area is SE_CheckBoxClickRect or SE_RadioButtonClickRect, which in QCommonStyle covers the label as well as the indicator.
State_NoChange	The checkbox is partially checked (a tristate checkbox).
State_On	The button is checked.
State_Off	The button is unchecked.

The other members of QStyleOptionButton are listed under Push buttons .

Tool buttons

QToolButton draws one complex control, CC_ToolButton, with a QStyleOptionToolButton . It has two subcontrols: the button itself and, for a button with a menu button , the menu indicator.

• CC_ToolButton

  • SC_ToolButton

    • PE_PanelButtonTool (PM_DefaultFrameWidth)

    • PE_FrameFocusRect

    • CE_ToolButtonLabel (PM_ButtonShiftHorizontal, PM_ButtonShiftVertical)

  • SC_ToolButtonMenu (PM_MenuButtonIndicator)

    • PE_IndicatorButtonDropDown

    • PE_IndicatorArrowDown

For instant and delayed popups there is no menu subcontrol, so QCommonStyle draws PE_IndicatorArrowDown in the corner of the button rectangle instead. The size hint uses CT_ToolButton, and the button consults SH_ToolButton_PopupDelay and SH_ToolButtonStyle. Tool buttons in a toolbar take their icon size from the toolbar. Standalone buttons use PM_ButtonIconSize.

QToolButton sets these state flags:

State	Set when
State_AutoRaise	The autoRaise() property is set.
State_Raised	The button isn’t checked or pressed. QCommonStyle then clears the flag again if State_AutoRaise is set and the mouse isn’t over the button.
State_Sunken	The button is pressed, or its menu is shown.
State_On	The button is checkable and checked.

The other members of QStyleOptionToolButton are:

Member	Description
arrowType	A Qt::ArrowType value that gives the direction of the arrow drawn instead of an icon, if any.
features	Flags of the ToolButtonFeature enum: whether the button shows an arrow, has a menu button, or has a delayed popup.
font	The QFont of the button label.
icon	The QIcon of the button.
iconSize	The size of the icon.
pos	The position of the button, as given by pos() .
text	The button text.
toolButtonStyle	A Qt::ToolButtonStyle value that decides whether the button shows the icon, the text, or both.

Combo boxes

QComboBox draws the button and the label with CC_ComboBox and CE_ComboBoxLabel, both with a QStyleOptionComboBox . QCommonStyle omits the text of the label for an editable box, where the QLineEdit child draws it. The popup list is an item view drawn by a delegate , but the style controls its size and position with SC_ComboBoxListBoxPopup. For an editable box, the style decides where the line edit goes with SC_ComboBoxEditField; the field itself is a QLineEdit child.

• CC_ComboBox (PM_ComboBoxFrameWidth)

  • SC_ComboBoxFrame

  • SC_ComboBoxArrow (PE_IndicatorArrowDown)

  • SC_ComboBoxEditField

  • SC_ComboBoxListBoxPopup, for positioning the popup

• CE_ComboBoxLabel (SC_ComboBoxEditField)

The size hint uses CT_ComboBox. Style hints such as SH_ComboBox_Popup, SH_ComboBox_PopupFrameStyle, and SH_ComboBox_UseNativePopup decide how the popup looks and behaves.

QComboBox sets these state flags:

State	Set when
State_Selected	The box isn’t editable and has focus.
State_Sunken	SC_ComboBoxArrow is active.
State_On	The popup list is visible.

The other members of QStyleOptionComboBox are:

Member	Description
currentIcon	The icon of the current item.
currentText	The text of the current item.
editable	Whether the combo box is editable.
frame	Whether the combo box has a frame.
iconSize	The size of the current item’s icon.
popupRect	The bounding rectangle of the popup list.
textAlignment	The alignment of the text in the label.

Spin boxes

QSpinBox , QDoubleSpinBox , and QDateTimeEdit draw CC_SpinBox with a QStyleOptionSpinBox . The edit field is a QLineEdit child whose geometry the style returns for SC_SpinBoxEditField.

• CC_SpinBox (PM_SpinBoxFrameWidth)

  • SC_SpinBoxFrame

  • SC_SpinBoxUp

    • PE_PanelButtonBevel

    • PE_IndicatorSpinUp or PE_IndicatorSpinPlus, depending on buttonSymbols()

  • SC_SpinBoxDown

    • PE_PanelButtonBevel

    • PE_IndicatorSpinDown or PE_IndicatorSpinMinus

  • SC_SpinBoxEditField

A style doesn’t have to draw the button panels with PE_PanelButtonBevel. The size hint uses CT_SpinBox, and the widget consults hints such as SH_SpinBox_ButtonsInsideFrame, SH_SpinBox_StepModifier, and SH_SpinControls_DisableOnBounds.

The spin box sets this state flag:

State	Set when
State_Sunken	The SC_SpinBoxUp or SC_SpinBoxDown subcontrol is pressed.

The other members of QStyleOptionSpinBox are:

Member	Description
frame	Whether the spin box draws a frame.
buttonSymbols	A ButtonSymbols value that selects the symbols on the buttons: arrows, plus and minus, or none.
stepEnabled	StepEnabled flags that tell which of the buttons can step the value. A button that can’t step is drawn disabled.

Sliders

QSlider draws CC_Slider with a QStyleOptionSlider . It calculates its size hint from PM_SliderThickness and CT_Slider, and its minimum size hint from PM_SliderLength.

• CC_Slider (PM_SliderLength, PM_SliderControlThickness, PM_SliderTickmarkOffset, PM_SliderSpaceAvailable)

  • SC_SliderGroove

  • SC_SliderHandle

  • SC_SliderTickmarks

QCommonStyle draws only the tick marks; the groove and the handle are always style specific. Styles don’t have to return a rectangle for SC_SliderTickmarks. Fusion returns an empty one and draws the ticks below the handle, in the area outlined in the screenshot. The widget consults SH_Slider_AbsoluteSetButtons, SH_Slider_PageSetButtons, and SH_Slider_SnapToValue.

QDial uses the same option and draws CC_Dial with the subcontrols SC_DialGroove, SC_DialHandle, and SC_DialTickmarks.

QSlider sets these state flags:

State	Set when
State_Horizontal	The slider is horizontal.
State_Sunken	Any subcontrol is pressed, including the groove. activeSubControls tells which one.

QStyleOptionSlider serves all QAbstractSlider s. Its members are:

Member	Description
orientation	A Qt::Orientation value: vertical or horizontal.
minimum	The minimum value.
maximum	The maximum value.
tickPosition	A TickPosition value that tells where the tick marks are drawn.
tickInterval	The distance between tick marks, in slider values.
upsideDown	The direction in which the value increases. All abstract sliders use this member instead of QStyleOption::direction .
sliderPosition	The position of the handle, as a slider value. It equals sliderValue while tracking() is on; otherwise the value only updates when the handle is released.
sliderValue	The current value.
singleStep	The amount the value changes on a single step, such as an arrow key press.
pageStep	The amount the value changes on a page step, such as a click in the groove.
notchTarget	The preferred distance between notches, in pixels. Used by QDial .
dialWrapping	Whether the dial wraps around. Used by QDial .
keyboardModifiers	The modifier keys that were held during the last mouse event, for styles that let modifiers change the drag behavior.

Scroll bars

QScrollBar draws CC_ScrollBar with a QStyleOptionSlider . While the user drags the slider, the bar snaps the value back if the pointer moves farther than PM_MaximumDragDistance outside the bar.

• CC_ScrollBar (PM_ScrollBarExtent, PM_ScrollBarSliderMin)

  • SC_ScrollBarGroove

  • SC_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 draws each subcontrol with the control element of the same name. Some styles draw the line indicators with PE_IndicatorArrowUp and the other arrow primitives, and the page areas with PE_PanelButtonBevel; that is up to the individual style. SC_ScrollBarFirst and SC_ScrollBarLast are optional buttons that jump to the ends; most styles return an empty rectangle for them. The size hint uses CT_ScrollBar, and behavior hints include SH_ScrollBar_LeftClickAbsolutePosition, SH_ScrollBar_ContextMenu, and SH_ScrollBar_Transient.

QScrollBar sets these state flags:

State	Set when
State_Horizontal	The scroll bar is horizontal.
State_Sunken	A subcontrol is pressed and the pointer hasn’t left it.
State_On	The bar is a transient scroll bar that is currently shown.

The members of QStyleOptionSlider are listed under Sliders . sliderPosition, sliderValue, pageStep, and upsideDown decide the size and position of the handle.

Progress bars

QProgressBar draws one control element, CE_ProgressBar, with a QStyleOptionProgressBar . QCommonStyle splits it into the groove, the contents, and the label:

• CE_ProgressBar

  • CE_ProgressBarGroove (SE_ProgressBarGroove)

  • CE_ProgressBarContents (SE_ProgressBarContents, PM_ProgressBarChunkWidth)

  • CE_ProgressBarLabel (SE_ProgressBarLabel)

Styles that draw the contents as a row of chunks use PE_IndicatorProgressChunk. In QCommonStyle and Fusion, the groove, the contents, and the label all get the whole bar; the label is centered text drawn over the contents, so its rectangle isn’t a separate area. The size hint uses CT_ProgressBar. A busy indicator, a bar whose minimum and maximum are both zero, is animated by the style.

QProgressBar sets this state flag:

State	Set when
State_Horizontal	The bar is horizontal.

The other members of QStyleOptionProgressBar are:

Member	Description
minimum	The minimum value.
maximum	The maximum value.
progress	The current value.
text	The label text.
textAlignment	The alignment of the text in the label.
textVisible	Whether the label is drawn.
invertedAppearance	Whether the bar fills from the opposite end, for example, from right to left in a horizontal bar.
bottomToTop	Whether the label of a vertical bar is rotated to read from bottom to top.

See also

Widget Style Reference Styling Containers and Windows Styling Menus and Item Views