Merge branch 'mod-overlay/back-button' into mod-overlay/integration

osu.Game/Graphics/Containers/HoldToConfirmContainer.cs

@@ -10,12 +10,32 @@ using osu.Game.Configuration;
 
 namespace osu.Game.Graphics.Containers
 {
+    /// <summary>
+    /// A container which adds a common "hold-to-perform" pattern to a container.
+    /// </summary>
+    /// <remarks>
+    /// This container does not handle triggering the hold/abort operations.
+    /// To use this class, please call <see cref="BeginConfirm"/> and <see cref="AbortConfirm"/> when necessary.
+    ///
+    /// The <see cref="Progress"/> is exposed as a transforming bindable which smoothly tracks the progress of a hold operation.
+    /// It can be used for animating and displaying progress directly.
+    /// </remarks>
     public abstract class HoldToConfirmContainer : Container
     {
-        public Action Action;
+        public const double DANGEROUS_HOLD_ACTIVATION_DELAY = 500;
 
         private const int fadeout_delay = 200;
 
+        /// <summary>
+        /// Whether the associated action is considered dangerous, warranting a longer hold.
+        /// </summary>
+        public bool IsDangerousAction { get; }
+
+        /// <summary>
+        /// The action to perform when a hold successfully completes.
+        /// </summary>
+        public Action Action;
+
         /// <summary>
         /// Whether currently in a fired state (and the confirm <see cref="Action"/> has been sent).
         /// </summary>
@@ -23,46 +43,61 @@ namespace osu.Game.Graphics.Containers
 
         private bool confirming;
 
+        /// <summary>
+        /// The current activation delay for this control.
+        /// </summary>
+        public IBindable<double> HoldActivationDelay => holdActivationDelay;
+
+        /// <summary>
+        /// The progress of any ongoing hold operation. 0 means no hold has started; 1 means a hold has been completed.
+        /// </summary>
+        public IBindable<double> Progress => progress;
+
         /// <summary>
         /// Whether the overlay should be allowed to return from a fired state.
         /// </summary>
         protected virtual bool AllowMultipleFires => false;
 
-        /// <summary>
-        /// Specify a custom activation delay, overriding the game-wide user setting.
-        /// </summary>
-        /// <remarks>
-        /// This should be used in special cases where we want to be extra sure the user knows what they are doing. An example is when changes would be lost.
-        /// </remarks>
-        protected virtual double? HoldActivationDelay => null;
+        private readonly Bindable<double> progress = new BindableDouble();
 
-        public Bindable<double> Progress = new BindableDouble();
+        private readonly Bindable<double> holdActivationDelay = new Bindable<double>();
 
-        private Bindable<double> holdActivationDelay;
+        [Resolved]
+        private OsuConfigManager config { get; set; }
 
-        [BackgroundDependencyLoader]
-        private void load(OsuConfigManager config)
+        protected HoldToConfirmContainer(bool isDangerousAction = false)
         {
-            holdActivationDelay = HoldActivationDelay != null
-                ? new Bindable<double>(HoldActivationDelay.Value)
-                : config.GetBindable<double>(OsuSetting.UIHoldActivationDelay);
+            IsDangerousAction = isDangerousAction;
         }
 
+        protected override void LoadComplete()
+        {
+            base.LoadComplete();
+
+            if (IsDangerousAction)
+                holdActivationDelay.Value = DANGEROUS_HOLD_ACTIVATION_DELAY;
+            else
+                config.BindWith(OsuSetting.UIHoldActivationDelay, holdActivationDelay);
+        }
+
+        /// <summary>
+        /// Begin a new confirmation. Should be called when the container is interacted with (ie. the user presses a key).
+        /// </summary>
+        /// <remarks>
+        /// Calling this method when already in the process of confirming has no effect.
+        /// </remarks>
         protected void BeginConfirm()
         {
             if (confirming || (!AllowMultipleFires && Fired)) return;
 
             confirming = true;
 
-            this.TransformBindableTo(Progress, 1, holdActivationDelay.Value * (1 - Progress.Value), Easing.Out).OnComplete(_ => Confirm());
-        }
-
-        protected virtual void Confirm()
-        {
-            Action?.Invoke();
-            Fired = true;
+            this.TransformBindableTo(progress, 1, holdActivationDelay.Value * (1 - progress.Value), Easing.Out).OnComplete(_ => Confirm());
         }
 
+        /// <summary>
+        /// Abort any ongoing confirmation. Should be called when the container's interaction is no longer valid (ie. the user releases a key).
+        /// </summary>
         protected void AbortConfirm()
         {
             if (!AllowMultipleFires && Fired) return;
@@ -71,9 +106,19 @@ namespace osu.Game.Graphics.Containers
             Fired = false;
 
             this
-                .TransformBindableTo(Progress, Progress.Value)
+                .TransformBindableTo(progress, progress.Value)
                 .Delay(200)
-                .TransformBindableTo(Progress, 0, fadeout_delay, Easing.InSine);
+                .TransformBindableTo(progress, 0, fadeout_delay, Easing.InSine);
+        }
+
+        /// <summary>
+        /// A method which is invoked when the confirmation sequence completes successfully.
+        /// By default, will fire the associated <see cref="Action"/>.
+        /// </summary>
+        protected virtual void Confirm()
+        {
+            Action?.Invoke();
+            Fired = true;
         }
     }
 }