Класс QWidget

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

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

Открытые типы

Свойства

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

Открытые функции

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

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

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

• 1 публичный слот, унаследованный от QObject

Сигналы

• 2 сигнала, унаследованные от QObject

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

• 10 статических публичных членов, унаследованных от QObject

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

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

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

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

Макросы

Дополнительные унаследованные члены

• 1 общедоступная переменная унаследованная от QObject
• 2 защищённые переменные унаследованные от 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() вызывается, когда пользователь дважды щелкает внутри виджета. Если пользователь дважды щелкает, виджет получает событие нажатия мыши, событие отпускания мыши, (событие щелчка мыши,) второе нажатие мыши, это событие и, наконец, второе событие отпускания мыши. (Также могут быть получены некоторые события перемещения мыши, если мышь не удерживается неподвижно во время этой операции.) Невозможно отличить щелчок от двойного щелчка до тех пор, пока не появится второй щелчок. (Это одна из причин, по которой большинство книг по GUI рекомендуют, чтобы двойные щелчки были расширением одиночных щелчков, а не вызывали другое действие.)

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

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

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

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

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

См. также windowFlags.

[virtual] QWidget::~QWidget()

Удаляет виджет.

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

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

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

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

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

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

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

void QWidget::activateWindow()

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

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

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

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

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

void QWidget::addAction(QAction *action)

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

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

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

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

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

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

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

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

void QWidget::adjustSize()

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

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

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

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

QPalette::ColorRole QWidget::backgroundRole() const

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

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

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

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

QBackingStore *QWidget::backingStore() const

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

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

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

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

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

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

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

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

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

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

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

void QWidget::clearFocus()

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

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

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

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

void QWidget::clearMask()

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

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

[slot] bool QWidget::close()

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

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

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

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

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

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

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

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

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

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

QMargins QWidget::contentsMargins() const

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

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

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

QRect QWidget::contentsRect() const

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Создает 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, чтобы её можно было вызывать из других функций 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)))

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

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

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

QGraphicsEffect *QWidget::graphicsEffect() const

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

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

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

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

QGraphicsProxyWidget *QWidget::graphicsProxyWidget() const

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

Эта функция была представлена в 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() и отобразить их как подсказку), сначала необходимо включить отслеживание мыши, как описано выше. Затем, чтобы убедиться, что подсказка обновляется немедленно, в своей реализации mouseMoveEvent() необходимо вызвать QToolTip::showText(), а не setToolTip().

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 должен быть активным. В 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().

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

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

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

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

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

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

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

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

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

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

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

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

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

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

void QWidget::setGraphicsEffect(QGraphicsEffect *effect)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

а не так:

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

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

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

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

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

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

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

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

void QWidget::setWindowRole(const QString &role)

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

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

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

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

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

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

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

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

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

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

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

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

void QWidget::setupUi(QWidget *widget)

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

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

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

[slot] void QWidget::show()

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

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

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

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

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

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

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

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

[slot] void QWidget::showFullScreen()

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

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

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

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

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

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

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

[slot] void QWidget::showMaximized()

Отображает виджет, развернув его на весь экран.

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

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

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

[slot] void QWidget::showMinimized()

Минимизирует виджет, отображая его в виде значка.

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

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

[slot] void QWidget::showNormal()

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

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

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

void QWidget::stackUnder(QWidget *w)

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

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

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

QStyle *QWidget::style() const

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

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

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

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

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

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

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

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

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

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

bool QWidget::underMouse() const

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

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

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

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

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

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

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

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

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

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

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

WId QWidget::winId() const

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

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

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

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

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

QWidget *QWidget::window() const

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

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

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

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

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

QWindow *QWidget::windowHandle() const

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

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

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

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

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

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

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

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

QString QWidget::windowRole() const

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

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

Qt::WindowStates QWidget::windowState() const

Возвращает текущее состояние окна. Состояние окна — это OR-комбинация состояний Qt::WindowState: Qt::WindowMinimized, Qt::WindowMaximized, Qt::WindowFullScreen и Qt::WindowActive.

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

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

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

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

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

Qt::WindowType QWidget::windowType() const

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

См. также windowFlags.