Класс QWidget

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

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

Общедоступные типы

Свойства

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

Реализованные публичные функции

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

Сигналы

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

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

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

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

Макросы

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Каждый виджет выполняет все операции рисования внутри своей функции 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 Style Sheets.

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

Начиная с 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). Для настройки рамки используйте значение, составленное из побитового ИЛИ любых флагов окна флагов окна.

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

Обратите внимание, что версия Qt для X11 может не поддерживать все сочетания флагов стиля на всех системах. Это связано с тем, что в 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()

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

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

Для получения фокуса ввода с клавиатуры виджет должен разрешить установку фокуса, т.е. вызвать 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 - Application Example.

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

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

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

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

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

void QWidget::ensurePolished() const

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

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

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

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

Примечание: Функция объявлена как 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().

Обработка событий мыши и планшета также немного специфична: только когда виджет enabled, 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)

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

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

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

См. также 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'' установленным в true.

Предупреждение: Вам обычно не нужно использовать эту функцию; вместо этого создавайте 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.

Истинное значение возникает, если ни сам виджет, ни любой родитель до, но не включая 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 и Пример Scribble.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[virtual protected] bool QWidget::nativeEvent(const QByteArray &eventType, void *message, 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)

Удаляет из системы ярлыков Qt ярлык с заданным id. Виджет больше не будет получать события 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() и Пример Scribble.

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

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. В реальных приложениях следует избегать её использования и использовать вместо этого один согласованный стиль графического интерфейса.

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

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

void QWidget::setTabOrder(QWidget *first, QWidget *second)

Помещает виджет second после виджета first в порядке фокуса.

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

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

а не так:

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

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

См. также 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-дизайнера в вашем приложении.

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