Класс QSplitter

Класс QSplitter реализует виджет разделителя. Подробнее...

• Список всех членов, включая унаследованные

Свойства

• childrenCollapsible : bool
• handleWidth : int
• opaqueResize : bool
• orientation : Qt::Orientation

Открытые функции

Переопределённые открытые функции

Сигналы

Защищённые функции

Переопределённые защищённые функции

Подробное описание

Разделитель позволяет пользователю управлять размером дочерних виджетов, перетаскивая границу между ними. Любое количество виджетов может контролироваться одним разделителем. Типичное использование QSplitter заключается в создании нескольких виджетов и добавлении их с помощью insertWidget() или addWidget().

Следующий пример покажет QListView, QTreeView и QTextEdit рядом, с двумя разделительными ручками:

    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);

Если виджет уже находится внутри QSplitter, когда вызывается insertWidget() или addWidget(), он переместится в новое положение. Это можно использовать для изменения порядка виджетов в разделителе позже. Вы можете использовать indexOf(), widget() и count() для доступа к виджетам внутри разделителя.

По умолчанию QSplitter выстраивает свои дочерние виджеты по горизонтали (бок о бок); вы можете выстроить их по вертикали, используя setOrientation(Qt::Vertical).

По умолчанию все виджеты могут быть произвольного размера между minimumSizeHint() (или minimumSize()) и maximumSize() виджетов.

QSplitter по умолчанию динамически изменяет размер своих дочерних виджетов. Если вы хотите, чтобы QSplitter изменял размер дочерних виджетов только в конце операции изменения размера, вызовите setOpaqueResize(false).

Первоначальное распределение размеров между виджетами определяется умножением начального размера на коэффициент растяжения. Вы также можете использовать setSizes() для задания размеров всех виджетов. Функция sizes() возвращает размеры, заданные пользователем. В качестве альтернативы вы можете сохранить и восстановить размеры виджетов из QByteArray, используя saveState() и restoreState() соответственно.

При скрытии дочернего виджета (hide()) его пространство распределяется между остальными дочерними виджетами. Оно будет восстановлено при повторном отображении (show).

Примечание: Добавление QLayout в QSplitter не поддерживается (ни через setLayout() ни путём назначения QSplitter родителем для QLayout); используйте addWidget() вместо этого (см. пример выше).

См. также QSplitterHandle, QHBoxLayout, QVBoxLayout и QTabWidget.

Документация по членам-функциям

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

Конструирует разделитель с заданной orientation и parent.

См. также setOrientation().

QSplitter::QSplitter(QWidget *parent = nullptr)

Конструирует горизонтальный разделитель с аргументом parent, переданным конструктору QFrame.

См. также setOrientation().

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

Этот сигнал генерируется, когда разделитель в определённом index был перемещён в позицию pos.

Для языков с право-на-лево, таких как арабский и иврит, макет горизонтальных разделителей инвертируется. pos тогда является расстоянием от правого края виджета.

См. также moveSplitter().

[virtual] QSplitter::~QSplitter()

Уничтожает разделитель. Все дочерние элементы удаляются.

void QSplitter::addWidget(QWidget *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).

Сообщает разделителю, что дочерний виджет, описанный в c, был вставлен или удалён.

Этот метод также используется для обработки ситуации, когда виджет создаётся с разделителем как родителем, но не добавляется явно с помощью insertWidget() или addWidget(). Это для совместимости, а не рекомендуемый способ размещения виджетов в разделителе в новом коде. Пожалуйста, используйте insertWidget() или addWidget() в новом коде.

См. также addWidget() и insertWidget().

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

Возвращает ближайшее допустимое положение к pos для виджета в index.

Для языков с право-на-лево, таких как арабский и иврит, макет горизонтальных разделителей инвертируется. Положения измеряются тогда от правого края виджета.

См. также getRange().

int QSplitter::count() const

Возвращает количество виджетов, содержащихся в макете разделителя.

См. также widget() и handle().

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

Возвращает новый разделитель как дочерний виджет этого разделителя. Эта функция может быть переопределена в подклассах для поддержки пользовательских разделителей.

См. также handle() и indexOf().

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

Переопределяет: QFrame::event(QEvent *e).

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

Возвращает допустимый диапазон разделителя в index в *min и *max, если min и max не равны 0.

QSplitterHandle *QSplitter::handle(int index) const

Возвращает разделитель слева (или сверху) от элемента в макете разделителя в заданном index, или nullptr если такого элемента нет. Разделитель в индексе 0 всегда скрыт.

Для языков с право-на-лево, таких как арабский и иврит, макет горизонтальных разделителей инвертируется. Разделитель будет справа от виджета в index.

См. также count(), widget(), indexOf(), createHandle() и setHandleWidth().

int QSplitter::indexOf(QWidget *widget) const

Возвращает индекс в макете разделителя указанного widget, или -1, если widget не найден. Это также работает для разделителей.

Разделители пронумерованы с 0. Количество разделителей равно количеству дочерних виджетов, но разделитель в позиции 0 всегда скрыт.

См. также count() и widget().

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

Вставляет указанный widget в макет разделителя в заданном index.

Если widget уже находится в разделителе, он будет перемещён в новое положение.

Если index — недопустимый индекс, то виджет будет вставлен в конец.

Примечание: Разделитель принимает владение виджетом.

См. также addWidget(), indexOf() и widget().

bool QSplitter::isCollapsible(int index) const

Возвращает true если виджет в позиции index можно сворачивать, в противном случае возвращает false.

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

Переопределяет: QWidget::minimumSizeHint() const.

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

Перемещает левую или верхнюю границу разделителя в позиции index как можно ближе к позиции pos, которая представляет расстояние от левого или верхнего края виджета.

Для языков с письмом справа налево, таких как арабский и иврит, расположение горизонтальных разделителей изменяется. В таком случае pos представляет расстояние от правого края виджета.

См. также splitterMoved(), closestLegalPosition() и getRange().

void QSplitter::refresh()

Обновляет состояние разделителя. Вам, как правило, не нужно вызывать эту функцию.

QWidget *QSplitter::replaceWidget(int index, QWidget *widget)

Заменяет виджет в макете разделителя в позиции index на widget.

Возвращает виджет, который был только что заменён, если index корректный и widget не является дочерним элементом разделителя. В противном случае возвращает null и никакой замены или добавления не происходит.

Геометрия нового вставленного виджета будет такой же, как у заменяемого виджета. Его видимое и свёрнутое состояния также наследуются.

Примечание: Разделитель принимает владение над widget и устанавливает родительский элемент заменённого виджета в null.

Примечание: Поскольку widget переходит под родительский элемент разделителя, его геометрия может не быть установлена сразу, но только после того, как 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)

Устанавливает возможность сворачивания виджета в позиции index на collapse.

По умолчанию дочерние элементы можно сворачивать, что означает, что пользователь может уменьшить их размер до 0, даже если у них есть ненулевой минимальный размер или минимальный размер.

Это поведение можно изменить для каждого виджета, вызвав эту функцию, или глобально для всех виджетов в разделителе, установив свойство childrenCollapsible.

См. также isCollapsible() и childrenCollapsible.

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

Отображает резиновую полосу в позиции pos. Если pos отрицательное, резиновая полоса удаляется.

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

Устанавливает размеры дочерних виджетов соответственно значениям, указанным в списке list.

Если разделитель горизонтальный, значения устанавливают ширину каждого виджета в пикселях слева направо. Если разделитель вертикальный, устанавливается высота каждого виджета сверху вниз.

Дополнительные значения в списке list игнорируются. Если список list содержит слишком мало значений, результат не определён, но программа всё равно будет работать корректно.

Общий размер виджета разделителя не изменяется. Вместо этого любое дополнительное/отсутствующее пространство распределяется между виджетами в соответствии с относительным весом размеров.

Если вы указываете размер 0, виджет будет невидим. Политики размеров виджетов сохраняются. То есть значение меньше минимального размера подсказки соответствующего виджета будет заменено значением подсказки.

См. также sizes().

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

Обновляет политику размеров виджета в позиции index, чтобы коэффициент растяжения был stretch.

stretch не является эффективным коэффициентом растяжения; эффективный коэффициент растяжения рассчитывается путём умножения начального размера виджета на stretch.

Эта функция предоставлена для удобства. Она эквивалентна

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

Возвращает список параметров размеров всех виджетов в этом разделителе.

Если ориентация разделителя горизонтальная, список содержит ширину виджетов в пикселях слева направо; если ориентация вертикальная, список содержит высоты виджетов в пикселях сверху вниз.

Указание значений функции setSizes() другого разделителя создаст разделитель с таким же макетом, как у этого.

Обратите внимание, что невидимые виджеты имеют размер 0.

См. также setSizes().

QWidget *QSplitter::widget(int index) const

Возвращает виджет в позиции index в макете разделителя или nullptr если такого виджета нет.

См. также count(), handle(), indexOf() и insertWidget().