Método IDCompositionVisual::AddVisual (dcomp.h)

Artigo
08/23/2023

Adiciona um novo visual filho à lista de filhos desse visual.

Sintaxe

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

Parâmetros

[in] visual

Tipo: IDCompositionVisual*

O visual filho a ser adicionado. Esse parâmetro não deve ser NULL.

[in] insertAbove

Tipo: BOOL

TRUE para colocar o novo visual filho na frente do visual especificado pelo parâmetro referenceVisual ou FALSE para colocá-lo atrás de referenceVisual.

[in, optional] referenceVisual

Tipo: IDCompositionVisual*

O visual filho existente ao lado do qual o novo visual deve ser adicionado.

Valor retornado

Tipo: HRESULT

Se a função for bem-sucedida, ela retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT. Confira Códigos de erro do DirectComposition para obter uma lista de códigos de erro.

Comentários

Os visuais filho são organizados em uma lista ordenada. O conteúdo de um visual filho é desenhado na frente (ou acima) do conteúdo de seu visual pai, mas atrás (ou abaixo) do conteúdo de seus filhos.

O parâmetro referenceVisual deve ser um filho existente do visual pai ou deve ser NULL. O parâmetro insertAbove indica se o novo filho deve ser renderizado imediatamente acima do visual de referência na ordem Z ou imediatamente abaixo dele.

Se o parâmetro referenceVisual for NULL, o visual especificado será renderizado acima ou abaixo de todos os filhos do visual pai, dependendo do valor do parâmetro insertAbove . Se insertAbove for TRUE, o novo visual filho estará acima de nenhum irmão, portanto, ele será renderizado abaixo de todos os seus irmãos. Por outro lado, se insertAbove for FALSE, o visual não estará abaixo de nenhum irmão, portanto, ele será renderizado acima de todos os seus irmãos.

O visual especificado pelo parâmetro visual não pode ser um filho de um único outro visual ou a raiz de uma árvore visual associada a um destino de composição. Se o visual já for um filho de outro visual, o AddVisual falhará. O visual filho deve ser removido da lista de filhos de seu pai anterior antes de adicioná-lo à lista de filhos do novo pai. Se visual for a raiz de uma árvore visual, o visual deverá ser dissociado dessa árvore visual antes de adicioná-lo à lista de filhos do novo pai. Para desassociar o visual de uma árvore visual, chame o método IDCompositionTarget::SetRoot e especifique um visual diferente ou NULL como o parâmetro visual .

Um visual filho não precisa ter sido criado pela mesma interface IDCompositionDevice que seu pai. Quando visuais de dispositivos diferentes são combinados na mesma árvore visual, o Microsoft DirectComposition compõe a árvore como normalmente faria, exceto que as alterações em um visual específico só entrarão em vigor quando IDCompositionDevice::Commit for chamado no objeto de dispositivo que criou o visual. A capacidade de combinar visuais de diferentes dispositivos permite que vários threads criem e manipulem uma única árvore visual, mantendo dispositivos independentes que podem ser usados para confirmar alterações de forma assíncrona

Esse método falhará se visual ou referenceVisual for um ponteiro inválido ou se o visual referenciado pelo parâmetro referenceVisual não for um filho do visual pai. Essas interfaces não podem ser implementações personalizadas; somente interfaces criadas pelo DirectComposition podem ser usadas com esse método.

Exemplos

Para obter um exemplo, consulte Como criar uma árvore visual simples.

Requisitos


Cliente mínimo com suporte	Windows 8 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2012 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	dcomp.h
Biblioteca	Dcomp.lib
DLL	Dcomp.dll