QSplitter 类

QSplitter 类实现分割器 Widget。 更多...

头: #include <QSplitter>
CMake: find_package(Qt6 COMPONENTS Widgets REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
继承: QFrame

特性

公共函数

  QSplitter (Qt::Orientation orientation , QWidget * parent = nullptr)
  QSplitter (QWidget * parent = nullptr)
virtual ~QSplitter ()
void addWidget (QWidget * widget )
bool childrenCollapsible () const
int count () const
void getRange (int index , int * min , int * max ) const
QSplitterHandle * handle (int index ) const
int handleWidth () const
int indexOf (QWidget * widget ) const
void insertWidget (int index , QWidget * widget )
bool isCollapsible (int index ) const
bool opaqueResize () const
Qt::Orientation orientation () const
void refresh ()
QWidget * replaceWidget (int index , QWidget * widget )
bool restoreState (const QByteArray & state )
QByteArray saveState () const
void setChildrenCollapsible (bool)
void setCollapsible (int index , bool collapse )
void setHandleWidth (int)
void setOpaqueResize (bool opaque = true)
void setOrientation (Qt::Orientation)
void setSizes (const QList<int> & list )
void setStretchFactor (int index , int stretch )
QList<int> sizes () const
QWidget * widget (int index ) const

重实现公共函数

virtual QSize minimumSizeHint () const override
virtual QSize sizeHint () const override

信号

void splitterMoved (int pos , int index )

保护函数

int closestLegalPosition (int pos , int index )
virtual QSplitterHandle * createHandle ()
void moveSplitter (int pos , int index )
void setRubberBand (int pos )

重实现保护函数

virtual void changeEvent (QEvent * ev ) override
virtual void childEvent (QChildEvent * c ) override
virtual bool event (QEvent * e ) override
virtual void resizeEvent (QResizeEvent *) override

详细描述

分割器允许用户通过拖拽子级 Widget 之间的边界控制其大小。单个分割器可以控制任何数量的 Widget。QSplitter 的典型使用是创建几个 Widget 并添加它们使用 insertWidget () 或 addWidget ().

以下范例将展示 QListView , QTreeView ,和 QTextEdit 并排,采用 2 个分割器手柄:

    QSplitter *splitter = new QSplitter(parent);
    QListView *listview = new QListView;
    QTreeView *treeview = new QTreeView;
    QTextEdit *textedit = new QTextEdit;
    splitter->addWidget(listview);
    splitter->addWidget(treeview);
    splitter->addWidget(textedit);
					

If a widget is already inside a QSplitter when insertWidget () 或 addWidget () is called, it will move to the new position. This can be used to reorder widgets in the splitter later. You can use indexOf (), widget (),和 count () to get access to the widgets inside the splitter.

A default QSplitter lays out its children horizontally (side by side); you can use setOrientation ( Qt::Vertical ) to lay its children out vertically.

By default, all widgets can be as large or as small as the user wishes, between the minimumSizeHint () (or minimumSize ()) and maximumSize () of the widgets.

QSplitter resizes its children dynamically by default. If you would rather have QSplitter resize the children only at the end of a resize operation, call setOpaqueResize (false).

The initial distribution of size between the widgets is determined by multiplying the initial size with the stretch factor. You can also use setSizes () to set the sizes of all the widgets. The function sizes () returns the sizes set by the user. Alternatively, you can save and restore the sizes of the widgets from a QByteArray 使用 saveState () 和 restoreState () 分别。

When you hide () a child, its space will be distributed among the other children. It will be reinstated when you show () 它再次。

注意: 添加 QLayout 到 QSplitter 是不被支持的 (通过 setLayout () 或使 QSplitter 父级 QLayout );使用 addWidget () 代替 (见以上范例)。

另请参阅 QSplitterHandle , QHBoxLayout , QVBoxLayout ,和 QTabWidget .

特性文档编制

childrenCollapsible : bool

This property holds whether child widgets can be resized down to size 0 by the user

By default, children are collapsible. It is possible to enable and disable the collapsing of individual children using setCollapsible ().

访问函数:

bool childrenCollapsible () const
void setChildrenCollapsible (bool)

另请参阅 setCollapsible ().

handleWidth : int

此特性保持分割器手柄的宽度

默认情况下,此特性包含从属用户平台和样式首选项的值。

若将 handleWidth 设为 1 (或 0),实际抓取区域将增长到其各自 Widget 的几个重叠像素。

访问函数:

int handleWidth () const
void setHandleWidth (int)

opaqueResize : bool

返回 true 若动态 (不透明) 重置 Widget 尺寸当交互移动分割器时。否则返回 false .

默认重置尺寸行为从属样式 (由 SH_Splitter_OpaqueResize 样式提示确定)。不管怎样,可以覆盖它通过调用 setOpaqueResize()

访问函数:

bool opaqueResize () const
void setOpaqueResize (bool opaque = true)

另请参阅 QStyle::StyleHint .

orientation : Qt::Orientation

此特性保持分割器的取向

By default, the orientation is horizontal (i.e., the widgets are laid out side by side). The possible orientations are Qt::Horizontal and Qt::Vertical .

访问函数:

Qt::Orientation orientation () const
void setOrientation (Qt::Orientation)

另请参阅 QSplitterHandle::orientation ().

成员函数文档编制

QSplitter:: QSplitter ( Qt::Orientation orientation , QWidget * parent = nullptr)

构造分割器采用给定 orientation and parent .

另请参阅 setOrientation ().

QSplitter:: QSplitter ( QWidget * parent = nullptr)

构造水平分割器按 parent 自变量被传递给 QFrame 构造函数。

另请参阅 setOrientation ().

[signal] void QSplitter:: splitterMoved ( int pos , int index )

This signal is emitted when the splitter handle at a particular index has been moved to position pos .

For right-to-left languages such as Arabic and Hebrew, the layout of horizontal splitters is reversed. pos is then the distance from the right edge of the widget.

另请参阅 moveSplitter ().

[虚拟] QSplitter:: ~QSplitter ()

销毁分割器。删除所有子级。

void QSplitter:: addWidget ( QWidget * widget )

添加给定 widget 到分割器布局在所有其它项之后。

widget 已在分割器中,将它移至新位置。

注意: 分割器拥有 Widget 的所有权。

另请参阅 insertWidget (), widget (),和 indexOf ().

[override virtual protected] void QSplitter:: changeEvent ( QEvent * ev )

重实现: QFrame::changeEvent (QEvent *ev).

[override virtual protected] void QSplitter:: childEvent ( QChildEvent * c )

重实现: QObject::childEvent (QChildEvent *event).

Tells the splitter that the child widget described by c has been inserted or removed.

This method is also used to handle the situation where a widget is created with the splitter as a parent but not explicitly added with insertWidget () 或 addWidget (). This is for compatibility and not the recommended way of putting widgets into a splitter in new code. Please use insertWidget () 或 addWidget () in new code.

另请参阅 addWidget () 和 insertWidget ().

[protected] int QSplitter:: closestLegalPosition ( int pos , int index )

Returns the closest legal position to pos of the widget at index .

For right-to-left languages such as Arabic and Hebrew, the layout of horizontal splitters is reversed. Positions are then measured from the right edge of the widget.

另请参阅 getRange ().

int QSplitter:: count () const

返回分割器布局所包含的 Widget 数。

另请参阅 widget () 和 handle ().

[virtual protected] QSplitterHandle *QSplitter:: createHandle ()

Returns a new splitter handle as a child widget of this splitter. This function can be reimplemented in subclasses to provide support for custom handles.

另请参阅 handle () 和 indexOf ().

[override virtual protected] bool QSplitter:: event ( QEvent * e )

重实现: QFrame::event (QEvent *e).

void QSplitter:: getRange ( int index , int * min , int * max ) const

Returns the valid range of the splitter at index in * min 和 * max if min and max are not 0.

QSplitterHandle *QSplitter:: handle ( int index ) const

Returns the handle to the left of (or above) the item in the splitter's layout at the given index ,或 nullptr if there is no such item. The handle at index 0 is always hidden.

For right-to-left languages such as Arabic and Hebrew, the layout of horizontal splitters is reversed. The handle will be to the right of the widget at index .

另请参阅 count (), widget (), indexOf (), createHandle (),和 setHandleWidth ().

int QSplitter:: indexOf ( QWidget * widget ) const

Returns the index in the splitter's layout of the specified widget ,或 -1 若 widget is not found. This also works for handles.

Handles are numbered from 0. There are as many handles as there are child widgets, but the handle at position 0 is always hidden.

另请参阅 count () 和 widget ().

void QSplitter:: insertWidget ( int index , QWidget * widget )

插入 widget specified into the splitter's layout at the given index .

widget 已在分割器中,将它移至新位置。

index is an invalid index, then the widget will be inserted at the end.

注意: 分割器拥有 Widget 的所有权。

另请参阅 addWidget (), indexOf (),和 widget ().

bool QSplitter:: isCollapsible ( int index ) const

返回 true 若 Widget 在 index 是可折叠的,否则返回 false .

[override virtual] QSize QSplitter:: minimumSizeHint () const

重实现访问函数为特性: QWidget::minimumSizeHint .

[protected] void QSplitter:: moveSplitter ( int pos , int index )

Moves the left or top edge of the splitter handle at index as close as possible to position pos , which is the distance from the left or top edge of the widget.

For right-to-left languages such as Arabic and Hebrew, the layout of horizontal splitters is reversed. pos is then the distance from the right edge of the widget.

另请参阅 splitterMoved (), closestLegalPosition (),和 getRange ().

void QSplitter:: refresh ()

Updates the splitter's state. You should not need to call this function.

[since 5.9] QWidget *QSplitter:: replaceWidget ( int index , QWidget * widget )

替换分割器布局中的 Widget 在给定 index by widget .

返回刚才被替换的 Widget 若 index 有效和 widget 尚不是分割器子级。否则,它返回 null 且不置换或添加。

新近插入 Widget 的几何体如同它替换的小部件。它可见和折叠状态也会被继承。

注意: 分割器拥有所有权对于 widget 并将替换小部件的父级设为 null。

注意: 因为 widget gets reparented 到分割器,其 geometry 可能不会被立即设置,直到 widget 接收适当事件。

该函数在 Qt 5.9 引入。

另请参阅 insertWidget () 和 indexOf ().

[override virtual protected] void QSplitter:: resizeEvent ( QResizeEvent *)

重实现: QWidget::resizeEvent (QResizeEvent *event).

bool QSplitter:: restoreState (const QByteArray & state )

将分割器布局还原成 state 指定。返回 true 若状态被还原;否则返回 false .

通常,这用于结合 QSettings 从过去的会话还原尺寸。这里是范例:

还原分割器的状态:

    QSettings settings;
    splitter->restoreState(settings.value("splitterSizes").toByteArray());
					

所提供的字节数组中的数据,无效或过期可能导致无法还原分割器布局。

另请参阅 saveState ().

QByteArray QSplitter:: saveState () const

保存分割器布局的状态。

通常,这用于结合 QSettings 以记住用于未来会议的尺寸。版本号作为数据的一部分被存储。这里是范例:

    QSettings settings;
    settings.setValue("splitterSizes", splitter->saveState());
					

另请参阅 restoreState ().

void QSplitter:: setCollapsible ( int index , bool collapse )

Sets whether the child widget at index is collapsible to collapse .

By default, children are collapsible, meaning that the user can resize them down to size 0, even if they have a non-zero minimumSize () 或 minimumSizeHint (). This behavior can be changed on a per-widget basis by calling this function, or globally for all the widgets in the splitter by setting the childrenCollapsible 特性。

另请参阅 isCollapsible () 和 childrenCollapsible .

[protected] void QSplitter:: setRubberBand ( int pos )

Displays a rubber band at position pos 。若 pos is negative, the rubber band is removed.

void QSplitter:: setSizes (const QList < int > & list )

Sets the child widgets' respective sizes to the values given in the list .

If the splitter is horizontal, the values set the width of each widget in pixels, from left to right. If the splitter is vertical, the height of each widget is set, from top to bottom.

Extra values in the list are ignored. If list contains too few values, the result is undefined, but the program will still be well-behaved.

The overall size of the splitter widget is not affected. Instead, any additional/missing space is distributed amongst the widgets according to the relative weight of the sizes.

If you specify a size of 0, the widget will be invisible. The size policies of the widgets are preserved. That is, a value smaller than the minimal size hint of the respective widget will be replaced by the value of the hint.

另请参阅 sizes ().

void QSplitter:: setStretchFactor ( int index , int stretch )

Updates the size policy of the widget at position index to have a stretch factor of stretch .

stretch is not the effective stretch factor; the effective stretch factor is calculated by taking the initial size of the widget and multiplying it with stretch .

This function is provided for convenience. It is equivalent to

QWidget *widget = splitter->widget(index);
QSizePolicy policy = widget->sizePolicy();
policy.setHorizontalStretch(stretch);
policy.setVerticalStretch(stretch);
widget->setSizePolicy(policy);
					

另请参阅 setSizes () 和 widget ().

[override virtual] QSize QSplitter:: sizeHint () const

重实现: QFrame::sizeHint () const.

QList < int > QSplitter:: sizes () const

返回此分割器所有 Widget 尺寸的参数列表。

若分割器方向水平,列表从左到右包含 Widget 宽度 (以像素为单位);若方向垂直,列表从顶到下包含 Widget 高度 (以像素为单位)。

将值赋予另一分割器的 setSizes () 函数将产生如此具有相同布局的分割器。

注意:不可见 Widget 拥有 0 尺寸。

另请参阅 setSizes ().

QWidget *QSplitter:: widget ( int index ) const

返回 Widget 在给定 index 在分割器布局中,或 nullptr 若没有这种 Widget。

另请参阅 count (), handle (), indexOf (),和 insertWidget ().