348 lines
21 KiB
XML
Raw Normal View History

<?xml version="1.0" encoding="utf-8"?>
<Type Name="DesignerTransaction" FullName="System.ComponentModel.Design.DesignerTransaction">
<TypeSignature Language="C#" Value="public abstract class DesignerTransaction : IDisposable" Maintainer="auto" />
<TypeSignature Language="ILAsm" Value=".class public auto ansi abstract beforefieldinit DesignerTransaction extends System.Object implements class System.IDisposable" />
<AssemblyInfo>
<AssemblyName>System</AssemblyName>
<AssemblyPublicKey>[00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00]</AssemblyPublicKey>
<AssemblyVersion>1.0.3300.0</AssemblyVersion>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ThreadSafetyStatement>Gtk# is thread aware, but not thread safe; See the &lt;link location="node:gtk-sharp/programming/threads"&gt;Gtk# Thread Programming&lt;/link&gt; for details.</ThreadSafetyStatement>
<Base>
<BaseTypeName>System.Object</BaseTypeName>
</Base>
<Interfaces>
<Interface>
<InterfaceName>System.IDisposable</InterfaceName>
</Interface>
</Interfaces>
<Docs>
<remarks>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Transactions can track actions that can be undone later. Changes made during a transaction can be reversed by canceling a transaction, which automatically attempts to reverse each change by setting each changed property to its pre-change value. Transactions can also improve performance during a series of operations by deferring updates to the display until the completion of the transaction.</para>
<para>When a transaction is in progress, some components defer their processing until the transaction has completed by listening to the <see cref="E:System.ComponentModel.Design.IDesignerHost.TransactionOpening" /> and <see cref="E:System.ComponentModel.Design.IDesignerHost.TransactionClosed" /> events. The Properties window, for example, does not update its display after a transaction has opened until the transaction has closed.</para>
<para>To use transactions for reversible or multiple operations, have your designer create a <see cref="T:System.ComponentModel.Design.DesignerTransaction" /> for each operation or series of operations which should be reversible. Be careful not to perform actions outside the transactions that might prevent a sequence of undo events from completing successfully.</para>
<para>You can obtain a new <see cref="T:System.ComponentModel.Design.DesignerTransaction" /> by calling the <see cref="M:System.ComponentModel.Design.IDesignerHost.CreateTransaction" /> method of an <see cref="T:System.ComponentModel.Design.IDesignerHost" />. Be sure to obtain each <see cref="T:System.ComponentModel.Design.DesignerTransaction" /> from the active <see cref="T:System.ComponentModel.Design.IDesignerHost" /> in order to correctly integrate with the designer transaction processing mechanism, rather than creating a new <see cref="T:System.ComponentModel.Design.DesignerTransaction" /> directly.</para>
<para>To perform an action within a transaction, you must first create a transaction. Then you must call the <see cref="M:System.ComponentModel.Design.IComponentChangeService.OnComponentChanging(System.Object,System.ComponentModel.MemberDescriptor)" /> method before each change or set of changes occurs, and the <see cref="M:System.ComponentModel.Design.IComponentChangeService.OnComponentChanged(System.Object,System.ComponentModel.MemberDescriptor,System.Object,System.Object)" /> method after each change or set of changes occur. Finally, complete and close the transaction by calling the <see cref="M:System.ComponentModel.Design.DesignerTransaction.Commit" /> method.</para>
<block subset="none" type="note">
<para>When making changes to property values, use the <see cref="M:System.ComponentModel.PropertyDescriptor.SetValue(System.Object,System.Object)" /> method of a <see cref="T:System.ComponentModel.PropertyDescriptor" />, which calls the component change methods of the <see cref="T:System.ComponentModel.Design.IComponentChangeService" /> and creates a <see cref="T:System.ComponentModel.Design.DesignerTransaction" /> representing the change automatically.</para>
</block>
<para>To perform a transaction, complete the following steps: </para>
<list type="ordered">
<item>
<para>Call <see cref="M:System.ComponentModel.Design.IDesignerHost.CreateTransaction" /> to obtain a <see cref="T:System.ComponentModel.Design.DesignerTransaction" /> that can be used to control the transaction.</para>
</item>
<item>
<para>Within a try block, for each action that you want to track with a <see cref="T:System.ComponentModel.Design.DesignerTransaction" />, call the <see cref="M:System.ComponentModel.Design.IComponentChangeService.OnComponentChanging(System.Object,System.ComponentModel.MemberDescriptor)" /> method, make the change or changes, then call the <see cref="M:System.ComponentModel.Design.IComponentChangeService.OnComponentChanged(System.Object,System.ComponentModel.MemberDescriptor,System.Object,System.Object)" /> method to signal that the change or changes have been made.</para>
</item>
<item>
<para>To complete the transaction, call <see cref="M:System.ComponentModel.Design.DesignerTransaction.Commit" /> from within a finally block.</para>
</item>
</list>
<para>In C#, you can use the using statement rather than a try/finally block, such as in the following example.</para>
<code> using (host.CreateTransaction() {
// Insert your code here.
}</code>
<para>To cancel and attempt to roll back a transaction before it has been committed, call the <see cref="M:System.ComponentModel.Design.DesignerTransaction.Cancel" /> method. When the <see cref="M:System.ComponentModel.Design.DesignerTransaction.Cancel" /> method is invoked, the actions tracked by the <see cref="T:System.ComponentModel.Design.DesignerTransaction" /> are reversed to attempt to roll back the changes. To undo actions that occurred as part of earlier transactions, you must use the undo command provided by the development environment.</para>
</remarks>
<summary>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Provides a way to group a series of design-time actions to improve performance and enable most types of changes to be undone.</para>
</summary>
</Docs>
<Members>
<Member MemberName=".ctor">
<MemberSignature Language="C#" Value="protected DesignerTransaction ();" />
<MemberSignature Language="ILAsm" Value=".method familyhidebysig specialname rtspecialname instance void .ctor() cil managed" />
<MemberType>Constructor</MemberType>
<AssemblyInfo>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue />
<Parameters />
<Docs>
<remarks>To be added</remarks>
<summary>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Initializes a new instance of the <see cref="T:System.ComponentModel.Design.DesignerTransaction" /> class with no description.</para>
</summary>
</Docs>
</Member>
<Member MemberName=".ctor">
<MemberSignature Language="C#" Value="protected DesignerTransaction (string description);" />
<MemberSignature Language="ILAsm" Value=".method familyhidebysig specialname rtspecialname instance void .ctor(string description) cil managed" />
<MemberType>Constructor</MemberType>
<AssemblyInfo>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue />
<Parameters>
<Parameter Name="description" Type="System.String" />
</Parameters>
<Docs>
<remarks>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>This constructor initializes the transaction with the specified description.</para>
</remarks>
<summary>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Initializes a new instance of the <see cref="T:System.ComponentModel.Design.DesignerTransaction" /> class using the specified transaction description.</para>
</summary>
<param name="description">
<attribution license="cc4" from="Microsoft" modified="false" />A description for this transaction. </param>
</Docs>
</Member>
<Member MemberName="Cancel">
<MemberSignature Language="C#" Value="public void Cancel ();" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance void Cancel() cil managed" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<remarks>To be added</remarks>
<summary>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Cancels the transaction and attempts to roll back the changes made by the events of the transaction.</para>
</summary>
</Docs>
</Member>
<Member MemberName="Canceled">
<MemberSignature Language="C#" Value="public bool Canceled { get; }" />
<MemberSignature Language="ILAsm" Value=".property instance bool Canceled" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<value>To be added: an object of type 'bool'</value>
<remarks>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>When a designer transaction is canceled, the transaction processing mechanism attempts to roll back the changes that have been made so far in the transaction. Whether this succeeds is dependent upon such factors as the type of each operation, whether other operations interfered with any of the involved code's state, and whether a sequence of expected operations failed to complete.</para>
</remarks>
<summary>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Gets a value indicating whether the transaction was canceled.</para>
</summary>
</Docs>
</Member>
<Member MemberName="Commit">
<MemberSignature Language="C#" Value="public void Commit ();" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance void Commit() cil managed" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<remarks>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>When a designer transaction is committed, the transaction is considered complete and does not track further changes.</para>
<para>Once a transaction has been committed, further calls to this method do nothing. Always call this method after creating a transaction to ensure that the transaction closes properly.</para>
</remarks>
<summary>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Commits this transaction.</para>
</summary>
</Docs>
</Member>
<Member MemberName="Committed">
<MemberSignature Language="C#" Value="public bool Committed { get; }" />
<MemberSignature Language="ILAsm" Value=".property instance bool Committed" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Docs>
<value>To be added: an object of type 'bool'</value>
<remarks>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>When a designer transaction is committed, the transaction is considered complete and does not track further changes.</para>
</remarks>
<summary>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Gets a value indicating whether the transaction was committed.</para>
</summary>
</Docs>
</Member>
<Member MemberName="Description">
<MemberSignature Language="C#" Value="public string Description { get; }" />
<MemberSignature Language="ILAsm" Value=".property instance string Description" />
<MemberType>Property</MemberType>
<AssemblyInfo>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.String</ReturnType>
</ReturnValue>
<Docs>
<value>To be added: an object of type 'string'</value>
<remarks>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>A transaction can have a description that is useful in identifying the nature of the operation or operations.</para>
</remarks>
<summary>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Gets a description for the transaction.</para>
</summary>
</Docs>
</Member>
<Member MemberName="Dispose">
<MemberSignature Language="C#" Value="protected virtual void Dispose (bool disposing);" />
<MemberSignature Language="ILAsm" Value=".method familyhidebysig newslot virtual instance void Dispose(bool disposing) cil managed" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="disposing" Type="System.Boolean" />
</Parameters>
<Docs>
<remarks>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>This method is called by the public Dispose() method and the <see cref="M:System.Object.Finalize" /> method. Dispose() invokes the protected Dispose(Boolean) method with the <paramref name="disposing" /> parameter set to true. <see cref="M:System.Object.Finalize" /> invokes Dispose with <paramref name="disposing" /> set to false.</para>
<para>When the <paramref name="disposing" /> parameter is true, this method releases all resources held by any managed objects that this <see cref="T:System.ComponentModel.Design.DesignerTransaction" /> references. This method invokes the Dispose() method of each referenced object.</para>
</remarks>
<summary>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Releases the unmanaged resources used by the <see cref="T:System.ComponentModel.Design.DesignerTransaction" /> and optionally releases the managed resources.</para>
</summary>
<param name="disposing">
<attribution license="cc4" from="Microsoft" modified="false" />true to release both managed and unmanaged resources; false to release only unmanaged resources. </param>
</Docs>
</Member>
<Member MemberName="Finalize">
<MemberSignature Language="C#" Value="~DesignerTransaction ();" />
<MemberSignature Language="ILAsm" Value=".method familyhidebysig virtual instance void Finalize() cil managed" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<remarks>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>This method overrides <see cref="M:System.Object.Finalize" /> and cleans up resources by calling Dispose(false). Override Dispose(Boolean) to customize the cleanup.</para>
<para>Application code should not call this method; an object's Finalize method is automatically invoked during garbage collection, unless finalization by the garbage collector has been disabled by a call to the <see cref="M:System.GC.SuppressFinalize(System.Object)" /> method.</para>
<para>For more information, see <format type="text/html"><a href="fd376774-1643-499b-869e-9546a3aeea70">Finalize Methods and Destructors</a></format>, <format type="text/html"><a href="a17b0066-71c2-4ba4-9822-8e19332fc213">Cleaning Up Unmanaged Resources</a></format>, and <format type="text/html"><a href="8026cb68-fe93-43fc-96c1-c09ad7d64cd3">Overriding the Finalize Method</a></format>.</para>
</remarks>
<summary>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Releases the resources associated with this object. This override commits this transaction if it was not already committed.</para>
</summary>
</Docs>
</Member>
<Member MemberName="OnCancel">
<MemberSignature Language="C#" Value="protected abstract void OnCancel ();" />
<MemberSignature Language="ILAsm" Value=".method familyhidebysig newslot virtual instance void OnCancel() cil managed" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<remarks>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>When a designer transaction is canceled, the transaction processing mechanism attempts to roll back the changes that have been made so far in the transaction. Whether this succeeds is dependent upon such factors as the type of each operation, whether other operations interfered with any of the involved code's state, and whether a sequence of expected operations failed to complete.</para>
</remarks>
<summary>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Raises the Cancel event.</para>
</summary>
</Docs>
</Member>
<Member MemberName="OnCommit">
<MemberSignature Language="C#" Value="protected abstract void OnCommit ();" />
<MemberSignature Language="ILAsm" Value=".method familyhidebysig newslot virtual instance void OnCommit() cil managed" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<remarks>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>When a designer transaction is committed, the transaction is considered complete and does not track further changes.</para>
</remarks>
<summary>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Performs the actual work of committing a transaction.</para>
</summary>
</Docs>
</Member>
<Member MemberName="System.IDisposable.Dispose">
<MemberSignature Language="C#" Value="void IDisposable.Dispose ();" />
<MemberSignature Language="ILAsm" Value=".method hidebysig newslot virtual instance void System.IDisposable.Dispose() cil managed" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<remarks>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>When a transaction is disposed, it is committed.</para>
</remarks>
<summary>
<attribution license="cc4" from="Microsoft" modified="false" />
<para>Releases all resources used by the <see cref="T:System.ComponentModel.Design.DesignerTransaction" />. </para>
</summary>
</Docs>
</Member>
</Members>
</Type>