Класс QWidget

Класс QWidget является базовым классом всех объектов пользовательского интерфейса. Подробнее...

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

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

Свойства

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

Реализованные Публичные Функции

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

Сигналы

Статические Публичные Члены

Защищенные Функции

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

Защищённые слоты

Макросы

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

Виджет — это атом пользовательского интерфейса: он получает события мыши, клавиатуры и другие события от системы окон и рисует своё представление на экране. Каждый виджет прямоугольный, и они упорядочены в порядке Z. Виджет обрезается своим родителем и виджетами, расположенными перед ним.

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

Конструктор каждого виджета принимает один или два стандартных аргумента:

1. QWidget *parent = nullptr — родитель нового виджета. Если он равен nullptr (по умолчанию), новый виджет будет окном. В противном случае он будет дочерним элементом parent и будет ограничен геометрией parent (если вы не укажете флаг окна Qt::Window).
2. Qt::WindowFlags f = { } (применимо) задаёт флаги окна; по умолчанию подходит для почти всех виджетов, но чтобы, например, получить окно без рамки системы окон, необходимо использовать специальные флаги.

QWidget имеет много функций-членов, но некоторые из них имеют мало непосредственной функциональности; например, QWidget имеет свойство шрифта, но никогда не использует его сам. Существует много подклассов, которые предоставляют реальную функциональность, например, QLabel, QPushButton, QListWidget и QTabWidget.

Главные и дочерние виджеты

Виджет без родительского виджета всегда является независимым окном (главный виджет). Для этих виджетов setWindowTitle() и setWindowIcon() соответственно устанавливают строку заголовка и значок.

Неокно виджеты — это дочерние виджеты, отображаемые внутри своих родительских виджетов. Большинство виджетов в Qt полезны в основном как дочерние виджеты. Например, можно отобразить кнопку как окно верхнего уровня, но большинство людей предпочитают размещать свои кнопки внутри других виджетов, например, QDialog.

На диаграмме показан виджет QGroupBox, используемый для размещения различных дочерних виджетов в макете, предоставляемом QGridLayout. Дочерние виджеты QLabel были выделены, чтобы указать их полные размеры.

Если вы хотите использовать QWidget для размещения дочерних виджетов, обычно необходимо добавить макет в родительский QWidget. Более подробная информация об управлении макетами приведена в разделе Управление макетами.

Композитные виджеты

Когда виджет используется в качестве контейнера для группировки ряда дочерних виджетов, он известен как композитный виджет. Их можно создать, создав виджет с необходимыми визуальными свойствами — например, QFrame — и добавив к нему дочерние виджеты, обычно управляемые макетом. На приведенной выше диаграмме показан такой композитный виджет, созданный с помощью Qt Designer.

Композитные виджеты также можно создать, создав подкласс стандартного виджета, такого как QWidget или QFrame, и добавив необходимый макет и дочерние виджеты в конструктор подкласса. Многие примеры, предоставляемые с Qt, используют этот подход, а также он описан в руководствах Qt по учебникам.

Настраиваемые виджеты и рисование

Поскольку QWidget является подклассом QPaintDevice, подклассы могут использоваться для отображения пользовательского содержимого, которое составляется с помощью ряда операций рисования с экземпляром класса QPainter. Этот подход отличается от подхода на основе холста, используемого Graphics View Framework, где элементы добавляются в сцену приложением и отрисовываются самим фреймворком.

Каждый виджет выполняет все операции рисования внутри своей функции paintEvent(). Она вызывается всякий раз, когда виджет необходимо перерисовать, либо в результате какого-либо внешнего изменения, либо по запросу приложения.

Пример Аналоговых часов демонстрирует, как простой виджет может обрабатывать события рисования.

Рекомендованные размеры и политики размеров

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

По умолчанию составные виджеты, которые не предоставляют подсказку размера, будут иметь размеры, соответствующие требованиям по пространству их дочерних виджетов.

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

Примечание: Размер виджетов верхнего уровня ограничен 2/3 высоты и ширины рабочего стола. Вы можете изменить размер виджета вручную, если эти ограничения недостаточны.

События

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

Если ваш виджет содержит только дочерние виджеты, вам, вероятно, не нужно реализовывать обработчики событий. Если вы хотите обнаружить щелчок мыши в дочернем виджете, вызовите функцию underMouse() дочернего виджета внутри функции mousePressEvent() виджета.

Пример Рисования реализует более широкий набор событий для обработки перемещения мыши, нажатий кнопок и изменения размера окна.

Вам необходимо обеспечить поведение и содержимое для собственных виджетов, но вот краткий обзор событий, относящихся к QWidget, начиная с самых распространённых:

• paintEvent() вызывается всякий раз, когда виджет необходимо перерисовать. Каждый виджет, отображающий пользовательское содержимое, должен реализовать его. Рисование с помощью QPainter может происходить только в paintEvent() или в функции, вызываемой paintEvent().
• resizeEvent() вызывается при изменении размера виджета.
• mousePressEvent() вызывается при нажатии кнопки мыши, когда курсор мыши находится внутри виджета или когда виджет захватил мышь с помощью grabMouse(). Нажатие мыши без отпускания по сути эквивалентно вызову grabMouse().
• mouseReleaseEvent() вызывается при отпускании кнопки мыши. Виджет получает события отпускания мыши, когда он получил соответствующее событие нажатия мыши. Это означает, что если пользователь нажимает мышь внутри вашего виджета, затем перетаскивает мышь куда-то ещё, прежде чем отпустить кнопку мыши, ваш виджет получает событие отпускания. Есть одно исключение: если появляется всплывающее меню, пока удерживается кнопка мыши, это всплывающее меню сразу же захватывает события мыши.
• mouseDoubleClickEvent() вызывается при двойном щелчке пользователем внутри виджета. Если пользователь дважды щелкает, виджет получает событие нажатия мыши, событие отпускания мыши, (событие щелчка мыши,) второе нажатие мыши, это событие и, наконец, второе отпускание мыши. (Возможно получение некоторых событий перемещения мыши, если мышь не удерживается неподвижно во время этой операции.) Невозможно отличить щелчок от двойного щелчка до появления второго щелчка. (Вот одна из причин, почему большинство книг по графическому интерфейсу рекомендуют, чтобы двойные щелчки являлись расширением одиночных щелчков, а не срабатывали как отдельное действие.)

Виджеты, которые принимают ввод с клавиатуры, должны переопределить несколько дополнительных обработчиков событий:

• keyPressEvent() вызывается всякий раз, когда нажимается клавиша, и снова, когда клавиша удерживается достаточно долго, чтобы начать автоповтор. Клавиши Tab и Shift+Tab передаются виджету только в том случае, если они не используются механизмами изменения фокуса. Чтобы принудительно обработать эти клавиши вашим виджетом, необходимо переопределить QWidget::event().
• focusInEvent() вызывается, когда виджет получает фокус клавиатуры (при условии, что вы вызвали setFocusPolicy()). Хорошо спроектированные виджеты указывают, что они владеют фокусом клавиатуры, чётко, но незаметно.
• focusOutEvent() вызывается, когда виджет теряет фокус клавиатуры.

Возможно, вам также потребуется переопределить некоторые менее распространённые обработчики событий:

• mouseMoveEvent() вызывается всякий раз, когда мышь перемещается, удерживая кнопку мыши. Это может быть полезно во время операций перетаскивания. Если вы вызываете setMouseTracking(true), вы получаете события перемещения мыши даже при отсутствии нажатых кнопок. (См. также руководство по перетаскиванию.)
• keyReleaseEvent() вызывается всякий раз, когда клавиша отпускается, и пока она удерживается (если клавиша имеет автоповтор). В этом случае виджет получит пару событий отпускания и нажатия клавиши для каждого повтора. Клавиши Tab и Shift+Tab передаются виджету только в том случае, если они не используются механизмами изменения фокуса. Чтобы принудительно обработать эти клавиши вашим виджетом, необходимо переопределить QWidget::event().
• wheelEvent() вызывается всякий раз, когда пользователь вращает колесо мыши, удерживая фокус на виджете.
• enterEvent() вызывается при входе курсора мыши в область экрана виджета. (Это исключает область экрана, принадлежащую любому дочернему виджету.)
• leaveEvent() вызывается при выходе курсора мыши из области экрана виджета. Если мышь входит в дочерний виджет, это не вызовет leaveEvent().
• moveEvent() вызывается при перемещении виджета относительно его родителя.
• closeEvent() вызывается при закрытии виджета пользователем (или при вызове close()).

Также существуют некоторые довольно необычные события, описанные в документации для QEvent::Type. Для обработки этих событий необходимо переопределить event() напрямую.

В реализации по умолчанию event() обрабатываются клавиши Tab и Shift+Tab (для перемещения фокуса клавиатуры) и передаются большинство других событий одному из более специализированных обработчиков выше.

События и механизм их доставки описаны в Системе событий.

Группы функций и свойств

Стили виджетов

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

Использование листов стилей виджетов подробно описано в документе Стили Qt.

Прозрачность и буферизация

Начиная с Qt 4.0, QWidget автоматически использует буферизацию при отрисовке, поэтому нет необходимости писать код буферизации в paintEvent() для избежания мерцания.

Начиная с Qt 4.1, содержимое родительских виджетов по умолчанию распространяется на все их дочерние виджеты, если не установлен Qt::WA_PaintOnScreen. Пользовательские виджеты могут использовать эту функцию, обновляя нестандартные области (для создания непрямоугольных дочерних виджетов) или рисуя с цветом, имеющим менее чем полный альфа-компонент. На рисунке ниже показано, как можно точно настроить атрибуты и свойства пользовательского виджета для достижения различных эффектов.

На рисунке выше представлен полупрозрачный прямоугольный дочерний виджет с удалённой областью, добавленный в родительский виджет (виджет QLabel, отображающий пиксель). Затем задаются различные свойства и атрибуты виджета для достижения разных эффектов:

• В левом виджете не заданы дополнительные свойства или атрибуты виджета. Этот стандартный режим подходит для большинства пользовательских виджетов, использующих прозрачность, нестандартные формы или не заполняющих всю область непрозрачной кистью.
• В центральном виджете задано свойство autoFillBackground. Это свойство используется с пользовательскими виджетами, которые полагаются на виджет для обеспечения фонового изображения по умолчанию и не заполняют всю область непрозрачной кистью.
• В правом виджете установлен атрибут виджета Qt::WA_OpaquePaintEvent. Это указывает, что виджет будет заполнять всю область непрозрачными цветами. Область виджета изначально будет *неинициализирована*, на рисунке она представлена диагональной красной сеткой, просвечивающей через перерисованную область. Атрибут Qt::WA_OpaquePaintArea полезен для виджетов, которые нуждаются в быстрой отрисовке собственного специализированного содержимого и не нуждаются в фоновом заполнении по умолчанию.

Для быстрого обновления пользовательских виджетов простыми цветами фона, таких как виджеты для реального времени или графики, лучше определить подходящий цвет фона (используя setBackgroundRole() с ролью QPalette::Window), установить свойство autoFillBackground и реализовать необходимую функциональность рисования в paintEvent() виджета.

Для быстрого обновления пользовательских виджетов, постоянно рисующих всю область непрозрачным содержимым, например, виджетов потоковой передачи видео, лучше установить атрибут виджета Qt::WA_OpaquePaintEvent, избегая излишних накладных расходов, связанных с перерисовкой фона виджета.

Если у виджета установлен атрибут виджета Qt::WA_OpaquePaintEvent *и* свойство autoFillBackground, атрибут Qt::WA_OpaquePaintEvent имеет приоритет. В зависимости от ваших потребностей, следует выбрать один из них.

Начиная с Qt 4.1, содержимое родительских виджетов также распространяется на стандартные виджеты Qt. Это может привести к неожиданным результатам, если родительский виджет оформлен нестандартно, как показано на рисунке ниже.

Возможности настройки поведения рисования стандартных виджетов Qt без создания подклассов несколько меньше, чем для пользовательских виджетов. Обычно нужный внешний вид стандартного виджета можно получить, установив свойство autoFillBackground.

Создание непрозрачных окон

Начиная с Qt 4.5, стало возможным создавать окна с полупрозрачными областями на системах окон, поддерживающих композицию.

Чтобы включить эту функцию в виджете верхнего уровня, установите его атрибут Qt::WA_TranslucentBackground с помощью setAttribute() и убедитесь, что его фон рисуется непрозрачными цветами в областях, которые должны быть частично прозрачными.

Примечания по платформам:

• X11: Эта функция использует сервер X, поддерживающий визуализацию ARGB и менеджер композиции окон.
• Windows: Для работы с прозрачностью виджету необходимо установить флаг окна Qt::FramelessWindowHint.

Собственные виджеты против чужеродных виджетов

Введённые в Qt 4.4, чужеродные виджеты — это виджеты, неизвестные системе окон. У них нет связанной с ними собственной дескриптора окна. Эта функция значительно ускоряет отрисовку, изменение размеров виджетов и устраняет мерцание.

Если вам требуется старое поведение с собственными окнами, вы можете выбрать один из следующих вариантов:

1. Используйте QT_USE_NATIVE_WINDOWS=1 в вашей среде.
2. Установите атрибут Qt::AA_NativeWindows для вашего приложения. Все виджеты будут собственными.
3. Установите атрибут Qt::WA_NativeWindow для виджетов: сам виджет и все его предки станут собственными (если не установлен Qt::WA_DontCreateNativeAncestors).
4. Вызовите QWidget::winId, чтобы принудительно использовать собственное окно (это подразумевает 3)).
5. Установите атрибут Qt::WA_PaintOnScreen, чтобы принудительно использовать собственное окно (это подразумевает 3)).

См. также QEvent, QPainter, QGridLayout и QBoxLayout.

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

перечисление QWidget::RenderFlagфлаги QWidget::RenderFlags

Это перечисление описывает, как отображать виджет при вызове QWidget::render().

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

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

setCursor(Qt::IBeamCursor);

width = baseSize().width() + i * sizeIncrement().width();
height = baseSize().height() + j * sizeIncrement().height();

setUpdatesEnabled(false);
bigVisualChanges();
setUpdatesEnabled(true);

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

QWidget::QWidget(QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())

Создаёт виджет, который является дочерним элементом parent, с флагами виджета, установленными в f.

Если parent равен nullptr, новый виджет становится окном. Если parent — это другой виджет, этот виджет становится дочерним окном внутри parent. Новый виджет удаляется при удалении его родителя.

Аргумент флагов виджета, f, обычно равен 0, но его можно установить для настройки рамки окна (т.е. parent должен быть nullptr). Для настройки рамки используйте значение, составленное путём побитового ИЛИ любого из флагов окон.

Если вы добавляете дочерний виджет к уже видимому виджету, вы должны явно отобразить дочерний виджет, чтобы сделать его видимым.

Обратите внимание, что версия Qt для X11 может не поддерживать все комбинации флагов стиля на всех системах. Это происходит потому, что в X11 Qt может только запросить менеджер окон, и менеджер окон может переопределить настройки приложения. В Windows Qt может установить любые желаемые флаги.

См. также windowFlags.

[slot] bool QWidget::close()

Закрывает этот виджет. Возвращает true если виджет был закрыт; в противном случае возвращает false.

Сначала он отправляет виджету событие QCloseEvent. Виджет скрывается (hidden), если он принимает событие закрытия. Если он игнорирует событие, ничего не происходит. По умолчанию реализация QWidget::closeEvent() принимает событие закрытия.

Если у виджета установлен флаг Qt::WA_DeleteOnClose, виджет также удаляется. Событие закрытия доставляется виджету независимо от того, виден он или нет.

Сигнал QApplication::lastWindowClosed() излучается, когда закрывается последнее видимое основное окно (т.е. окно без родителя) с установленным атрибутом Qt::WA_QuitOnClose. По умолчанию этот атрибут установлен для всех виджетов, за исключением временных окон, таких как всплывающие окна, окна инструментов и всплывающие меню.

[signal] void QWidget::customContextMenuRequested(const QPoint &pos)

Этот сигнал излучается, когда политика контекстного меню виджета (contextMenuPolicy) равна Qt::CustomContextMenu, и пользователь запросил контекстное меню на виджете. Позиция pos — это позиция события контекстного меню, полученного виджетом. Обычно она задаётся в координатах виджета. Исключение составляют QAbstractScrollArea и его подклассы, которые преобразуют событие контекстного меню в координаты viewport().

См. также mapToGlobal(), QMenu и contextMenuPolicy.

[slot] void QWidget::hide()

Скрывает виджет. Эта функция эквивалентна setVisible(false).

Примечание: Если вы работаете с QDialog или его подклассами и вызываете функцию show() после этой функции, диалоговое окно будет отображено в исходном положении.

См. также hideEvent(), isHidden(), show(), setVisible(), isVisible() и close().

[slot] void QWidget::lower()

Опускает виджет в низ стека родительского виджета.

После вызова виджет будет отображаться позади (и, следовательно, скрыт) любого перекрывающегося виджета-потомка.

См. также raise() и stackUnder().

[slot] void QWidget::raise()

Приподнимает этот виджет наверх стека родительского виджета.

После вызова виджет будет отображаться поверх любого перекрывающегося виджета-потомка.

Примечание: При использовании activateWindow() вы можете вызвать эту функцию, чтобы убедиться, что окно расположено сверху.

См. также lower() и stackUnder().

[slot] void QWidget::repaint()

Перерисовывает виджет напрямую, вызвав paintEvent() немедленно, если обновления отключены или виджет скрыт.

Рекомендуется использовать repaint() только если вам нужно немедленное перерисовка, например, во время анимации. Почти во всех случаях update() лучше, поскольку он позволяет Qt оптимизировать производительность и минимизировать мерцание.

Предупреждение: Если вы вызываете repaint() в функции, которая может вызываться из paintEvent(), вы можете получить бесконечную рекурсию. Функция update() никогда не вызывает рекурсию.

См. также update(), paintEvent() и setUpdatesEnabled().

[slot] void QWidget::setDisabled(bool disable)

Отключает события ввода виджета, если disable равно true; в противном случае включает события ввода.

Для получения дополнительной информации см. документацию к enabled.

См. также isEnabledTo(), QKeyEvent, QMouseEvent и changeEvent().

[slot] void QWidget::setFocus()

Это перегруженная функция.

Предоставляет фокус клавиатурного ввода этому виджету (или его прокси-виджету), если этот виджет или один из его родителей является активным окном (активным окном).

[slot] void QWidget::setHidden(bool hidden)

Удобная функция, эквивалентная setVisible(!hidden).

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

[slot] void QWidget::show()

Отображает виджет и его дочерние виджеты.

Это эквивалентно вызову showFullScreen(), showMaximized() или setVisible(true) в зависимости от поведения по умолчанию платформы для флагов окна.

См. также raise(), showEvent(), hide(), setVisible(), showMinimized(), showMaximized(), showNormal(), isVisible() и windowFlags().

[slot] void QWidget::showFullScreen()

Отображает виджет в полноэкранном режиме.

Вызов этой функции влияет только на окна.

Чтобы выйти из полноэкранного режима, вызовите showNormal().

Полноэкранный режим работает нормально в Windows, но имеет определённые проблемы в X. Эти проблемы обусловлены ограничениями протокола ICCCM, который определяет взаимодействие между клиентами X11 и менеджером окон. ICCCM просто не понимает концепции окон в полноэкранном режиме без декораций. Поэтому мы можем только запросить окно без рамок и разместить его, чтобы заполнить весь экран. В зависимости от менеджера окон, это может или не может работать. Окно без рамок запрашивается с помощью подсказок MOTIF, которые в той или иной степени поддерживаются практически всеми современными менеджерами окон.

Альтернативой было бы полное обход менеджера окон и создание окна с флагом Qt::X11BypassWindowManagerHint. Однако это имеет другие серьёзные проблемы, такие как полная поломка фокуса клавиатуры и очень странные эффекты при изменении рабочего стола или при открытии других окон пользователем.

Менеджеры окон X11, которые следуют современным спецификациям после ICCCM, правильно поддерживают полноэкранный режим.

См. также showNormal(), showMaximized(), show(), hide() и isVisible().

[slot] void QWidget::showMaximized()

Отображает виджет в максимальном режиме.

Вызов этой функции влияет только на окна.

В X11 эта функция может работать некорректно с определёнными менеджерами окон. См. документацию по геометрии окна для объяснения.

См. также setWindowState(), showNormal(), showMinimized(), show(), hide() и isVisible().

[slot] void QWidget::showMinimized()

Отображает виджет минимизированным, в виде значка.

Вызов этой функции влияет только на окна.

См. также showNormal(), showMaximized(), show(), hide(), isVisible() и isMinimized().

[slot] void QWidget::showNormal()

Восстанавливает виджет после максимизации или минимизации.

Вызов этой функции влияет только на окна.

См. также setWindowState(), showMinimized(), showMaximized(), show(), hide() и isVisible().

[slot] void QWidget::update()

Обновляет виджет, если обновления не отключены и виджет не скрыт.

Эта функция не вызывает немедленную перерисовку; вместо этого она планирует событие рисования для обработки, когда Qt возвращается к главному циклу событий. Это позволяет Qt оптимизировать скорость и минимизировать мерцание по сравнению с вызовом repaint().

Вызов update() несколько раз обычно приводит к одному вызову paintEvent().

Qt обычно стирает область виджета перед вызовом paintEvent(). Если установлен атрибут виджета Qt::WA_OpaquePaintEvent, виджет отвечает за прорисовку всех своих пикселей непрозрачным цветом.

См. также repaint(), paintEvent(), setUpdatesEnabled() и Пример аналоговых часов.

[protected slot] void QWidget::updateMicroFocus()

Обновляет микрофокус виджета.

[signal] void QWidget::windowIconChanged(const QIcon &icon)

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

Примечание: Сигнал-нотификатор для свойства windowIcon.

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

[signal] void QWidget::windowTitleChanged(const QString &title)

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

Примечание: Сигнал-нотификатор для свойства windowTitle.

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

[virtual] QWidget::~QWidget()

Уничтожает виджет.

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

[virtual protected] void QWidget::actionEvent(QActionEvent *event)

Этот обработчик событий вызывается с данным event всякий раз, когда действия виджета изменяются.

См. также addAction(), insertAction(), removeAction(), actions() и QActionEvent.

QList<QAction *> QWidget::actions() const

Возвращает (возможно пустой) список действий этого виджета.

См. также contextMenuPolicy, insertAction() и removeAction().

void QWidget::activateWindow()

Устанавливает верхний виджет, содержащий этот виджет, в качестве активного окна.

Активное окно — это видимое верхнее окно, у которого есть фокус ввода с клавиатуры.

Эта функция выполняет ту же операцию, что и щелчок мышью по строке заголовка верхнего окна. В X11 результат зависит от диспетчера окон. Если вы хотите гарантировать, что окно также расположено поверх других, вы также должны вызвать raise(). Обратите внимание, что окно должно быть видимым, в противном случае activateWindow() не окажет никакого эффекта.

В Windows, если вы вызываете это, когда приложение не является активным, то оно не станет активным окном. Вместо этого изменится цвет записи в панели задач, чтобы указать, что окно изменилось каким-либо образом. Это связано с тем, что Microsoft не позволяет приложению прерывать текущую работу пользователя в другом приложении.

См. также isActiveWindow(), window(), show() и QWindowsWindowFunctions::setWindowActivationBehavior().

void QWidget::addAction(QAction *action)

Добавляет действие action в список действий этого виджета.

Все виджеты QWidgets имеют список QAction, но они могут отображаться графически многими различными способами. По умолчанию список QAction (как возвращается actions()) используется для создания контекстного QMenu.

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

Владение action не переходит к этому QWidget.

См. также removeAction(), insertAction(), actions() и QMenu.

void QWidget::addActions(QList<QAction *> actions)

Добавляет действия actions в список действий этого виджета.

См. также removeAction(), QMenu и addAction().

void QWidget::adjustSize()

Изменяет размер виджета для соответствия его содержимому.

Эта функция использует sizeHint() если она допустима, т.е. ширина и высота размера подсказки >= 0. В противном случае она устанавливает размер в прямоугольник детей, охватывающий все дочерние виджеты (объединение всех прямоугольников дочерних виджетов).

Для окон также учитывается размер экрана. Если sizeHint() меньше (200, 100) и политика размера — расширение, окно будет не меньше (200, 100). Максимальный размер окна составляет 2/3 ширины и высоты экрана.

См. также sizeHint() и childrenRect().

QPalette::ColorRole QWidget::backgroundRole() const

Возвращает роль фона виджета.

Роль фона определяет кисть из palette виджета, используемую для отрисовки фона.

Если роль фона не задана явно, виджет наследует роль фона своего родительского виджета.

См. также setBackgroundRole() и foregroundRole().

QBackingStore *QWidget::backingStore() const

Возвращает QBackingStore, в который будет нарисован этот виджет.

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

[virtual protected] void QWidget::changeEvent(QEvent *event)

Этот обработчик событий можно переопределить для обработки изменений состояния.

Изменяемое состояние в этом событии можно получить через предоставленный event.

События изменения включают: QEvent::ToolBarChange, QEvent::ActivationChange, QEvent::EnabledChange, QEvent::FontChange, QEvent::StyleChange, QEvent::PaletteChange, QEvent::WindowTitleChange, QEvent::IconTextChange, QEvent::ModifiedChange, QEvent::MouseTrackingChange, QEvent::ParentChange, QEvent::WindowStateChange, QEvent::LanguageChange, QEvent::LocaleChange, QEvent::LayoutDirectionChange, QEvent::ReadOnlyChange.

QWidget *QWidget::childAt(int x, int y) const

Возвращает видимый дочерний виджет в позиции (x, y) в системе координат виджета. Если видимого дочернего виджета в указанной позиции нет, функция возвращает nullptr.

QWidget *QWidget::childAt(const QPoint &p) const

Это перегруженная функция.

Возвращает видимый дочерний виджет в точке p в собственной системе координат виджета.

void QWidget::clearFocus()

Убирает фокус ввода с клавиатуры с виджета.

Если у виджета есть активный фокус, ему отправляется событие потери фокуса, чтобы сообщить ему о потере фокуса.

Этот виджет должен разрешить установку фокуса, чтобы получить фокус ввода с клавиатуры, т.е. он должен вызвать setFocusPolicy().

См. также hasFocus(), setFocus(), focusInEvent(), focusOutEvent(), setFocusPolicy() и QApplication::focusWidget().

void QWidget::clearMask()

Удаляет любую маску, установленную с помощью setMask().

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

[virtual protected] void QWidget::closeEvent(QCloseEvent *event)

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

По умолчанию событие принимается, и виджет закрывается. Вы можете переопределить эту функцию, чтобы изменить способ, которым виджет реагирует на запросы закрытия окна. Например, вы можете предотвратить закрытие окна, вызвав ignore() для всех событий.

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

void MainWindow::closeEvent(QCloseEvent *event)
{
    if (maybeSave()) {
        writeSettings();
        event->accept();
    } else {
        event->ignore();
    }
}

См. также event(), hide(), close(), QCloseEvent и Application Example.

QMargins QWidget::contentsMargins() const

Функция contentsMargins возвращает отступы содержимого виджета.

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

См. также setContentsMargins() и contentsRect().

QRect QWidget::contentsRect() const

Возвращает область внутри отступов виджета.

См. также setContentsMargins() и contentsMargins().

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

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

Обработчик вызывается, когда политика контекстного меню виджета contextMenuPolicy равна Qt::DefaultContextMenu.

В реализации по умолчанию событие контекстного меню игнорируется. Дополнительные сведения см. в документации QContextMenuEvent.

См. также event(), QContextMenuEvent и customContextMenuRequested().

[protected] void QWidget::create(WId window = 0, bool initializeWindow = true, bool destroyOldWindow = true)

Создаёт новое окно виджета.

Параметры window, initializeWindow и destroyOldWindow игнорируются в Qt 5. Используйте QWindow::fromWinId() для создания QWindow, оборачивающего внешнее окно, и передайте его в QWidget::createWindowContainer().

См. также createWindowContainer() и QWindow::fromWinId().

[static] QWidget *QWidget::createWindowContainer(QWindow *window, QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags())

Создаёт QWidget, который позволяет встраивать window в приложение на основе QWidget.

Контейнер окна создаётся как дочерний элемент parent и с флагами окна flags.

После того, как окно будет встроено в контейнер, контейнер будет контролировать геометрию и видимость окна. Явные вызовы QWindow::setGeometry(), QWindow::show() или QWindow::hide() для встроенного окна не рекомендуется.

Контейнер принимает владение window. Окно можно удалить из контейнера окна, вызвав QWindow::setParent().

Контейнер окна прикрепляется как родное дочернее окно к главному окну, которое он содержит. Когда контейнер окна используется как дочерний элемент QAbstractScrollArea или QMdiArea, он создаст родное окно для каждого виджета в цепочке его предков, чтобы обеспечить правильное расположение и обрезку в этом случае. Создание родного окна для контейнера окна также обеспечивает правильное расположение и обрезку. Это должно быть выполнено до показа контейнера окна. Приложения с множеством родных дочерних окон могут испытывать проблемы с производительностью.

Контейнер окна имеет ряд известных ограничений:

• Порядок расположения; Встроенное окно будет расположено поверх иерархии виджетов как непрозрачный прямоугольник. Порядок расположения нескольких перекрывающихся экземпляров контейнеров окон не определён.
• Интеграция отрисовки; Контейнер окна не взаимодействует с QGraphicsProxyWidget, QWidget::render() или подобными функциями.
• Обработка фокуса; Контейнер окна может иметь любую политику фокуса и будет передавать фокус окну, вызвав QWindow::requestActivate(). Однако возврат к обычной цепочке фокуса из экземпляра QWindow будет зависеть от реализации самого экземпляра QWindow. Например, при входе в окно на основе Qt Quick с фокусом по табу, весьма вероятно, что дальнейшие нажатия клавиш табуляции будут происходить только внутри приложения QML. Также, действительно ли QWindow::requestActivate() даёт фокус окну, зависит от платформы.
• Использование большого количества экземпляров контейнеров окон в приложении на основе QWidget может значительно ухудшить общую производительность приложения.

[protected] void QWidget::destroy(bool destroyWindow = true, bool destroySubWindows = true)

Освобождает ресурсы системы окон. Уничтожает окно виджета, если destroyWindow равно true.

destroy() рекурсивно вызывает себя для всех дочерних виджетов, передавая destroySubWindows в качестве параметра destroyWindow. Для лучшего контроля над уничтожением дочерних виджетов, уничтожьте дочерние виджеты выборочно сначала.

Эта функция обычно вызывается из деструктора QWidget.

[virtual protected] void QWidget::dragEnterEvent(QDragEnterEvent *event)

Этот обработчик событий вызывается, когда происходит перетаскивание и курсор входит в этот виджет. Событие передаётся в параметре event.

Если событие игнорируется, виджет не получит никаких событий перемещения при перетаскивании.

См. документацию по перетаскиванию для обзора того, как предоставить перетаскивание в вашем приложении.

См. также QDrag и QDragEnterEvent.

[virtual protected] void QWidget::dragLeaveEvent(QDragLeaveEvent *event)

Этот обработчик событий вызывается, когда происходит перетаскивание и курсор покидает этот виджет. Событие передаётся в параметре event.

См. документацию по перетаскиванию для обзора того, как предоставить перетаскивание в вашем приложении.

См. также QDrag и QDragLeaveEvent.

[virtual protected] void QWidget::dragMoveEvent(QDragMoveEvent *event)

Этот обработчик событий вызывается, если происходит перетаскивание, и когда выполняется любое из следующих условий: курсор входит в этот виджет, курсор перемещается внутри этого виджета или нажата клавиша модификатора на клавиатуре, пока этот виджет имеет фокус. Событие передаётся в параметре event.

См. документацию по перетаскиванию для обзора того, как предоставить перетаскивание в вашем приложении.

См. также QDrag и QDragMoveEvent.

[virtual protected] void QWidget::dropEvent(QDropEvent *event)

Этот обработчик событий вызывается, когда перетаскивание отпускается на этом виджете. Событие передаётся в параметре event.

См. документацию по перетаскиванию для обзора того, как предоставить перетаскивание в вашем приложении.

См. также QDrag и QDropEvent.

WId QWidget::effectiveWinId() const

Возвращает эффективный идентификатор окна системы виджета, т.е. идентификатор окна родного родителя.

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

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

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

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

void QWidget::ensurePolished() const

Обеспечивает, что виджет и его дочерние элементы были отполированы QStyle (т.е., имеют подходящий шрифт и палитру).

QWidget вызывает эту функцию после того, как он был полностью построен, но до первого показа. Вы можете вызвать эту функцию, если хотите убедиться, что виджет отполирован перед выполнением операции, например, для реализации sizeHint() виджета может потребоваться корректный размер шрифта. Обратите внимание, что эта функция вызывается из реализации по умолчанию sizeHint().

Полировка полезна для завершающей инициализации, которая должна происходить после вызова всех конструкторов (как базовых классов, так и подклассов).

Если вам нужно изменить некоторые настройки, когда виджет отполирован, переопределите event() и обработайте тип события QEvent::Polish.

Примечание: Функция объявлена как const, чтобы её можно было вызывать из других константных функций (например, sizeHint()).

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

[virtual protected] void QWidget::enterEvent(QEvent *event)

Этот обработчик событий может быть переопределен в подклассе для получения событий входа в виджет, которые передаются в параметре event.

Событие отправляется виджету, когда курсор мыши входит в виджет.

См. также leaveEvent(), mouseMoveEvent() и event().

[override virtual protected] bool QWidget::event(QEvent *event)

Переопределяет: QObject::event(QEvent *e).

Это основной обработчик событий; он обрабатывает событие event. Вы можете переопределить эту функцию в подклассе, но мы рекомендуем использовать один из специализированных обработчиков событий вместо этого.

События нажатия и отпускания клавиш обрабатываются иначе, чем другие события. event() проверяет клавиши Tab и Shift+Tab и пытается соответствующим образом переместить фокус. Если нет виджета, на который можно переместить фокус (или нажата не клавиша Tab или Shift+Tab), event() вызывает keyPressEvent().

Обработка событий мыши и планшета также немного специфична: только когда виджет включён, event() вызовет специализированные обработчики, такие как mousePressEvent; в противном случае он отбросит событие.

Эта функция возвращает true если событие было распознано, в противном случае она возвращает false. Если распознанное событие было принято (см. QEvent::accepted), любая дальнейшая обработка, такая как распространение события на родительский виджет, останавливается.

См. также closeEvent(), focusInEvent(), focusOutEvent(), enterEvent(), keyPressEvent(), keyReleaseEvent(), leaveEvent(), mouseDoubleClickEvent(), mouseMoveEvent(), mousePressEvent(), mouseReleaseEvent(), moveEvent(), paintEvent(), resizeEvent(), QObject::event() и QObject::timerEvent().

[static] QWidget *QWidget::find(WId id)

Возвращает указатель на виджет с идентификатором/дескриптором окна id.

Тип идентификатора окна зависит от используемой системной оболочки; см. qwindowdefs.h для определения. Если виджета с таким идентификатором нет, возвращается nullptr.

[virtual protected] void QWidget::focusInEvent(QFocusEvent *event)

Обработчик событий может быть переопределён в подклассе для получения событий фокусировки (получение фокуса) виджета. Событие передаётся в параметре event.

Виджет обычно должен установить setFocusPolicy() на значение, отличное от Qt::NoFocus, чтобы получать события фокусировки. (Обратите внимание, что программист приложения может вызвать setFocus() для любого виджета, даже тех, которые обычно не принимают фокус.)

Стандартная реализация обновляет виджет (за исключением окон, не задающих focusPolicy()).

См. также focusOutEvent(), setFocusPolicy(), keyPressEvent(), keyReleaseEvent(), event() и QFocusEvent.

[protected] bool QWidget::focusNextChild()

Находит новый виджет, которому следует передать фокус (соответствующий нажатию Tab) и возвращает true если такой виджет найден, или false, если нет.

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

[virtual protected] bool QWidget::focusNextPrevChild(bool next)

Находит новый виджет, которому следует передать фокус (соответствующий нажатию Tab и Shift+Tab) и возвращает true если такой виджет найден, или false, если нет.

Если next истинно, функция ищет вперёд, если ложно — назад.

Иногда вам потребуется переопределить эту функцию. Например, веб-браузер может переопределить её для перемещения "текущей активной ссылки" вперёд или назад, а затем вызвать focusNextPrevChild() только когда достигнет последней или первой ссылки на "странице".

Дочерние виджеты вызывают focusNextPrevChild() на своих родительских виджетах, но только окно, содержащее дочерние виджеты, решает, куда перенаправить фокус. Переопределяя эту функцию для объекта, вы получаете контроль над перемещением фокуса для всех дочерних виджетов.

См. также focusNextChild() и focusPreviousChild().

[virtual protected] void QWidget::focusOutEvent(QFocusEvent *event)

Обработчик событий может быть переопределён в подклассе для получения событий фокусировки (потеря фокуса) виджета. Событие передаётся в параметре event.

Виджет обычно должен установить setFocusPolicy() на значение, отличное от Qt::NoFocus, чтобы получать события фокусировки. (Обратите внимание, что программист приложения может вызвать setFocus() для любого виджета, даже тех, которые обычно не принимают фокус.)

Стандартная реализация обновляет виджет (за исключением окон, не задающих focusPolicy()).

См. также focusInEvent(), setFocusPolicy(), keyPressEvent(), keyReleaseEvent(), event() и QFocusEvent.

[protected] bool QWidget::focusPreviousChild()

Находит новый виджет, которому следует передать фокус (соответствующий нажатию Shift+Tab) и возвращает true если такой виджет найден, или false, если нет.

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

QWidget *QWidget::focusProxy() const

Возвращает прокси виджета фокуса, или nullptr если прокси виджета нет.

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

QWidget *QWidget::focusWidget() const

Возвращает последний дочерний виджет этого виджета, для которого был вызван setFocus. Для виджетов верхнего уровня это виджет, который получит фокус в случае активации этого окна.

Это не то же самое, что QApplication::focusWidget(), которое возвращает виджет фокуса в текущем активном окне.

QFontInfo QWidget::fontInfo() const

Возвращает информацию о шрифте для текущего шрифта виджета. Эквивалентно QFontInfo(widget->font()).

См. также font(), fontMetrics() и setFont().

QFontMetrics QWidget::fontMetrics() const

Возвращает метрики шрифта для текущего шрифта виджета. Эквивалентно QFontMetrics(widget->font()).

См. также font(), fontInfo() и setFont().

QPalette::ColorRole QWidget::foregroundRole() const

Возвращает роль переднего плана.

Роль переднего плана определяет цвет из palette виджета, используемый для отрисовки переднего плана.

Если роль переднего плана не установлена явно, функция возвращает роль, которая контрастирует с ролью заднего плана.

См. также setForegroundRole() и backgroundRole().

QPixmap QWidget::grab(const QRect &rectangle = QRect(QPoint(0, 0), QSize(-1, -1)))

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

Если задан прямоугольник с некорректным размером (по умолчанию), отображается весь виджет.

Примечание: Эта функция может быть вызвана через механизм метаобъектов и из QML. См. Q_INVOKABLE.

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

См. также render() и QPixmap.

void QWidget::grabGesture(Qt::GestureType gesture, Qt::GestureFlags flags = Qt::GestureFlags())

Подписывает виджет на данное событие gesture со специфическими флагами flags.

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

См. также ungrabGesture() и QGestureEvent.

void QWidget::grabKeyboard()

Захватывает ввод с клавиатуры.

Этот виджет получает все события клавиатуры до тех пор, пока не будет вызван releaseKeyboard(); другие виджеты не получают событий клавиатуры вообще. События мыши не затронуты. Используйте grabMouse(), если нужно захватить и мышь.

Виджет фокуса не затронут, за исключением того, что он не получает никаких событий клавиатуры. setFocus() перемещает фокус как обычно, но новый виджет фокуса получает события клавиатуры только после вызова releaseKeyboard().

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

См. также releaseKeyboard(), grabMouse(), releaseMouse() и focusWidget().

void QWidget::grabMouse()

Захватывает ввод с мыши.

Этот виджет получает все события мыши до тех пор, пока не будет вызван releaseMouse(); другие виджеты не получают событий мыши вообще. События клавиатуры не затронуты. Используйте grabKeyboard(), если нужно захватить клавиатуру.

Предупреждение: Ошибки в приложениях с захватом мыши очень часто блокируют терминал. Используйте эту функцию с большой осторожностью и рассмотрите возможность использования параметра командной строки -nograb во время отладки.

Практически никогда нет необходимости захватывать мышь при использовании Qt, поскольку Qt делает это разумно. В частности, Qt захватывает мышь при нажатии кнопки мыши и удерживает её, пока не будет отпущена последняя кнопка.

Примечание: Только видимые виджеты могут захватывать ввод с мыши. Если для виджета isVisible() возвращает false, этот виджет не может вызвать grabMouse().

Примечание: В Windows функция grabMouse() работает только если курсор мыши находится внутри окна, принадлежащего этому процессу. В macOS функция grabMouse() работает только когда курсор находится внутри рамки этого виджета.

См. также releaseMouse(), grabKeyboard() и releaseKeyboard().

void QWidget::grabMouse(const QCursor &cursor)

Эта функция перегружает grabMouse().

Захватывает ввод мыши и изменяет форму курсора.

Курсор примет форму cursor (на всё время захвата фокуса мыши) и только этот виджет будет получать события мыши до тех пор, пока не будет вызван releaseMouse().

Предупреждение: Захват мыши может заблокировать терминал.

Примечание: См. примечание в QWidget::grabMouse().

См. также releaseMouse(), grabKeyboard(), releaseKeyboard() и setCursor().

int QWidget::grabShortcut(const QKeySequence &key, Qt::ShortcutContext context = Qt::WindowShortcut)

Добавляет ярлык в систему ярлыков Qt, который отслеживает заданную последовательность key в заданном context. Если context равен Qt::ApplicationShortcut, ярлык применяется ко всему приложению. В противном случае, он либо локальный для этого виджета (Qt::WidgetShortcut), либо для самого окна (Qt::WindowShortcut).

Если ту же последовательность key захватили несколько виджетов, при её нажатии событие QEvent::Shortcut отправляется всем соответствующим виджетам в неопределённом порядке, но со значением флага ``ambiguous'' (неопределённый).

Предупреждение: Обычно вам не нужно использовать эту функцию; вместо этого создайте QAction с необходимыми последовательностями нажатия клавиш (если вам также нужны эквивалентные пункты меню и кнопки на панели инструментов) или QShortcut, если вам нужны только последовательности нажатия клавиш. И QAction, и QShortcut обрабатывают всю фильтрацию событий за вас и предоставляют сигналы, которые срабатывают при нажатии пользователем последовательности клавиш, поэтому они намного проще в использовании, чем эта низкоуровневая функция.

См. также releaseShortcut() и setShortcutEnabled().

QGraphicsEffect *QWidget::graphicsEffect() const

Функция graphicsEffect возвращает указатель на графический эффект виджета.

Если у виджета нет графического эффекта, возвращается nullptr.

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

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

QGraphicsProxyWidget *QWidget::graphicsProxyWidget() const

Возвращает прокси-виджет для соответствующего вложенного виджета в представлении графики; в противном случае возвращает nullptr.

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

См. также QGraphicsProxyWidget::createProxyForChildWidget() и QGraphicsScene::addWidget().

bool QWidget::hasEditFocus() const

Возвращает true, если у этого виджета в данный момент есть фокус редактирования; в противном случае возвращает false.

Эта функция доступна только в Qt для встраиваемой Linux-системы.

См. также setEditFocus() и QApplication::navigationMode().

[virtual] bool QWidget::hasHeightForWidth() const

Возвращает true, если предпочтительная высота виджета зависит от его ширины; в противном случае возвращает false.

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

[virtual] int QWidget::heightForWidth(int w) const

Возвращает предпочтительную высоту этого виджета, учитывая ширину w.

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

[virtual protected] void QWidget::hideEvent(QHideEvent *event)

Этот обработчик событий может быть переопределен в подклассе для получения событий скрытия виджета. Событие передаётся в параметре event.

События скрытия отправляются виджетам сразу после их скрытия.

Примечание: Виджет получает спонтанные события показа и скрытия, когда его состояние отображения меняется системой окон, например, спонтанное событие скрытия, когда пользователь сворачивает окно, и спонтанное событие показа, когда окно восстанавливается. После получения спонтанного события скрытия виджет всё ещё считается видимым в смысле isVisible().

См. также visible, event() и QHideEvent.

[override virtual protected] void QWidget::initPainter(QPainter *painter) const

Инициализирует перо, фон и шрифт painter такими же, как у данного виджета. Эта функция вызывается автоматически при открытии рисовальщика на QWidget.

[virtual protected] void QWidget::inputMethodEvent(QInputMethodEvent *event)

Этот обработчик событий для события event может быть переопределён в подклассе для получения событий композиции метода ввода. Этот обработчик вызывается при изменении состояния метода ввода.

Обратите внимание, что при создании пользовательских виджетов редактирования текста атрибут окна Qt::WA_InputMethodEnabled должен быть явно задан (с помощью функции setAttribute()), чтобы получать события метода ввода.

Реализация по умолчанию вызывает event->ignore(), что отклоняет событие метода ввода. Подробнее см. документацию по QInputMethodEvent.

См. также event() и QInputMethodEvent.

[virtual] QVariant QWidget::inputMethodQuery(Qt::InputMethodQuery query) const

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

query определяет, какое свойство запрашивается.

См. также inputMethodEvent(), QInputMethodEvent, QInputMethodQueryEvent и inputMethodHints.

void QWidget::insertAction(QAction *before, QAction *action)

Вставляет действие action в список действий этого виджета перед действием before. Добавляет действие в конец, если before является nullptr или before не является допустимым действием для этого виджета.

В QWidget должно быть только одно действие каждого типа.

См. также removeAction(), addAction(), QMenu, contextMenuPolicy и actions().

void QWidget::insertActions(QAction *before, QList<QAction *> actions)

Вставляет действия actions в список действий этого виджета перед действием before. Добавляет действия в конец, если before является nullptr или before не является допустимым действием для этого виджета.

В QWidget может быть не более одного действия каждого типа.

См. также removeAction(), QMenu, insertAction() и contextMenuPolicy.

bool QWidget::isAncestorOf(const QWidget *child) const

Возвращает true, если этот виджет является родителем (или предком, и так далее на любом уровне) данного child, и оба виджета находятся в одном окне; в противном случае возвращает false.

bool QWidget::isEnabledTo(const QWidget *ancestor) const

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

Это выполняется, если ни сам виджет, ни любой родитель до, но не включая ancestor, не были явно отключены.

isEnabledTo(0) возвращает false, если этот виджет или любой из его предков был явно отключен.

Здесь термин ``предок'' обозначает родительский виджет в рамках одного окна.

Поэтому isEnabledTo(0) останавливается на окне этого виджета, в отличие от isEnabled(), которое также учитывает родительские окна.

См. также setEnabled() и enabled.

bool QWidget::isHidden() const

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

Скрытый виджет будет виден только при вызове show() для него. Он не будет автоматически показан, когда показывается родитель.

Для проверки видимости используйте !isVisible() вместо этого (обратите внимание на знак восклицания).

isHidden() подразумевает !isVisible(), но виджет может быть невидимым и не скрытым одновременно. Это относится к виджетам, которые являются дочерними элементами виджетов, которые не видны.

Виджеты скрыты, если:

• они были созданы как независимые окна,
• они были созданы как дочерние элементы видимых виджетов,
• hide() или setVisible(false) был вызван.

bool QWidget::isVisibleTo(const QWidget *ancestor) const

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

Истинное значение возникает, если ни сам виджет, ни какой-либо родитель до, но не включая ancestor, не был явно скрыт.

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

isVisibleTo(0) идентично isVisible().

См. также show(), hide() и isVisible().

bool QWidget::isWindow() const

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

Окно — это виджет, который визуально не является дочерним элементом другого виджета и обычно имеет рамку и заголовок окна.

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

QDialog и QMainWindow виджеты по умолчанию являются окнами, даже если родительский виджет указан в конструкторе. Это поведение определяется флагом Qt::Window.

См. также window(), isModal() и parentWidget().

[virtual protected] void QWidget::keyPressEvent(QKeyEvent *event)

Этот обработчик событий, для события event, может быть переопределён в подклассе для получения событий нажатия клавиш для виджета.

Виджет должен вызвать setFocusPolicy(), чтобы первоначально получить фокус и иметь фокус, чтобы получить событие нажатия клавиши.

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

По умолчанию реализация закрывает всплывающие виджеты, если пользователь нажимает последовательность клавиш для QKeySequence::Cancel (обычно клавиша Escape). В противном случае событие игнорируется, чтобы родительский виджет мог его интерпретировать.

Обратите внимание, что QKeyEvent начинается с isAccepted() == true, поэтому вам не нужно вызывать QKeyEvent::accept() — просто не вызывайте реализацию базового класса, если вы действуете на клавишу.

См. также keyReleaseEvent(), setFocusPolicy(), focusInEvent(), focusOutEvent(), event(), QKeyEvent и Пример Tetrix.

[virtual protected] void QWidget::keyReleaseEvent(QKeyEvent *event)

Этот обработчик событий, для события event, может быть переопределён в подклассе для получения событий отпускания клавиш для виджета.

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

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

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

Обратите внимание, что QKeyEvent начинается с isAccepted() == true, поэтому вам не нужно вызывать QKeyEvent::accept() — просто не вызывайте реализацию базового класса, если вы действуете на клавишу.

См. также keyPressEvent(), QEvent::ignore(), setFocusPolicy(), focusInEvent(), focusOutEvent(), event() и QKeyEvent.

[static] QWidget *QWidget::keyboardGrabber()

Возвращает виджет, который в данный момент захватывает вход с клавиатуры.

Если в этом приложении в данный момент ни один виджет не захватывает ввод с клавиатуры, возвращается nullptr.

См. также grabMouse() и mouseGrabber().

QLayout *QWidget::layout() const

Возвращает менеджер компоновки, установленный на этом виджете, или nullptr , если менеджер компоновки не установлен.

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

См. также setLayout(), sizePolicy() и Управление компоновкой.

[virtual protected] void QWidget::leaveEvent(QEvent *event)

Этот обработчик событий может быть переопределён в подклассе для получения событий выхода виджета, которые передаются в параметре event.

Событие выхода отправляется виджету, когда указатель мыши покидает виджет.

См. также enterEvent(), mouseMoveEvent() и event().

QPoint QWidget::mapFrom(const QWidget *parent, const QPoint &pos) const

Преобразует координату виджета pos из системы координат parent в систему координат этого виджета. parent не должен быть nullptr и должен быть родителем вызываемого виджета.

См. также mapTo(), mapFromParent(), mapFromGlobal() и underMouse().

QPoint QWidget::mapFromGlobal(const QPoint &pos) const

Преобразует глобальные экранные координаты pos в координаты виджета.

См. также mapToGlobal(), mapFrom() и mapFromParent().

QPoint QWidget::mapFromParent(const QPoint &pos) const

Преобразует координату родительского виджета pos в координаты виджета.

То же, что и mapFromGlobal(), если у виджета нет родителя.

См. также mapToParent(), mapFrom(), mapFromGlobal() и underMouse().

QPoint QWidget::mapTo(const QWidget *parent, const QPoint &pos) const

Преобразует координату виджета pos в систему координат parent. parent не должен быть nullptr и должен быть родителем вызываемого виджета.

См. также mapFrom(), mapToParent(), mapToGlobal() и underMouse().

QPoint QWidget::mapToGlobal(const QPoint &pos) const

Преобразует координату виджета pos в глобальные экранные координаты. Например, mapToGlobal(QPoint(0,0)) даст глобальные координаты верхнего левого пикселя виджета.

См. также mapFromGlobal(), mapTo() и mapToParent().

QPoint QWidget::mapToParent(const QPoint &pos) const

Преобразует координату виджета pos в координаты родительского виджета.

То же, что и mapToGlobal(), если у виджета нет родителя.

См. также mapFromParent(), mapTo(), mapToGlobal() и underMouse().

QRegion QWidget::mask() const

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

См. также setMask(), clearMask(), QRegion::isEmpty() и Пример часов с формой.

[override virtual protected] int QWidget::metric(QPaintDevice::PaintDeviceMetric m) const

Переопределяет: QPaintDevice::metric(QPaintDevice::PaintDeviceMetric metric) const.

Внутренняя реализация виртуальной функции QPaintDevice::metric().

m — метрика для получения.

[virtual protected] void QWidget::mouseDoubleClickEvent(QMouseEvent *event)

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

По умолчанию вызывается mousePressEvent().

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

См. также mousePressEvent(), mouseReleaseEvent(), mouseMoveEvent(), event(), и QMouseEvent.

[static] QWidget *QWidget::mouseGrabber()

Возвращает виджет, который в данный момент захватывает ввод мыши.

Если ни один виджет в этом приложении в данный момент не захватывает мышь, nullptr возвращается.

См. также grabMouse() и keyboardGrabber().

[virtual protected] void QWidget::mouseMoveEvent(QMouseEvent *event)

Этот обработчик событий, для события event, может быть переопределен в подклассе для получения событий перемещения мыши для виджета.

Если отслеживание мыши выключено, события перемещения мыши происходят только если нажата кнопка мыши, пока мышь перемещается. Если отслеживание мыши включено, события перемещения мыши происходят даже если не нажата ни одна кнопка мыши.

QMouseEvent::pos() сообщает о позиции курсора мыши относительно этого виджета. Для событий нажатия и отпускания позиция обычно такая же, как позиция последнего события перемещения мыши, но она может отличаться, если рука пользователя дрожит. Это особенность базовой системы окон, а не Qt.

Если вы хотите отобразить всплывающую подсказку немедленно, во время перемещения мыши (например, чтобы получить координаты мыши с помощью QMouseEvent::pos() и отобразить их как всплывающую подсказку), сначала необходимо включить отслеживание мыши, как описано выше. Затем, чтобы убедиться, что всплывающая подсказка обновляется немедленно, необходимо вызвать QToolTip::showText() вместо setToolTip() в вашей реализации mouseMoveEvent().

См. также setMouseTracking(), mousePressEvent(), mouseReleaseEvent(), mouseDoubleClickEvent(), event(), QMouseEvent и Пример Scribble.

[virtual protected] void QWidget::mousePressEvent(QMouseEvent *event)

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

Если вы создаете новые виджеты в mousePressEvent(), mouseReleaseEvent() может не закончиться там, где вы ожидаете, в зависимости от базовой системы окон (или менеджера окон X11), расположения виджетов и, возможно, других факторов.

По умолчанию реализуется закрытие всплывающих виджетов при щелчке за пределами окна. Для других типов виджетов ничего не делает.

См. также mouseReleaseEvent(), mouseDoubleClickEvent(), mouseMoveEvent(), event(), QMouseEvent и Пример Scribble.

[virtual protected] void QWidget::mouseReleaseEvent(QMouseEvent *event)

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

См. также mousePressEvent(), mouseDoubleClickEvent(), mouseMoveEvent(), event(), QMouseEvent и Пример Scribble.

void QWidget::move(int x, int y)

Это перегруженный метод.

Это соответствует move(QPoint(x, y)).

Примечание: Метод-сеттер для свойства pos.

[virtual protected] void QWidget::moveEvent(QMoveEvent *event)

Этот обработчик событий может быть переопределен в подклассе для получения событий перемещения виджета, которые передаются в параметре event. Когда виджет получает это событие, он уже находится в новом положении.

Старое положение доступно через QMoveEvent::oldPos().

См. также resizeEvent(), event(), move() и QMoveEvent.

[virtual protected] bool QWidget::nativeEvent(const QByteArray &eventType, void *message, long *result)

Этот специальный обработчик событий может быть переопределен в подклассе для получения событий родной платформы, определённых по eventType, которые передаются в параметре message.

В вашей реализации этой функции, если вы хотите остановить обработку события Qt, верните true и установите result. Параметр result имеет значение только в Windows. Если вы вернете false, это родное событие передается обратно в Qt, который преобразует событие в событие Qt и отправляет его виджету.

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

Примечание: Эта функция заменяет функции фильтрации событий x11Event(), winEvent() и macEvent() Qt 4.

См. также QAbstractNativeEventFilter.

QWidget *QWidget::nativeParentWidget() const

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

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

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

QWidget *QWidget::nextInFocusChain() const

Возвращает следующий виджет в цепочке фокуса этого виджета.

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

void QWidget::overrideWindowFlags(Qt::WindowFlags flags)

Устанавливает флаги окна для виджета на flags, без уведомления системы окон.

Предупреждение: Не вызывайте эту функцию, если вы не точно знаете, что делаете.

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

[override virtual] QPaintEngine *QWidget::paintEngine() const

Переопределяет: QPaintDevice::paintEngine() const.

Возвращает движок отрисовки виджета.

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

[virtual protected] void QWidget::paintEvent(QPaintEvent *event)

Этот обработчик событий может быть переопределен в подклассе для получения событий отрисовки, передаваемых в event.

Событие отрисовки — это запрос на перерисовку всего или части виджета. Это может произойти по одной из следующих причин:

• repaint() или update() были вызваны,
• виджет был скрыт и теперь виден, или
• по многим другим причинам.

Многие виджеты могут просто перерисовать всю свою поверхность, когда их об этом просят, но некоторые медленные виджеты должны оптимизировать, рисуя только запрошенную область: QPaintEvent::region(). Эта оптимизация скорости не изменяет результат, так как рисование обрезается до этой области во время обработки события. QListView и QTableView делают это, например.

Qt также пытается ускорить отрисовку, объединяя несколько событий отрисовки в одно. Когда update() вызывается несколько раз или система окон отправляет несколько событий отрисовки, Qt объединяет эти события в одно событие с большей областью (см. QRegion::united()). Функция repaint() не позволяет оптимизировать, поэтому рекомендуется использовать update() всякий раз, когда это возможно.

Когда происходит событие отрисовки, область обновления обычно была стерта, поэтому вы рисуете на фоне виджета.

Фон можно установить с помощью setBackgroundRole() и setPalette().

Начиная с Qt 4.0, QWidget автоматически создает буферизацию при отрисовке, поэтому нет необходимости писать код для двойной буферизации в paintEvent(), чтобы избежать мерцания.

Примечание: Обычно следует воздерживаться от вызова update() или repaint() внутри paintEvent(). Например, вызов update() или repaint() для дочерних элементов внутри paintEvent() приводит к неопределённому поведению; дочерний элемент может или не может получить событие отрисовки.

Предупреждение: Если вы используете пользовательский движок отрисовки без буфера Qt, необходимо установить Qt::WA_PaintOnScreen. В противном случае, QWidget::paintEngine() никогда не будет вызываться; вместо этого будет использоваться буфер.

См. также event(), repaint(), update(), QPainter, QPixmap, QPaintEvent и Пример аналоговых часов.

QWidget *QWidget::parentWidget() const

Возвращает родительский элемент виджета или nullptr, если у него нет родительского виджета.

QWidget *QWidget::previousInFocusChain() const

Функция previousInFocusChain возвращает предыдущий виджет в цепочке фокуса этого виджета.

Эта функция была представлена в Qt 4.6.

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

void QWidget::releaseKeyboard()

Отпускает захват клавиатуры.

См. также grabKeyboard(), grabMouse() и releaseMouse().

void QWidget::releaseMouse()

Отпускает захват мыши.

См. также grabMouse(), grabKeyboard() и releaseKeyboard().

void QWidget::releaseShortcut(int id)

Удаляет ярлык с заданным id из системы ярлыков Qt. Виджет больше не будет получать события QEvent::Shortcut для последовательности клавиш ярлыка (если у него нет других ярлыков с той же последовательностью клавиш).

Предупреждение: Вам обычно не нужно использовать эту функцию, так как система ярлыков Qt автоматически удаляет ярлыки при уничтожении их родительского виджета. Лучше использовать QAction или QShortcut для обработки ярлыков, так как они более удобны в использовании, чем эта функция низкого уровня. Обратите также внимание, что это дорогостоящая операция.

См. также grabShortcut() и setShortcutEnabled().

void QWidget::removeAction(QAction *action)

Удаляет действие action из списка действий этого виджета.

См. также insertAction(), actions() и insertAction().

void QWidget::render(QPaintDevice *target, const QPoint &targetOffset = QPoint(), const QRegion &sourceRegion = QRegion(), QWidget::RenderFlags renderFlags = RenderFlags(DrawWindowBackground | DrawChildren))

Отображает sourceRegion этого виджета в target, используя renderFlags для определения способа отображения. Отрисовка начинается в targetOffset в target. Например:

QPixmap pixmap(widget->size());
widget->render(&pixmap);

Если sourceRegion является пустой областью, эта функция будет использовать QWidget::rect() в качестве области, т.е. весь виджет.

Убедитесь, что вы вызываете QPainter::end() для активного художника устройства target (если таковой имеется) перед отображением. Например:

QPainter painter(this);
...
painter.end();
myWidget->render(this);

Примечание: Чтобы получить содержимое QOpenGLWidget, используйте QOpenGLWidget::grabFramebuffer() вместо этого.

Примечание: Чтобы получить содержимое QGLWidget (устаревший), используйте QGLWidget::grabFrameBuffer() или QGLWidget::renderPixmap() вместо этого.

Эта функция была представлена в Qt 4.3.

void QWidget::render(QPainter *painter, const QPoint &targetOffset = QPoint(), const QRegion &sourceRegion = QRegion(), QWidget::RenderFlags renderFlags = RenderFlags(DrawWindowBackground | DrawChildren))

Это перегруженная функция.

Отображает виджет в QPainter::device() художника painter.

Применяемые преобразования и настройки к painter будут использоваться при отображении.

Примечание: painter должен быть активным. В macOS виджет будет отображён в QPixmap, а затем нарисован painter.

См. также QPainter::device().

void QWidget::repaint(int x, int y, int w, int h)

Это перегруженная функция.

Этот вариант перерисовывает прямоугольник (x, y, w, h) внутри виджета.

Если w отрицательно, оно заменяется на width() - x, а если h отрицательно, оно заменяется на height() - y.

void QWidget::repaint(const QRect &rect)

Это перегруженная функция.

Этот вариант перерисовывает прямоугольник rect внутри виджета.

void QWidget::repaint(const QRegion &rgn)

Это перегруженная функция.

Этот вариант перерисовывает область rgn внутри виджета.

void QWidget::resize(int w, int h)

Это перегруженная функция.

Это соответствует resize(QSize(w, h)).

Примечание: Функция-сеттер для свойства size.

[virtual protected] void QWidget::resizeEvent(QResizeEvent *event)

Этот обработчик событий может быть переопределён в подклассе для получения событий изменения размера виджета, которые передаются в параметре event. При вызове resizeEvent(), у виджета уже есть его новые геометрические данные. Предыдущий размер доступен через QResizeEvent::oldSize().

Виджет будет стерт и получит событие отрисовки сразу после обработки события изменения размера. Внутри этого обработчика не нужно (и не следует) выполнять отрисовку.

См. также moveEvent(), event(), resize(), QResizeEvent, paintEvent() и Пример Scribble.

bool QWidget::restoreGeometry(const QByteArray &geometry)

Восстанавливает геометрию и состояние виджетов верхнего уровня, сохранённых в массиве байтов geometry. Возвращает true при успехе; в противном случае возвращает false.

Если восстановленная геометрия находится вне экрана, она будет изменена, чтобы находиться внутри доступной геометрии экрана.

Для восстановления геометрии, сохранённой с помощью QSettings, можно использовать код подобный этому:

QSettings settings("MyCompany", "MyApp");
myWidget->restoreGeometry(settings.value("myWidget/geometry").toByteArray());

См. документацию Геометрия окна для обзора проблем с геометрией окон.

Используйте QMainWindow::restoreState() для восстановления геометрии и состояния панелей инструментов и плавающих окон.

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

См. также saveGeometry(), QSettings, QMainWindow::saveState() и QMainWindow::restoreState().

QByteArray QWidget::saveGeometry() const

Сохраняет текущую геометрию и состояние виджетов верхнего уровня.

Для сохранения геометрии при закрытии окна, можно реализовать событие закрытия следующим образом:

void MyWidget::closeEvent(QCloseEvent *event)
{
    QSettings settings("MyCompany", "MyApp");
    settings.setValue("geometry", saveGeometry());
    QWidget::closeEvent(event);
}

См. документацию Геометрия окна для обзора проблем с геометрией окон.

Используйте QMainWindow::saveState() для сохранения геометрии и состояния панелей инструментов и плавающих окон.

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

См. также restoreGeometry(), QMainWindow::saveState() и QMainWindow::restoreState().

QScreen *QWidget::screen() const

Возвращает экран, на котором находится виджет.

Эта функция была представлена в Qt 5.14.

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

void QWidget::scroll(int dx, int dy)

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

После прокрутки виджеты получат события отрисовки для областей, которые необходимо перерисовать. Для виджетов, которые Qt знает как непрозрачные, это только недавно открытые части. Например, если непрозрачный виджет прокручен влево на 8 пикселей, необходимо обновить только полоску шириной 8 пикселей на правом краю.

Поскольку виджеты по умолчанию распространяют содержимое своих родителей, вам необходимо установить свойство autoFillBackground или использовать setAttribute(), чтобы установить атрибут Qt::WA_OpaquePaintEvent, для того, чтобы сделать виджет непрозрачным.

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

См. также Прозрачность и двойная буферизация.

void QWidget::scroll(int dx, int dy, const QRect &r)

Это перегруженный метод.

Этот вариант прокручивает только r и не перемещает дочерние элементы виджета.

Если r пуста или недействительна, результат не определен.

См. также QScrollArea.

void QWidget::setAttribute(Qt::WidgetAttribute attribute, bool on = true)

Устанавливает атрибут attribute для этого виджета, если on равно true; в противном случае очищает атрибут.

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

void QWidget::setBackgroundRole(QPalette::ColorRole role)

Устанавливает роль фона виджета в role.

Роль фона определяет кисть из палитры виджета palette, которая используется для отрисовки фона.

Если role равно QPalette::NoRole, то виджет наследует роль фона родителя.

Обратите внимание, что стили могут свободно выбирать любой цвет из палитры. Вы можете изменить палитру или установить стилевое оформление, если вы не достигли желаемого результата с помощью setBackgroundRole().

См. также backgroundRole() и foregroundRole().

void QWidget::setBaseSize(int basew, int baseh)

Это перегруженный метод.

Это соответствует setBaseSize(QSize(basew, baseh)). Устанавливает базовый размер виджета шириной basew и высотой baseh.

Примечание: Метод-установщик свойства baseSize.

void QWidget::setContentsMargins(int left, int top, int right, int bottom)

Устанавливает отступы вокруг содержимого виджета с размерами left, top, right и bottom. Отступы используются системой макетов и могут быть использованы подклассами для указания области отрисовки (например, за исключением рамки).

Изменение отступов вызовет resizeEvent().

См. также contentsRect() и contentsMargins().

void QWidget::setContentsMargins(const QMargins &margins)

Это перегруженный метод.

Функция setContentsMargins устанавливает отступы вокруг содержимого виджета.

Устанавливает отступы вокруг содержимого виджета с размерами, определяемыми margins. Отступы используются системой макетов и могут быть использованы подклассами для указания области отрисовки (например, за исключением рамки).

Изменение отступов вызовет resizeEvent().

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

См. также contentsRect() и contentsMargins().

void QWidget::setEditFocus(bool enable)

Если enable равно true, этот виджет получает фокус редактирования, в этом случае Qt::Key_Up и Qt::Key_Down будут переданы виджету нормально; в противном случае, Qt::Key_Up и Qt::Key_Down используются для изменения фокуса.

Эта функция доступна только в Qt для Embedded Linux.

См. также hasEditFocus() и QApplication::navigationMode().

void QWidget::setFixedHeight(int h)

Устанавливает минимальную и максимальную высоту виджета в h, не изменяя ширину. Предоставлено для удобства.

См. также sizeHint(), minimumSize(), maximumSize() и setFixedSize().

void QWidget::setFixedSize(const QSize &s)

Устанавливает минимальный и максимальный размеры виджета в s, предотвращая его рост или уменьшение.

Это переопределит ограничения размера, установленные QLayout.

Для удаления ограничений установите размер в QWIDGETSIZE_MAX.

В качестве альтернативы, если вы хотите, чтобы виджет имел фиксированный размер, основанный на его содержимом, вы можете вызвать QLayout::setSizeConstraint(QLayout::SetFixedSize);

См. также maximumSize и minimumSize.

void QWidget::setFixedSize(int w, int h)

Это перегруженный метод.

Устанавливает ширину виджета в w и высоту в h.

void QWidget::setFixedWidth(int w)

Устанавливает минимальную и максимальную ширину виджета в w, не изменяя высоту. Предоставлено для удобства.

См. также sizeHint(), minimumSize(), maximumSize() и setFixedSize().

void QWidget::setFocus(Qt::FocusReason reason)

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

Сначала событие о предстоящем изменении фокуса отправляется виджету с фокусом (если таковой имеется), чтобы сообщить ему, что он собирается потерять фокус. Затем фокус меняется, событие потери фокуса отправляется предыдущему элементу с фокусом, и событие получения фокуса отправляется новому элементу, чтобы сообщить ему, что он только что получил фокус. (Ничего не происходит, если виджеты получения и потери фокуса совпадают.)

Примечание: Встраиваемых платформах setFocus() не приведет к открытию панели ввода методом ввода. Если вы хотите, чтобы это произошло, вы должны сами отправить событие QEvent::RequestSoftwareInputPanel в виджет.

setFocus() предоставляет фокус виджету независимо от его политики фокуса, но не очищает захват клавиатуры (см. grabKeyboard()).

Обратите внимание, что если виджет скрыт, он не будет принимать фокус, пока не будет показан.

Предупреждение: Если вы вызываете setFocus() в функции, которая может вызываться из focusOutEvent() или focusInEvent(), вы можете получить рекурсию.

См. также hasFocus(), clearFocus(), focusInEvent(), focusOutEvent(), setFocusPolicy(), focusWidget(), QApplication::focusWidget(), grabKeyboard(), grabMouse(), Фокус клавиатуры в виджетах и QEvent::RequestSoftwareInputPanel.

void QWidget::setFocusProxy(QWidget *w)

Устанавливает прокси-виджет фокуса виджета на виджет w. Если w это nullptr, функция сбрасывает этот виджет, чтобы у него не было прокси-виджета фокуса.

Некоторые виджеты могут «иметь фокус», но создают дочерний виджет, например QLineEdit, для фактического управления фокусом. В этом случае виджет может установить редактор как свой прокси-виджет фокуса.

setFocusProxy() устанавливает виджет, который фактически получит фокус, когда «этот виджет» получит его. Если есть прокси-виджет фокуса, setFocus() и hasFocus() работают с прокси-виджетом фокуса. Если «этот виджет» является виджетом фокуса, то setFocusProxy() перемещает фокус в новый прокси-виджет фокуса.

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

void QWidget::setForegroundRole(QPalette::ColorRole role)

Устанавливает роль переднего плана виджета в role.

Роль переднего плана определяет цвет из палитры виджета palette, используемый для отрисовки переднего плана.

Если role равно QPalette::NoRole, виджет использует роль переднего плана, которая контрастирует с ролью фона.

Обратите внимание, что стили могут свободно выбирать любой цвет из палитры. Вы можете изменить палитру или установить стилевое оформление, если не получили желаемого результата с помощью setForegroundRole().

См. также foregroundRole() и backgroundRole().

void QWidget::setGeometry(int x, int y, int w, int h)

Это перегруженный метод.

Это соответствует setGeometry(QRect(x, y, w, h)).

Примечание: Метод-сеттер для свойства geometry.

void QWidget::setGraphicsEffect(QGraphicsEffect *effect)

Функция setGraphicsEffect предназначена для установки графического эффекта виджета.

Устанавливает effect в качестве эффекта виджета. Если на этом виджете уже установлен эффект, QWidget удалит существующий эффект перед установкой нового effect.

Если effect установлен на другом виджете, setGraphicsEffect() удалит эффект с этого виджета и установит его на текущий виджет.

QWidget принимает владение effect.

Примечание: Этот метод применит эффект к самому себе и всем своим дочерним виджетам.

Примечание: Графические эффекты не поддерживаются для виджетов на основе OpenGL, таких как QGLWidget, QOpenGLWidget и QQuickWidget.

Этот метод был введён в Qt 4.6.

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

void QWidget::setLayout(QLayout *layout)

Устанавливает менеджер компоновки для данного виджета на layout.

Если на этом виджете уже установлен менеджер компоновки, QWidget не позволит установить другой. Сначала необходимо удалить существующий менеджер компоновки (возвращаемый методом layout()), прежде чем вызывать setLayout() с новым менеджером компоновки.

Если layout является менеджером компоновки другого виджета, setLayout() переродирует менеджер компоновки и сделает его менеджером компоновки для этого виджета.

Пример:

    QVBoxLayout *layout = new QVBoxLayout;
    layout->addWidget(formWidget);
    setLayout(layout);

Альтернативой вызову этой функции является передача этого виджета в конструктор менеджера компоновки.

QWidget примет владение layout.

См. также layout() и Управление компоновкой.

void QWidget::setMask(const QBitmap &bitmap)

Делает видимыми только те пиксели виджета, для которых в bitmap соответствует бит 1. Если область включает пиксели за пределами rect() виджета, элементы управления системного окна в этой области могут быть или не быть видимыми в зависимости от платформы.

Обратите внимание, что этот эффект может быть медленным, если область является особенно сложной.

Следующий код демонстрирует, как изображение с альфа-каналом может быть использовано для создания маски для виджета:

    QLabel topLevelLabel;
    QPixmap pixmap(":/images/tux.png");
    topLevelLabel.setPixmap(pixmap);
    topLevelLabel.setMask(pixmap.mask());

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

Маскированные виджеты получают события мыши только на своих видимых участках.

См. также mask(), clearMask(), windowOpacity() и Пример часов с формой.

void QWidget::setMask(const QRegion &region)

Это перегруженный метод.

Делает видимыми только те части виджета, которые перекрываются region. Если область включает пиксели за пределами rect() виджета, элементы управления системного окна в этой области могут быть или не быть видимыми в зависимости от платформы.

Обратите внимание, что этот эффект может быть медленным, если область является особенно сложной.

См. также windowOpacity.

void QWidget::setMaximumSize(int maxw, int maxh)

Это перегруженный метод.

Этот метод соответствует setMaximumSize(QSize(maxw, maxh)). Устанавливает максимальную ширину в maxw и максимальную высоту в maxh.

Примечание: Метод-сеттер для свойства maximumSize.

void QWidget::setMinimumSize(int minw, int minh)

Это перегруженный метод.

Этот метод соответствует setMinimumSize(QSize(minw, minh)). Устанавливает минимальную ширину в minw и минимальную высоту в minh.

Примечание: Метод-сеттер для свойства minimumSize.

void QWidget::setParent(QWidget *parent)

Устанавливает родительский виджет для текущего виджета на parent и сбрасывает флаги окна. Виджет перемещается в позицию (0, 0) в новом родительском виджете.

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

Если новый родительский виджет находится в том же окне, что и старый родитель, установка родителя не изменяет порядок перехода на вкладку или фокус клавиатуры.

Если «новый» родительский виджет совпадает со старым родительским виджетом, эта функция ничего не делает.

Примечание: Виджет становится невидимым при изменении родителя, даже если он был ранее видим. Для повторного отображения виджета необходимо вызвать show().

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

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

void QWidget::setParent(QWidget *parent, Qt::WindowFlags f)

Это перегруженный метод.

Эта функция также принимает флаги виджета, f, в качестве аргумента.

void QWidget::setShortcutAutoRepeat(int id, bool enable = true)

Если enable равно true, автоматический повтор сочетания клавиш с заданным id включён; в противном случае он выключен.

Этот метод был введён в Qt 4.2.

См. также grabShortcut() и releaseShortcut().

void QWidget::setShortcutEnabled(int id, bool enable = true)

Если enable равно true, сочетание клавиш с заданным id включено; в противном случае сочетание клавиш отключено.

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

См. также grabShortcut() и releaseShortcut().

void QWidget::setSizeIncrement(int w, int h)

Это перегруженный метод.

Устанавливает приращение размера по оси x (ширина) в w и по оси y (высота) в h.

Примечание: Метод-сеттер для свойства sizeIncrement.

void QWidget::setSizePolicy(QSizePolicy::Policy horizontal, QSizePolicy::Policy vertical)

Это перегруженный метод.

Устанавливает политику размеров виджета на horizontal и vertical, с стандартным растяжением и без высоты относительно ширины.

Примечание: Метод-сеттер для свойства sizePolicy.

См. также QSizePolicy::QSizePolicy().

void QWidget::setStyle(QStyle *style)

Устанавливает графический стиль виджета на style. Владение объектом стиля не передаётся.

Если стиль не задан, виджет использует стиль приложения QApplication::style() вместо.

Установка стиля виджета не влияет на существующие или будущие дочерние виджеты.

Предупреждение: Эта функция особенно полезна для демонстрационных целей, где вы хотите продемонстрировать возможности стилизации Qt. Реальные приложения должны избегать её и использовать один согласованный графический стиль.

Предупреждение: Сейчас стили CSS Qt не поддерживаются для пользовательских подклассов QStyle. Мы планируем решить эту проблему в будущей версии.

См. также style(), QStyle, QApplication::style() и QApplication::setStyle().

[static] void QWidget::setTabOrder(QWidget *first, QWidget *second)

Устанавливает second виджет после first виджета в порядке фокуса.

Это эффективно удаляет second виджет из его цепочки фокуса и вставляет его после first виджета.

Обратите внимание, что так как порядок перехода на вкладку second виджета изменяется, цепочка должна быть организована так:

setTabOrder(a, b); // a to b
setTabOrder(b, c); // a to b to c
setTabOrder(c, d); // a to b to c to d

а не так:

// WRONG
setTabOrder(c, d); // c to d
setTabOrder(a, b); // a to b AND c to d
setTabOrder(b, c); // a to b to c, but not c to d

Если first или second имеют прокси фокуса, setTabOrder() корректно заменяет прокси.

Примечание: Начиная с Qt 5.10: Виджет, у которого есть дочерний элемент как прокси фокуса, понимается как составной виджет. При установке порядка перехода на вкладку между одним или двумя составными виджетами локальный порядок перехода на вкладку внутри каждого будет сохранён. Это означает, что если оба виджета являются составными виджетами, результирующий порядок перехода на вкладку будет от последнего дочернего элемента внутри first до первого дочернего элемента внутри second.

См. также setFocusPolicy(), setFocusProxy() и Фокус клавиатуры в виджетах.

void QWidget::setWindowFlag(Qt::WindowType flag, bool on = true)

Устанавливает флаг окна flag для этого виджета, если on имеет значение true; в противном случае очищает флаг.

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

См. также setWindowFlags(), windowFlags() и windowType().

void QWidget::setWindowRole(const QString &role)

Устанавливает роль окна на role. Это имеет смысл только для окон на X11.

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

void QWidget::setWindowState(Qt::WindowStates windowState)

Устанавливает состояние окна в windowState. Состояние окна — это объединённое по оператору OR значение из Qt::WindowState: Qt::WindowMinimized, Qt::WindowMaximized, Qt::WindowFullScreen и Qt::WindowActive.

Если окно не отображается (т.е. isVisible() возвращает false), состояние окна вступит в силу при вызове show(). Для видимых окон изменение происходит мгновенно. Например, чтобы переключиться между полноэкранным и обычным режимом, используйте следующий код:

w->setWindowState(w->windowState() ^ Qt::WindowFullScreen);

Для восстановления и активации минимизированного окна (при сохранении его максимального и/или полноэкранного состояния) используйте следующее:

w->setWindowState((w->windowState() & ~Qt::WindowMinimized) | Qt::WindowActive);

Вызов этой функции скроет виджет. Вам необходимо вызвать show(), чтобы снова отобразить виджет.

Примечание: На некоторых системах окон Qt::WindowActive не работает мгновенно и может быть проигнорировано в определённых случаях.

При изменении состояния окна виджет получает changeEvent() типа QEvent::WindowStateChange.

См. также Qt::WindowState и windowState().

void QWidget::setupUi(QWidget *widget)

Настраивает пользовательский интерфейс для указанного виджета widget.

Примечание: Эта функция доступна для виджетов, которые производятся от описаний пользовательского интерфейса, созданных с использованием uic.

См. также Использование файла UI-дизайнера в вашем приложении C++.

[virtual protected] void QWidget::showEvent(QShowEvent *event)

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

Непроизвольные события отображения отправляются виджетам непосредственно перед их отображением. Произвольные события отображения окон доставляются позже.

Примечание: Виджет получает произвольные события отображения и скрытия, когда его статус отображения изменяется системой окон, например, произвольное событие скрытия, когда пользователь минимизирует окно, и произвольное событие отображения, когда окно восстанавливается. После получения произвольного события скрытия виджет всё ещё считается видимым в смысле isVisible().

См. также visible, event() и QShowEvent.

void QWidget::stackUnder(QWidget *w)

Размещает виджет под w в стеке родительского виджета.

Для работы виджет и w должны быть братьями.

См. также raise() и lower().

QStyle *QWidget::style() const

См. также QWidget::setStyle(), QApplication::setStyle() и QApplication::style().

[virtual protected] void QWidget::tabletEvent(QTabletEvent *event)

Этот обработчик событий, для события event, может быть переопределён в подклассе для получения событий планшета для виджета.

Если вы переопределяете этот обработчик, очень важно ignore() событие, если вы его не обрабатываете, чтобы родительский виджет мог его интерпретировать.

По умолчанию обработчик игнорирует событие.

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

См. также QEvent::ignore(), QEvent::accept(), event(), setTabletTracking() и QTabletEvent.

bool QWidget::testAttribute(Qt::WidgetAttribute attribute) const

Возвращает true если атрибут attribute установлен для этого виджета; в противном случае возвращает false.

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

bool QWidget::underMouse() const

Возвращает true если виджет находится под курсором мыши; в противном случае возвращает false.

Это значение не обновляется должным образом во время операций перетаскивания.

См. также enterEvent() и leaveEvent().

void QWidget::ungrabGesture(Qt::GestureType gesture)

Отписывает виджет от данного типа жеста gesture

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

См. также grabGesture() и QGestureEvent.

void QWidget::update(int x, int y, int w, int h)

Это перегруженная функция.

Этот вариант обновляет прямоугольник (x, y, w, h) внутри виджета.

void QWidget::update(const QRect &rect)

Это перегруженная функция.

Этот вариант обновляет прямоугольник rect внутри виджета.

void QWidget::update(const QRegion &rgn)

Это перегруженная функция.

Этот вариант перерисовывает область rgn внутри виджета.

void QWidget::updateGeometry()

Уведомляет систему компоновки, что этот виджет изменился и может потребоваться изменение геометрии.

Вызовите эту функцию, если sizeHint() или sizePolicy() изменились.

Для явных скрытых виджетов updateGeometry() — это пустая операция. Система компоновки будет уведомлена, как только виджет будет показан.

QRegion QWidget::visibleRegion() const

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

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

Функция repaint() при необходимости вызывает эту функцию, поэтому обычно её вызывать не нужно.

[virtual protected] void QWidget::wheelEvent(QWheelEvent *event)

Этот обработчик событий, для события event, может быть переопределён в подклассе для получения событий прокрутки для виджета.

Если вы переопределяете этот обработчик, очень важно ignore() событие, если вы его не обрабатываете, чтобы родительский виджет мог его интерпретировать.

По умолчанию обработчик игнорирует событие.

См. также QEvent::ignore(), QEvent::accept(), event() и QWheelEvent.

WId QWidget::winId() const

Возвращает идентификатор окна системы окон виджета.

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

Если виджет не является родным (чужой), и winId() вызывается на нём, этому виджету будет предоставлен родной дескриптор.

Это значение может изменяться во время выполнения. Событие с типом QEvent::WinIdChange будет отправлено виджету после изменения идентификатора системы окон.

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

QWidget *QWidget::window() const

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

Если виджет является окном, возвращается сам виджет.

Типичное использование — изменение заголовка окна:

aWidget->window()->setWindowTitle("New Window Title");

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

QWindow *QWidget::windowHandle() const

Если это родной виджет, возвращает связанное QWindow. В противном случае возвращает null.

Родные виджеты включают виджеты верхнего уровня, QGLWidget и дочерние виджеты, на которых был вызван winId().

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

См. также winId() и screen().

QString QWidget::windowRole() const

Возвращает роль окна или пустую строку.

См. также setWindowRole(), windowIcon и windowTitle.

Qt::WindowStates QWidget::windowState() const

Возвращает текущее состояние окна. Состояние окна — это результат побитового ИЛИ операций над значениями Qt::WindowState: Qt::WindowMinimized, Qt::WindowMaximized, Qt::WindowFullScreen и Qt::WindowActive.

См. также Qt::WindowState и setWindowState().

Qt::WindowType QWidget::windowType() const

Возвращает тип окна этого виджета. Это идентично windowFlags() & Qt::WindowType_Mask.

См. также windowFlags.