CGpGraphics.BeginContainermethod

Begins a new graphics container.

Syntax

FUNCTION BeginContainer () AS GraphicsContainer

FUNCTION BeginContainer (BYVAL destrect AS GpRectF PTR, BYVAL srcrect AS GpRectF PTR, BYVAL nUnit AS GpUnit) AS GraphicsContainer

FUNCTION BeginContainer (BYVAL destrect AS GpRect PTR, BYVAL srcrect AS GpRect PTR, BYVAL nUnit AS GpUnit) AS GraphicsContainer

Parameters

Return value

This method returns a value that identifies the container.

Description

Begins a new graphics container.

Remarks

Use this method to create nested graphics containers. Graphics containers are used to retain graphics state, such as transformations, clipping regions, and various rendering properties.

The BeginContainer method returns a value of type GraphicsContainer. When you have finished using a container, pass that value to the EndContainer method. The GraphicsContainer data type is defined in Gdiplusenums.bi.

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.

For more information about graphics containers, see Nested Graphics Containers

Example

' ======================================================================================== ' This example demonstrates how to use GdipBeginContainer and GdipEndContainer ' to isolate transformations and rendering settings within a scoped graphics container. ' ======================================================================================== SUB Example_BeginContainer (BYVAL hdc AS HDC)

' // Create a graphics object from the window device context DIM graphics AS CGpGraphics = hdc ' // Set the scale transform graphics.ScaleTransformForDpi

' // Draw base rectangle (no transformation) DIM basePen AS CGpPen = CGpPen(ARGB_BLACK, 2) graphics.DrawRectangle(@basePen, 20, 20, 100, 50)

' // Begin container (save state) DIM container AS GraphicsContainer = graphics.BeginContainer()

' // Apply transformation inside container graphics.TranslateTransform(150, 0) graphics.RotateTransform(30, MatrixOrderAppend)

' // Draw transformed rectangle DIM redPen AS CGpPen = CGpPen(ARGB_RED, 2) graphics.DrawRectangle(@redPen, 20, 20, 100, 50)

' // End container (restores previous state) graphics.EndContainer(container)

' // Draw another rectangle (back to original state) DIM bluePen AS CGpPen = CGpPen(ARGB_BLUE, 2.0) graphics.DrawRectangle(@bluePen, 20, 90, 100, 50)

END SUB ' ========================================================================================

Reference

• Include file CGpGraphics.inc
• Defined in AfxNova/CGpGraphics.inc:1540
• Documented in Graphics/GdiPlus Classes/CGpGraphics Classes.md
• Topic: CGpGraphics Class