Класс QMainWindow

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

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

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

Свойства

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

Public Slots

Signals

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

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

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

Главное окно предоставляет фреймворк для построения пользовательского интерфейса приложения. Qt имеет QMainWindow и его родственные классы для управления главным окном. QMainWindow имеет собственную компоновку, к которой можно добавить QToolBars, QDockWidgets, 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(nullptr);

См. также 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 панелей инструментов и виджетов плавающей панели этого главного окна. Также восстанавливает настройки угла. Номер 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

Для восстановления сохраненного состояния передайте возвращаемое значение и номер версии в 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) размещает second док-виджет ниже first.

Примечание: если 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

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

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