Método Graphics::BeginContainer(constRect&,constRect&,Unit) (gdiplusgraphics.h)

Artigo
01/10/2024

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

Sintaxe

GraphicsContainer BeginContainer(
  [in, ref] const Rect & dstrect,
  [in, ref] const Rect & srcrect,
  [in]      Unit         unit
);

Parâmetros

[in, ref] dstrect

Tipo: const Rect

Referência a um retângulo que, junto com srcrect, especifica uma transformação para o contêiner.

[in, ref] srcrect

Tipo: const Rect

Referência a um retângulo que, juntamente com dstrect, especifica uma transformação para o contêiner.

[in] unit

Tipo: Unidade

Unidade de medida para o contêiner.

Retornar valor

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.

Os parâmetros dstrect e srcrect especificam uma transformação. É a transformação que, quando aplicada a srcrect, resulta em dstrect.

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 chama o método Graphics::BeginContainer para criar um contêiner de gráficos. O código especifica uma transformação para o contêiner passando dois retângulos para o método Graphics::BeginContainer . O código chama Graphics::FillEllipse duas vezes: uma vez dentro do contêiner e uma vez fora do contêiner (após a chamada para Graphics::EndContainer).

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

   // Define a translation and scale transformation for the container.
   Rect srcRect(0, 0, 200, 100);
   Rect destRect(100, 100, 200, 200);

   // Create a graphics container with a (100, 100) translation 
   // and (1, 2) scale.
   GraphicsContainer container;
   container = graphics.BeginContainer(destRect, srcRect, UnitPixel);

   // Fill an ellipse in the container.
   SolidBrush redBrush(Color(255, 255, 0, 0));
   graphics.FillEllipse(&redBrush, 0, 0, 100, 60);

   // End the container.
   graphics.EndContainer(container);

   // Fill the same ellipse outside the container.
   SolidBrush blueBrush(Color(255, 0, 0, 255));
   graphics.FillEllipse(&blueBrush, 0, 0, 100, 60);
}

Requisitos


Cliente mínimo com suporte	Windows XP, Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	gdiplusgraphics.h (inclua Gdiplus.h)
Biblioteca	Gdiplus.lib
DLL	Gdiplus.dll