Класс QMainWindow

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

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

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

Свойства

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

Открытые слоты

Сигналы

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

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

Фреймворк главного окна Qt

Главное окно предоставляет основу для построения пользовательского интерфейса приложения. Qt предоставляет QMainWindow и его сопутствующие классы для управления главным окном. QMainWindow имеет собственную компоновку, к которой можно добавить QToolBar, QDockWidget, QMenuBar и QStatusBar. В центральной области компоновки можно разместить любой виджет. Ниже представлено изображение компоновки.

Создание компонентов главного окна

Центральный виджет обычно представляет собой стандартный виджет Qt, такой как QTextEdit или QGraphicsView. Для сложных приложений также можно использовать пользовательские виджеты. Центральный виджет устанавливается с помощью setCentralWidget().

Главные окна имеют либо единый (SDI) или множественный (MDI) интерфейс документа. Приложения MDI в Qt создаются с помощью QMdiArea в качестве центрального виджета.

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

Создание меню

Qt реализует меню в QMenu, а QMainWindow хранит их в QMenuBar. QAction добавляются в меню, отображая их как пункты меню.

Для добавления новых меню в строку меню главного окна вызывается menuBar(), которая возвращает QMenuBar для окна, а затем добавляется меню с помощью QMenuBar::addMenu().

QMainWindow поставляется с панелью меню по умолчанию, но вы также можете установить её самостоятельно с помощью setMenuBar(). Если необходимо реализовать пользовательскую панель меню (т.е. не использовать виджет QMenuBar), её можно установить с помощью setMenuWidget().

Пример создания меню:

    void MainWindow::createMenus()
    {
        fileMenu = menuBar()->addMenu(tr("&File"));
        fileMenu->addAction(newAct);
        fileMenu->addAction(openAct);
        fileMenu->addAction(saveAct);

Функция createPopupMenu() создает всплывающие меню, когда главное окно получает события контекстного меню. По умолчанию генерируется меню с флажками из виджетов панели инструментов и док-виджетов. Вы можете переопределить createPopupMenu() для создания пользовательского меню.

Создание панелей инструментов

Панели инструментов реализованы в классе QToolBar. Вы добавляете панель инструментов в главное окно с помощью addToolBar().

Начальное расположение панелей инструментов контролируется присвоением им конкретной области Qt::ToolBarArea. Вы можете разделить область, вставив разрыв панели инструментов — это можно представить как разрыв строки в текстовом редакторе — с помощью addToolBarBreak() или insertToolBarBreak() . Вы также можете ограничить размещение пользователем с помощью QToolBar::setAllowedAreas() и QToolBar::setMovable().

Размер значков панели инструментов можно получить с помощью iconSize(). Размеры зависят от платформы; вы можете установить фиксированный размер с помощью setIconSize(). Вы можете изменить внешний вид всех кнопок на панели инструментов с помощью setToolButtonStyle().

Пример создания панели инструментов:

    void MainWindow::createToolBars()
    {
        fileToolBar = addToolBar(tr("File"));
        fileToolBar->addAction(newAct);

Создание док-виджетов

Док-виджеты реализованы в классе QDockWidget. Док-виджет — это окно, которое может быть прикреплено к главному окну. Вы добавляете док-виджеты в главное окно с помощью addDockWidget().

Существует четыре области док-виджетов, задаваемые перечислением Qt::DockWidgetArea: слева, справа, сверху и снизу. Вы можете указать, какую область док-виджета следует занимать в местах пересечения областей с помощью setCorner(). По умолчанию каждая область может содержать только один ряд (вертикальный или горизонтальный) док-виджетов, но если вы включите вложенность с помощью setDockNestingEnabled(), док-виджеты можно добавлять в любом направлении.

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

Пример создания и добавления док-виджетов в главное окно:

    QDockWidget *dockWidget = new QDockWidget(tr("Dock Widget"), this);
    dockWidget->setAllowedAreas(Qt::LeftDockWidgetArea |
                                Qt::RightDockWidgetArea);
    dockWidget->setWidget(dockWidgetContents);
    addDockWidget(Qt::LeftDockWidgetArea, dockWidget);

Панель состояния

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

Сохранение состояния

QMainWindow может сохранить состояние своей компоновки с помощью saveState(); она может быть позже получена с помощью restoreState(). Сохраняются положение и размеры (относительно размера главного окна) панелей инструментов и док-виджетов.

См. также QMenuBar, QToolBar, QStatusBar, QDockWidget, Qt Widgets - Пример приложения, Пример док-виджетов, Пример MDI, Пример SDI и Пример меню.

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

Перечисление QMainWindow::DockOption флагов QMainWindow::DockOptions

Это перечисление содержит флаги, которые определяют поведение прикрепления QMainWindow.

Эти параметры контролируют только то, как док-виджеты могут быть размещены в QMainWindow. Они не переупорядочивают док-виджеты в соответствии с указанными параметрами. По этой причине их следует устанавливать до добавления каких-либо док-виджетов в главное окно. Исключение составляют параметры AnimatedDocks и VerticalTabs, которые могут быть установлены в любое время.

Тип DockOptions является псевдонимом для QFlags<DockOption>. Он хранит логическое ИЛИ комбинацию значений DockOption.

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

QMainWindow::QMainWindow(QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags())

Конструирует QMainWindow с указанным parent и заданными флагами виджета flags.

QMainWindow устанавливает флаг Qt::Window сам и, следовательно, всегда создается как виджет верхнего уровня.

[signal] void QMainWindow::iconSizeChanged(const QSize &iconSize)

Этот сигнал подается при изменении размера значков, используемых в окне. Новый размер значка передан в iconSize.

Вы можете подключить этот сигнал к другим компонентам, чтобы поддерживать согласованный внешний вид вашего приложения.

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

[signal, since 5.8] void QMainWindow::tabifiedDockWidgetActivated(QDockWidget *dockWidget)

Этот сигнал подается при активации панели с вкладками путем выбора вкладки. Активированная панель передана в dockWidget.

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

См. также tabifyDockWidget() и tabifiedDockWidgets().

[signal] void QMainWindow::toolButtonStyleChanged(Qt::ToolButtonStyle toolButtonStyle)

Этот сигнал подается при изменении стиля, используемого для кнопок инструментальной панели в окне. Новый стиль передан в toolButtonStyle.

Вы можете подключить этот сигнал к другим компонентам, чтобы поддерживать согласованный внешний вид вашего приложения.

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

[virtual] QMainWindow::~QMainWindow()

Удаляет главное окно.

void QMainWindow::addDockWidget(Qt::DockWidgetArea area, QDockWidget *dockwidget)

Добавляет заданную dockwidget в указанную area.

void QMainWindow::addDockWidget(Qt::DockWidgetArea area, QDockWidget *dockwidget, Qt::Orientation orientation)

Добавляет dockwidget в заданную area в направлении, заданном orientation.

void QMainWindow::addToolBar(Qt::ToolBarArea area, QToolBar *toolbar)

Добавляет панель инструментов в указанную область в этом главном окне. Панель инструментов размещается в конце текущего блока панели инструментов (т.е. строки). Если главное окно уже управляет панелью инструментов, то она будет только перемещена в область.

См. также insertToolBar(), addToolBarBreak() и insertToolBarBreak().

void QMainWindow::addToolBar(QToolBar *toolbar)

Это перегруженный метод.

Эквивалентно вызову addToolBar(Qt::TopToolBarArea, toolbar)

QToolBar *QMainWindow::addToolBar(const QString &title)

Это перегруженный метод.

Создаёт объект QToolBar, устанавливая его заголовок окна на title, и вставляет его в область верхней панели инструментов.

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

void QMainWindow::addToolBarBreak(Qt::ToolBarArea area = Qt::TopToolBarArea)

Добавляет разделитель панели инструментов в заданную область после всех других присутствующих объектов.

QWidget *QMainWindow::centralWidget() const

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

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

[override virtual protected] void QMainWindow::contextMenuEvent(QContextMenuEvent *event)

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

Qt::DockWidgetArea QMainWindow::corner(Qt::Corner corner) const

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

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

[virtual] QMenu *QMainWindow::createPopupMenu()

Возвращает всплывающее меню, содержащее флажковые пункты для панелей инструментов и виджетов привязки, присутствующих в главном окне. Если панелей инструментов и виджетов привязки нет, эта функция возвращает nullptr.

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

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

См. также addDockWidget(), addToolBar() и menuBar().

Qt::DockWidgetArea QMainWindow::dockWidgetArea(QDockWidget *dockwidget) const

Возвращает Qt::DockWidgetArea для dockwidget. Если dockwidget не был добавлен в главное окно, эта функция возвращает Qt::NoDockWidgetArea.

См. также addDockWidget(), splitDockWidget() и Qt::DockWidgetArea.

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

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

void QMainWindow::insertToolBar(QToolBar *before, QToolBar *toolbar)

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

См. также insertToolBarBreak(), addToolBar() и addToolBarBreak().

void QMainWindow::insertToolBarBreak(QToolBar *before)

Вставляет разделитель панели инструментов перед панелью инструментов, указанной before.

QMenuBar *QMainWindow::menuBar() const

Возвращает строку меню для главного окна. Эта функция создаёт и возвращает пустую строку меню, если строки меню не существует.

Если вы хотите, чтобы все окна в приложении Mac использовали одну строку меню, не используйте эту функцию для её создания, потому что созданная здесь строка меню будет иметь это QMainWindow в качестве своего родителя. Вместо этого вы должны создать строку меню, у которой нет родителя, которую вы можете затем использовать совместно между всеми окнами Mac. Создайте строку меню без родителя таким образом:

QMenuBar *menuBar = new QMenuBar(nullptr);

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

QWidget *QMainWindow::menuWidget() const

Возвращает строку меню для главного окна. Эта функция возвращает null, если строка меню ещё не была создана.

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

void QMainWindow::removeDockWidget(QDockWidget *dockwidget)

Удаляет dockwidget из макета главного окна и скрывает его. Обратите внимание, что dockwidget не удаляется.

void QMainWindow::removeToolBar(QToolBar *toolbar)

Удаляет панель инструментов из макета главного окна и скрывает её. Обратите внимание, что панель инструментов не удаляется.

void QMainWindow::removeToolBarBreak(QToolBar *before)

Удаляет разделитель панели инструментов, вставленный ранее перед панелью инструментов, указанной before.

[since 5.6] void QMainWindow::resizeDocks(const QList<QDockWidget *> &docks, const QList<int> &sizes, Qt::Orientation orientation)

Изменяет размеры виджетов привязки в списке docks на соответствующие размеры в пикселях из списка sizes. Если orientation равен Qt::Horizontal, корректирует ширину, в противном случае корректирует высоту виджетов привязки. Размеры будут изменены таким образом, чтобы были соблюдены максимальные и минимальные размеры, и само QMainWindow не будет изменён в размерах. Любое дополнительное/отсутствующее пространство распределяется между виджетами в соответствии с относительным весом размеров.

Пример:

    resizeDocks({blueWidget, yellowWidget}, {20 , 40}, Qt::Horizontal);

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

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

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

bool QMainWindow::restoreDockWidget(QDockWidget *dockwidget)

Восстанавливает состояние dockwidget, если он создан после вызова restoreState(). Возвращает true, если состояние было восстановлено; в противном случае возвращает false.

См. также restoreState() и saveState().

bool QMainWindow::restoreState(const QByteArray &state, int version = 0)

Восстанавливает состояние панелей инструментов и виджетов привязки этого главного окна. Также восстанавливаются настройки угла. Номер версии сравнивается с тем, который хранится в state. Если они не совпадают, состояние главного окна остаётся неизменным, и эта функция возвращает false; в противном случае состояние восстанавливается, и эта функция возвращает true.

Для восстановления геометрии, сохранённой с помощью QSettings, можно использовать код, подобный этому:

void MainWindow::readSettings()
{
    QSettings settings("MyCompany", "MyApp");
    restoreGeometry(settings.value("myWidget/geometry").toByteArray());
    restoreState(settings.value("myWidget/windowState").toByteArray());
}

См. также saveState(), QWidget::saveGeometry(), QWidget::restoreGeometry() и restoreDockWidget().

QByteArray QMainWindow::saveState(int version = 0) const

Сохраняет текущее состояние панелей инструментов и виджетов привязки этого главного окна. Это включает настройки угла, которые можно установить с помощью setCorner(). Номер версии сохраняется как часть данных.

Свойство objectName используется для идентификации каждой QToolBar и QDockWidget. Необходимо убедиться, что это свойство уникально для каждой QToolBar и QDockWidget, которые вы добавляете в QMainWindow.

Для восстановления сохранённого состояния передайте возвращаемое значение и номер версии в restoreState().

Для сохранения геометрии при закрытии окна можно реализовать обработчик закрытия таким образом:

void MyMainWindow::closeEvent(QCloseEvent *event)
{
    QSettings settings("MyCompany", "MyApp");
    settings.setValue("geometry", saveGeometry());
    settings.setValue("windowState", saveState());
    QMainWindow::closeEvent(event);
}

См. также restoreState(), QWidget::saveGeometry(), и QWidget::restoreGeometry().

void QMainWindow::setCentralWidget(QWidget *widget)

Устанавливает заданный widget в качестве центрального виджета главного окна.

Примечание: QMainWindow принимает во владение указатель widget и удаляет его в соответствующее время.

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

void QMainWindow::setCorner(Qt::Corner corner, Qt::DockWidgetArea area)

Устанавливает заданную область area для виджета плавающего окна, чтобы она занимала указанный corner.

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

void QMainWindow::setMenuBar(QMenuBar *menuBar)

Устанавливает строку меню главного окна в menuBar.

Примечание: QMainWindow принимает во владение указатель menuBar и удаляет его в соответствующее время.

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

void QMainWindow::setMenuWidget(QWidget *menuBar)

Устанавливает строку меню для главного окна в menuBar.

QMainWindow принимает во владение указатель menuBar и удаляет его в соответствующее время.

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

void QMainWindow::setStatusBar(QStatusBar *statusbar)

Устанавливает строку состояния для главного окна в statusbar.

Установка строки состояния в nullptr удалит ее из главного окна. Обратите внимание, что QMainWindow принимает во владение указатель statusbar и удаляет его в соответствующее время.

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

void QMainWindow::setTabPosition(Qt::DockWidgetAreas areas, QTabWidget::TabPosition tabPosition)

Устанавливает положение вкладок для заданных областей плавающих окон areas в указанное tabPosition. По умолчанию все области плавающих окон отображают вкладки внизу.

См. также tabPosition() и setTabShape().

void QMainWindow::splitDockWidget(QDockWidget *first, QDockWidget *second, Qt::Orientation orientation)

Разделяет пространство, занимаемое виджетом плавающего окна first, на две части, перемещает first виджет плавающего окна в первую часть и second виджет плавающего окна во вторую часть.

orientation задает способ разделения пространства: Разделение Qt::Horizontal помещает второй виджет плавающего окна справа от первого; разделение Qt::Vertical помещает второй виджет плавающего окна ниже первого.

Примечание: если first в данный момент находится в области плавающего окна с вкладками, second будет добавлен как новая вкладка, а не как сосед first. Это связано с тем, что одна вкладка может содержать только один виджет плавающего окна.

Примечание: Qt::LayoutDirection влияет на порядок виджетов плавающего окна в двух частях разделительной области. При включенном направлении отображения справа налево размещение виджетов плавающего окна будет обратным.

См. также tabifyDockWidget(), addDockWidget() и removeDockWidget().

QStatusBar *QMainWindow::statusBar() const

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

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

QTabWidget::TabPosition QMainWindow::tabPosition(Qt::DockWidgetArea area) const

Возвращает положение вкладки для area.

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

QList<QDockWidget *> QMainWindow::tabifiedDockWidgets(QDockWidget *dockwidget) const

Возвращает виджеты плавающих окон, которые сгруппированы с помощью вкладок вместе с dockwidget.

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

void QMainWindow::tabifyDockWidget(QDockWidget *first, QDockWidget *second)

Перемещает виджет плавающего окна second поверх виджета плавающего окна first, создавая область плавающего окна с вкладками в главном окне.

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

[since 5.2] QWidget *QMainWindow::takeCentralWidget()

Удаляет центральный виджет из этого главного окна.

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

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

Qt::ToolBarArea QMainWindow::toolBarArea(const QToolBar *toolbar) const

Возвращает Qt::ToolBarArea для toolbar. Если toolbar не добавлен в главное окно, эта функция возвращает Qt::NoToolBarArea.

См. также addToolBar(), addToolBarBreak() и Qt::ToolBarArea.

bool QMainWindow::toolBarBreak(QToolBar *toolbar) const

Возвращает значение true, если перед toolbar есть разрыв строки инструментов, иначе false.

См. также addToolBarBreak() и insertToolBarBreak().