Ribbon interface adapted tool button / Ribbon界面适用的toolButton 更多...

#include <SARibbonToolButton.h>

类 SARibbonToolButton 继承关系图:

类
struct	LayoutFactor
	Layout factor structure for fine-tuning button appearance / 用于微调按钮外观的布局系数结构体更多...

class	PrivateData

Public 类型
enum	RibbonButtonType { LargeButton , SmallButton }
	Button type enumeration / 按钮样式枚举更多...

Public 成员函数
	SARibbonToolButton (QWidget *parent=nullptr)

	SARibbonToolButton (QAction defaultAction, QWidget parent=nullptr)

RibbonButtonType	buttonType () const
	Gets the current button type (LargeButton or SmallButton) / 获取当前按钮的类型（大按钮或小按钮）

void	setButtonType (const RibbonButtonType &buttonType)
	Sets the button type to LargeButton or SmallButton / 设置按钮类型为大按钮或小按钮

bool	isSmallRibbonButton () const
	Checks if the button is a small ribbon button / 判断按钮是否为小Ribbon按钮

bool	isLargeRibbonButton () const
	Checks if the button is a large ribbon button / 判断按钮是否为大Ribbon按钮

int	spacing () const
	Gets the current spacing value / 获取当前的间距值

void	setSpacing (int v)
	Sets the spacing between elements and the border / 设置元素与边框之间的间距

void	updateRect ()
	Forces an update of the internal layout rectangles / 强制更新内部布局矩形

void	setLayoutFactor (const LayoutFactor &fac)
	Sets the layout factor for fine-tuning the button's appearance / 设置布局系数以微调按钮外观

const LayoutFactor &	layoutFactor () const
	Gets a const reference to the current layout factor / 获取当前布局系数的常量引用

LayoutFactor &	layoutFactor ()
	Gets a mutable reference to the current layout factor / 获取当前布局系数的可变引用

void	setEnableWordWrap (bool on)
	Enables or disables automatic text wrapping for large buttons / 为大按钮启用或禁用自动文字换行

bool	isEnableWordWrap ()
	Checks if automatic text wrapping is enabled / 检查是否启用了自动文字换行

void	setButtonMaximumAspectRatio (qreal v=1.4)
	Sets the button's maximum aspect ratio (width/height) / 设置按钮的最大宽高比

qreal	buttonMaximumAspectRatio () const
	Gets the button's maximum aspect ratio (width/height) / 获取按钮的最大宽高比

void	invalidateSizeHint ()
	Invalidates the cached size hint / 使缓存的size hint失效

virtual QSize	sizeHint () const Q_DECL_OVERRIDE
	Returns the recommended size for the button / 返回按钮的推荐尺寸

virtual QSize	minimumSizeHint () const Q_DECL_OVERRIDE
	Returns the recommended minimum size for the button / 返回按钮的推荐最小尺寸

Protected 成员函数
virtual void	paintEvent (QPaintEvent *e) Q_DECL_OVERRIDE

virtual void	resizeEvent (QResizeEvent *e) Q_DECL_OVERRIDE
	在resizeevent计算绘图所需的尺寸，避免在绘图过程中实时绘制提高效率

virtual void	mouseMoveEvent (QMouseEvent *e) Q_DECL_OVERRIDE
	鼠标移动事件

virtual void	mousePressEvent (QMouseEvent *e) Q_DECL_OVERRIDE
	SARibbonToolButton::mousePressEvent

virtual void	mouseReleaseEvent (QMouseEvent *e) Q_DECL_OVERRIDE

virtual void	focusOutEvent (QFocusEvent *e) Q_DECL_OVERRIDE

virtual void	leaveEvent (QEvent *e) Q_DECL_OVERRIDE

virtual bool	hitButton (const QPoint &pos) const Q_DECL_OVERRIDE

virtual bool	event (QEvent *e) Q_DECL_OVERRIDE

virtual void	changeEvent (QEvent *e) Q_DECL_OVERRIDE

virtual void	actionEvent (QActionEvent *e) Q_DECL_OVERRIDE

virtual void	paintButton (QPainter &p, const QStyleOptionToolButton &opt)
	Paints the button's background and frame / 绘制按钮的背景和边框

virtual void	paintIcon (QPainter &p, const QStyleOptionToolButton &opt, const QRect &iconDrawRect)
	Paints the button's icon / 绘制按钮的图标

virtual void	paintText (QPainter &p, const QStyleOptionToolButton &opt, const QRect &textDrawRect)
	Paints the button's text / 绘制按钮的文字

virtual void	paintIndicator (QPainter &p, const QStyleOptionToolButton &opt, const QRect &indicatorDrawRect)
	Paints the button's indicator (e.g., dropdown arrow) / 绘制按钮的指示器（例如下拉箭头）

详细描述

Ribbon interface adapted tool button / Ribbon界面适用的toolButton

This button is designed specifically for the Ribbon interface, supporting two display modes: large buttons and small buttons. It also supports automatic text wrapping for large buttons to optimize space usage.

该按钮专为Ribbon界面设计，支持大按钮和小按钮两种显示模式。图标尺寸会根据按钮尺寸动态调整，无法通过 setIconSize 手动设置。大按钮模式下还支持文字自动换行，以优化空间利用。

注解: The icon size is dynamically adjusted according to the button size and cannot be set manually via setIconSize / setIconSize 函数不在起作用，iconsize是根据当前尺寸动态调整的

成员枚举类型说明

◆ RibbonButtonType

enum SARibbonToolButton::RibbonButtonType

Button type enumeration / 按钮样式枚举

枚举值
LargeButton	Large button type, corresponding to the large button in SARibbonBar / 大按钮类型，此类型对应SARibbonBar的大按钮
SmallButton	Small button type, corresponding to the small button in SARibbonBar, equivalent to a normal toolbar button / 小按钮类型，此类型对应SARibbonBar的小按钮，等同于普通工具条的按钮

成员函数说明

◆ buttonMaximumAspectRatio()

qreal SARibbonToolButton::buttonMaximumAspectRatio ( ) const

Gets the button's maximum aspect ratio (width/height) / 获取按钮的最大宽高比

返回: The current maximum aspect ratio / 当前的最大宽高比

参见: setButtonMaximumAspectRatio, layoutFactor

◆ buttonType()

SARibbonToolButton::RibbonButtonType SARibbonToolButton::buttonType ( ) const

Gets the current button type (LargeButton or SmallButton) / 获取当前按钮的类型（大按钮或小按钮）

返回: The current button type / 当前按钮类型

参见: setButtonType

◆ invalidateSizeHint()

void SARibbonToolButton::invalidateSizeHint ( )

Invalidates the cached size hint / 使缓存的size hint失效

This function clears the internally cached sizeHint() value and calls updateGeometry(), which notifies the layout system that this widget needs to be relayouted. It is called automatically when properties affecting the size (like text, font, or button type) change.

此函数会清除内部缓存的 sizeHint() 值并调用 updateGeometry()，通知布局系统此控件需要重新布局。当影响尺寸的属性（如文字、字体或按钮类型）发生变化时，会自动调用此函数。

◆ isEnableWordWrap()

bool SARibbonToolButton::isEnableWordWrap ( )

Checks if automatic text wrapping is enabled / 检查是否启用了自动文字换行

返回: true if word wrap is enabled; otherwise false / 如果启用了文字换行则返回 true；否则返回 false

参见: setEnableWordWrap

◆ isLargeRibbonButton()

bool SARibbonToolButton::isLargeRibbonButton ( ) const

Checks if the button is a large ribbon button / 判断按钮是否为大Ribbon按钮

返回: true if the button type is LargeButton; otherwise false / 如果按钮类型为 LargeButton 则返回 true；否则返回 false

参见: isSmallRibbonButton, buttonType

◆ isSmallRibbonButton()

bool SARibbonToolButton::isSmallRibbonButton ( ) const

Checks if the button is a small ribbon button / 判断按钮是否为小Ribbon按钮

返回: true if the button type is SmallButton; otherwise false / 如果按钮类型为 SmallButton 则返回 true；否则返回 false

参见: isLargeRibbonButton, buttonType

◆ layoutFactor() [1/2]

SARibbonToolButton::LayoutFactor & SARibbonToolButton::layoutFactor ( )

Gets a mutable reference to the current layout factor / 获取当前布局系数的可变引用

返回: A mutable reference to the layout factor / 布局系数的可变引用

参见: setLayoutFactor, setButtonMaximumAspectRatio

◆ layoutFactor() [2/2]

const SARibbonToolButton::LayoutFactor & SARibbonToolButton::layoutFactor ( ) const

Gets a const reference to the current layout factor / 获取当前布局系数的常量引用

返回: A const reference to the layout factor / 布局系数的常量引用

参见: setLayoutFactor, setButtonMaximumAspectRatio

◆ minimumSizeHint()

QSize SARibbonToolButton::minimumSizeHint ( ) const

virtual

Returns the recommended minimum size for the button / 返回按钮的推荐最小尺寸

For SARibbonToolButton, the minimum size hint is the same as the size hint.

对于 SARibbonToolButton，最小尺寸提示与尺寸提示相同。

返回: The recommended minimum size / 推荐的最小尺寸

◆ mouseMoveEvent()

void SARibbonToolButton::mouseMoveEvent ( QMouseEvent * e )

protectedvirtual

鼠标移动事件

由于Ribbon的Indicator和正常的Toolbutton不一样，因此无法用QStyleOptionToolButton的activeSubControls的状态

因此需要重新捕获鼠标的位置来更新按钮当前的一些状态

参数

e

◆ mousePressEvent()

void SARibbonToolButton::mousePressEvent ( QMouseEvent * e )

protectedvirtual

SARibbonToolButton::mousePressEvent

参数

e

注意这里要用QAbstractButton的mousePressEvent，而不是QToolButton的mousePressEvent QToolButton的mousePressEvent主要是为了弹出菜单，这里弹出菜单的方式是不一样的，因此不能执行QToolButton的mousePressEvent

◆ paintButton()

void SARibbonToolButton::paintButton	(	QPainter &	p,
		const QStyleOptionToolButton &	opt
	)

protectedvirtual

Paints the button's background and frame / 绘制按钮的背景和边框

This function handles the special visual effects for the Ribbon style, particularly for the MenuButtonPopup mode where the icon and text areas can have different hover states.

此函数处理Ribbon样式的特殊视觉效果，特别是在 MenuButtonPopup 模式下，图标和文字区域可以有不同的悬停状态。

参数

p	The painter to use / 用于绘制的painter
opt	The style option for the tool button / 工具按钮的样式选项

◆ paintIcon()

void SARibbonToolButton::paintIcon	(	QPainter &	p,
		const QStyleOptionToolButton &	opt,
		const QRect &	iconDrawRect
	)

protectedvirtual

Paints the button's icon / 绘制按钮的图标

The icon is painted within the specified rectangle, scaled appropriately based on the available space.

图标会在指定的矩形区域内绘制，并根据可用空间进行适当缩放。

参数

p	The painter to use / 用于绘制的painter
opt	The style option for the tool button / 工具按钮的样式选项
iconDrawRect	The rectangle in which to draw the icon / 绘制图标的矩形区域

被 SARibbonColorToolButton 重载.

◆ paintIndicator()

void SARibbonToolButton::paintIndicator	(	QPainter &	p,
		const QStyleOptionToolButton &	opt,
		const QRect &	indicatorDrawRect
	)

protectedvirtual

Paints the button's indicator (e.g., dropdown arrow) / 绘制按钮的指示器（例如下拉箭头）

The indicator is painted within the specified rectangle if the button has a menu (i.e., features include MenuButtonPopup or HasMenu).

如果按钮有菜单（即特性包含 MenuButtonPopup 或 HasMenu），则会在指定的矩形区域内绘制指示器。

参数

p	The painter to use / 用于绘制的painter对象
opt	The style option for the tool button / 工具按钮的样式选项
indicatorDrawRect	The rectangle in which to draw the indicator / 绘制指示器的矩形区域

◆ paintText()

void SARibbonToolButton::paintText	(	QPainter &	p,
		const QStyleOptionToolButton &	opt,
		const QRect &	textDrawRect
	)

protectedvirtual

Paints the button's text / 绘制按钮的文字

The text is painted within the specified rectangle, with alignment and elision (truncation with "...") handled according to the button's type and word-wrap setting.

文字会在指定的矩形区域内绘制，其对齐方式和省略（用“...”截断）会根据按钮的类型和文字换行设置进行处理。

参数

p	The painter to use / 用于绘制的painter对象
opt	The style option for the tool button / 工具按钮的样式选项
textDrawRect	The rectangle in which to draw the text / 绘制文字的矩形区域

以下内容参考QCommonStyle.cpp void QCommonStyle::drawComplexControl(ComplexControl cc, const QStyleOptionComplex *opt,QPainter *p, const QWidget *widget) const case CC_ToolButton:

◆ resizeEvent()

void SARibbonToolButton::resizeEvent ( QResizeEvent * e )

protectedvirtual

在resizeevent计算绘图所需的尺寸，避免在绘图过程中实时绘制提高效率

参数

e

◆ setButtonMaximumAspectRatio()

void SARibbonToolButton::setButtonMaximumAspectRatio ( qreal v = 1.4 )

Sets the button's maximum aspect ratio (width/height) / 设置按钮的最大宽高比

This is a convenience function that directly sets the buttonMaximumAspectRatio member of the LayoutFactor structure. It has the same effect as modifying the structure and calling setLayoutFactor.

此函数是直接设置 LayoutFactor 结构体中 buttonMaximumAspectRatio 成员的便捷方法。其效果等同于修改结构体后调用 setLayoutFactor。

参数

v	The new maximum aspect ratio value / 新的最大宽高比值

参见: buttonMaximumAspectRatio, setLayoutFactor

◆ setButtonType()

void SARibbonToolButton::setButtonType ( const RibbonButtonType & buttonType )

Sets the button type to LargeButton or SmallButton / 设置按钮类型为大按钮或小按钮

Changing the button type will invalidate the size hint and trigger a relayout. Note: This function may override the tool button style. If you need to set a specific style (e.g., Qt::ToolButtonIconOnly), do so after calling this function.

设置按钮类型会令尺寸提示失效并触发重新布局。注意：此函数可能会覆盖工具按钮样式。如需设置特定样式（例如 Qt::ToolButtonIconOnly），请在此函数调用之后设置。

参数

buttonType The new button type / 新的按钮类型

参见: isLargeRibbonButton, isSmallRibbonButton

◆ setEnableWordWrap()

void SARibbonToolButton::setEnableWordWrap ( bool on )

Enables or disables automatic text wrapping for large buttons / 为大按钮启用或禁用自动文字换行

When enabled, the text in a large button will attempt to wrap onto a second line if it is too long to fit on one line. This is particularly useful for long action names in the Ribbon interface. The button's size hint will be recalculated after calling this function.

启用后，如果大按钮中的文字过长无法在一行内显示，将尝试换行到第二行。这在Ribbon界面中处理较长的操作名称时非常有用。调用此函数后，按钮的size hint将被重新计算。

Example:

// Enable word wrap for a button with a potentially long label/为一个可能有长标签的按钮启用文字换行

myLongLabelButton->setEnableWordWrap(true);

参数

on	`true` to enable word wrap; `false` to disable it / `true` 启用换行，`false` 禁用换行

参见: isEnableWordWrap

◆ setLayoutFactor()

void SARibbonToolButton::setLayoutFactor ( const LayoutFactor & fac )

Sets the layout factor for fine-tuning the button's appearance / 设置布局系数以微调按钮外观

This function allows you to customize the button's text height and maximum aspect ratio. After calling this function, the button's geometry will be invalidated to trigger a relayout.

此函数允许您自定义按钮的文本高度和最大宽高比。调用此函数后，按钮的几何尺寸将被标记为无效，以触发重新布局。

Example:

SARibbonToolButton::LayoutFactor lf;
lf.twoLineHeightFactor = 2.2; // Make two-line text taller/让两行文字更高
lf.buttonMaximumAspectRatio = 1.6; // Allow a wider button/允许按钮更宽
myRibbonButton->setLayoutFactor(lf);

参数

fac	The new layout factor / 新的布局系数

参见: layoutFactor, setButtonMaximumAspectRatio

◆ setSpacing()

void SARibbonToolButton::setSpacing ( int v )

Sets the spacing between elements and the border / 设置元素与边框之间的间距

This spacing affects the layout of the icon, text, and indicator within the button. After calling this function, the button's geometry will be invalidated to trigger a relayout.

此间距会影响按钮内图标、文字和指示器的布局。调用此函数后，按钮的几何尺寸将被标记为无效，以触发重新布局。

参数

v	The new spacing value in pixels / 新的间距值（像素）

参见: spacing

◆ sizeHint()

QSize SARibbonToolButton::sizeHint ( ) const

virtual

Returns the recommended size for the button / 返回按钮的推荐尺寸

This size is calculated based on the button's type, text, icon, and current layout factors. The result is cached for performance. The cache is invalidated when relevant properties change.

此尺寸是根据按钮的类型、文字、图标和当前布局系数计算得出的。为提高性能，计算结果会被缓存。当相关属性改变时，缓存会自动失效。

返回: The recommended size / 推荐的尺寸

◆ spacing()

int SARibbonToolButton::spacing ( ) const

Gets the current spacing value / 获取当前的间距值

Spacing is the gap between the icon, text, indicator, and the button's border.

间距是图标、文字、指示器与按钮边框之间的间隙。

返回: The current spacing in pixels / 当前的间距值（像素）

参见: setSpacing

◆ updateRect()

void SARibbonToolButton::updateRect ( )

Forces an update of the internal layout rectangles / 强制更新内部布局矩形

This function recalculates the drawing rectangles for the icon, text, and indicator based on the current button size and style. It also invalidates the cached size hint. This is typically called automatically during a resize event.

此函数会根据当前按钮尺寸和样式，重新计算图标、文字和指示器的绘制矩形。同时会使缓存的尺寸提示失效。此函数通常在调整大小事件中被自动调用。

注解: This function invalidates the size hint cache but does not call updateGeometry(). If you need to trigger a parent layout update, call updateGeometry() manually after this function. / 此函数会清除 sizehint 缓存，但不会调用 updateGeometry()。如果需要触发布局更新，应在调用此函数后手动调用 updateGeometry()。

该类的文档由以下文件生成:

/home/runner/work/SARibbon/SARibbon/src/SARibbonBar/SARibbonToolButton.h
/home/runner/work/SARibbon/SARibbon/src/SARibbonBar/SARibbonToolButton.cpp

类

Public 类型

Public 成员函数

Protected 成员函数

详细描述

成员枚举类型说明

◆ RibbonButtonType

成员函数说明

◆ buttonMaximumAspectRatio()

◆ buttonType()

◆ invalidateSizeHint()

◆ isEnableWordWrap()

◆ isLargeRibbonButton()

◆ isSmallRibbonButton()

◆ layoutFactor() [1/2]

◆ layoutFactor() [2/2]

◆ minimumSizeHint()

◆ mouseMoveEvent()

◆ mousePressEvent()

◆ paintButton()

◆ paintIcon()

◆ paintIndicator()

◆ paintText()

◆ resizeEvent()

◆ setButtonMaximumAspectRatio()

◆ setButtonType()

◆ setEnableWordWrap()

◆ setLayoutFactor()

◆ setSpacing()

◆ sizeHint()

◆ spacing()

◆ updateRect()