Метод IDCompositionVisual::AddVisual (dcomp.h)

Статья
08/23/2023

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

Синтаксис

HRESULT AddVisual(
  [in]           IDCompositionVisual *visual,
  [in]           BOOL                insertAbove,
  [in, optional] IDCompositionVisual *referenceVisual
);

Параметры

[in] visual

Тип: IDCompositionVisual*

Добавляемый дочерний визуальный элемент. Этот параметр не должен иметь значение NULL.

[in] insertAbove

Тип: BOOL

Значение TRUE, чтобы поместить новый дочерний визуальный элемент перед визуальным элементом, заданным параметром referenceVisual , или FALSE, чтобы поместить его позади referenceVisual.

[in, optional] referenceVisual

Тип: IDCompositionVisual*

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

Возвращаемое значение

Тип: HRESULT

Если функция завершается успешно, она возвращает S_OK. В противном случае возвращается код ошибки HRESULT . Список кодов ошибок см. в разделе Коды ошибок DirectComposition .

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

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

Если параметр referenceVisual имеет значение NULL, указанный визуальный элемент отображается над или под всеми дочерними элементами родительского визуального элемента в зависимости от значения параметра insertAbove . Если параметр insertAbove имеет значение TRUE, то новый дочерний визуальный элемент находится выше, не имеет одноуровневого элемента, поэтому он отображается ниже всех его одноуровневых элементов. И наоборот, если параметр insertAbove имеет значение FALSE, визуальный элемент находится ниже, чем ни одноуровневый элемент, поэтому он отображается выше всех его одноуровневых элементов.

Визуальный элемент, заданный параметром визуального элемента , не может быть ни дочерним элементом одного другого визуального элемента, ни корнем визуального дерева, связанного с целевым объектом композиции. Если визуальный элемент уже является дочерним элементом другого визуального элемента, addVisual завершается ошибкой . Дочерний визуальный элемент должен быть удален из списка дочерних элементов предыдущего родительского элемента, прежде чем добавлять его в список дочерних элементов нового родительского элемента. Если визуальный элемент является корнем визуального дерева, перед добавлением его в список дочерних элементов нового родительского элемента визуальный элемент необходимо отменить связь с этим визуальным деревом. Чтобы отменить связь визуального элемента с визуальным деревом, вызовите метод IDCompositionTarget::SetRoot и укажите другой визуальный элемент или значение NULL в качестве параметра визуального элемента .

Дочерний визуальный элемент не обязательно должен быть создан тем же интерфейсом IDCompositionDevice , что и его родительский элемент. Если визуальные элементы с разных устройств объединяются в одном визуальном дереве, Microsoft DirectComposition создает дерево, как обычно, за исключением того, что изменения конкретного визуального элемента вступают в силу только при вызове IDCompositionDevice::Commit для объекта устройства, создавшего визуальный элемент. Возможность объединения визуальных элементов с разных устройств позволяет нескольким потокам создавать и управлять одним визуальным деревом, сохраняя при этом независимые устройства, которые можно использовать для асинхронной фиксации изменений.

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

Примеры

Пример см. в разделе Создание простого визуального дерева.

Требования


Минимальная версия клиента	Windows 8 [только классические приложения]
Минимальная версия сервера	Windows Server 2012 [только классические приложения]
Целевая платформа	Windows
Header	dcomp.h
Библиотека	Dcomp.lib
DLL	Dcomp.dll