Method function IGDIPlus.IGPGraphics.EndContainer(TGPGraphicsContainer) : TGPGraphics

This is a Beta Read Only version of this page. Please review and send recommendations to mitov@mitov.com. We will enable the editing as soon as we are happy with the overall Wiki site.

Class: IGPGraphics

Syntax

Delphi:

function EndContainer( state : TGPGraphicsContainer ) : TGPGraphics;

C++ Builder:

TGPGraphics __fastcall EndContainer( TGPGraphicsContainer state );

Visual C++ (MFC):

EndContainer(  state );

Summary

Closes a graphics container that was previously opened by the BeginContainer method.

Description

Call this method to close a graphics container that was previously opened by the BeginContainer method.

Example:

The following example sets a clipping region for a Graphics object and begins a graphics container. It then sets an additional clipping region for the container and draws rectangles that demonstrate the effective clipping region inside the container.

var
  AGraphics : IGPGraphics;
  APath : GraphicsPath ;
  ABlackPen : IGPPen;
  AContainer : IGPGraphicsContainer;

begin
  AGraphics := TGPGraphics.Create( ACanvas );

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

  // Begin a graphics container.
  AContainer = AGraphics.BeginContainer();

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

  // Fill a red rectangle in the container.
  AGraphics.FillRectangle( TGPSolidBrush.Create( aclRed ), 0, 0, 400, 400);

  // End the container, and fill the same rectangle with blue.
  graphics.EndContainer( AContainer );
  AGraphics.FillRectangle( TGPSolidBrush.Create( aclBlue ), 0, 0, 400, 400);

  // Set the clipping region to infinite, and draw the outlines
  // of the two previous clipping regions.
  AGraphics.ResetClip();
  ABlack := TGPPen.Create( aclBlack, 2.0 );
  AGraphics.DrawRectangle( ABlack, 10, 10, 150, 150 );
  AGraphics.DrawRectangle( ABlack, 100, 50, 100, 75 );
end;

Remarks When you call the BeginContainer method of a Graphics object, an information block that holds the state of the Graphics object is put on a stack. The BeginContainer method returns a value that identifies that information block. When you pass the identifying value to the EndContainer method, the information block is removed from the stack and is used to restore the Graphics object to the state it was in at the time of the BeginContainer call.

Containers can be nested; that is, you can call the BeginContainer method several times before you call the EndContainer method. Each time you call the BeginContainer method, an information block is put on the stack, and you receive an identifier for the information block. When you pass one of those identifiers to the EndContainer method, the Graphics object is returned to the state it was in at the time of the BeginContainer call that returned that particular identifier. The information block placed on the stack by that BeginContainer call is removed from the stack, and all information blocks placed on that stack after that BeginContainer call are also removed.

Calls to the Save method place information blocks on the same stack as calls to the BeginContainer method. Just as an EndContainer call is paired with a BeginContainer call, a Restore call is paired with a Save call.

Caution When you call EndContainer, all information blocks placed on the stack (by Save or by BeginContainer) after the corresponding call to BeginContainer are removed from the stack. Likewise, when you call Restore, all information blocks placed on the stack (by Save or by BeginContainer) after the corresponding call to Save are removed from the stack.