Graphics.BeginContainer Method

Definition

Namespace:

System.Drawing

Assembly:

System.Drawing.Common.dll

Saves a graphics container with the current state of this Graphics and opens and uses a new graphics container.

Overloads

BeginContainer()	Saves a graphics container with the current state of this Graphics and opens and uses a new graphics container.
BeginContainer(Rectangle, Rectangle, GraphicsUnit)	Saves a graphics container with the current state of this Graphics and opens and uses a new graphics container with the specified scale transformation.
BeginContainer(RectangleF, RectangleF, GraphicsUnit)	Saves a graphics container with the current state of this Graphics and opens and uses a new graphics container with the specified scale transformation.

BeginContainer()

Saves a graphics container with the current state of this Graphics and opens and uses a new graphics container.

public:
 System::Drawing::Drawing2D::GraphicsContainer ^ BeginContainer();

public System.Drawing.Drawing2D.GraphicsContainer BeginContainer ();

member this.BeginContainer : unit -> System.Drawing.Drawing2D.GraphicsContainer

Public Function BeginContainer () As GraphicsContainer

Returns

GraphicsContainer

This method returns a GraphicsContainer that represents the state of this Graphics at the time of the method call.

Examples

The following code 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.

The result is a green rectangle that overlies a red rectangle of the same size.

private:
   void BeginContainerVoid( 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( gcnew SolidBrush( Color::Red ), 0, 0, 200, 200 );

      // End graphics container.
      e->Graphics->EndContainer( containerState );

      // Fill untransformed rectangle with green.
      e->Graphics->FillRectangle( gcnew SolidBrush( Color::Green ), 0, 0, 200, 200 );
   }

private void BeginContainerVoid(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);
}

Private Sub BeginContainerVoid(ByVal e As PaintEventArgs)

    ' Begin graphics container.
    Dim containerState As GraphicsContainer = _
    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)
End Sub

Remarks

Use this method with the EndContainer 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, an information block that holds the state of the Graphics is put on a stack. The BeginContainer method returns a GraphicsContainer 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 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 for the information block. When you pass one of those objects to the EndContainer method, the Graphics is returned to the state it was in at the time of the BeginContainer method call that returned that particular GraphicsContainer. 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 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 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.

The graphics state established by the BeginContainer method includes the rendering qualities of the default graphics state; any rendering-quality state changes existing when the method is called are reset to the default values.

BeginContainer(Rectangle, Rectangle, GraphicsUnit)

Saves a graphics container with the current state of this Graphics and opens and uses a new graphics container with the specified scale transformation.

public:
 System::Drawing::Drawing2D::GraphicsContainer ^ BeginContainer(System::Drawing::Rectangle dstrect, System::Drawing::Rectangle srcrect, System::Drawing::GraphicsUnit unit);

public System.Drawing.Drawing2D.GraphicsContainer BeginContainer (System.Drawing.Rectangle dstrect, System.Drawing.Rectangle srcrect, System.Drawing.GraphicsUnit unit);

member this.BeginContainer : System.Drawing.Rectangle * System.Drawing.Rectangle * System.Drawing.GraphicsUnit -> System.Drawing.Drawing2D.GraphicsContainer

Public Function BeginContainer (dstrect As Rectangle, srcrect As Rectangle, unit As GraphicsUnit) As GraphicsContainer

Parameters

dstrect

Rectangle

Rectangle structure that, together with the srcrect parameter, specifies a scale transformation for the container.

srcrect

Rectangle

Rectangle structure that, together with the dstrect parameter, specifies a scale transformation for the container.

unit

GraphicsUnit

Member of the GraphicsUnit enumeration that specifies the unit of measure for the container.

Returns

GraphicsContainer

This method returns a GraphicsContainer that represents the state of this Graphics at the time of the method call.

Examples

The following code 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:

• Creates two rectangles to specify a scale transformation for the new container.

• Opens the new graphics container and saves the old container.

• Fills a red rectangle in the (scaled coordinates of the) new container.

• Closes the new container and restores the saved container.

• Fills a green rectangle (to the unscaled coordinates) of the saved container.

The result is a green rectangle that overlies a smaller red rectangle.

private:
   void BeginContainerRectangle( PaintEventArgs^ e )
   {
      // Define transformation for container.
      Rectangle srcRect = Rectangle(0,0,200,200);
      Rectangle destRect = Rectangle(100,100,150,150);

      // Begin graphics container.
      GraphicsContainer^ containerState = e->Graphics->BeginContainer( destRect, srcRect, GraphicsUnit::Pixel );

      // Fill red rectangle in container.
      e->Graphics->FillRectangle( gcnew SolidBrush( Color::Red ), 0, 0, 200, 200 );

      // End graphics container.
      e->Graphics->EndContainer( containerState );

      // Fill untransformed rectangle with green.
      e->Graphics->FillRectangle( gcnew SolidBrush( Color::Green ), 0, 0, 200, 200 );
   }

private void BeginContainerRectangle(PaintEventArgs e)
{
    // Define transformation for container.
    Rectangle srcRect = new Rectangle(0, 0, 200, 200);
    Rectangle destRect = new Rectangle(100, 100, 150, 150);
             
    // Begin graphics container.
    GraphicsContainer containerState = e.Graphics.BeginContainer(
        destRect, srcRect,
        GraphicsUnit.Pixel);
             
    // Fill red rectangle in container.
    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);
}

Private Sub BeginContainerRectangle(ByVal e As PaintEventArgs)

    ' Define transformation for container.
    Dim srcRect As New Rectangle(0, 0, 200, 200)
    Dim destRect As New Rectangle(100, 100, 150, 150)

    ' Begin graphics container.
    Dim containerState As GraphicsContainer = _
    e.Graphics.BeginContainer(destRect, srcRect, GraphicsUnit.Pixel)

    ' Fill red rectangle in container.
    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

Remarks

Use this method with the EndContainer 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, an information block that holds the state of the Graphics is put on a stack. The BeginContainer method returns a GraphicsContainer 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 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 for the information block. When you pass one of those objects to the EndContainer method, the Graphics is returned to the state it was in at the time of the BeginContainer method call that returned that particular GraphicsContainer. 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 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 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.

This method specifies a scale transformation for the new graphics container with the dstrect and srcrect parameters. The scale is equal to the transformation that, when applied to srcrect, results in dstrect.

The graphics state established by the BeginContainer method includes the rendering qualities of the default graphics state; any rendering-quality state changes existing when the method is called are reset to the default values.

BeginContainer(RectangleF, RectangleF, GraphicsUnit)

Saves a graphics container with the current state of this Graphics and opens and uses a new graphics container with the specified scale transformation.

public:
 System::Drawing::Drawing2D::GraphicsContainer ^ BeginContainer(System::Drawing::RectangleF dstrect, System::Drawing::RectangleF srcrect, System::Drawing::GraphicsUnit unit);

public System.Drawing.Drawing2D.GraphicsContainer BeginContainer (System.Drawing.RectangleF dstrect, System.Drawing.RectangleF srcrect, System.Drawing.GraphicsUnit unit);

member this.BeginContainer : System.Drawing.RectangleF * System.Drawing.RectangleF * System.Drawing.GraphicsUnit -> System.Drawing.Drawing2D.GraphicsContainer

Public Function BeginContainer (dstrect As RectangleF, srcrect As RectangleF, unit As GraphicsUnit) As GraphicsContainer

Parameters

dstrect

RectangleF

RectangleF structure that, together with the srcrect parameter, specifies a scale transformation for the new graphics container.

srcrect

RectangleF

RectangleF structure that, together with the dstrect parameter, specifies a scale transformation for the new graphics container.

unit

GraphicsUnit

Member of the GraphicsUnit enumeration that specifies the unit of measure for the container.

Returns

GraphicsContainer

This method returns a GraphicsContainer that represents the state of this Graphics at the time of the method call.

Examples

The following code 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:

• Creates two rectangles to specify a scale transformation for the new container.

• Opens the new graphics container and saves the old container.

• Fills a red rectangle in the (scaled coordinates of the) new container.

• Closes the new container and restores the saved container.

• Fills a green rectangle (to the unscaled coordinates) of the saved container.

The result is a green rectangle that overlies a smaller red rectangle.

private:
   void BeginContainerRectangleF( PaintEventArgs^ e )
   {
      // Define transformation for container.
      RectangleF srcRect = RectangleF(0.0F,0.0F,200.0F,200.0F);
      RectangleF destRect = RectangleF(100.0F,100.0F,150.0F,150.0F);

      // Begin graphics container.
      GraphicsContainer^ containerState = e->Graphics->BeginContainer( destRect, srcRect, GraphicsUnit::Pixel );

      // Fill red rectangle in container.
      e->Graphics->FillRectangle( gcnew SolidBrush( Color::Red ), 0.0F, 0.0F, 200.0F, 200.0F );

      // End graphics container.
      e->Graphics->EndContainer( containerState );

      // Fill untransformed rectangle with green.
      e->Graphics->FillRectangle( gcnew SolidBrush( Color::Green ), 0.0F, 0.0F, 200.0F, 200.0F );
   }

private void BeginContainerRectangleF(PaintEventArgs e)
{
    // Define transformation for container.
    RectangleF srcRect = new RectangleF(0.0F, 0.0F, 200.0F, 200.0F);
    RectangleF destRect = new RectangleF(100.0F, 100.0F, 150.0F, 150.0F);
             
    // Begin graphics container.
    GraphicsContainer containerState = e.Graphics.BeginContainer(
        destRect, srcRect,
        GraphicsUnit.Pixel);
             
    // Fill red rectangle in container.
    e.Graphics.FillRectangle(new SolidBrush(Color.Red), 0.0F, 0.0F, 200.0F, 200.0F);
             
    // End graphics container.
    e.Graphics.EndContainer(containerState);
             
    // Fill untransformed rectangle with green.
    e.Graphics.FillRectangle(new SolidBrush(Color.Green), 0.0F, 0.0F, 200.0F, 200.0F);
}

Private Sub BeginContainerRectangleF(ByVal e As PaintEventArgs)

    ' Define transformation for container.
    Dim srcRect As New RectangleF(0.0F, 0.0F, 200.0F, 200.0F)
    Dim destRect As New RectangleF(100.0F, 100.0F, 150.0F, 150.0F)

    ' Begin graphics container.
    Dim containerState As GraphicsContainer = _
    e.Graphics.BeginContainer(destRect, srcRect, GraphicsUnit.Pixel)

    ' Fill red rectangle in container.
    e.Graphics.FillRectangle(New SolidBrush(Color.Red), 0.0F, 0.0F, _
    200.0F, 200.0F)

    ' End graphics container.
    e.Graphics.EndContainer(containerState)

    ' Fill untransformed rectangle with green.
    e.Graphics.FillRectangle(New SolidBrush(Color.Green), 0.0F, 0.0F, _
    200.0F, 200.0F)
End Sub

Remarks

Use this method with the EndContainer 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, an information block that holds the state of the Graphics is put on a stack. The BeginContainer method returns a GraphicsContainer 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 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 for the information block. When you pass one of those objects to the EndContainer method, the Graphics is returned to the state it was in at the time of the BeginContainer method call that returned that particular GraphicsContainer. 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 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 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.

This method specifies a scale transformation for the new graphics container with the dstrect and srcrect parameters. The scale is equal to the transformation that, when applied to srcrect, results in dstrect.

The graphics state established by the BeginContainer method includes the rendering qualities of the default graphics state; any rendering-quality state changes existing when the method is called are reset to the default values.