Lattice/Lattice.UI.Docking/Abstractions/IDockHost.cs

using Lattice.Core.Docking.Abstractions;
using Lattice.Core.Docking.Models;

namespace Lattice.UI.Docking.Abstractions;

/// <summary>
/// Определяет контракт для главного контейнера док-системы, который служит корневым элементом
/// для всего пользовательского интерфейса системы докинга. Управляет размещением и состоянием
/// всех дочерних элементов, включая плавающие окна и автоскрываемые панели.
/// </summary>
/// <remarks>
/// Реализации этого интерфейса представляют собой центральный координатор UI-слоя,
/// который интегрирует функциональность менеджера макета, системы перетаскивания
/// и контекстных меню в единый визуальный компонент.
/// </remarks>
public interface IDockHost : IDockControl
{
    /// <summary>
    /// Получает коллекцию контролов плавающих окон, связанных с этим хостом.
    /// </summary>
    /// <value>
    /// Коллекция объектов, реализующих <see cref="IFloatingWindowControl"/>,
    /// представляющих все активные плавающие окна в системе.
    /// </value>
    /// <remarks>
    /// Плавающие окна могут быть созданы пользователем путем перетаскивания элементов
    /// за пределы основного окна или программно через методы API.
    /// </remarks>
    IEnumerable<IFloatingWindowControl> FloatingWindows { get; }

    /// <summary>
    /// Получает коллекцию контролов автоскрываемых панелей, прикрепленных к краям окна.
    /// </summary>
    /// <value>
    /// Коллекция объектов, реализующих <see cref="IAutoHidePanelControl"/>,
    /// представляющих автоскрываемые панели на разных сторонах окна.
    /// </value>
    /// <remarks>
    /// Автоскрываемые панели скрываются, оставляя видимой только полоску-заголовок,
    /// и разворачиваются при наведении курсора или клике.
    /// </remarks>
    IEnumerable<IAutoHidePanelControl> AutoHidePanels { get; }

    /// <summary>
    /// Получает или задает значение, указывающее, отображается ли панель инструментов (Toolbox).
    /// </summary>
    /// <value>
    /// true, если панель инструментов видима; в противном случае — false.
    /// Значение по умолчанию зависит от реализации.
    /// </value>
    /// <remarks>
    /// Панель инструментов обычно содержит элементы для быстрого доступа к командам
    /// или создания новых компонентов в приложении.
    /// </remarks>
    bool ShowToolbox { get; set; }

    /// <summary>
    /// Получает или задает значение, указывающее, отображается ли строка состояния.
    /// </summary>
    /// <value>
    /// true, если строка состояния видима; в противном случае — false.
    /// Значение по умолчанию зависит от реализации.
    /// </value>
    /// <remarks>
    /// Строка состояния обычно отображает текущий статус приложения,
    /// информацию о выбранном элементе или прогресс выполнения операций.
    /// </remarks>
    bool ShowStatusBar { get; set; }

    /// <summary>
    /// Получает или задает значение, указывающее, отображается ли главное меню приложения.
    /// </summary>
    /// <value>
    /// true, если главное меню видимо; в противном случае — false.
    /// Значение по умолчанию зависит от реализации.
    /// </remarks>
    bool ShowMenu { get; set; }

    /// <summary>
    /// Создает новое плавающее окно для размещения указанного элемента док-системы.
    /// </summary>
    /// <param name="element">
    /// Элемент док-системы (группа или лист), который будет размещен в плавающем окне.
    /// </param>
    /// <param name="title">Заголовок создаваемого окна.</param>
    /// <returns>
    /// Экземпляр <see cref="IFloatingWindowControl"/>, представляющий созданное плавающее окно.
    /// </returns>
    /// <exception cref="ArgumentNullException">
    /// Выбрасывается, если <paramref name="element"/> равен null.
    /// </exception>
    /// <remarks>
    /// Созданное окно может быть перемещено пользователем в любое место экрана,
    /// изменено в размерах и обычно содержит стандартные элементы управления окном
    /// (заголовок, кнопки закрытия/сворачивания).
    /// </remarks>
    IFloatingWindowControl CreateFloatingWindow(IDockElement element, string title);

    /// <summary>
    /// Закрывает указанное плавающее окно и возвращает его содержимое в основной макет.
    /// </summary>
    /// <param name="window">
    /// Плавающее окно, которое необходимо закрыть.
    /// </param>
    /// <exception cref="ArgumentNullException">
    /// Выбрасывается, если <paramref name="window"/> равен null.
    /// </exception>
    /// <remarks>
    /// При закрытии плавающего окна его содержимое обычно возвращается в то место
    /// в основном макете, откуда оно было извлечено, или в ближайшую допустимую позицию.
    /// </remarks>
    void CloseFloatingWindow(IFloatingWindowControl window);

    /// <summary>
    /// Добавляет автоскрываемую панель с указанным содержимым к заданной стороне окна.
    /// </summary>
    /// <param name="content">
    /// Контент, который будет отображаться в автоскрываемой панели.
    /// </param>
    /// <param name="side">
    /// Сторона окна, к которой будет прикреплена панель.
    /// </param>
    /// <returns>
    /// Экземпляр <see cref="IAutoHidePanelControl"/>, представляющий созданную панель.
    /// </returns>
    /// <exception cref="ArgumentNullException">
    /// Выбрасывается, если <paramref name="content"/> равен null.
    /// </exception>
    /// <remarks>
    /// Автоскрываемые панели полезны для инструментов, к которым нужен частый,
    /// но не постоянный доступ, так как они экономят пространство экрана.
    /// </remarks>
    IAutoHidePanelControl AddAutoHidePanel(Core.Docking.Abstractions.IDockContent content, DockSide side);

    /// <summary>
    /// Удаляет автоскрываемую панель из интерфейса.
    /// </summary>
    /// <param name="panel">
    /// Автоскрываемая панель, которую необходимо удалить.
    /// </param>
    /// <exception cref="ArgumentNullException">
    /// Выбрасывается, если <paramref name="panel"/> равен null.
    /// </exception>
    /// <remarks>
    /// После удаления панели её содержимое обычно либо закрывается полностью,
    /// либо преобразуется в обычную закрепленную панель, в зависимости от настроек.
    /// </remarks>
    void RemoveAutoHidePanel(IAutoHidePanelControl panel);

    /// <summary>
    /// Событие, возникающее при изменении структуры макета док-системы.
    /// </summary>
    /// <remarks>
    /// Может вызываться при добавлении/удалении элементов, изменении размеров,
    /// создании/закрытии плавающих окон и других операциях, влияющих на компоновку.
    /// </remarks>
    event EventHandler LayoutChanged;

    /// <summary>
    /// Событие, возникающее при создании нового плавающего окна.
    /// </summary>
    event EventHandler<FloatingWindowCreatedEventArgs> FloatingWindowCreated;

    /// <summary>
    /// Событие, возникающее при закрытии плавающего окна.
    /// </summary>
    event EventHandler<FloatingWindowClosedEventArgs> FloatingWindowClosed;
}

/// <summary>
/// Предоставляет данные для события создания плавающего окна.
/// Содержит ссылку на созданное окно и информацию о его содержимом.
/// </summary>
public class FloatingWindowCreatedEventArgs : EventArgs
{
    /// <summary>
    /// Получает созданное плавающее окно.
    /// </summary>
    /// <value>
    /// Экземпляр <see cref="IFloatingWindowControl"/>, представляющий новое окно.
    /// </value>
    public IFloatingWindowControl Window { get; }

    /// <summary>
    /// Инициализирует новый экземпляр класса <see cref="FloatingWindowCreatedEventArgs"/>.
    /// </summary>
    /// <param name="window">Созданное плавающее окно.</param>
    /// <exception cref="ArgumentNullException">
    /// Выбрасывается, если <paramref name="window"/> равен null.
    /// </exception>
    public FloatingWindowCreatedEventArgs(IFloatingWindowControl window)
    {
        Window = window ?? throw new ArgumentNullException(nameof(window));
    }
}

/// <summary>
/// Предоставляет данные для события закрытия плавающего окна.
/// Содержит ссылку на закрываемое окно и информацию о причине закрытия.
/// </summary>
public class FloatingWindowClosedEventArgs : EventArgs
{
    /// <summary>
    /// Получает закрытое плавающее окно.
    /// </summary>
    /// <value>
    /// Экземпляр <see cref="IFloatingWindowControl"/>, представляющее закрытое окно.
    /// </value>
    public IFloatingWindowControl Window { get; }

    /// <summary>
    /// Получает значение, указывающее, было ли окно закрыто пользователем.
    /// </summary>
    /// <value>
    /// true, если окно было закрыто действием пользователя (клик на крестик);
    /// false, если закрытие было инициировано программно.
    /// </value>
    public bool IsUserInitiated { get; }

    /// <summary>
    /// Инициализирует новый экземпляр класса <see cref="FloatingWindowClosedEventArgs"/>.
    /// </summary>
    /// <param name="window">Закрытое плавающее окно.</param>
    /// <param name="isUserInitiated">
    /// Признак того, что закрытие было инициировано пользователем.
    /// </param>
    /// <exception cref="ArgumentNullException">
    /// Выбрасывается, если <paramref name="window"/> равен null.
    /// </exception>
    public FloatingWindowClosedEventArgs(IFloatingWindowControl window, bool isUserInitiated = true)
    {
        Window = window ?? throw new ArgumentNullException(nameof(window));
        IsUserInitiated = isUserInitiated;
    }
}