DragAndDrop core

Lattice.UI.Docking/Abstractions/IDockHost.cs

@@ -0,0 +1,235 @@
+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;
+    }
+}