// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information.
 
#nullable disable
 
using Microsoft.CodeAnalysis.Host;
using Microsoft.CodeAnalysis.Text;
using Microsoft.VisualStudio.Text;
 
namespace Microsoft.CodeAnalysis.Editor.Undo;
 
/// <summary>
/// A service that allows consumers to register undo transactions for a supplied
/// <see cref="SourceText"/> with a supplied description. The description is the
/// display string by which the IDE's undo stack UI will subsequently refer to the transaction.
/// </summary>
internal interface ISourceTextUndoService : IWorkspaceService
{
    /// <summary>
    /// Registers undo transaction for the supplied <see cref="SourceText"/>.
    /// </summary>
    /// <param name="sourceText">The <see cref="SourceText"/> for which undo transaction is being registered.</param>
    /// <param name="description">The display string by which the IDE's undo stack UI will subsequently refer to the transaction.</param>
    ISourceTextUndoTransaction RegisterUndoTransaction(SourceText sourceText, string description);
 
    /// <summary>
    /// Starts previously registered undo transaction for the supplied <see cref="ITextSnapshot"/> (if any).
    /// </summary>
    /// <param name="snapshot">The <see cref="ITextSnapshot"/> for the <see cref="SourceText"/> for undo transaction being started.</param>
    /// <remarks>
    /// This method will handle the translation from <see cref="ITextSnapshot"/> to <see cref="SourceText"/>
    /// and update the IDE's undo stack UI with the transaction's previously registered description string.
    /// </remarks>
    bool BeginUndoTransaction(ITextSnapshot snapshot);
 
    /// <summary>
    /// Completes and deletes the supplied undo transaction.
    /// </summary>
    /// <param name="transaction">The undo transaction that is being ended.</param>
    bool EndUndoTransaction(ISourceTextUndoTransaction transaction);
}