Класс QWidget

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

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

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

Свойства

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

Реализованные общедоступные функции

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

Сигналы

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

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

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

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

Макросы

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

setCursor(Qt::IBeamCursor);

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

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

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

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

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

Если parent равен nullptr, новый виджет становится окном. Если parent — это другой виджет, этот виджет становится дочерним окном внутри parent. Новый виджет удаляется при удалении его 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()

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

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

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

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

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

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

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

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

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

[virtual] QWidget::~QWidget()

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

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

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

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

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

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

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

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

void QWidget::activateWindow()

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

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

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

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

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

void QWidget::addAction(QAction *action)

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

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

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

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

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

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

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

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

void QWidget::adjustSize()

Настраивает размер виджета в соответствии с его содержимым.

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

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

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

QPalette::ColorRole QWidget::backgroundRole() const

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

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

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

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

QBackingStore *QWidget::backingStore() const

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

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

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

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

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

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

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

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

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

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

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

void QWidget::clearFocus()

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

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

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

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

void QWidget::clearMask()

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

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

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

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

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

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

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

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

QMargins QWidget::contentsMargins() const

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

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

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

QRect QWidget::contentsRect() const

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

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

[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 игнорируется в Qt 5. Пожалуйста, используйте QWindow::fromWinId() для создания QWindow, обертывающего внешнее окно, и передайте его в QWidget::createWindowContainer() вместо этого.

Инициализирует окно (устанавливает геометрию и т.д.), если initializeWindow равно true. Если initializeWindow равно false, инициализация не выполняется. Этот параметр имеет смысл только если window является допустимым окном.

Удаляет старое окно, если destroyOldWindow равно true. Если destroyOldWindow равно false, вы сами отвечаете за удаление окна (с использованием платформенного кода).

Конструктор QWidget вызывает create(0,true,true) для создания окна для этого виджета.

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

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

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

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

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

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

void QWidget::ensurePolished() const

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[protected] bool QWidget::focusNextChild()

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

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

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

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

Если next равно 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

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

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

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

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

void QWidget::getContentsMargins(int *left, int *top, int *right, int *bottom) const

Возвращает отступы содержимого виджета для left, top, right и bottom.

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

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

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

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

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

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

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

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

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

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

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

void QWidget::grabKeyboard()

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

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

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

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

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

void QWidget::grabMouse()

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

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

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

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

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

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

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

void QWidget::grabMouse(const QCursor &cursor)

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

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

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

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

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

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

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

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

Если ту же последовательность key захватили несколько виджетов, при её выполнении событие QEvent::Shortcut отправляется всем виджетам, к которым оно относится, в неопределённом порядке, но с установленным флагом «неопределённый».

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

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

QGraphicsEffect *QWidget::graphicsEffect() const

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

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

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

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

QGraphicsProxyWidget *QWidget::graphicsProxyWidget() const

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

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

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

bool QWidget::hasEditFocus() const

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

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

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

[virtual] bool QWidget::hasHeightForWidth() const

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

В данном контексте предок означает родительский виджет в том же окне.

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

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

bool QWidget::isHidden() const

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

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

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

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

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

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

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

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

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

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

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

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

bool QWidget::isWindow() const

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[static] QWidget *QWidget::keyboardGrabber()

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

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

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

QLayout *QWidget::layout() const

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

QRegion QWidget::mask() const

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

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

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

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

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

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

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

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

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

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

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

[static] QWidget *QWidget::mouseGrabber()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

См. также QAbstractNativeEventFilter.

QWidget *QWidget::nativeParentWidget() const

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

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

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

QWidget *QWidget::nextInFocusChain() const

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

QWidget *QWidget::parentWidget() const

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

QWidget *QWidget::previousInFocusChain() const

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

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

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

void QWidget::releaseKeyboard()

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

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

void QWidget::releaseMouse()

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

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

void QWidget::releaseShortcut(int id)

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

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

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

void QWidget::removeAction(QAction *action)

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

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

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

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

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

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

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

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

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

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

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

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

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

Отображает виджет в QPainter::device() отрисовщика painter.

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

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

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

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

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

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

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

void QWidget::repaint(const QRect &rect)

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

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

void QWidget::repaint(const QRegion &rgn)

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

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

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

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

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

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

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

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

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

См. также moveEvent(), event(), resize(), QResizeEvent, paintEvent() и Пример "Рисования".

bool QWidget::restoreGeometry(const QByteArray &geometry)

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

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

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

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

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

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

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

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

QByteArray QWidget::saveGeometry() const

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

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

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

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

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

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

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

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

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

void QWidget::setContentsMargins(const QMargins &margins)

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

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

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

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

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

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

void QWidget::setEditFocus(bool enable)

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

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

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

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

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

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

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

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

void QWidget::setLayout(QLayout *layout)

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

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

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

Пример:

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

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

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

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

void QWidget::setMask(const QBitmap &bitmap)

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

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

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

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

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

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

См. также mask(), clearMask(), windowOpacity() и Пример часов со скругленными формами.

void QWidget::setMask(const QRegion &region)

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

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

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

См. также windowOpacity.

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

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

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

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

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

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

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

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

void QWidget::setParent(QWidget *parent)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

void QWidget::setStyle(QStyle *style)

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

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

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

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

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

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

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

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

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

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

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

не так:

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

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

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

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

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

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

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

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

void QWidget::setWindowRole(const QString &role)

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

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

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

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

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

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

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

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

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

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

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

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

void QWidget::setupUi(QWidget *widget)

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

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

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

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

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

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

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

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

void QWidget::stackUnder(QWidget *w)

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

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

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

QStyle *QWidget::style() const

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

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

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

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

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

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

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

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

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

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

bool QWidget::underMouse() const

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

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

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

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

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

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

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

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

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

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

void QWidget::update(const QRect &rect)

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

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

void QWidget::update(const QRegion &rgn)

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

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

void QWidget::updateGeometry()

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

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

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

QRegion QWidget::visibleRegion() const

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

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

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

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

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

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

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

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

WId QWidget::winId() const

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

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

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

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

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

QWidget *QWidget::window() const

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

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

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

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

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

QWindow *QWidget::windowHandle() const

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

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

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

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

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.