This documentation is archived and is not being maintained.

Graphics.Save Method

Saves the current state of this Graphics object and identifies the saved state with a GraphicsState object.

[Visual Basic]
Public Function Save() As GraphicsState
[C#]
public GraphicsState Save();
[C++]
public: GraphicsState* Save();
[JScript]
public function Save() : GraphicsState;

Return Value

This method returns a GraphicsState object that represents the saved state of this Graphics object.

Remarks

When you call the Save method of a Graphics object, an information block that holds the state of the Graphics object is put on a stack. The Save method returns a GraphicsState object that identifies that information block. When you pass the identifying GraphicsState object to the Graphics.Restore 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 Save method call. Note that the GraphicsState object returned by a given call to the Save method can be passed only once to the Restore method.

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

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

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. Likewise, 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.

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:

  • Translates the world transform of the Windows form by a vector (100, 0).
  • Saves the graphics state of the form.
  • Resets the world transform of the form to an identity (two by two identity matrix plus a zero-vector translation) and fills a rectangle with a solid red brush.
  • Restores the translated graphics state and fills a rectangle with a solid blue brush.

[Visual Basic, C#] The result is an untranslated red-filled rectangle on the left and a translated blue-filled rectangle on the right of the form.

[Visual Basic] 
Public Sub SaveRestore(e As PaintEventArgs)
' Translate transformation matrix.
e.Graphics.TranslateTransform(100, 0)
' Save translated graphics state.
Dim transState As GraphicsState = e.Graphics.Save()
' Reset transformation matrix to identity and fill rectangle.
e.Graphics.ResetTransform()
e.Graphics.FillRectangle(New SolidBrush(Color.Red), 0, 0, 100, 100)
' Restore graphics state to translated state and fill second
' rectangle.
e.Graphics.Restore(transState)
e.Graphics.FillRectangle(New SolidBrush(Color.Blue), 0, 0, _
100, 100)
End Sub
        
[C#] 
public void SaveRestore(PaintEventArgs e)
{
// Translate transformation matrix.
e.Graphics.TranslateTransform(100, 0);
// Save translated graphics state.
GraphicsState transState = e.Graphics.Save();
// Reset transformation matrix to identity and fill rectangle.
e.Graphics.ResetTransform();
e.Graphics.FillRectangle(new SolidBrush(Color.Red), 0, 0, 100, 100);
// Restore graphics state to translated state and fill second rectangle.
e.Graphics.Restore(transState);
e.Graphics.FillRectangle(new SolidBrush(Color.Blue), 0, 0, 100, 100);
}
        

[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: