Класс QWidget

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

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

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

Свойства

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

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

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

Сигналы

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

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

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

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

Макросы

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

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

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

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

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

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

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

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

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

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

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

Составные виджеты

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

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

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

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

Каждый виджет выполняет все операции рисования внутри своей функции paintEvent(). Она вызывается всякий раз, когда виджет необходимо перерисовать, либо в результате внешнего изменения, либо по запросу приложения.

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

Рекомендации по размеру и политики размеров

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

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

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

Примечание: Размер виджетов верхнего уровня ограничен 2/3 высоты и ширины рабочего стола. Вы можете изменить размер виджета вручную, если этих границ недостаточно.

События

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

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

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

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

• paintEvent() вызывается всякий раз, когда виджет необходимо перерисовать. Каждый виджет, отображающий пользовательское содержимое, должен реализовывать его. Рисование с помощью QPainter может выполняться только в paintEvent() или в функции, вызываемой paintEvent().
• resizeEvent() вызывается, когда виджет был изменен по размеру.
• mousePressEvent() вызывается при нажатии кнопки мыши, когда указатель мыши находится внутри виджета, или когда виджет захватил мышь с помощью grabMouse(). Нажатие мыши без ее отпускания по существу эквивалентно вызову grabMouse().
• mouseReleaseEvent() вызывается при отпускании кнопки мыши. Виджет получает события отпускания мыши, когда он получил соответствующее событие нажатия мыши. Это означает, что если пользователь нажимает мышь внутри вашего виджета, затем перемещает мышь куда-то еще, прежде чем отпустить кнопку мыши, ваш виджет получает событие отпускания. Есть одно исключение: если появляется всплывающее меню, пока кнопка мыши удерживается нажатой, это всплывающее меню немедленно захватывает события мыши.
• mouseDoubleClickEvent() вызывается при двойном щелчке пользователя внутри виджета. Если пользователь дважды щелкает, виджет получает событие нажатия мыши, событие отпускания мыши, (событие щелчка мыши), второе нажатие мыши, это событие и, наконец, второе событие отпускания мыши. (Также могут быть получены некоторые события перемещения мыши, если мышь не удерживается неподвижно во время этой операции.) Невозможно отличить щелчок от двойного щелчка до появления второго щелчка. (Это одна из причин, по которой большинство книг по интерфейсам пользователя рекомендуют рассматривать двойной щелчок как расширение одиночного щелчка, а не как отдельное действие.)

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

• keyPressEvent() вызывается при каждом нажатии клавиши и повторно, когда клавиша удерживается достаточно долго для автоповтора. Клавиши Tab и Shift+Tab передаются виджету только в том случае, если они не используются механизмами изменения фокуса. Чтобы заставить эти клавиши обрабатываться вашим виджетом, вы должны переопределить QWidget::event().
• focusInEvent() вызывается, когда виджет получает фокус клавиатуры (предполагая, что вы вызываете setFocusPolicy()). Хорошо спроектированные виджеты указывают, что они владеют фокусом клавиатуры ясным, но незаметным способом.
• focusOutEvent() вызывается, когда виджет теряет фокус клавиатуры.

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

• mouseMoveEvent() вызывается всякий раз, когда мышь перемещается, при этом зажата кнопка мыши. Это может быть полезно при операциях перетаскивания. Если вы вызовете setMouseTracking(true), вы получите события перемещения мыши даже когда ни одна кнопка не зажата. (См. также руководство Перетаскивание.)
• keyReleaseEvent() вызывается всякий раз, когда отпускается клавиша, и при этом она зажата (если клавиша повторяется автоматически). В этом случае виджет получит пару событий отпускания и нажатия клавиши для каждой итерации повторения. Клавиши Tab и Shift+Tab передаются виджету только в том случае, если они не используются механизмами изменения фокуса. Чтобы принудительно обработать эти клавиши вашим виджетом, необходимо переопределить QWidget::event().
• wheelEvent() вызывается всякий раз, когда пользователь вращает колесо мыши, а виджет имеет фокус.
• enterEvent() вызывается при входе курсора мыши в экранное пространство виджета. (Это не включает экранное пространство, принадлежащее любому из дочерних виджетов.)
• leaveEvent() вызывается, когда курсор мыши выходит из экранного пространства виджета. Если курсор переходит на дочерний виджет, это не вызовет leaveEvent().
• moveEvent() вызывается, когда виджет был перемещен относительно своего родительского виджета.
• closeEvent() вызывается, когда пользователь закрывает виджет (или когда вызывается close() ).

Также есть некоторые довольно запутанные события, описанные в документации для QEvent::Type. Для обработки этих событий необходимо напрямую переопределить event().

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

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

Группы функций и свойств

Стили виджетов

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

Использование таблиц стилей виджетов более подробно описано в документе Стили Qt.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Родные виджеты против внешних виджетов

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

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

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

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

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

enum QWidget::RenderFlagflags QWidget::RenderFlags

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

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

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

setCursor(Qt::IBeamCursor);

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

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

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

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

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

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

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

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

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

См. также windowFlags.

[slot] bool QWidget::close()

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

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

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

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

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

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

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

[slot] void QWidget::hide()

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

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

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

[slot] void QWidget::lower()

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

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

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

[slot] void QWidget::raise()

Приподнимает этот виджет доверху стека виджетов родительского виджета.

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

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

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

[slot] void QWidget::repaint()

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

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

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

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

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

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

Дополнительную информацию см. в документации к enabled.

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

[slot] void QWidget::setFocus()

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

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

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

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

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

[slot] void QWidget::show()

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

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

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

[slot] void QWidget::showFullScreen()

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

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

Для выхода из полноэкранного режима, вызовите showNormal().

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

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

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

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

[slot] void QWidget::showMaximized()

Отображает виджет в максимальном размере.

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

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

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

[slot] void QWidget::showMinimized()

Отображает виджет в свёрнутом виде, как значок.

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

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

[slot] void QWidget::showNormal()

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

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

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

[slot] void QWidget::update()

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

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

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

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

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

[protected slot] void QWidget::updateMicroFocus()

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

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

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

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

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

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

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

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

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

[virtual] QWidget::~QWidget()

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

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

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

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

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

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

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

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

void QWidget::activateWindow()

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

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

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

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

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

void QWidget::addAction(QAction *action)

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

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

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

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

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

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

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

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

void QWidget::adjustSize()

Настраивает размер виджета для соответствия его содержимому.

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

Для окон также учитывается размер экрана. Если sizeHint() меньше (200, 100) и политика размера является расширяющей, окно будет иметь минимальный размер (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) в системе координат виджета. Если по указанным координатам нет видимого дочернего виджета, функция возвращает nullptr.

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

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

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

void QWidget::clearFocus()

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

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

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

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

void QWidget::clearMask()

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

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

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

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

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

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

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

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

QMargins QWidget::contentsMargins() const

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

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

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

QRect QWidget::contentsRect() const

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

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

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

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

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

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

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

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

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

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

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

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

Создаёт QWidget, позволяющий встроить window в приложение на основе QWidget.

Контейнер окна создаётся как дочерний элемент parent и с флагами окна flags.

После того, как окно было встроено в контейнер, контейнер будет управлять геометрией и видимостью окна. Явные вызовы QWindow::setGeometry(), QWindow::show() или QWindow::hide() для встроенного окна не рекомендуются.

Контейнер перенимает владение window. Окно можно удалить из контейнера окна с помощью вызова QWindow::setParent().

Контейнер окна подключается как родное дочернее окно к верхнему окну, которое является его родителем. Если контейнер окна используется в качестве дочернего элемента QAbstractScrollArea или QMdiArea, он создаст родное окно для каждого виджета в цепочке родителей, чтобы обеспечить правильное расположение и обрезку в этом случае. Создание родного окна для контейнера окна также позволяет обеспечить правильное расположение и обрезку. Это необходимо сделать перед отображением контейнера окна. Приложения с большим количеством родных дочерних окон могут испытывать проблемы с производительностью.

У контейнера окна есть ряд известных ограничений:

• Порядок расположения; Встроенное окно будет расположено поверх иерархии виджетов как непрозрачный прямоугольник. Порядок расположения нескольких перекрывающихся экземпляров контейнеров окон не определён.
• Интеграция отрисовки; Контейнер окна не взаимодействует с QGraphicsProxyWidget, QWidget::render() или подобными функциями.
• Обработка фокуса; Можно разрешить контейнеру окна иметь любую политику фокуса, и он перенаправит фокус на окно с помощью вызова QWindow::requestActivate(). Однако возвращение к обычной цепочке фокуса из экземпляра QWindow будет зависеть от реализации самого экземпляра QWindow. Например, при входе в окно на основе Qt Quick с помощью фокуса табуляции, вполне вероятно, что дальнейшие нажатия клавиш табуляции будут циклировать только внутри приложения QML. Также, действительно ли QWindow::requestActivate() предоставляет фокус окну, зависит от платформы.
• Использование большого количества экземпляров контейнеров окон в приложении на основе QWidget может значительно ухудшить общую производительность приложения.

[protected] void QWidget::destroy(bool destroyWindow = true, bool destroySubWindows = true)

Освобождает системные ресурсы окна. Уничтожает окно виджета, если destroyWindow имеет значение true.

destroy() рекурсивно вызывает себя для всех дочерних виджетов, передавая destroySubWindows в качестве параметра destroyWindow. Для большего контроля над уничтожением дочерних виджетов, сначала уничтожьте дочерние виджеты выборочно.

Эта функция обычно вызывается из деструктора QWidget.

[virtual protected] void QWidget::dragEnterEvent(QDragEnterEvent *event)

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

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

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

См. также QDrag и QDragEnterEvent.

[virtual protected] void QWidget::dragLeaveEvent(QDragLeaveEvent *event)

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

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

См. также QDrag и QDragLeaveEvent.

[virtual protected] void QWidget::dragMoveEvent(QDragMoveEvent *event)

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

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

См. также QDrag и QDragMoveEvent.

[virtual protected] void QWidget::dropEvent(QDropEvent *event)

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

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

См. также QDrag и QDropEvent.

WId QWidget::effectiveWinId() const

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

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

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

Функция была введена в 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(QEvent *e).

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

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

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

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

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

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

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

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

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

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

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

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

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

[protected] bool QWidget::focusNextChild()

Находит новый виджет, которому следует передать фокус клавиатуры, в соответствии с нажатием клавиши Tab, и возвращает true, если новый виджет найден, или false, если нет.

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

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

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

Если next имеет значение true, эта функция выполняет поиск вперёд, если next имеет значение false, она выполняет поиск назад.

Иногда необходимо переопределить эту функцию. Например, веб-браузер может переопределить её, чтобы переместить "текущую активную ссылку" вперёд или назад, и вызвать focusNextPrevChild() только когда достигнет последней или первой ссылки на "странице".

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

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

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

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

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

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

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

[protected] bool QWidget::focusPreviousChild()

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

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

QWidget *QWidget::focusProxy() const

Возвращает прокси фокуса или nullptr, если прокси фокуса нет.

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

QWidget *QWidget::focusWidget() const

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

Это не то же самое, что QApplication::focusWidget(), которое возвращает виджет фокуса в текущем активном окне.

QFontInfo QWidget::fontInfo() const

Возвращает информацию о шрифте для текущего шрифта виджета. Эквивалентно QFontInfo(widget->font()).

См. также font(), fontMetrics() и setFont().

QFontMetrics QWidget::fontMetrics() const

Возвращает метрики шрифта для текущего шрифта виджета. Эквивалентно QFontMetrics(widget->font()).

См. также font(), fontInfo() и setFont().

QPalette::ColorRole QWidget::foregroundRole() const

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

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

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

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

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 = Qt::GestureFlags())

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

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

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

void QWidget::grabKeyboard()

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

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

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

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

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

void QWidget::grabMouse()

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

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

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

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

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

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

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

void QWidget::grabMouse(const QCursor &cursor)

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

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

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

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

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

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

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

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

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

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

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

QGraphicsEffect *QWidget::graphicsEffect() const

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

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

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

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

QGraphicsProxyWidget *QWidget::graphicsProxyWidget() const

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

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

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

bool QWidget::hasEditFocus() const

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

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

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

[virtual] bool QWidget::hasHeightForWidth() const

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Стандартная реализация вызывает event->ignore(), что отклоняет событие метода ввода. Подробнее см. в документации QInputMethodEvent.

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

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

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

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

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

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

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

В QWidget должно быть только одно действие каждого типа.

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

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

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

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

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

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

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

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

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

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

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, если этот виджет станет видимым, если предок отображён; в противном случае возвращает false.

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

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

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

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

bool QWidget::isWindow() const

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[static] QWidget *QWidget::keyboardGrabber()

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

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

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

QLayout *QWidget::layout() const

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

QRegion QWidget::mask() const

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

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

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

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

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

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

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

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

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

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

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

[static] QWidget *QWidget::mouseGrabber()

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

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

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

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

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

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

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

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

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

[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 и Пример Scribble.

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

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

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

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

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

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

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

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

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

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

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

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

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

См. также QAbstractNativeEventFilter.

QWidget *QWidget::nativeParentWidget() const

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

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

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

QWidget *QWidget::nextInFocusChain() const

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

QWidget *QWidget::parentWidget() const

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

QWidget *QWidget::previousInFocusChain() const

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

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

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

void QWidget::releaseKeyboard()

Освобождает захват клавиатуры.

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

void QWidget::releaseMouse()

Освобождает захват мыши.

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

void QWidget::releaseShortcut(int id)

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

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

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

void QWidget::removeAction(QAction *action)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

void QWidget::repaint(const QRect &rect)

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

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

void QWidget::repaint(const QRegion &rgn)

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

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

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

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

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

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

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

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

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

См. также moveEvent(), event(), resize(), QResizeEvent, paintEvent() и Пример 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().

QScreen *QWidget::screen() const

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

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

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

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

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

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

Поскольку виджеты по умолчанию распространяют содержимое своих родителей, вам нужно установить свойство autoFillBackground или использовать setAttribute() для установки атрибута Qt::WA_OpaquePaintEvent, чтобы сделать виджет непрозрачным.

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

См. также Прозрачность и буферизация.

void QWidget::scroll(int dx, int dy, const QRect &r)

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

Этот вариант прокручивает только r и не перемещает дочерние элементы виджета.

Если r пустая или некорректная, результат не определен.

См. также QScrollArea.

void QWidget::setAttribute(Qt::WidgetAttribute attribute, bool on = true)

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

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

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

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

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

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

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

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

void QWidget::setBaseSize(int basew, int baseh)

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

Это соответствует setBaseSize(QSize(basew, baseh)). Устанавливает базовый размер виджета в ширину basew и высоту baseh.

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

void QWidget::setContentsMargins(int left, int top, int right, int bottom)

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

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

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

void QWidget::setContentsMargins(const QMargins &margins)

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

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

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

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

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

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

void QWidget::setEditFocus(bool enable)

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

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

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

void QWidget::setFixedHeight(int h)

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

См. также sizeHint(), minimumSize(), maximumSize() и setFixedSize().

void QWidget::setFixedSize(const QSize &s)

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

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

Чтобы удалить ограничения, установите размер в QWIDGETSIZE_MAX.

В качестве альтернативы, если вы хотите, чтобы виджет имел фиксированный размер, основанный на его содержимом, вы можете вызвать QLayout::setSizeConstraint(QLayout::SetFixedSize);

См. также maximumSize и minimumSize.

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

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

Устанавливает ширину виджета в w и высоту в h.

void QWidget::setFixedWidth(int w)

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

См. также sizeHint(), minimumSize(), maximumSize() и setFixedSize().

void QWidget::setFocus(Qt::FocusReason reason)

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

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

Примечание: Встраиваемых платформах, setFocus() не приведет к открытию панели ввода методом ввода. Если вы хотите, чтобы это произошло, вы должны отправить событие QEvent::RequestSoftwareInputPanel в виджет самостоятельно.

setFocus() дает фокус виджету независимо от его политики фокуса, но не очищает захват клавиатуры (см. grabKeyboard()).

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

Предупреждение: Если вы вызываете setFocus() в функции, которая сама может быть вызвана из focusOutEvent() или focusInEvent(), у вас может возникнуть бесконечная рекурсия.

См. также hasFocus(), clearFocus(), focusInEvent(), focusOutEvent(), setFocusPolicy(), focusWidget(), QApplication::focusWidget(), grabKeyboard(), grabMouse(), Фокус клавиатуры в виджетах и QEvent::RequestSoftwareInputPanel.

void QWidget::setFocusProxy(QWidget *w)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

void QWidget::setGraphicsEffect(QGraphicsEffect *effect)

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

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

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

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

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

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

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

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

void QWidget::setLayout(QLayout *layout)

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

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

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

Пример:

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

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

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

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

void QWidget::setMask(const QBitmap &bitmap)

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

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

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

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

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

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

См. также mask(), clearMask(), windowOpacity() и Пример часов с формой.

void QWidget::setMask(const QRegion &region)

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

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

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

См. также windowOpacity.

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

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

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

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

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

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

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

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

void QWidget::setParent(QWidget *parent)

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

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

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

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

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

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

Предупреждение: Стили 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. Состояние окна — это комбинация OR'ed значений Qt::WindowState: Qt::WindowMinimized, Qt::WindowMaximized, Qt::WindowFullScreen и Qt::WindowActive.

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

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

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

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

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

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

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

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

void QWidget::setupUi(QWidget *widget)

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

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

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

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

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

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

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

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

void QWidget::stackUnder(QWidget *w)

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

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

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

QStyle *QWidget::style() const

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

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

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

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

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

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

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

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

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

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

bool QWidget::underMouse() const

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

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

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

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

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

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

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

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

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

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

void QWidget::update(const QRect &rect)

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

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

void QWidget::update(const QRegion &rgn)

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

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

void QWidget::updateGeometry()

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

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

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

QRegion QWidget::visibleRegion() const

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

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

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

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

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

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

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

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

WId QWidget::winId() const

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

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

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

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

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

QWidget *QWidget::window() const

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

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

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

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

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

QWindow *QWidget::windowHandle() const

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

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

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

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

QString QWidget::windowRole() const

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

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

Qt::WindowStates QWidget::windowState() const

Возвращает текущее состояние окна. Состояние окна — это объединение по битовому ИЛИ значений из Qt::WindowState: Qt::WindowMinimized, Qt::WindowMaximized, Qt::WindowFullScreen и Qt::WindowActive.

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

Qt::WindowType QWidget::windowType() const

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

См. также windowFlags.