Класс QTabWidget

Класс QTabWidget предоставляет набор виджетов с вкладками. Подробнее...

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

Открытые типы

Свойства

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

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

Public Slots

Signals

Protected Functions

Реализованные защищенные функции

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

Виджет QTabWidget предоставляет панель вкладок (см. QTabBar) и область «страниц», которая используется для отображения страниц, связанных с каждой вкладкой. По умолчанию панель вкладок отображается над областью страниц, но доступны различные конфигурации (см. TabPosition). Каждая вкладка связана с другим виджетом (называемым страницей). Только текущая страница отображается в области страниц; все остальные страницы скрыты. Пользователь может отобразить другую страницу, нажав на её вкладку или нажав комбинацию Alt+буква, если она есть.

Обычный способ использования QTabWidget:

1. Создайте QTabWidget.
2. Создайте QWidget для каждой из страниц в диалоговом окне вкладок, но не указывайте родительские виджеты для них.
3. Вставьте дочерние виджеты в виджет страницы, используя макеты для их позиционирования как обычно.
4. Вызовите addTab() или insertTab() для размещения виджетов страниц в виджете вкладок, присвойте каждой вкладке соответствующее имя с необязательной комбинацией клавиш.

Положение вкладок определяется свойством tabPosition, а их форма — свойством tabShape.

Сигнал currentChanged() генерируется, когда пользователь выбирает страницу.

Индекс текущей страницы доступен как currentIndex(), а текущий виджет страницы — с помощью currentWidget(). Вы можете получить указатель на виджет страницы с заданным индексом с помощью widget(), а индекс позиции виджета с помощью indexOf(). Используйте setCurrentWidget() или setCurrentIndex() для отображения определённой страницы.

Вы можете изменить текст и значок вкладки с помощью setTabText() или setTabIcon(). Вкладку и связанную с ней страницу можно удалить с помощью removeTab().

Каждая вкладка либо включена, либо выключена в любой момент (см. setTabEnabled()). Если вкладка включена, текст вкладки рисуется нормально, и пользователь может выбрать эту вкладку. Если она выключена, вкладка рисуется по-другому, и пользователь не может выбрать эту вкладку. Обратите внимание, что даже если вкладка выключена, страница всё ещё может быть видимой, например, если все вкладки выключены.

Виджеты вкладок могут быть очень хорошим способом разделить сложное диалоговое окно. Альтернативой является использование QStackedWidget, для которого вам необходимо предоставить способ перемещения между страницами, например, QToolBar или QListWidget.

Большая часть функциональности в QTabWidget обеспечивается QTabBar (вверху, обеспечивая вкладки) и QStackedWidget (большая часть области, организующая отдельные страницы).

См. также QTabBar, QStackedWidget, QToolBox и Пример диалогового окна с вкладками.

Документация по типам элементов

enum QTabWidget::TabPosition

Этот перечисление определяет, где QTabWidget рисует строку вкладок:

enum QTabWidget::TabShape

Этот перечисление определяет форму вкладок:

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

QTabWidget::QTabWidget(QWidget *parent = nullptr)

Создает виджет вкладок с родителем parent.

[signal] void QTabWidget::currentChanged(int index)

Этот сигнал излучается всякий раз, когда изменяется индекс текущей страницы. Параметр — новый индекс текущей страницы index, или -1, если его нет (например, если в QTabWidget нет виджетов).

Примечание: Сигнал уведомления для свойства currentIndex.

См. также currentWidget() и currentIndex.

[slot] void QTabWidget::setCurrentWidget(QWidget *widget)

Устанавливает widget в качестве текущего виджета. Используемый widget должен быть страницей в этом виджете вкладок.

См. также addTab(), setCurrentIndex() и currentWidget().

[signal] void QTabWidget::tabBarClicked(int index)

Этот сигнал излучается, когда пользователь нажимает на вкладку с индексом index.

index относится к нажатой вкладке или -1, если под курсором нет вкладки.

Эта функция была добавлена в Qt 5.2.

[signal] void QTabWidget::tabBarDoubleClicked(int index)

Этот сигнал испускается, когда пользователь дважды щелкает по вкладке с индексом index.

index — индекс нажатой вкладки, или -1, если никакая вкладка не находится под курсором.

Эта функция была добавлена в Qt 5.2.

[signal] void QTabWidget::tabCloseRequested(int index)

Этот сигнал испускается, когда нажимается кнопка закрытия вкладки. index — индекс вкладки, которую следует удалить.

Эта функция была добавлена в Qt 4.5.

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

[virtual] QTabWidget::~QTabWidget()

Удаляет виджет вкладок.

int QTabWidget::addTab(QWidget *page, const QString &label)

Добавляет вкладку с заданным page и label в виджет вкладок и возвращает индекс вкладки в панели вкладок. Владение page передаётся QTabWidget.

Если label вкладки содержит амперсанд (&), символ, следующий за амперсандом, используется в качестве сочетания клавиш для вкладки. Например, если label — "Bro&wse", то сочетание Alt+W станет сочетанием клавиш, которое переместит фокус на эту вкладку.

Примечание: Если вы вызываете addTab() после show(), система компоновки попытается адаптироваться к изменениям в иерархии виджетов и может вызвать мерцание. Для предотвращения этого можно установить свойство QWidget::updatesEnabled в значение false перед изменениями; не забудьте установить свойство в значение true, когда изменения будут выполнены, чтобы виджет снова получал события рисования.

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

int QTabWidget::addTab(QWidget *page, const QIcon &icon, const QString &label)

Это перегруженная функция.

Добавляет вкладку с заданным page, icon и label в виджет вкладок и возвращает индекс вкладки в панели вкладок. Владение page передаётся QTabWidget.

Эта функция аналогична addTab(), но с дополнительным параметром icon.

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

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

void QTabWidget::clear()

Удаляет все страницы, но не удаляет их. Вызов этой функции эквивалентен вызову removeTab() до тех пор, пока виджет вкладок не станет пустым.

QWidget *QTabWidget::cornerWidget(Qt::Corner corner = Qt::TopRightCorner) const

Возвращает виджет, отображаемый в corner (углу) виджета вкладок или nullptr.

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

QWidget *QTabWidget::currentWidget() const

Возвращает указатель на страницу, которая в данный момент отображается в диалоге вкладок. Диалог вкладок делает всё возможное, чтобы это значение никогда не было 0 (но при достаточном усердии оно может быть).

См. также currentIndex() и setCurrentWidget().

[override virtual protected] bool QTabWidget::event(QEvent *ev)

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

[override virtual] bool QTabWidget::hasHeightForWidth() const

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

[override virtual] int QTabWidget::heightForWidth(int width) const

Переопределяет: QWidget::heightForWidth(int w) const.

int QTabWidget::indexOf(QWidget *w) const

Возвращает индекс позиции страницы, занятой виджетом w, или -1, если виджет не найден.

[protected] void QTabWidget::initStyleOption(QStyleOptionTabWidgetFrame *option) const

Инициализирует option значениями из этого QTabWidget. Этот метод полезен для подклассов, когда им нужен QStyleOptionTabWidgetFrame, но они не хотят заполнять всю информацию сами.

См. также QStyleOption::initFrom() и QTabBar::initStyleOption().

int QTabWidget::insertTab(int index, QWidget *page, const QString &label)

Вставляет вкладку с заданным label и page в виджет вкладок в указанную позицию index и возвращает индекс вставленной вкладки в панели вкладок. Владение page передаётся QTabWidget.

Текст label отображается на вкладке и может иметь различный вид в зависимости от настроек виджета вкладок.

Если label вкладки содержит амперсанд (&), символ, следующий за амперсандом, используется в качестве сочетания клавиш для вкладки. Например, если label — "Bro&wse", то сочетание Alt+W станет сочетанием клавиш, которое переместит фокус на эту вкладку.

Если index находится вне диапазона, вкладка просто добавляется в конец. В противном случае она вставляется в указанную позицию.

Если QTabWidget был пуст до вызова этой функции, новая страница становится текущей страницей. Вставка новой вкладки в индекс, меньший или равный текущему индексу, увеличит текущий индекс, но сохранит текущую страницу.

Примечание: Если вы вызываете insertTab() после show(), система компоновки попытается адаптироваться к изменениям в иерархии виджетов и может вызвать мерцание. Для предотвращения этого можно установить свойство QWidget::updatesEnabled в значение false перед изменениями; не забудьте установить свойство в значение true, когда изменения будут выполнены, чтобы виджет снова получал события рисования.

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

int QTabWidget::insertTab(int index, QWidget *page, const QIcon &icon, const QString &label)

Это перегруженная функция.

Вставляет вкладку с заданным label, page и icon в виджет вкладок в указанную позицию index и возвращает индекс вставленной вкладки в панели вкладок. Владение page передаётся QTabWidget.

Эта функция аналогична insertTab(), но с дополнительным параметром icon.

bool QTabWidget::isTabEnabled(int index) const

Возвращает true, если страница в позиции index включена; в противном случае возвращает false.

См. также setTabEnabled() и QWidget::isEnabled().

bool QTabWidget::isTabVisible(int index) const

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

Эта функция была добавлена в Qt 5.15.

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

[override virtual protected] void QTabWidget::keyPressEvent(QKeyEvent *e)

Переопределяет: QWidget::keyPressEvent(QKeyEvent *event).

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

Переопределяет функцию доступа к свойству: QWidget::minimumSizeHint.

Возвращает подходящий минимальный размер для виджета вкладок.

[override virtual protected] void QTabWidget::paintEvent(QPaintEvent *event)

Переопределяет: QWidget::paintEvent(QPaintEvent *event).

Рисует панель вкладок виджета вкладок в ответ на событие рисования event.

void QTabWidget::removeTab(int index)

Удаляет вкладку в позиции index из этого стека виджетов. Виджет страницы сам по себе не удаляется.

См. также addTab() и insertTab().

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

Переопределяет: QWidget::resizeEvent(QResizeEvent *event).

void QTabWidget::setCornerWidget(QWidget *widget, Qt::Corner corner = Qt::TopRightCorner)

Устанавливает заданный widget для отображения в указанном углу виджета вкладки. Геометрия виджета определяется на основе его sizeHint() и стиля().

Будет использована только горизонтальная часть угла.

Передача nullptr не отображает виджет в углу.

Любой ранее установленный виджет угла скрывается.

Все виджеты, установленные здесь, будут удалены виджетом вкладки при его уничтожении, если вы не переместите виджет отдельно в другое родительское окно после установки другого виджета угла (или nullptr).

Примечание: виджеты углов предназначены для позиций вкладок Север и Юг; другие ориентации, как известно, работают некорректно.

См. также cornerWidget() и setTabPosition().

[protected] void QTabWidget::setTabBar(QTabBar *tb)

Заменяет заголовок диалога QTabBar на панель вкладок tb. Обратите внимание, что это должно быть выполнено до добавления вкладок, в противном случае поведение не определено.

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

void QTabWidget::setTabEnabled(int index, bool enable)

Если enable имеет значение true, страница с позицией index включена; в противном случае страница с позицией index отключена. Вкладка страницы перерисовывается соответствующим образом.

QTabWidget использует QWidget::setEnabled() внутри, а не хранит отдельный флаг.

Обратите внимание, что даже отключенная вкладка/страница может быть видимой. Если страница уже видима, QTabWidget не будет её скрывать; если все страницы отключены, QTabWidget отобразит одну из них.

См. также isTabEnabled() и QWidget::setEnabled().

void QTabWidget::setTabIcon(int index, const QIcon &icon)

Устанавливает иконку для вкладки на позиции index.

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

void QTabWidget::setTabText(int index, const QString &label)

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

Если предоставленный текст содержит символ амперсанда ('&'), для него автоматически создаётся ярлык. Символ, следующий за '&', будет использоваться в качестве клавиши быстрого доступа. Любой предыдущий ярлык будет перезаписан или очищен, если ярлык не определён в тексте. Подробности см. в документации QShortcut (чтобы отобразить фактический амперсанд, используйте '&&').

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

void QTabWidget::setTabToolTip(int index, const QString &tip)

Устанавливает подсказку для вкладки страницы на позиции index в tip.

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

void QTabWidget::setTabVisible(int index, bool visible)

Если visible имеет значение true, страница на позиции index видима; в противном случае страница на позиции index скрыта. Вкладка страницы перерисовывается соответствующим образом.

Эта функция была добавлена в Qt 5.15.

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

void QTabWidget::setTabWhatsThis(int index, const QString &text)

Устанавливает текст справки «Что это?» для страницы на позиции index в text.

Эта функция была добавлена в Qt 4.1.

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

[override virtual protected] void QTabWidget::showEvent(QShowEvent *)

Переопределяет: QWidget::showEvent(QShowEvent *event).

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

Переопределяет функцию доступа к свойству: QWidget::sizeHint.

QTabBar *QTabWidget::tabBar() const

Возвращает текущую QTabBar.

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

QIcon QTabWidget::tabIcon(int index) const

Возвращает иконку вкладки на странице с позицией index.

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

[virtual protected] void QTabWidget::tabInserted(int index)

Этот виртуальный обработчик вызывается после добавления или вставки новой вкладки в позицию index.

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

[virtual protected] void QTabWidget::tabRemoved(int index)

Этот виртуальный обработчик вызывается после удаления вкладки из позиции index.

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

QString QTabWidget::tabText(int index) const

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

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

QString QTabWidget::tabToolTip(int index) const

Возвращает подсказку для вкладки страницы на позиции index или пустую строку, если подсказка не установлена.

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

QString QTabWidget::tabWhatsThis(int index) const

Возвращает текст справки «Что это?» для страницы на позиции index или пустую строку, если текст не задан.

Эта функция была добавлена в Qt 4.1.

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

QWidget *QTabWidget::widget(int index) const

Возвращает страницу вкладки на позиции index или nullptr если index выходит за пределы диапазона.