Класс QMainWindow

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

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

Публичные типы

Свойства

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

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

• 211 public functions inherited from QWidget
• 31 public functions inherited from QObject
• 14 public functions inherited from QPaintDevice

Public Slots

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

Сигналы

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

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

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

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

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

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

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

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

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

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

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

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

Главные окна имеют либо однодокументный (SDI) или многодокументный (MDI) интерфейс. Вы создаёте MDI-приложения в Qt, используя QMdiArea в качестве центрального виджета.

Теперь мы рассмотрим каждый из других виджетов, которые можно добавить в главное окно. Мы даём примеры того, как их создать и добавить.

Создание Меню

Qt реализует меню в классе QMenu, а QMainWindow хранит их в QMenuBar. QActions добавляются в меню, которые отображаются в виде пунктов меню.

Вы можете добавить новые меню в строку меню главного окна, вызвав 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 и Пример Меню.

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

enum QMainWindow::DockOptionflags QMainWindow::DockOptions

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

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

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

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

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

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

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

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

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

[virtual protected] void QMainWindow::contextMenuEvent(QContextMenuEvent *event)

Переопределено из QWidget::contextMenuEvent().

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

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

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

[virtual] QMenu *QMainWindow::createPopupMenu()

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

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

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

См. также addDockWidget(), addToolBar() и menuBar().

Qt::DockWidgetArea QMainWindow::dockWidgetArea(QDockWidget *dockwidget) const

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

См. также addDockWidget(), splitDockWidget() и Qt::DockWidgetArea.

[virtual protected] bool QMainWindow::event(QEvent *event)

Переопределено из QObject::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. Если они не совпадают, состояние главного окна остаётся неизменным, и эта функция возвращает 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.

Установка строки состояния в 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().

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

[signal] void QMainWindow::toolButtonStyleChanged(Qt::ToolButtonStyle toolButtonStyle)

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

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

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