Класс QWidget

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

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

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

Свойства

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

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

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

• 31 публичных функций унаследовано от QObject
• 14 публичных функций унаследовано от QPaintDevice

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

• 1 public slot inherited from QObject

Сигналы

• 2 signals inherited from QObject

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

• 9 static public members inherited from QObject

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

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

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

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

Макросы

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

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

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

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

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

1. QWidget *parent = 0 — родитель нового виджета. Если он равен 0 (по умолчанию), новый виджет будет окном. В противном случае он будет дочерним элементом 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 Style Sheets.

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

Начиная с 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.

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

enum QWidget::RenderFlagflags 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 = ...)

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

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

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

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

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

См. также windowFlags.

[virtual] QWidget::~QWidget()

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

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

[virtual protected] void QWidget::actionEvent(QActionEvent *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.

void QWidget::changeEvent(QEvent *event)

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

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

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

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

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

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

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

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

void QWidget::clearFocus()

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

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

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

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

void QWidget::clearMask()

Удаляет любую маску, установленную функцией setMask().

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

bool QWidget::close()

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

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

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

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

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

Создаёт 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 с фокусом на вкладке, с большой вероятностью, дальнейшие нажатия клавиши Tab будут циклировать только внутри приложения QML. Кроме того, фактически ли QWindow::requestActivate() даёт окну фокус, зависит от платформы.
• Использование многих экземпляров контейнера окна в приложении на основе QWidget может значительно снизить общую производительность приложения.

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

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

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

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

Это основной обработчик событий; он обрабатывает событие 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 для фактического определения. Если виджета с таким идентификатором нет, возвращается 0.

[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

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

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

Подписывает виджет на указанное 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 захватили несколько виджетов, при возникновении последовательности key событие QEvent::Shortcut отправляется всем виджетам, к которым оно относится, в неопределенном порядке, но со значением флага «неопределенное» true.

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

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

QGraphicsEffect *QWidget::graphicsEffect() const

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

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

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

[slot] void QWidget::hide()

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

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

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

[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 равен 0 или before не является допустимым действием для этого виджета.

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

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

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

Вставляет действия actions в список действий данного виджета перед действием before. Добавляет в конец списка, если before равен 0 или 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()

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

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

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

QLayout *QWidget::layout() const

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

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

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

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

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

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

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

[slot] void QWidget::lower()

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

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

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

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

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

См. также 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 не должен быть равен 0 и должен быть родителем вызывающего виджета.

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

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

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

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

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

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

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

[static] QWidget *QWidget::mouseGrabber()

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

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

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

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

Эта функция была введена в 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().

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

Обратите внимание, что эта функция не должна вызываться пользователем явно, так как она предназначена только для переопределения. Функция вызывается 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

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

QWidget *QWidget::previousInFocusChain() const

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

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

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

[slot] void QWidget::raise()

Возводит этот виджет наверх стека родительского виджета.

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

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

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

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

Отображает 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 = ...)

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

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

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

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

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

[slot] void QWidget::repaint()

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

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

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

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

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

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

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

bool QWidget::restoreGeometry(const QByteArray &geometry)

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

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

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

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

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

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

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

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

QByteArray QWidget::saveGeometry() const

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

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

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

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

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

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

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

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

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

После прокрутки виджеты получат события paint для областей, которые нужно перерисовать. Для виджетов, которые 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().

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

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

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

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

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.

[slot] void QWidget::setFocus()

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

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

void QWidget::setFocusProxy(QWidget *w)

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

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

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

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

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

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

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

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

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

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

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

не так:

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

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

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

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

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

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

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

void QWidget::setWindowRole(const QString &role)

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

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

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

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

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

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

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

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

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

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

void QWidget::setupUi(QWidget *widget)

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

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

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

void QWidget::show()

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

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

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

void QWidget::showEvent(QShowEvent *event)

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

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

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

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

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

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, который может быть переопределён в подклассе для обработки событий планшета для виджета.

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

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

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

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

[slot] void QWidget::update()

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

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

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

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

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

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

[protected slot] void QWidget::updateMicroFocus()

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

QRegion QWidget::visibleRegion() const

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Qt::WindowType QWidget::windowType() const

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

См. также windowFlags.