Класс QWidget

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

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

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

Свойства

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

Переопределённые публичные функции

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

Сигналы

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

Protected Functions

Reimplemented Protected Functions

Protected Slots

Macros

Detailed Description

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

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

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

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

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

Top-Level and Child Widgets

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

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

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

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

Composite Widgets

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

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

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

Поскольку 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().

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

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

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

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

См. также windowFlags.

[slot] bool QWidget::close()

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

Сначала он отправляет виджету QCloseEvent. Виджет скрывается, если он принимает событие закрытия. Если он игнорирует событие, ничего не происходит. По умолчанию реализация 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(Qt::InputMethodQuery query = Qt::ImQueryAll)

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

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

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

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

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

[signal, since 5.2] 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().

void QWidget::addAction(QAction *action)

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

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

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

Владение action не передаётся этому QWidget.

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

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

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

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

void QWidget::adjustSize()

Настраивает размер виджета, чтобы он соответствовал его содержимому.

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

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

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

QPalette::ColorRole QWidget::backgroundRole() const

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

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

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

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

[since 5.0] 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() для всех событий.

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

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

См. также event(), hide(), close(), QCloseEvent, и Пример Qt Widgets - Приложение.

QMargins QWidget::contentsMargins() const

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

См. также 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 окна первого нативного родительского виджета, т.е. верхнего виджета, содержащего этот виджет.

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

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

void QWidget::ensurePolished() const

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

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

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

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

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

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

[virtual protected] void QWidget::enterEvent(QEnterEvent *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 равно true, функция ищет вперёд, если next равно false, она ищет назад.

Иногда вам потребуется переопределить эту функцию. Например, веб-браузер может переопределить её, чтобы переместить «текущую активную ссылку» вперёд или назад, и вызывать 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().

[invokable, since 5.0] 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())

Подписывает виджет на определённый жест с определёнными флагами.

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

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

QGraphicsProxyWidget *QWidget::graphicsProxyWidget() const

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

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

bool QWidget::hasEditFocus() const

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

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

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

[virtual, since 5.0] 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, const 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.

Случай true имеет место, если ни сам виджет, ни какой-либо родитель до, но не включая 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().

[since 6.0] QPointF QWidget::mapFrom(const QWidget *parent, const QPointF &pos) const

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

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

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

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

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

[since 6.0] QPointF QWidget::mapFromGlobal(const QPointF &pos) const

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

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

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

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

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

[since 6.0] QPointF QWidget::mapFromParent(const QPointF &pos) const

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

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

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

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

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

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

[since 6.0] QPointF QWidget::mapTo(const QWidget *parent, const QPointF &pos) const

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

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

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

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

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

[since 6.0] QPointF QWidget::mapToGlobal(const QPointF &pos) const

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

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

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

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

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

[since 6.0] QPointF QWidget::mapToParent(const QPointF &pos) const

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

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

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

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

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

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

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, и Пример рисования.

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

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

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

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

См. также mouseReleaseEvent(), mouseDoubleClickEvent(), mouseMoveEvent(), event(), QMouseEvent, и Пример рисования.

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

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

См. также mousePressEvent(), mouseDoubleClickEvent(), mouseMoveEvent(), event(), QMouseEvent, и Пример рисования.

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, qintptr *result)

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

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

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

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

См. также QAbstractNativeEventFilter.

QWidget *QWidget::nativeParentWidget() const

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

См. также 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 возвращает предыдущий виджет в цепочке фокуса этого виджета.

См. также 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() вместо этого.

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() и Пример рисования.

bool QWidget::restoreGeometry(const QByteArray &geometry)

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

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

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

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

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

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

См. также 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(), чтобы сохранить геометрию и состояние панелей инструментов и плавающих окон.

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

[since 5.14] QScreen *QWidget::screen() const

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

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

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

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

Если 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().

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

void QWidget::setEditFocus(bool enable)

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

Эта функция доступна только в Qt для встраиваемой 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, для фактического управления фокусом. В этом случае виджет может установить виджет QLineEdit как свой прокси фокуса.

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

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

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

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

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

Если 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.

См. также 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::setScreen(QScreen *screen)

Устанавливает экран, на котором должен быть показан виджет, на screen.

Установка экрана имеет смысл только для окон. При необходимости окно виджета будет пересоздано на screen.

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

См. также screen() и QWindow::setScreen().

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

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

См. также 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() и Фокус клавиатуры в виджетах.

[since 5.9] 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. Состояние окна — это объединённое значение 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 Designer в приложении.

[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

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

[since 5.0] 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.