Метод Graphics::Restore (gdiplusgraphics.h)

Статья
08/24/2023

Метод Graphics::Restore устанавливает состояние этого объекта Graphics в состояние, сохраненное при предыдущем вызове метода Graphics::Save этого объекта Graphics .

Синтаксис

Status Restore(
  [in] GraphicsState gstate
);

Параметры

[in] gstate

Тип: GraphicsState

32-разрядное значение (возвращаемое предыдущим вызовом метода Graphics::Save этого объекта Graphics ), определяющее блок сохраненного состояния.

Возвращаемое значение

Тип: Состояние

В случае успешного выполнения метода возвращается ОК, который является элементом перечисления Status .

Если метод завершается ошибкой, он возвращает один из других элементов перечисления Status .

При вызове метода Graphics::Save объекта Graphics информационный блок, содержащий состояние объекта Graphics , помещается в стек. Метод Graphics::Save возвращает значение, определяющее этот информационный блок. При передаче идентифицирующие значения методу Restore информационный блок удаляется из стека и используется для восстановления объекта Graphics до состояния, в которое он находился на момент вызова Graphics::Save . Обратите внимание, что идентификатор, возвращенный заданным вызовом метода Graphics::Save , можно передать методу Graphics::Restore только один раз.

Вызовы метода Graphics::Save могут быть вложенными; то есть метод Graphics::Save можно вызвать несколько раз перед вызовом метода Graphics::Restore . При каждом вызове метода Graphics::Save в стек помещается информационный блок, и вы получаете идентификатор блока сведений. При передаче одного из этих идентификаторов в метод Graphics::Restore объект Graphics возвращается в состояние, в которое он находился на момент вызова Graphics::Save , который вернул этот идентификатор. Блок сведений, размещенный в стеке вызовом Graphics::Save , удаляется из стека, а все информационные блоки, размещенные в этом стеке после вызова Graphics::Save , также удаляются.

Вызовы метода BeginContainer помещают информационные блоки в тот же стек, что и вызовы метода Graphics::Save . Так же, как вызов Graphics::Restore связан с вызовом Graphics::Save , вызов EndContainer связан с вызовом BeginContainer .

Примечание При вызове Graphics::Restore все информационные блоки, размещенные в стеке (с помощью Graphics::Save или BeginContainer) после соответствующего вызова Graphics::Save , удаляются из стека. Аналогичным образом, при вызове EndContainer все информационные блоки, размещенные в стеке (с помощью Graphics::Save или BeginContainer) после соответствующего вызова BeginContainer , удаляются из стека.

Примеры

В следующих примерах показаны два способа использования метода Graphics::Restore . В первом примере показано, как восстановить вложенные сохраненные состояния, а во втором примере показано, как восстановить только первое из двух вложенных сохраненных состояний.

Восстановление вложенных сохраненных состояний

В следующем примере для преобразования мира объекта Graphics задается поворот, а затем сохраняется состояние объекта Graphics . Затем код вызывает TranslateTransform и сохраняет состояние снова. Затем код вызывает ScaleTransform. На этом этапе преобразование мира объекта Graphics является составным преобразованием: сначала вращайте, затем преобразуйте, а затем масштабируйте. Код использует красное перо для рисования эллипса, преобразованного этим составным преобразованием.

Код передает состояние 2, возвращенное вторым вызовом команды Save, в метод Graphics::Restore и снова рисует многоточие с помощью зеленого пера. Зеленый эллипс поворачивается и преобразуется, но не масштабируется. Наконец, код передает состояние state1, которое было возвращено первым вызовом Save, методу Graphics::Restore и снова рисует многоточие с помощью синего пера. Синий эллипс поворачивается, но не преобразуется или масштабируется.

VOID Example_Save1(HDC hdc)
{
   Graphics graphics(hdc);
   GraphicsState state1, state2;

   graphics.RotateTransform(30.0f);
   state1 = graphics.Save();
   graphics.TranslateTransform(100.0f, 0.0f, MatrixOrderAppend);
   state2 = graphics.Save();
   graphics.ScaleTransform(1.0f, 3.0f, MatrixOrderAppend);
   
   // Draw an ellipse. 
   // Three transformations apply: rotate, then translate, then scale.
   Pen redPen(Color(255, 255, 0, 0));
   graphics.DrawEllipse(&redPen, 0, 0, 100, 20);
 
   // Restore to state2 and draw the ellipse again. 
   // Two transformations apply: rotate then translate.
   graphics.Restore(state2);
   Pen greenPen(Color(255, 0, 255, 0));
   graphics.DrawEllipse(&greenPen, 0, 0, 100, 20);

   // Restore to state1 and draw the ellipse again. 
   // Only the rotation transformation applies.
   graphics.Restore(state1);
   Pen bluePen(Color(255, 0, 0, 255));
   graphics.DrawEllipse(&bluePen, 0, 0, 100, 20);
}

Восстановление только первого из двух вложенных сохраненных состояний

Код передает состояние state1, которое было возвращено первым вызовом команды Save, методу Graphics::Restore и рисует многоточие снова с помощью зеленого пера. Зеленый эллипс поворачивается, но не преобразуется или масштабируется.

Затем код пытается восстановить состояние, определенное состоянием state2. Попытка завершается ошибкой, так как вызов Restore(state1) удалил из стека блоки сведений, определяемые как state1 , так и state2 .

VOID Example_Save2(HDC hdc)
{
   Graphics graphics(hdc);
   GraphicsState state1, state2;

   graphics.RotateTransform(30.0f);
   state1 = graphics.Save();
   graphics.TranslateTransform(100.0f, 0.0f, MatrixOrderAppend);
   state2 = graphics.Save();
   graphics.ScaleTransform(1.0f, 3.0f, MatrixOrderAppend);
   
   // Draw an ellipse. 
   // Three transformations apply: rotate, then translate, then scale.
   Pen redPen(Color(255, 255, 0, 0));
   graphics.DrawEllipse(&redPen, 0, 0, 100, 20);
 
   // Restore to state1 and draw the ellipse again. 
   // Only the rotation transformation applies.
   graphics.Restore(state1);
   Pen greenPen(Color(255, 0, 255, 0));
   graphics.DrawEllipse(&greenPen, 0, 0, 100, 20);

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

   // 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.
   Pen bluePen(Color(255, 0, 0, 255));
   graphics.DrawEllipse(&bluePen, 0, 0, 100, 20);
}

Требования


Минимальная версия клиента	Windows XP, Windows 2000 Профессиональная [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	gdiplusgraphics.h (включая Gdiplus.h)
Библиотека	Gdiplus.lib
DLL	Gdiplus.dll

См. также раздел

Графика

Graphics::Save