Переработаны методы.
This commit is contained in:
@@ -5,57 +5,80 @@
|
||||
/// в операции перетаскивания.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Объекты, реализующие этот интерфейс, могут инициировать операции перетаскивания
|
||||
/// и предоставлять данные для передачи другим элементам через механизм drag-and-drop.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Интерфейс полностью асинхронный и поддерживает отмену операций через CancellationToken.
|
||||
/// Все методы должны быть потокобезопасными и поддерживать вызов из любого потока.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public interface IDragSource
|
||||
{
|
||||
/// <summary>
|
||||
/// Определяет, может ли объект начать операцию перетаскивания.
|
||||
/// Пытается начать операцию перетаскивания из указанной позиции.
|
||||
/// </summary>
|
||||
/// <param name="startPosition">Начальная позиция операции в координатах экрана.</param>
|
||||
/// <param name="cancellationToken">Токен отмены операции.</param>
|
||||
/// <returns>
|
||||
/// Кортеж, содержащий флаг возможности начала перетаскивания и информацию о перетаскивании.
|
||||
/// Информация о перетаскивании, если операция может быть начата; в противном случае — null.
|
||||
/// Возвращаемый объект <see cref="Models.DragInfo"/> должен быть полностью инициализирован,
|
||||
/// включая данные, разрешенные эффекты и ссылку на источник.
|
||||
/// </returns>
|
||||
/// <remarks>
|
||||
/// Этот метод вызывается системой перетаскивания для проверки возможности
|
||||
/// начала операции. Если метод возвращает true, он должен заполнить
|
||||
/// DragInfo необходимыми данными.
|
||||
/// <para>
|
||||
/// Этот метод вызывается сервисом перетаскивания при попытке начать операцию
|
||||
/// (обычно при нажатии и перемещении мыши). Метод должен проверить, может ли
|
||||
/// источник начать перетаскивание в текущем контексте.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Реализация должна быть быстрой и не выполнять длительных операций.
|
||||
/// Если подготовка данных требует времени, ее следует выполнить асинхронно
|
||||
/// после подтверждения возможности начала.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
Task<(bool CanStart, Models.DragInfo? DragInfo)> CanStartDragAsync(CancellationToken cancellationToken = default);
|
||||
Task<Models.DragInfo?> TryStartDragAsync(Geometry.Point startPosition, CancellationToken cancellationToken = default);
|
||||
|
||||
/// <summary>
|
||||
/// Начинает операцию перетаскивания.
|
||||
/// Уведомляет источник о завершении операции перетаскивания.
|
||||
/// </summary>
|
||||
/// <param name="dragInfo">Информация о перетаскивании.</param>
|
||||
/// <returns>
|
||||
/// true, если операция перетаскивания успешно начата; в противном случае — false.
|
||||
/// </returns>
|
||||
/// <remarks>
|
||||
/// Этот метод вызывается, когда пользователь начинает перетаскивание элемента.
|
||||
/// Реализация должна подготовить данные для перетаскивания и, возможно,
|
||||
/// создать визуальное представление перетаскиваемого объекта.
|
||||
/// </remarks>
|
||||
Task<bool> StartDragAsync(Models.DragInfo dragInfo, CancellationToken cancellationToken = default);
|
||||
|
||||
/// <summary>
|
||||
/// Вызывается при завершении операции перетаскивания.
|
||||
/// </summary>
|
||||
/// <param name="dragInfo">Исходная информация о перетаскивании.</param>
|
||||
/// <param name="dragInfo">Информация о перетаскивании, полученная при начале операции.</param>
|
||||
/// <param name="effects">Эффекты, которые были применены при сбросе.</param>
|
||||
/// <param name="cancellationToken">Токен отмены операции.</param>
|
||||
/// <returns>Задача, представляющая асинхронную операцию.</returns>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Этот метод вызывается после завершения операции перетаскивания
|
||||
/// (успешного или неуспешного). Реализация может выполнить очистку
|
||||
/// или обновить состояние на основе результата операции.
|
||||
/// (успешного или неуспешного). Реализация может:
|
||||
/// </para>
|
||||
/// <list type="bullet">
|
||||
/// <item>Выполнить очистку ресурсов, связанных с операцией</item>
|
||||
/// <item>Обновить состояние на основе результата (например, удалить данные при перемещении)</item>
|
||||
/// <item>Отобразить визуальную обратную связь о результате</item>
|
||||
/// </list>
|
||||
/// <para>
|
||||
/// Если операция завершилась с эффектом <see cref="Enums.DragDropEffects.Move"/>,
|
||||
/// источник обычно должен удалить или обновить исходные данные.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
Task DragCompletedAsync(Models.DragInfo dragInfo, Enums.DragDropEffects effects, CancellationToken cancellationToken = default);
|
||||
Task OnDragCompletedAsync(Models.DragInfo dragInfo, Enums.DragDropEffects effects, CancellationToken cancellationToken = default);
|
||||
|
||||
/// <summary>
|
||||
/// Вызывается при отмене операции перетаскивания.
|
||||
/// Уведомляет источник об отмене операции перетаскивания.
|
||||
/// </summary>
|
||||
/// <param name="dragInfo">Исходная информация о перетаскивании.</param>
|
||||
/// <param name="dragInfo">Информация о перетаскивании, полученная при начале операции.</param>
|
||||
/// <param name="cancellationToken">Токен отмены операции.</param>
|
||||
/// <returns>Задача, представляющая асинхронную операцию.</returns>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Этот метод вызывается, когда операция перетаскивания была отменена
|
||||
/// пользователем (например, нажатием клавиши Escape).
|
||||
/// пользователем (например, нажатием клавиши Escape) или системой.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Реализация должна выполнить очистку и восстановить исходное состояние.
|
||||
/// Обычно это включает освобождение ресурсов и сброс визуальных индикаторов.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
Task DragCancelledAsync(Models.DragInfo dragInfo, CancellationToken cancellationToken = default);
|
||||
Task OnDragCancelledAsync(Models.DragInfo dragInfo, CancellationToken cancellationToken = default);
|
||||
}
|
||||
@@ -5,8 +5,15 @@
|
||||
/// в операции перетаскивания.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Объекты, реализующие этот интерфейс, могут обрабатывать данные, сброшенные
|
||||
/// пользователем, и предоставлять визуальную обратную связь во время перетаскивания.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Интерфейс поддерживает асинхронные операции и отмену через CancellationToken.
|
||||
/// Все методы должны быть потокобезопасными и идемпотентными (многократный вызов
|
||||
/// с одинаковыми параметрами должен давать одинаковый результат).
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public interface IDropTarget
|
||||
{
|
||||
@@ -14,42 +21,98 @@ public interface IDropTarget
|
||||
/// Определяет, может ли объект принять сбрасываемые данные.
|
||||
/// </summary>
|
||||
/// <param name="dropInfo">Информация о потенциальном сбросе.</param>
|
||||
/// <param name="cancellationToken">Токен отмены операции.</param>
|
||||
/// <returns>
|
||||
/// true, если объект может принять данные; в противном случае — false.
|
||||
/// </returns>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Этот метод вызывается, когда перетаскиваемый объект находится над целью.
|
||||
/// Реализация должна проверить, совместимы ли данные с целью, и установить
|
||||
/// предлагаемые эффекты в <paramref name="dropInfo"/>.
|
||||
/// предлагаемые эффекты в свойстве <see cref="Models.DropInfo.SuggestedEffects"/>.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Метод может вызываться многократно при перемещении курсора над целью.
|
||||
/// Реализация должна быть эффективной и избегать длительных операций.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Если метод возвращает false, система не будет вызывать другие методы
|
||||
/// для этой цели до тех пор, пока курсор не покинет ее область.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
Task<bool> CanAcceptDropAsync(Models.DropInfo dropInfo, CancellationToken cancellationToken = default);
|
||||
|
||||
/// <summary>
|
||||
/// Вызывается, когда перетаскиваемый объект находится над целью.
|
||||
/// Вызывается, когда перетаскиваемый объект перемещается над целью.
|
||||
/// </summary>
|
||||
/// <param name="dropInfo">Информация о текущем положении перетаскивания.</param>
|
||||
/// <param name="cancellationToken">Токен отмены операции.</param>
|
||||
/// <returns>Задача, представляющая асинхронную операцию.</returns>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Этот метод вызывается постоянно, пока пользователь перемещает объект над целью.
|
||||
/// Реализация может обновить визуальную обратную связь или изменить предлагаемые эффекты.
|
||||
/// Реализация может:
|
||||
/// </para>
|
||||
/// <list type="bullet">
|
||||
/// <item>Обновить визуальную обратную связь (подсветка, изменение курсора)</item>
|
||||
/// <item>Вычислить точную позицию сброса (например, между элементами списка)</item>
|
||||
/// <item>Уточнить предлагаемые эффекты на основе текущей позиции</item>
|
||||
/// <item>Прокрутить содержимое, если цель поддерживает прокрутку</item>
|
||||
/// </list>
|
||||
/// <para>
|
||||
/// Метод должен быть оптимизирован для частого вызова. Длительные операции
|
||||
/// должны выполняться асинхронно без блокировки потока.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
Task DragOverAsync(Models.DropInfo dropInfo, CancellationToken cancellationToken = default);
|
||||
Task OnDragOverAsync(Models.DropInfo dropInfo, CancellationToken cancellationToken = default);
|
||||
|
||||
/// <summary>
|
||||
/// Вызывается, когда пользователь сбрасывает данные на цель.
|
||||
/// </summary>
|
||||
/// <param name="dropInfo">Информация о сбросе.</param>
|
||||
/// <param name="dropInfo">Информация о сбросе, включая данные и позицию.</param>
|
||||
/// <param name="cancellationToken">Токен отмены операции.</param>
|
||||
/// <returns>Задача, представляющая асинхронную операцию.</returns>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Этот метод вызывается, когда пользователь отпускает кнопку мыши над целью.
|
||||
/// Реализация должна обработать принятие данных и выполнить соответствующее действие.
|
||||
/// Реализация должна обработать принятие данных и выполнить соответствующее действие:
|
||||
/// </para>
|
||||
/// <list type="bullet">
|
||||
/// <item>Добавить данные в коллекцию (для копирования)</item>
|
||||
/// <item>Переместить данные (при поддержке перемещения)</item>
|
||||
/// <item>Создать ссылку на данные</item>
|
||||
/// <item>Выполнить пользовательскую логику обработки</item>
|
||||
/// </list>
|
||||
/// <para>
|
||||
/// После успешной обработки данных следует вызвать <see cref="Models.DropInfo.MarkAsHandled()"/>,
|
||||
/// чтобы указать системе, что операция обработана и дополнительная обработка не требуется.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Если операция завершилась успешно, система уведомит источник через
|
||||
/// <see cref="IDragSource.OnDragCompletedAsync"/> с соответствующими эффектами.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
Task DropAsync(Models.DropInfo dropInfo, CancellationToken cancellationToken = default);
|
||||
Task OnDropAsync(Models.DropInfo dropInfo, CancellationToken cancellationToken = default);
|
||||
|
||||
/// <summary>
|
||||
/// Вызывается, когда перетаскиваемый объект покидает область цели.
|
||||
/// </summary>
|
||||
/// <param name="cancellationToken">Токен отмены операции.</param>
|
||||
/// <returns>Задача, представляющая асинхронную операцию.</returns>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Этот метод вызывается, когда пользователь перемещает объект за пределы цели.
|
||||
/// Реализация должна очистить любую визуальную обратную связь, установленную ранее.
|
||||
/// Реализация должна:
|
||||
/// </para>
|
||||
/// <list type="bullet">
|
||||
/// <item>Очистить любую визуальную обратную связь, установленную ранее</item>
|
||||
/// <item>Сбросить временное состояние, связанное с операцией</item>
|
||||
/// <item>Освободить ресурсы, выделенные для предварительного просмотра</item>
|
||||
/// </list>
|
||||
/// <para>
|
||||
/// Метод гарантированно вызывается после любого успешного или неуспешного
|
||||
/// вызова <see cref="OnDragOverAsync"/>, если курсор покидает область цели.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
Task DragLeaveAsync(CancellationToken cancellationToken = default);
|
||||
Task OnDragLeaveAsync(CancellationToken cancellationToken = default);
|
||||
}
|
||||
Reference in New Issue
Block a user