Класс QMainWindow

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

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

Общие типы

Свойства

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

Public Slots

Signals

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

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

Фреймворк главного окна 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, Пример приложения, Пример виджетов закладок, Пример MDI, Пример SDI и Пример меню.

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

перечисление QMainWindow::DockOptionflags 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().