同步

Packages/dev.yarnspinner.unity/Runtime/Views/ActionMarkupHandler.cs

@@ -0,0 +1,125 @@
+/*
+Yarn Spinner is licensed to you under the terms found in the file LICENSE.md.
+*/
+
+using UnityEngine;
+using Yarn.Markup;
+using System.Threading;
+
+#if USE_TMP
+using TMPro;
+#else
+using TMP_Text = Yarn.Unity.TMPShim;
+#endif
+
+#nullable enable
+
+namespace Yarn.Unity
+{
+    /// <summary>
+    /// A <see cref="IActionMarkupHandler"/> is an object that reacts to the
+    /// delivery of a line of dialogue, and can optionally control the timing of
+    /// that delivery.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// There are a number of cases where a line's delivery needs to have its
+    /// timing controlled. For example, <see cref="PauseEventProcessor"/> adds a
+    /// small delay between each character, creating a 'typewriter' effect as
+    /// each letter appears over time.
+    /// </para>
+    /// <para>
+    /// Another example of a <see cref="IActionMarkupHandler"/> is an in-line
+    /// event or animation, such as causing a character to play an animation
+    /// (and waiting for that animation to complete before displaying the rest
+    /// of the line).
+    /// </para>
+    /// </remarks>
+    public interface IActionMarkupHandler
+    {
+        /// <summary>
+        /// Called when the line view receives the line, to prepare for showing
+        /// the line.
+        /// </summary>
+        /// <remarks>
+        /// This method is called before any part of the line is visible, and is
+        /// an opportunity to set up any part of the <see
+        /// cref="ActionMarkupHandler"/>'s display before the user can see it.
+        /// </remarks>
+        /// <param name="line">The line being presented.</param>
+        /// <param name="text">A <see cref="TMP_Text"/> object that the line is
+        /// being displayed in.</param>
+        public void OnPrepareForLine(MarkupParseResult line, TMP_Text text);
+
+        /// <summary>
+        /// Called immediately before the first character in the line is
+        /// presented. 
+        /// </summary>
+        /// <param name="line">The line being presented.</param>
+        /// <param name="text">A <see cref="TMP_Text"/> object that the line is
+        /// being displayed in.</param>
+        public void OnLineDisplayBegin(MarkupParseResult line, TMP_Text text);
+
+        /// <summary>
+        /// Called repeatedly for each visible character in the line.
+        /// </summary>
+        /// <remarks> This method is a <see cref="ActionMarkupHandler"/>
+        /// object's main opportunity to take action during line
+        /// display.</remarks>
+        /// <param name="currentCharacterIndex">The zero-based index of the
+        /// character being displayed.</param>
+        /// <param name="text">A <see cref="TMP_Text"/> object that the line is
+        /// being displayed in.</param>
+        /// <param name="cancellationToken">A cancellation token representing
+        /// whether the </param>
+        /// <returns>A task that completes when the <see
+        /// cref="ActionMarkupHandler"/> has completed presenting this
+        /// character. Dialogue presenters will wait until this task is complete
+        /// before displaying the remainder of the line.</returns>
+        public YarnTask OnCharacterWillAppear(int currentCharacterIndex, MarkupParseResult line, CancellationToken cancellationToken);
+
+        /// <summary>
+        /// Called after the last call to <see cref="PresentCharacter(int,
+        /// TMP_Text, CancellationToken)"/>.
+        /// </summary>
+        /// <remarks>This method is an opportunity for a <see
+        /// cref="ActionMarkupHandler"/> to finalise its presentation after
+        /// all of the characters in the line have been presented.</remarks>
+        public void OnLineDisplayComplete();
+
+        /// <summary>
+        /// Called right before the line will dismiss itself.
+        /// </summary>
+        /// <remarks>
+        /// This does not mean that the entirety of the view itself will have been removed, just the <see cref="DialoguePresenterBase"/> has completed displaying everything and is returning control back to the <see cref="DialogueRunner"/> to let more content flow.
+        /// </remarks>
+        public void OnLineWillDismiss();
+    }
+
+    /// <summary>
+    /// This is an abstract monobehaviour that conforms to the <see cref="IActionMarkupHandler"/> interface.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Intended to be used in situations where you require a monobehaviour version of the interfaces.
+    /// This is used by <see cref="LinePresenter"/> to have a list of handlers that can be connected up via the inspector.
+    /// </para>
+    /// </remarks>
+    public abstract class ActionMarkupHandler : MonoBehaviour, IActionMarkupHandler
+    {
+        /// <inheritdoc/>
+        public abstract void OnPrepareForLine(MarkupParseResult line, TMP_Text text);
+
+        /// <inheritdoc/>
+        public abstract void OnLineDisplayBegin(MarkupParseResult line, TMP_Text text);
+
+        /// <inheritdoc/>
+        public abstract YarnTask OnCharacterWillAppear(int currentCharacterIndex, MarkupParseResult line, CancellationToken cancellationToken);
+
+        /// <inheritdoc/>
+        public abstract void OnLineDisplayComplete();
+
+        /// <inheritdoc/>
+        public abstract void OnLineWillDismiss();
+    }
+}