gui-cs.Terminal.Gui/Terminal.Gui/Text/Autocomplete/IAutocomplete.cs

using System.Collections.ObjectModel;

namespace Terminal.Gui;

/// <summary>
///     Renders an overlay on another view at a given point that allows selecting from a range of 'autocomplete'
///     options.
/// </summary>
public interface IAutocomplete
{
    // TODO: Update to use Key instead of KeyCode
    /// <summary>The key that the user can press to close the currently popped autocomplete menu</summary>
    KeyCode CloseKey { get; set; }

    /// <summary>
    ///     The colors to use to render the overlay. Accessing this property before the Application has been initialized
    ///     will cause an error
    /// </summary>
    ColorScheme ColorScheme { get; set; }

    /// <summary>The context used by the autocomplete menu.</summary>
    AutocompleteContext Context { get; set; }

    /// <summary>The host control that will use autocomplete.</summary>
    View HostControl { get; set; }

    /// <summary>The maximum number of visible rows in the autocomplete dropdown to render</summary>
    int MaxHeight { get; set; }

    /// <summary>The maximum width of the autocomplete dropdown</summary>
    int MaxWidth { get; set; }

    /// <summary>Gets or sets where the popup will be displayed.</summary>
    bool PopupInsideContainer { get; set; }

    // TODO: Update to use Key instead of KeyCode
    /// <summary>The key that the user can press to reopen the currently popped autocomplete menu</summary>
    KeyCode Reopen { get; set; }

    /// <summary>The currently selected index into <see cref="Suggestions"/> that the user has highlighted</summary>
    int SelectedIdx { get; set; }

    // TODO: Update to use Key instead of KeyCode
    /// <summary>The key that the user must press to accept the currently selected autocomplete suggestion</summary>
    KeyCode SelectionKey { get; set; }

    /// <summary>
    ///     Gets or Sets the class responsible for generating <see cref="Suggestions"/> based on a given
    ///     <see cref="AutocompleteContext"/> of the <see cref="HostControl"/>.
    /// </summary>
    ISuggestionGenerator SuggestionGenerator { get; set; }

    /// <summary>The strings that form the current list of suggestions to render based on what the user has typed so far.</summary>
    ReadOnlyCollection<Suggestion> Suggestions { get; set; }

    /// <summary>True if the autocomplete should be considered open and visible</summary>
    bool Visible { get; set; }

    /// <summary>Clears <see cref="Suggestions"/></summary>
    void ClearSuggestions ();

    /// <summary>
    ///     Populates <see cref="Suggestions"/> with all <see cref="Suggestion"/> proposed by
    ///     <see cref="SuggestionGenerator"/> at the given <paramref name="context"/> (cursor position)
    /// </summary>
    void GenerateSuggestions (AutocompleteContext context);

    /// <summary>
    ///     Handle mouse events before <see cref="HostControl"/> e.g. to make mouse events like report/click apply to the
    ///     autocomplete control instead of changing the cursor position in the underlying text view.
    /// </summary>
    /// <param name="me">The mouse event.</param>
    /// <param name="fromHost">If was called from the popup or from the host.</param>
    /// <returns><c>true</c>if the mouse can be handled <c>false</c>otherwise.</returns>
    bool OnMouseEvent (MouseEvent me, bool fromHost = false);

    /// <summary>
    ///     Handle key events before <see cref="HostControl"/> e.g. to make key events like up/down apply to the
    ///     autocomplete control instead of changing the cursor position in the underlying text view.
    /// </summary>
    /// <param name="a">The key event.</param>
    /// <returns><c>true</c>if the key can be handled <c>false</c>otherwise.</returns>
    bool ProcessKey (Key a);

    /// <summary>Renders the autocomplete dialog inside the given <see cref="HostControl"/> at the given point.</summary>
    /// <param name="renderAt"></param>
    void RenderOverlay (Point renderAt);
}