Graphics::BeginContainer

Article
08/24/2023

La méthode Graphics::BeginContainer démarre un nouveau conteneur de graphiques.

Syntaxe

GraphicsContainer BeginContainer();

Valeur de retour

Type : GraphicsContainer

Cette méthode retourne une valeur qui identifie le conteneur.

Notes

Utilisez cette méthode pour créer des conteneurs graphiques imbriqués. Les conteneurs graphiques sont utilisés pour conserver l’état des graphiques, tels que les transformations, les régions de découpage et diverses propriétés de rendu.

La méthode Graphics::BeginContainer retourne une valeur de type GraphicsContainer. Une fois que vous avez terminé d’utiliser un conteneur, transmettez cette valeur à la méthode Graphics::EndContainer . Le type de données GraphicsContainer est défini dans Gdiplusenums.h.

Lorsque vous appelez la méthode Graphics::BeginContainer d’un objet Graphics , un bloc d’informations qui contient l’état de l’objet Graphics est placé sur une pile. La méthode Graphics::BeginContainer retourne une valeur qui identifie ce bloc d’informations. Lorsque vous passez la valeur d’identification à la méthode Graphics::EndContainer , le bloc d’informations est supprimé de la pile et est utilisé pour restaurer l’objet Graphics à l’état dans lequel il se trouvait au moment de l’appel Graphics::BeginContainer .

Les conteneurs peuvent être imbriqués ; Autrement dit, vous pouvez appeler la méthode Graphics::BeginContainer plusieurs fois avant d’appeler la méthode Graphics::EndContainer . Chaque fois que vous appelez la méthode Graphics::BeginContainer , un bloc d’informations est placé sur la pile et vous recevez un identificateur pour le bloc d’informations. Lorsque vous passez l’un de ces identificateurs à la méthode Graphics::EndContainer , l’objet Graphics est retourné à l’état dans lequel il se trouvait au moment de l’appel Graphics::BeginContainer qui a retourné cet identificateur particulier. Le bloc d’informations placé sur la pile par cet appel Graphics::BeginContainer est supprimé de la pile, et tous les blocs d’informations placés sur cette pile après cet appel Graphics::BeginContainer sont également supprimés.

Les appels à la méthode Graphics::Save placent des blocs d’informations sur la même pile que les appels à la méthode Graphics::BeginContainer . Tout comme un appel Graphics::EndContainer est associé à un appel Graphics::BeginContainer , un appel Graphics::Restore est associé à un appel Graphics::Save .

Attention Lorsque vous appelez Graphics::EndContainer, tous les blocs d’informations placés sur la pile (par Graphics::Save ou par Graphics::BeginContainer) après l’appel correspondant à Graphics::BeginContainer sont supprimés de la pile. De même, lorsque vous appelez Graphics::Restore, tous les blocs d’informations placés sur la pile (par Graphics::Save ou par Graphics::BeginContainer) après l’appel correspondant à Graphics::Save sont supprimés de la pile.

Pour plus d’informations sur les conteneurs graphiques, consultez Conteneurs graphiques imbriqués.

Exemples

L’exemple suivant définit une zone de découpage pour un objet Graphics et commence un conteneur de graphiques. Il définit ensuite une zone de découpage supplémentaire pour le conteneur et dessine des rectangles qui illustrent la zone de découpage effective à l’intérieur du conteneur.

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);
}