Класс 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() соответственно.

При скрытии дочернего элемента его пространство будет распределено между другими дочерними элементами. Оно будет восстановлено при повторном отображении.

Примечание: Добавление 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.

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

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

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

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

void QSplitter::refresh()

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

[since 5.9] 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, даже если у них есть ненулевой minimumSize() или minimumSizeHint(). Это поведение может быть изменено для каждого виджета, вызвав эту функцию, или глобально для всех виджетов в разделителе, установив свойство 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().