DesignerTransaction Classe
Definição
Importante
Algumas informações se referem a produtos de pré-lançamento que podem ser substancialmente modificados antes do lançamento. A Microsoft não oferece garantias, expressas ou implícitas, das informações aqui fornecidas.
Fornece uma maneira de agrupar uma série de ações de tempo de design para melhorar o desempenho e habilitar a maioria dos tipos de alterações a serem desfeitas.
public ref class DesignerTransaction abstract : IDisposable
public abstract class DesignerTransaction : IDisposable
type DesignerTransaction = class
interface IDisposable
Public MustInherit Class DesignerTransaction
Implements IDisposable
- Herança
-
DesignerTransaction
- Implementações
Exemplos
O programa de exemplo de código a seguir demonstra como criar um DesignerTransaction de um designer. Para executar este exemplo, compile o código-fonte em uma biblioteca de classes. Você deve adicionar uma referência ao assembly System.Design. Em um novo projeto, adicione uma referência à DLL compilada e adicione o componente na biblioteca à Caixa de Ferramentas.
Há amplo suporte para esse recurso no Visual Studio.
Consulte também Passo a passo: preenchendo automaticamente a caixa de ferramentas com componentes personalizados.
Opcionalmente, o designer pode exibir notificações sobre eventos de transação do designer. Se você adicionar uma instância do a DTComponent
um formulário enquanto estiver no modo de design, uma caixa de mensagem será exibida perguntando se você gostaria de receber notificações de evento de transação do designer. Você pode alternar essas notificações usando o menu de atalho que aparece quando você clica com o botão direito do mouse em uma instância do DTComponent
. As transações são criadas quando você altera valores usando o janela Propriedades. Você também pode fazer com que o designer execute uma transação clicando em Executar Transação de Exemplo no menu de atalho do componente.
#using <system.dll>
#using <system.design.dll>
#using <system.windows.forms.dll>
using namespace System;
using namespace System::ComponentModel;
using namespace System::ComponentModel::Design;
using namespace System::Windows::Forms;
using namespace System::Windows::Forms::Design;
/*
This sample demonstrates how to perform a series of actions in a designer
transaction, how to change values of properties of a component from a
designer, and how to complete transactions without being interrupted
by other activities.
To run this sample, add this code to a class library project and compile.
Create a new Windows Forms project or load a form in the designer. Add a
reference to the class library that was compiled in the first step.
Right-click the Toolbox in design mode and click Customize Toolbox.
Browse to the class library that was compiled in the first step and
select OK until the DTComponent item appears in the Toolbox. Add an
instance of this component to the form.
When the component is created and added to the component tray for your
design project, the Initialize method of the designer is called.
This method displays a message box informing you that designer transaction
event handlers will be registered unless you click Cancel. When you set
properties in the properties window, each change will be encapsulated in
a designer transaction, allowing the change to be undone later.
When you right-click the component, the shortcut menu for the component
is displayed. The designer constructs this menu according to whether
designer transaction notifications are enabled, and offers the option
of enabling or disabling the notifications, depending on the current
mode. The shortcut menu also presents a Perform Example Transaction
item, which will set the values of the component's StringProperty and
CountProperty properties. You can undo the last designer transaction using
the Undo command provided by the Visual Studio development environment.
*/
private ref class DTDesigner: public ComponentDesigner
{
private:
bool notification_mode;
int count;
void LinkDTNotifications( Object^ /*sender*/, EventArgs^ /*e*/ )
{
if ( !notification_mode )
{
IDesignerHost^ host = dynamic_cast<IDesignerHost^>(GetService( IDesignerHost::typeid ));
if ( host != nullptr )
{
notification_mode = true;
host->TransactionOpened += gcnew EventHandler( this, &DTDesigner::OnDesignerTransactionOpened );
host->TransactionClosed += gcnew DesignerTransactionCloseEventHandler( this, &DTDesigner::OnDesignerTransactionClosed );
}
}
}
void UnlinkDTNotifications( Object^ /*sender*/, EventArgs^ /*e*/ )
{
if ( notification_mode )
{
IDesignerHost^ host = dynamic_cast<IDesignerHost^>(GetService( IDesignerHost::typeid ));
if ( host != nullptr )
{
notification_mode = false;
host->TransactionOpened -= gcnew EventHandler( this, &DTDesigner::OnDesignerTransactionOpened );
host->TransactionClosed -= gcnew DesignerTransactionCloseEventHandler( this, &DTDesigner::OnDesignerTransactionClosed );
}
}
}
void OnDesignerTransactionOpened( Object^ /*sender*/, EventArgs^ /*e*/ )
{
MessageBox::Show( "A Designer Transaction was started. (TransactionOpened)" );
}
void OnDesignerTransactionClosed( Object^ /*sender*/, DesignerTransactionCloseEventArgs^ /*e*/ )
{
MessageBox::Show( "A Designer Transaction was completed. (TransactionClosed)" );
}
void DoTransaction( Object^ /*sender*/, EventArgs^ /*e*/ )
{
IDesignerHost^ host = static_cast<IDesignerHost^>(GetService( IDesignerHost::typeid ));
DesignerTransaction^ t = host->CreateTransaction( "Change Text and Size" );
/* The code within the using statement is considered to be a single transaction.
When the user selects Undo, the system will undo everything executed in this code block.
*/
if ( notification_mode )
MessageBox::Show( "Entering a Designer-Initiated Designer Transaction" );
// The .NET Framework automatically associates the TypeDescriptor with the correct component
PropertyDescriptor^ someText = TypeDescriptor::GetProperties( Component )[ "StringProperty" ];
someText->SetValue( Component, "This text was set by the designer for this component." );
PropertyDescriptor^ anInteger = TypeDescriptor::GetProperties( Component )[ "CountProperty" ];
anInteger->SetValue( Component, count );
count++;
// Complete the designer transaction.
t->Commit();
if ( notification_mode )
MessageBox::Show( "Designer-Initiated Designer Transaction Completed" );
}
public:
property DesignerVerbCollection^ Verbs
{
// The Verbs property is overridden from ComponentDesigner
virtual DesignerVerbCollection^ get() override
{
DesignerVerbCollection^ dvc = gcnew DesignerVerbCollection;
dvc->Add( gcnew DesignerVerb( "Perform Example Transaction",gcnew EventHandler( this, &DTDesigner::DoTransaction ) ) );
if ( notification_mode )
dvc->Add( gcnew DesignerVerb( "End Designer Transaction Notifications",
gcnew EventHandler( this, &DTDesigner::UnlinkDTNotifications ) ) );
else
dvc->Add( gcnew DesignerVerb( "Show Designer Transaction Notifications",
gcnew EventHandler( this, &DTDesigner::LinkDTNotifications ) ) );
return dvc;
}
}
virtual void Initialize( IComponent^ component ) override
{
ComponentDesigner::Initialize( component );
notification_mode = false;
count = 10;
IDesignerHost^ host = dynamic_cast<IDesignerHost^>(GetService( IDesignerHost::typeid ));
if ( host == nullptr )
{
MessageBox::Show( "The IDesignerHost service interface could not be obtained." );
return;
}
if ( MessageBox::Show( "Press the Yes button to display notification message boxes for the designer transaction opened and closed notifications.", "Link DesignerTransaction Notifications?", MessageBoxButtons::YesNo, MessageBoxIcon::Question, MessageBoxDefaultButton::Button1, MessageBoxOptions::RightAlign ) == DialogResult::Yes )
{
host->TransactionOpened += gcnew EventHandler( this, &DTDesigner::OnDesignerTransactionOpened );
host->TransactionClosed += gcnew DesignerTransactionCloseEventHandler( this, &DTDesigner::OnDesignerTransactionClosed );
notification_mode = true;
}
}
public:
~DTDesigner()
{
UnlinkDTNotifications( this, gcnew EventArgs );
}
};
// Associate the DTDesigner with this component
[DesignerAttribute(DTDesigner::typeid)]
public ref class DTComponent: public System::ComponentModel::Component
{
private:
String^ m_String;
int m_Count;
void InitializeComponent()
{
m_String = "Initial Value";
m_Count = 0;
}
public:
property String^ StringProperty
{
String^ get()
{
return m_String;
}
void set( String^ value )
{
m_String = value;
}
}
property int CountProperty
{
int get()
{
return m_Count;
}
void set( int value )
{
m_Count = value;
}
}
};
using System;
using System.ComponentModel;
using System.ComponentModel.Design;
using System.Windows.Forms;
using System.Windows.Forms.Design;
/*
This sample demonstrates how to perform a series of actions in a designer
transaction, how to change values of properties of a component from a
designer, and how to complete transactions without being interrupted
by other activities.
To run this sample, add this code to a class library project and compile.
Create a new Windows Forms project or load a form in the designer. Add a
reference to the class library that was compiled in the first step.
Right-click the Toolbox in design mode and click Customize Toolbox.
Browse to the class library that was compiled in the first step and
select OK until the DTComponent item appears in the Toolbox. Add an
instance of this component to the form.
When the component is created and added to the component tray for your
design project, the Initialize method of the designer is called.
This method displays a message box informing you that designer transaction
event handlers will be registered unless you click Cancel. When you set
properties in the properties window, each change will be encapsulated in
a designer transaction, allowing the change to be undone later.
When you right-click the component, the shortcut menu for the component
is displayed. The designer constructs this menu according to whether
designer transaction notifications are enabled, and offers the option
of enabling or disabling the notifications, depending on the current
mode. The shortcut menu also presents a Perform Example Transaction
item, which will set the values of the component's StringProperty and
CountProperty properties. You can undo the last designer transaction using
the Undo command provided by the Visual Studio development environment.
*/
namespace DesignerTransactionSample
{
// Associate the DTDesigner with this component
[DesignerAttribute(typeof(DTDesigner))]
public class DTComponent : System.ComponentModel.Component
{
private string m_String;
private int m_Count;
public string StringProperty
{
get
{ return m_String; }
set
{ m_String = value; }
}
public int CountProperty
{
get
{ return m_Count; }
set
{ m_Count = value; }
}
private void InitializeComponent()
{
m_String = "Initial Value";
m_Count = 0;
}
}
internal class DTDesigner : ComponentDesigner
{
private bool notification_mode = false;
private int count = 10;
// The Verbs property is overridden from ComponentDesigner
public override DesignerVerbCollection Verbs
{
get
{
DesignerVerbCollection dvc = new DesignerVerbCollection();
dvc.Add( new DesignerVerb("Perform Example Transaction", new EventHandler(this.DoTransaction)) );
if(notification_mode)
dvc.Add(new DesignerVerb("End Designer Transaction Notifications", new EventHandler(this.UnlinkDTNotifications)));
else
dvc.Add(new DesignerVerb("Show Designer Transaction Notifications", new EventHandler(this.LinkDTNotifications))); return dvc;
}
}
public override void Initialize(System.ComponentModel.IComponent component)
{
base.Initialize(component);
IDesignerHost host = (IDesignerHost)GetService(typeof(IDesignerHost));
if(host == null)
{
MessageBox.Show("The IDesignerHost service interface could not be obtained.");
return;
}
if( MessageBox.Show("Press the Yes button to display notification message boxes for the designer transaction opened and closed notifications.","Link DesignerTransaction Notifications?", MessageBoxButtons.YesNo, MessageBoxIcon.Question, MessageBoxDefaultButton.Button1, MessageBoxOptions.RightAlign) == DialogResult.Yes )
{
host.TransactionOpened += new EventHandler(OnDesignerTransactionOpened);
host.TransactionClosed += new DesignerTransactionCloseEventHandler(OnDesignerTransactionClosed);
notification_mode = true;
}
}
private void LinkDTNotifications(object sender, EventArgs e)
{
if(notification_mode == false)
{
IDesignerHost host = (IDesignerHost)GetService(typeof(IDesignerHost));
if(host != null)
{
notification_mode = true;
host.TransactionOpened += new EventHandler(OnDesignerTransactionOpened);
host.TransactionClosed += new DesignerTransactionCloseEventHandler(OnDesignerTransactionClosed);
}
}
}
private void UnlinkDTNotifications(object sender, EventArgs e)
{
if(notification_mode)
{
IDesignerHost host = (IDesignerHost)GetService(typeof(IDesignerHost));
if(host != null)
{
notification_mode = false;
host.TransactionOpened -= new EventHandler(OnDesignerTransactionOpened);
host.TransactionClosed -= new DesignerTransactionCloseEventHandler(OnDesignerTransactionClosed);
}
}
}
private void OnDesignerTransactionOpened(object sender, EventArgs e)
{
System.Windows.Forms.MessageBox.Show("A Designer Transaction was started. (TransactionOpened)");
}
private void OnDesignerTransactionClosed(object sender, DesignerTransactionCloseEventArgs e)
{
System.Windows.Forms.MessageBox.Show("A Designer Transaction was completed. (TransactionClosed)");
}
private void DoTransaction(object sender, EventArgs e)
{
IDesignerHost host = (IDesignerHost)GetService(typeof(IDesignerHost));
DesignerTransaction t = host.CreateTransaction("Change Text and Size");
/* The code within the using statement is considered to be a single transaction.
When the user selects Undo, the system will undo everything executed in this code block. */
using (t)
{
if(notification_mode)
System.Windows.Forms.MessageBox.Show("Entering a Designer-Initiated Designer Transaction");
// The .NET Framework automatically associates the TypeDescriptor with the correct component
PropertyDescriptor someText = TypeDescriptor.GetProperties(Component)["StringProperty"];
someText.SetValue(Component, "This text was set by the designer for this component.");
PropertyDescriptor anInteger = TypeDescriptor.GetProperties(Component)["CountProperty"];
anInteger.SetValue(Component, count);
count++;
// Complete the designer transaction.
t.Commit();
if(notification_mode)
System.Windows.Forms.MessageBox.Show("Designer-Initiated Designer Transaction Completed");
}
}
protected override void Dispose(bool disposing)
{
UnlinkDTNotifications(this, new EventArgs());
base.Dispose(disposing);
}
}
}
Imports System.ComponentModel
Imports System.ComponentModel.Design
Imports System.Windows.Forms
Imports System.Windows.Forms.Design
' This sample demonstrates how to perform a series of actions in a designer
' transaction, how to change values of properties of a component from a
' designer, and how to complete transactions without being interrupted
' by other activities.
' To run this sample, add this code to a class library project and compile.
' Create a new Windows Forms project or load a form in the designer. Add a
' reference to the class library that was compiled in the first step.
' Right-click the Toolbox in design mode and click Customize Toolbox.
' Browse to the class library that was compiled in the first step and
' select OK until the DTComponent item appears in the Toolbox. Add an
' instance of this component to the form.
' When the component is created and added to the component tray for your
' design project, the Initialize method of the designer is called.
' This method displays a message box informing you that designer transaction
' event handlers are being registered unless you click Cancel. When you set
' properties in the properties window, each change will be encapsulated in
' a designer transaction, allowing the change to be undone later.
' When you right-click the component, the shortcut menu for the component
' is displayed. The designer constructs this menu according to whether
' designer transaction notifications are enabled, and offers the option
' of enabling or disabling the notifications, depending on the current
' mode. The shortcut menu also presents a Perform Example Transaction
' item which will set the values of the component's StringProperty and
' CountProperty properties. You can undo the last designer transaction using
' the Undo command provided by the Visual Studio development environment.
Namespace DesignerTransactionSample
' Associate the DTDesigner with this component
<DesignerAttribute(GetType(DTDesigner))> _
Public Class DTComponent
Inherits System.ComponentModel.Component
Private m_String As String
Private m_Count As Integer
Public Property StringProperty() As String
Get
Return m_String
End Get
Set(ByVal Value As String)
m_String = Value
End Set
End Property
Public Property CountProperty() As Integer
Get
Return m_Count
End Get
Set(ByVal Value As Integer)
m_Count = Value
End Set
End Property
Private Sub InitializeComponent()
m_String = "Initial Value"
m_Count = 0
End Sub
End Class
Friend Class DTDesigner
Inherits ComponentDesigner
Private notification_mode As Boolean = False
Private count As Integer = 10
' The Verbs property is overridden from ComponentDesigner
Public Overrides ReadOnly Property Verbs() As DesignerVerbCollection
Get
Dim dvc As New DesignerVerbCollection()
dvc.Add(New DesignerVerb("Perform Example Transaction", AddressOf Me.DoTransaction))
If notification_mode Then
dvc.Add(New DesignerVerb("End Designer Transaction Notifications", AddressOf Me.UnlinkDTNotifications))
Else
dvc.Add(New DesignerVerb("Show Designer Transaction Notifications", AddressOf Me.LinkDTNotifications))
End If
Return dvc
End Get
End Property
Public Overrides Sub Initialize(ByVal component As System.ComponentModel.IComponent)
MyBase.Initialize(component)
Dim host As IDesignerHost = CType(GetService(GetType(IDesignerHost)), IDesignerHost)
If host Is Nothing Then
MessageBox.Show("The IDesignerHost service interface could not be obtained.")
Return
End If
If MessageBox.Show("Press the Yes button to display notification message boxes for the designer transaction opened and closed notifications.", "Link DesignerTransaction Notifications?", MessageBoxButtons.YesNo, MessageBoxIcon.Question, MessageBoxDefaultButton.Button1, MessageBoxOptions.RightAlign) = DialogResult.Yes Then
AddHandler host.TransactionOpened, AddressOf OnDesignerTransactionOpened
AddHandler host.TransactionClosed, AddressOf OnDesignerTransactionClosed
notification_mode = True
End If
End Sub
Private Sub LinkDTNotifications(ByVal sender As Object, ByVal e As EventArgs)
If notification_mode = False Then
Dim host As IDesignerHost = CType(GetService(GetType(IDesignerHost)), IDesignerHost)
If (host IsNot Nothing) Then
notification_mode = True
AddHandler host.TransactionOpened, AddressOf OnDesignerTransactionOpened
AddHandler host.TransactionClosed, AddressOf OnDesignerTransactionClosed
End If
End If
End Sub
Private Sub UnlinkDTNotifications(ByVal sender As Object, ByVal e As EventArgs)
If notification_mode Then
Dim host As IDesignerHost = CType(GetService(GetType(IDesignerHost)), IDesignerHost)
If (host IsNot Nothing) Then
notification_mode = False
RemoveHandler host.TransactionOpened, AddressOf Me.OnDesignerTransactionOpened
RemoveHandler host.TransactionClosed, AddressOf Me.OnDesignerTransactionClosed
End If
End If
End Sub
Private Sub OnDesignerTransactionOpened(ByVal sender As Object, ByVal e As EventArgs)
System.Windows.Forms.MessageBox.Show("A Designer Transaction was started. (TransactionOpened)")
End Sub
Private Sub OnDesignerTransactionClosed(ByVal sender As Object, ByVal e As DesignerTransactionCloseEventArgs)
System.Windows.Forms.MessageBox.Show("A Designer Transaction was completed. (TransactionClosed)")
End Sub
Private Sub DoTransaction(ByVal sender As Object, ByVal e As EventArgs)
Dim host As IDesignerHost = CType(GetService(GetType(IDesignerHost)), IDesignerHost)
Dim t As DesignerTransaction = host.CreateTransaction("Change Text and Size")
' The code within the using statement is considered to be a single transaction.
' When the user selects Undo, the system will undo everything executed in this code block.
Try
If (notification_mode) Then
System.Windows.Forms.MessageBox.Show("Entering a Designer-Initiated Designer Transaction")
End If
Dim someText As PropertyDescriptor = TypeDescriptor.GetProperties(Component)("StringProperty")
someText.SetValue(Component, "This text was set by the designer for this component.")
Dim anInteger As PropertyDescriptor = TypeDescriptor.GetProperties(Component)("CountProperty")
anInteger.SetValue(Component, count)
count = count + 1
Exit Try
Finally
t.Commit()
End Try
If (notification_mode) Then
System.Windows.Forms.MessageBox.Show("Designer-Initiated Designer Transaction Completed")
End If
End Sub
Protected Overloads Overrides Sub Dispose(ByVal disposing As Boolean)
UnlinkDTNotifications(Me, New EventArgs())
MyBase.Dispose(disposing)
End Sub
End Class
End Namespace 'DesignerTransactionSample
Comentários
As transações podem acompanhar ações que podem ser desfeitas posteriormente. As alterações feitas durante uma transação podem ser revertidas cancelando uma transação, que tenta reverter automaticamente cada alteração definindo cada propriedade alterada como seu valor de pré-alteração. As transações também podem melhorar o desempenho durante uma série de operações, adiando atualizações para a exibição até a conclusão da transação.
Quando uma transação está em andamento, alguns componentes adiam o processamento até que a transação seja concluída ouvindo os TransactionOpening eventos e TransactionClosed . O janela Propriedades, por exemplo, não atualiza sua exibição depois que uma transação é aberta até que a transação seja fechada.
Para usar transações para operações reversíveis ou múltiplas, faça com que o designer crie um DesignerTransaction para cada operação ou série de operações que devem ser reversíveis. Tenha cuidado para não executar ações fora das transações que podem impedir que uma sequência de eventos de desfazer seja concluída com êxito.
Você pode obter um novo DesignerTransaction chamando o CreateTransaction método de um IDesignerHost. Certifique-se de obter cada DesignerTransaction um do ativo IDesignerHost para se integrar corretamente ao mecanismo de processamento de transações do designer, em vez de criar um novo DesignerTransaction diretamente.
Para executar uma ação em uma transação, primeiro você deve criar uma transação. Em seguida, você deve chamar o OnComponentChanging método antes que cada alteração ou conjunto de alterações ocorra e o OnComponentChanged método após cada alteração ou conjunto de alterações ocorrer. Por fim, conclua e feche a transação chamando o Commit método .
Observação
Ao fazer alterações nos valores de propriedade, use o SetValue método de um PropertyDescriptor, que chama os métodos de alteração de componente do IComponentChangeService e cria um DesignerTransaction que representa a alteração automaticamente.
Para executar uma transação, conclua as seguintes etapas:
Chame CreateTransaction para obter um DesignerTransaction que pode ser usado para controlar a transação.
Em um
try
bloco, para cada ação que você deseja controlar com um DesignerTransaction, chame o OnComponentChanging método , faça a alteração ou as alterações e chame o OnComponentChanged método para sinalizar que a alteração ou as alterações foram feitas.Para concluir a transação, chame Commit de dentro de um
finally
bloco.
Em C#, você pode usar a using
instrução em vez de um try/finally
bloco, como no exemplo a seguir.
using (host.CreateTransaction() {
// Insert your code here.
}
Para cancelar e tentar reverter uma transação antes de ser confirmada, chame o Cancel método . Quando o Cancel método é invocado, as ações controladas pelo DesignerTransaction são invertidas para tentar reverter as alterações. Para desfazer ações que ocorreram como parte de transações anteriores, você deve usar o comando desfazer fornecido pelo ambiente de desenvolvimento.
Construtores
DesignerTransaction() |
Inicializa uma nova instância da classe DesignerTransaction sem nenhuma descrição. |
DesignerTransaction(String) |
Inicializa uma nova instância da classe DesignerTransaction usando a descrição de transação especificada. |
Propriedades
Canceled |
Obtém um valor que indica se a transação foi cancelada. |
Committed |
Obtém um valor que indica se a transação foi confirmada. |
Description |
Obtém uma descrição para a transação. |
Métodos
Cancel() |
Cancela a transação e tenta reverter as alterações feitas pelos eventos da transação. |
Commit() |
Confirma a transação. |
Dispose(Boolean) |
Libera os recursos não gerenciados usados pelo DesignerTransaction e opcionalmente libera os recursos gerenciados. |
Equals(Object) |
Determina se o objeto especificado é igual ao objeto atual. (Herdado de Object) |
Finalize() |
Libera todos os recursos do sistema operacional associados a este objeto. Esta substituição confirma esta transação se ela ainda não foi confirmada. |
GetHashCode() |
Serve como a função de hash padrão. (Herdado de Object) |
GetType() |
Obtém o Type da instância atual. (Herdado de Object) |
MemberwiseClone() |
Cria uma cópia superficial do Object atual. (Herdado de Object) |
OnCancel() |
Aciona o evento |
OnCommit() |
Realiza o real trabalho de confirmar uma transação. |
ToString() |
Retorna uma cadeia de caracteres que representa o objeto atual. (Herdado de Object) |
Implantações explícitas de interface
IDisposable.Dispose() |
Libera todos os recursos usados pelo DesignerTransaction. |