Класс QMainWindow

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

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

Типы

Свойства

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

Public Slots

Signals

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

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

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

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

Примечание: Создание главного окна без центрального виджета не поддерживается. Вам необходимо иметь центральный виджет, даже если это просто заполнитель.

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

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

Главные окна имеют либо однодокументный (SDI), либо многодокументный (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, Пример приложения, Пример виджетов доков, Пример MDI, Пример SDI и Пример меню.

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

перечисление QMainWindow::DockOptionфлаги QMainWindow::DockOptions

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

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

Это перечисление было введено или изменено в Qt 4.3.

Тип 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] 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)

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

См. также 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)

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

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

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

См. также 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)

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

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

void QMainWindow::insertToolBarBreak(QToolBar *before)

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

QMenuBar *QMainWindow::menuBar() const

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

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

QMenuBar *menuBar = new QMenuBar(0);

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

QWidget *QMainWindow::menuWidget() const

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

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

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

void QMainWindow::removeDockWidget(QDockWidget *dockwidget)

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

void QMainWindow::removeToolBar(QToolBar *toolbar)

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

void QMainWindow::removeToolBarBreak(QToolBar *before)

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

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 и удаляет его в соответствующее время.

Данная функция была добавлена в Qt 4.2.

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

void QMainWindow::setStatusBar(QStatusBar *statusbar)

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

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

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

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

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

Примечание: Параметр док-опции VerticalTabs переопределяет позиции вкладок, установленные этим методом.

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

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

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

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

orientation определяет способ разделения: Qt::Horizontal размещает second справа от first; Qt::Vertical — ниже.

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

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

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

QStatusBar *QMainWindow::statusBar() const

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

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

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

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

Примечание: Параметр док-опции VerticalTabs переопределяет позиции вкладок, возвращаемые этой функцией.

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

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

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

Возвращает док-виджеты, объединённые вкладки с dockwidget.

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

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

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

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

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

QWidget *QMainWindow::takeCentralWidget()

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

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

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

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

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

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

bool QMainWindow::toolBarBreak(QToolBar *toolbar) const

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

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