This documentation is archived and is not being maintained.

Graphics.EndContainer Method

Closes the current graphics container and restores the state of this Graphics object to the state saved by a call to the BeginContainer method.

[Visual Basic]
Public Sub EndContainer( _
   ByVal container As GraphicsContainer _
)
[C#]
public void EndContainer(
 GraphicsContainer container
);
[C++]
public: void EndContainer(
 GraphicsContainer* container
);
[JScript]
public function EndContainer(
   container : GraphicsContainer
);

Parameters

container
GraphicsContainer object that represents the container this method restores.

Return Value

This method does not return a value.

Remarks

Use this method with the BeginContainer method to create nested graphics containers. Graphics containers retain graphics state, such as transformation, clipping region, and rendering properties.

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 GraphicsContainer object that identifies that information block. When you pass the identifying object 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 method 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 a GraphicsContainer object for the information block. When you pass one of those objects to the EndContainer method, the Graphics object is returned to the state it was in at the time of the BeginContainer method call that returned that particular GraphicsContainer object. The information block placed on the stack by that BeginContainer method call is removed from the stack, and all information blocks placed on that stack after that BeginContainer method call are also removed.

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

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

Example

[Visual Basic, C#] The following example is designed for use with Windows Forms, and it requires PaintEventArgs e, which is a parameter of the Paint event handler. The code performs the following actions:

  • Opens a new graphics container and saves the old container.
  • Translates the world coordinates in the container.
  • Fills a red rectangle in the (translated coordinates of the) new container.
  • Closes the new container and restores the saved container.
  • Fills a green rectangle (to the untranslated coordinates) of the saved container.

[Visual Basic, C#] The result is a green rectangle that overlies a red rectangle of the same size.

[Visual Basic] 
Public Sub EndContainerState(e As PaintEventArgs)
' Begin graphics container.
Dim containerState As GraphicsContainer = _
e.Graphics.BeginContainer()
' Translate world transformation.
e.Graphics.TranslateTransform(100F, 100F)
' Fill translated rectangle in container with red.
e.Graphics.FillRectangle(New SolidBrush(Color.Red), 0, 0, _
200, 200)
' End graphics container.
e.Graphics.EndContainer(containerState)
' Fill untransformed rectangle with green.
e.Graphics.FillRectangle(New SolidBrush(Color.Green), 0, 0, _
200, 200)
End Sub
        
[C#] 
public void EndContainerState(PaintEventArgs e)
{
// Begin graphics container.
GraphicsContainer containerState = e.Graphics.BeginContainer();
// Translate world transformation.
e.Graphics.TranslateTransform(100.0F, 100.0F);
// Fill translated rectangle in container with red.
e.Graphics.FillRectangle(new SolidBrush(Color.Red), 0, 0, 200, 200);
// End graphics container.
e.Graphics.EndContainer(containerState);
// Fill untransformed rectangle with green.
e.Graphics.FillRectangle(new SolidBrush(Color.Green), 0, 0, 200, 200);
}
        

[C++, JScript] No example is available for C++ or JScript. To view a Visual Basic or C# example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family

See Also

Graphics Class | Graphics Members | System.Drawing Namespace

Show: