using System;

using UnityEngine;

using Framework.Async;

namespace Framework.Dialogue2 {

  /// <summary>Static or animated dialogue canvas the user can interact with</summary>
  /// <remarks>
  ///   <para>
  ///     This interface allows dialogue APIs to be mocked and implemented on different
  ///     systems (i.e. uGUI, immediate mode GUI, as speech bubbles, as scrolling log).
  ///     The following scenarios are explicit design goals for this interface:
  ///   </para>
  ///   <para>
  ///     - Speech bubbles appearing next to characters
  ///     - Subtitles being faded in and out
  ///     - Chatlog-like display in a rolling canvas
  ///     - RPG dialogue boxes
  ///   </para>
  /// </remarks>
  public interface IDialogueCanvas {

    /// <summary>Triggered when the user confirms speech dialogue or picks a choice</summary>
    /// <remarks>
    ///   <para>
    ///     If the dialogue implementation uses clickable or otherwise interactive UI,
    ///     this event will fire when the user either clicks the speech panel (when
    ///     no choices are being presented) or one of the choice buttons.
    ///   </para>
    ///   <para>
    ///     When choices are available, the parameter will be the zero-based index of
    ///     the picked choice. When only speech is displayed, the parameter will have
    ///     a value of -1.
    ///   </para>
    /// </remarks>
    event Action<int> Selected;

#if false // Current plan was to fire a 'Selected' event instead? Good/bad?
    /// <summary>Triggered when the dialogue has completed its fade-out animation</summary>
    /// <remarks>
    ///   If you want to wait with an in-game action until the dialogue has fully
    ///   disappeared, this event will do the trick. It may be fired instantly
    ///   (and possibly from the <see cref="Hide" /> call) if no animation is used.
    /// </remarks>
    event Action Hidden;
#endif

    /// <summary>Current visibility state of the canvas</summary>
    IDialogueCanvasVisibility Visibility { get; }

    /// <summary>Current placement of the canvas within the scene</summary>
    IDialogueCanvasPlacement Placement { get; }

    /// <summary>Displays text spoken or thought by a character</summary>
    /// <param name="speech">Text that will be displayed</param>
    /// <remarks>
    ///   <para>
    ///     This opens the speech panel if it was hidden or replaces the text
    ///     currently being shown in the speech panel if it was visible.
    ///   </para>
    ///   <para>
    ///     If the canvas is animated, the change may not take place instantly
    ///     (but you should expect the <see cref="Selected" /> event at any time after
    ///     this call).
    ///   </para>
    /// </remarks>
    void ShowSpeech(IDialogueText speech);

    /// <summary>Lets the player make a choice</summary>
    /// <param name="choices">Choices the player can select from</param>
    /// <remarks>
    ///   <para>
    ///     This displays the choice buttons and hides the speech panel if it was
    ///     visible. Use if the player is confronted with a self-explaining choice.
    ///   </para>
    ///   <para>
    ///     If the canvas is animated, the change may not take place instantly
    ///     (but you should expect the <see cref="Selected" /> event at any time after
    ///     this call).
    ///   </para>
    /// </remarks>
    void ShowChoices(ArraySegment<IDialogueText> choices);

    /// <summary>
    ///   Displays text spoken or thought by a character (or the player) and lets
    ///   the player make a choice.
    /// </summary>
    /// <param name="speech">Text that will be displayed</param>
    /// <param name="choices">Choices the player can select from</param>
    /// <remarks>
    ///   <para>
    ///     This opens the speech panel or replaces the text in it just like
    ///     the <see cref="ShowSpeech" /> method, but in addition to that also
    ///     displays choices so the player can make a choice in response or
    ///     following the text shown in the speech panel.
    ///   </para>
    ///   <para>
    ///     If the canvas is animated, the change may not
    ///     take place instantly (but you should expect the <see cref="Selected" />
    ///     event at any time after this call).
    ///   </para>
    /// </remarks>
    void ShowSpeechAndChoices(IDialogueText speech, ArraySegment<IDialogueText> choices);

    /// <summary>Hides the dialogue and choice</summary>
    /// <remarks>
    ///   If the canvas is animated, the change may not
    ///   take place instantly (but you should expect the <see cref="Selected" />
    ///   event at any time after this call).
    /// </remarks>
    void Hide();

    /// <summary>Picks a choice as if the user had clicked on a choice button</summary>
    /// <param name="choiceIndex">Index of the choice that has been selected</param>
    /// <remarks>
    ///   Use this to make the dialogue canvas act as if the user had made
    ///   a choice or clicked the speech panel. The main purpose of this method is to
    ///   support input outside of the UI panel - i.e. keyboard shortcuts or even
    ///   interactions with the game world.
    /// </remarks>
    void Select(int choiceIndex);

  }

} // namespace Framework.Dialogue2