Класс QMainWindow

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

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

Типы публичного доступа

Свойства

Публичные функции

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

Сигналы

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

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

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

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

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

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

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

Главные окна имеют либо однодокументный (SDI) интерфейс, либо многодокументный (MDI) интерфейс. В Qt MDI-приложения создаются с помощью 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, так что она появляется перед ней. Например, в обычной схеме слева направо это означает, что 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)

Восстанавливает состояние панелей инструментов и виджетов панелей этого главного окна. Также восстанавливаются настройки угла. Номер version сравнивается с тем, который хранится в 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(). Номер version сохраняется как часть данных.

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

Чтобы восстановить сохранённое состояние, передайте возвращаемое значение и номер version в 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. По умолчанию, все области показывают вкладки снизу.

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

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

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

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

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

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