Method function IGDIPlus.IGPGraphics.Restore(TGPGraphicsState) : TGPGraphics

From Mitov Wiki Doc
Revision as of 17:19, 18 October 2012 by David Alm (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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

Contents

Syntax

Delphi:

function Restore( gstate : TGPGraphicsState ) : TGPGraphics;

C++ Builder:

TGPGraphics __fastcall Restore( TGPGraphicsState gstate );

Visual C++ (MFC):

Restore(  gstate );

Summary

Sets the state of this TGPGraphics object to the state stored by a previous call to the TGPGraphics.Save method of this TGPGraphics object.

Description

Call this method to set the state of this TGPGraphics object to the state stored by a previous call to the TGPGraphics.Save method of this Graphics object.


Examples:

The following examples show two ways to use the Save method. The first example shows how to restore nested saved states, and the second example shows how to restore only the first of two nested saved states.

Restoring Nested Saved States

The following example sets the world transformation of a Graphics object to a rotation and then saves the state of the Graphics object. Next, the code calls TranslateTransform, and saves the state again. Then the code calls ScaleTransform. At that point, the world transformation of the Graphics object is a composite transformation: first rotate, then translate, then scale. The code uses a red pen to draw an ellipse that is transformed by that composite transformation.


The code passes state2, which was returned by the second call to Save, to the Restore method, and draws the ellipse again using a green pen. The green ellipse is rotated and translated but not scaled. Finally the code passes state1, which was returned by the first call to Save, to the Restore method, and draws the ellipse again using a blue pen. The blue ellipse is rotated but not translated or scaled.

var
  AGraphics : IGPGraphics;
  AState1, AState2 : IGPGraphicsState;

begin
  AGraphics := TGPGraphics.Create( ACanvas );

  AGraphics.RotateTransform(30.0);
  AState1 = graphics.Save();
  AGraphics.TranslateTransform(100.0, 0.0, MatrixOrderAppend);
  AState2 = graphics.Save();
  AGraphics.ScaleTransform(1.0, 3.0, MatrixOrderAppend);

  // Draw an ellipse.
  // Three transformations apply: rotate, then translate, then scale.
  AGraphics.DrawEllipse(TGPPen.Create( aclRed ), 0, 0, 100, 20);

  // Restore to AState2 and draw the ellipse again.
  // Two transformations apply: rotate then translate.
  AGraphics.Restore(AState2);
  AGraphics.DrawEllipse(TGPPen.Create( aclGreen ), 0, 0, 100, 20);

  // Restore to AState1 and draw the ellipse again.
  // Only the rotation transformation applies.
  AGraphics.Restore(AState1);
  AGraphics.DrawEllipse( TGPPen.Create( aclBlue ), 0, 0, 100, 20);
end;

Restoring Only the First of Two Nested Saved States

The following example sets the world transformation of a Graphics object to a rotation and then saves the state of the Graphics object. Next, the code calls TranslateTransform, and saves the state again. Then the code calls ScaleTransform. At that point, the world transformation of the Graphics object is a composite transformation: first rotate, then translate, then scale. The code uses a red pen to draw an ellipse that is transformed by that composite transformation.


The code passes state1, which was returned by the first call to Save, to the Restore method, and draws the ellipse again using a green pen. The green ellipse is rotated but not translated or scaled.


Next the code attempts to restore the state identified by state2. The attempt fails because the call Restore(state1) removed the information blocks identified by both state1 and state2 from the stack.

var
  AGraphics : IGPGraphics;
  AState1, AState2 : IGPGraphicsState;

begin
  AGraphics := TGPGraphics.Create( ACanvas );

  AGraphics.RotateTransform(30.0);
  AState1 = graphics.Save();
  AGraphics.TranslateTransform(100.0, 0.0, MatrixOrderAppend);
  AState2 = graphics.Save();
  AGraphics.ScaleTransform(1.0, 3.0, MatrixOrderAppend);

  // Draw an ellipse.
  // Three transformations apply: rotate, then translate, then scale.
  AGraphics.DrawEllipse(TGPPen.Create( aclRed ), 0, 0, 100, 20 );

  // Restore to AState1 and draw the ellipse again.
  // Only the rotation transformation applies.
  AGraphics.Restore(AState1);
  AGraphics.DrawEllipse(TGPPen.Create( aclGreen ), 0, 0, 100, 20 );

  // The information block identified by AState2 has been lost.
  // The following call to Restore has no effect because
  // Restore(AState1) removed from the stack the
  // information blocks identified by AState1 and AState2.
  AGraphics.Restore(AState2);

  // The Graphics object is still in the state identified by state1.
  // The following code draws a blue ellipse on top of the previously
  // drawn green ellipse.
  AGraphics.DrawEllipse(TGPPen.Create( aclBlue ), 0, 0, 100, 20 );

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 Graphics::Save method returns a value that identifies that information block. When you pass the identifying value to the 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 call. Note that the identifier 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 an identifier for the information block. When you pass one of those identifiers to the Restore method, the Graphics object is returned to the state it was in at the time of the Save call that returned that particular identifier. The information block placed on the stack by that Save call is removed from the stack, and all information blocks placed on that stack after that Save 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, an EndContainer call is paired with a BeginContainer call.


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

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox