using System;

namespace Framework.Dialogue {

  /// <summary>Manages UI widgets in a canvas used to display dialogue</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 the speech or picks a choice</summary>
    /// <remarks>
    ///   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.
    /// </remarks>
    event Action<int> Selected;

    /// <summary>Displays text spoken or thought by a character</summary>
    /// <param name="text">Text that will be displayed</param>
    /// <remarks>
    ///   This opens the speech panel if it was hidden or replaces the text
    ///   currently being shown in the speech panel if it was visible.
    /// </remarks>
    void ShowSpeech(string text);

    /// <summary>Lets the player make a choice</summary>
    /// <param name="choices">Choices the player can select from</param>
    /// <remarks>
    ///   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.
    /// </remarks>
    void ShowChoices(string[] 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>
    ///   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.
    /// </remarks>
    void ShowSpeechAndChoices(string speech, string[] choices);

    /// <summary>Hides the dialogue and choice</summary>
    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.Dialogue