Graphics::BeginContainer

Artigo
08/24/2023

O método Graphics::BeginContainer inicia um novo contêiner de gráficos.

Sintaxe

GraphicsContainer BeginContainer();

Valor retornado

Tipo: GraphicsContainer

Esse método retorna um valor que identifica o contêiner.

Comentários

Use esse método para criar contêineres de elementos gráficos aninhados. Os contêineres de gráficos são usados para reter o estado gráfico, como transformações, regiões de recorte e várias propriedades de renderização.

O método Graphics::BeginContainer retorna um valor do tipo GraphicsContainer. Quando terminar de usar um contêiner, passe esse valor para o método Graphics::EndContainer . O tipo de dados GraphicsContainer é definido em Gdiplusenums.h.

Quando você chama o método Graphics::BeginContainer de um objeto Graphics , um bloco de informações que contém o estado do objeto Graphics é colocado em uma pilha. O método Graphics::BeginContainer retorna um valor que identifica esse bloco de informações. Quando você passa o valor de identificação para o método Graphics::EndContainer , o bloco de informações é removido da pilha e é usado para restaurar o objeto Graphics para o estado em que ele estava no momento da chamada Graphics::BeginContainer .

Os contêineres podem ser aninhados; ou seja, você pode chamar o método Graphics::BeginContainer várias vezes antes de chamar o método Graphics::EndContainer . Sempre que você chama o método Graphics::BeginContainer , um bloco de informações é colocado na pilha e você recebe um identificador para o bloco de informações. Quando você passa um desses identificadores para o método Graphics::EndContainer , o objeto Graphics é retornado ao estado em que estava no momento da chamada Graphics::BeginContainer que retornou esse identificador específico. O bloco de informações colocado na pilha por essa chamada Graphics::BeginContainer é removido da pilha e todos os blocos de informações colocados nessa pilha depois dessa chamada Graphics::BeginContainer também são removidos.

As chamadas para o método Graphics::Save colocam blocos de informações na mesma pilha que as chamadas para o método Graphics::BeginContainer . Assim como uma chamada Graphics::EndContainer é emparelhada com uma chamada Graphics::BeginContainer , uma chamada Graphics::Restore é emparelhada com uma chamada Graphics::Save .

Cuidado Quando você chama Graphics::EndContainer, todos os blocos de informações colocados na pilha (por Graphics::Save ou por Graphics::BeginContainer) após a chamada correspondente para Graphics::BeginContainer são removidos da pilha. Da mesma forma, quando você chama Graphics::Restore, todos os blocos de informações colocados na pilha (por Graphics::Save ou por Graphics::BeginContainer) após a chamada correspondente para Graphics::Save são removidos da pilha.

Para obter mais informações sobre contêineres de elementos gráficos, consulte Contêineres de Elementos Gráficos Aninhados.

Exemplos

O exemplo a seguir define uma região de recorte para um objeto Graphics e inicia um contêiner de gráficos. Em seguida, ele define uma região de recorte adicional para o contêiner e desenha retângulos que demonstram a região de recorte eficaz dentro do contêiner.

VOID Example_BeginContainer(HDC hdc)
{
   Graphics graphics(hdc);

   // Set the clipping region for the Graphics object.
   graphics.SetClip(Rect(10, 10, 150, 150));

   // Begin a graphics container.
   GraphicsContainer container = graphics.BeginContainer();

   // Set an additional clipping region for the container.
   graphics.SetClip(Rect(100, 50, 100, 75));

   // Fill a red rectangle in the container.
   SolidBrush redBrush(Color(255, 255, 0, 0));
   graphics.FillRectangle(&redBrush, 0, 0, 400, 400);

   // End the container, and fill the same rectangle with blue. 
   graphics.EndContainer(container);
   SolidBrush blueBrush(Color(128, 0, 0, 255));
   graphics.FillRectangle(&blueBrush, 0, 0, 400, 400);

   // Set the clipping region to infinite, and draw the outlines 
   // of the two previous clipping regions.
   graphics.ResetClip();
   Pen blackPen(Color(255, 0, 0, 0), 2.0f);
   graphics.DrawRectangle(&blackPen, 10, 10, 150, 150);
   graphics.DrawRectangle(&blackPen, 100, 50, 100, 75);
}