David Alm: Automated Syncronization with Documentation

2012-10-18T17:19:06Z

Automated Syncronization with Documentation

New page

This is a Beta Read Only version of this page.
Please review and send recommendations to [mailto:mitov@mitov.com mitov@mitov.com].
We will enable the editing as soon as we are happy with the overall Wiki site.


'''Class:''' [[Interface IGDIPlus.IGPGraphics|IGPGraphics]]

== Syntax ==
=== Delphi: ===
<code>
'''function''' Restore( gstate : TGPGraphicsState ) : [[Class IGDIPlus.TGPGraphics|TGPGraphics]];
</code>

=== C++ Builder: ===
<code>
[[Class IGDIPlus.TGPGraphics|TGPGraphics]] '''__fastcall''' Restore( TGPGraphicsState gstate );
</code>

=== Visual C++ (MFC): ===
<code>
Restore( gstate );
</code>

== Summary ==
Sets the state of this [[Class IGDIPlus.TGPGraphics|TGPGraphics]] object to the state stored by a previous call to the [[Class IGDIPlus.TGPGraphics|TGPGraphics]].[[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|Save]] method of this [[Class IGDIPlus.TGPGraphics|TGPGraphics]] object.

== Description ==
Call this method to set the state of this [[Class IGDIPlus.TGPGraphics|TGPGraphics]] object
to the state stored by a previous call to the
[[Class IGDIPlus.TGPGraphics|TGPGraphics]].[[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|Save]] method of this Graphics object.

Examples:

The following examples show two ways to use the [[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|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 [[Method function IGDIPlus.IGPGraphics.TranslateTransform(Single;Single;TGPMatrixOrder) : TGPGraphics|TranslateTransform]], and
saves the state again. Then the code calls [[Method function IGDIPlus.IGPGraphics.ScaleTransform(Single;Single;TGPMatrixOrder) : TGPGraphics|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 [[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|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 [[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|Save]], to the Restore
method, and draws the ellipse again using a blue pen. The
blue ellipse is rotated but not translated or scaled.

<code>
var
AGraphics : [[Interface IGDIPlus.IGPGraphics|IGPGraphics]];
AState1, AState2 : IGPGraphicsState;

begin
AGraphics := [[Class IGDIPlus.TGPGraphics|TGPGraphics]].Create( ACanvas );

AGraphics.[[Method function IGDIPlus.IGPGraphics.RotateTransform(Single;TGPMatrixOrder) : TGPGraphics|RotateTransform]](30.0);
AState1 = graphics.[[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|Save]]();
AGraphics.[[Method function IGDIPlus.IGPGraphics.TranslateTransform(Single;Single;TGPMatrixOrder) : TGPGraphics|TranslateTransform]](100.0, 0.0, [[Enum item IGDIPlus.TGPMatrixOrder.MatrixOrderAppend|MatrixOrderAppend]]);
AState2 = graphics.[[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|Save]]();
AGraphics.[[Method function IGDIPlus.IGPGraphics.ScaleTransform(Single;Single;TGPMatrixOrder) : TGPGraphics|ScaleTransform]](1.0, 3.0, [[Enum item IGDIPlus.TGPMatrixOrder.MatrixOrderAppend|MatrixOrderAppend]]);

// Draw an ellipse.
// Three transformations apply: rotate, then translate, then scale.
AGraphics.[[Method function IGDIPlus.IGPGraphics.DrawEllipse(IGPPen;TGPRect) : TGPGraphics|DrawEllipse]]([[Class IGDIPlus.TGPPen|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.[[Method function IGDIPlus.IGPGraphics.DrawEllipse(IGPPen;TGPRect) : TGPGraphics|DrawEllipse]]([[Class IGDIPlus.TGPPen|TGPPen]].Create( aclGreen ), 0, 0, 100, 20);

// Restore to AState1 and draw the ellipse again.
// Only the rotation transformation applies.
AGraphics.Restore(AState1);
AGraphics.[[Method function IGDIPlus.IGPGraphics.DrawEllipse(IGPPen;TGPRect) : TGPGraphics|DrawEllipse]]( [[Class IGDIPlus.TGPPen|TGPPen]].Create( aclBlue ), 0, 0, 100, 20);
end;
</code>

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 [[Method function IGDIPlus.IGPGraphics.TranslateTransform(Single;Single;TGPMatrixOrder) : TGPGraphics|TranslateTransform]], and
saves the state again. Then the code calls [[Method function IGDIPlus.IGPGraphics.ScaleTransform(Single;Single;TGPMatrixOrder) : TGPGraphics|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 [[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|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.

<code>
var
AGraphics : [[Interface IGDIPlus.IGPGraphics|IGPGraphics]];
AState1, AState2 : IGPGraphicsState;

begin
AGraphics := [[Class IGDIPlus.TGPGraphics|TGPGraphics]].Create( ACanvas );

AGraphics.[[Method function IGDIPlus.IGPGraphics.RotateTransform(Single;TGPMatrixOrder) : TGPGraphics|RotateTransform]](30.0);
AState1 = graphics.[[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|Save]]();
AGraphics.[[Method function IGDIPlus.IGPGraphics.TranslateTransform(Single;Single;TGPMatrixOrder) : TGPGraphics|TranslateTransform]](100.0, 0.0, [[Enum item IGDIPlus.TGPMatrixOrder.MatrixOrderAppend|MatrixOrderAppend]]);
AState2 = graphics.[[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|Save]]();
AGraphics.[[Method function IGDIPlus.IGPGraphics.ScaleTransform(Single;Single;TGPMatrixOrder) : TGPGraphics|ScaleTransform]](1.0, 3.0, [[Enum item IGDIPlus.TGPMatrixOrder.MatrixOrderAppend|MatrixOrderAppend]]);

// Draw an ellipse.
// Three transformations apply: rotate, then translate, then scale.
AGraphics.[[Method function IGDIPlus.IGPGraphics.DrawEllipse(IGPPen;TGPRect) : TGPGraphics|DrawEllipse]]([[Class IGDIPlus.TGPPen|TGPPen]].Create( aclRed ), 0, 0, 100, 20 );

// Restore to AState1 and draw the ellipse again.
// Only the rotation transformation applies.
AGraphics.Restore(AState1);
AGraphics.[[Method function IGDIPlus.IGPGraphics.DrawEllipse(IGPPen;TGPRect) : TGPGraphics|DrawEllipse]]([[Class IGDIPlus.TGPPen|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.[[Method function IGDIPlus.IGPGraphics.DrawEllipse(IGPPen;TGPRect) : TGPGraphics|DrawEllipse]]([[Class IGDIPlus.TGPPen|TGPPen]].Create( aclBlue ), 0, 0, 100, 20 );
</code>
Remarks
When you call the [[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|Save]] method of a Graphics object, an
information block that holds the state of the Graphics object
is put on a stack. The Graphics::[[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|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
[[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|Save]] call. Note that the identifier returned by a given call
to the [[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|Save]] method can be passed only once to the Restore
method.

Calls to the [[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|Save]] method can be nested; that is, you can call
the [[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|Save]] method several times before you call the Restore
method. Each time you call the [[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|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 [[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|Save]] call that returned
that particular identifier. The information block placed on
the stack by that [[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|Save]] call is removed from the stack, and
all information blocks placed on that stack after that [[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|Save]]
call are also removed.

Calls to the [[Method function IGDIPlus.IGPGraphics.BeginContainer(TGPRect;TGPRect;TGPUnit) : TGPGraphicsContainer|BeginContainer]] method place information blocks
on the same stack as calls to the [[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|Save]] method. Just as a
Restore call is paired with a [[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|Save]] call, an [[Method function IGDIPlus.IGPGraphics.EndContainer(TGPGraphicsContainer) : TGPGraphics|EndContainer]] call
is paired with a [[Method function IGDIPlus.IGPGraphics.BeginContainer(TGPRect;TGPRect;TGPUnit) : TGPGraphicsContainer|BeginContainer]] call.

Note When you call Restore, all information blocks placed on
the stack (by [[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|Save]] or by [[Method function IGDIPlus.IGPGraphics.BeginContainer(TGPRect;TGPRect;TGPUnit) : TGPGraphicsContainer|BeginContainer]]) after the
corresponding call to [[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|Save]] are removed from the stack.
Likewise, When you call [[Method function IGDIPlus.IGPGraphics.EndContainer(TGPGraphicsContainer) : TGPGraphics|EndContainer]], all information blocks
placed on the stack (by [[Method function IGDIPlus.IGPGraphics.Save() : TGPGraphicsState|Save]] or by [[Method function IGDIPlus.IGPGraphics.BeginContainer(TGPRect;TGPRect;TGPUnit) : TGPGraphicsContainer|BeginContainer]]) after the
corresponding call to [[Method function IGDIPlus.IGPGraphics.BeginContainer(TGPRect;TGPRect;TGPUnit) : TGPGraphicsContainer|BeginContainer]] are removed from the
stack.

Method function IGDIPlus.IGPGraphics.Restore(TGPGraphicsState) : TGPGraphics - Revision history

David Alm: Automated Syncronization with Documentation