Класс QMainWindow

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

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

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

Свойства

• 59 свойств унаследовано от QWidget
• 1 свойство унаследовано от QObject

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

• 214 public functions inherited from QWidget
• 34 public functions inherited from QObject
• 14 public functions inherited from QPaintDevice

Публичные слоты

• 19 public slots inherited from QWidget
• 1 public slot inherited from QObject

Сигналы

• 3 сигнала унаследованы от QWidget
• 2 сигнала унаследованы от QObject

Переопределённые защищённые функции

• 35 защищённых функций унаследованы от QWidget
• 9 защищённых функций унаследованы от QObject
• 1 защищённая функция унаследована от QPaintDevice

Дополнительные унаследованные члены

• 1 публичная переменная унаследована от QObject
• 5 статических публичных членов унаследованы от QWidget
• 10 статических публичных членов унаследованы от QObject
• 35 защищённых функций унаследованы от QWidget
• 9 защищённых функций унаследованы от QObject
• 1 защищённая функция унаследована от QPaintDevice
• 1 защищённый слот унаследован от QWidget
• 2 защищённых переменных унаследованы от QObject
• 1 защищённый тип унаследован от QPaintDevice

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

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

Фреймворк главного окна 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::DockOptionфлаги QMainWindow::DockOptions

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

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

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

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

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

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

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

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

[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().

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

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

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

[virtual] QMenu *QMainWindow::createPopupMenu()

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

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

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

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

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

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

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

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

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

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

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

void QMainWindow::setStatusBar(QStatusBar *statusbar)

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

Установка строки состояния в 0 удалит ее из главного окна. Обратите внимание, что 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 помещает второй док-виджет справа от первого; разделение 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().

void QMainWindow::tabifiedDockWidgetActivated(QDockWidget *dockWidget)

Этот сигнал излучается, когда активируется док-виджет с вкладками путем выбора вкладки. Активированный док-виджет передается в dockWidget.

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

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

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().

void QMainWindow::toolButtonStyleChanged(Qt::ToolButtonStyle toolButtonStyle)

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

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

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