From 2f77b9c2aa0db159bfef00c138845b18635d631d Mon Sep 17 00:00:00 2001 From: Kurt Date: Fri, 23 May 2025 20:44:06 -0500 Subject: [PATCH] Add xmldoc --- .../Controls/PKM Editor/MoveDisplayState.cs | 21 ++++++++ .../Controls/PKM Editor/PKMEditor.cs | 17 ------ .../Controls/SAV Editor/SlotChangeManager.cs | 24 ++++----- PKHeX.WinForms/Controls/Slots/CryPlayer.cs | 27 ++++++++++ .../Slots/DoubleBufferedDataGridView.cs | 6 +++ PKHeX.WinForms/Controls/Slots/DragManager.cs | 42 ++++++++++++++- PKHeX.WinForms/Controls/Slots/DropModifier.cs | 12 +++++ .../Controls/Slots/SlotChangeInfo.cs | 52 +++++++++++++++---- .../Controls/Slots/SlotHoverHandler.cs | 22 ++++++++ .../Controls/Slots/SlotTrackerImage.cs | 14 ++++- 10 files changed, 195 insertions(+), 42 deletions(-) create mode 100644 PKHeX.WinForms/Controls/PKM Editor/MoveDisplayState.cs diff --git a/PKHeX.WinForms/Controls/PKM Editor/MoveDisplayState.cs b/PKHeX.WinForms/Controls/PKM Editor/MoveDisplayState.cs new file mode 100644 index 000000000..de7575876 --- /dev/null +++ b/PKHeX.WinForms/Controls/PKM Editor/MoveDisplayState.cs @@ -0,0 +1,21 @@ +using System.Drawing; +using System.Runtime.CompilerServices; +using PKHeX.Core; +using PKHeX.Drawing.PokeSprite.Properties; + +namespace PKHeX.WinForms.Controls; + +public static class MoveDisplayState +{ + [MethodImpl(MethodImplOptions.AggressiveInlining)] + public static Bitmap? GetMoveImage(bool isIllegal, PKM pk, int index) + { + if (isIllegal) + return Resources.warn; + + if (MoveInfo.IsDummiedMove(pk, index)) + return Resources.hint; + + return null; + } +} diff --git a/PKHeX.WinForms/Controls/PKM Editor/PKMEditor.cs b/PKHeX.WinForms/Controls/PKM Editor/PKMEditor.cs index f4dff6905..50692654d 100644 --- a/PKHeX.WinForms/Controls/PKM Editor/PKMEditor.cs +++ b/PKHeX.WinForms/Controls/PKM Editor/PKMEditor.cs @@ -2,13 +2,11 @@ using PKHeX.Drawing; using PKHeX.Drawing.Misc; using PKHeX.Drawing.PokeSprite; -using PKHeX.Drawing.PokeSprite.Properties; using System; using System.Collections.Generic; using System.ComponentModel; using System.Drawing; using System.Linq; -using System.Runtime.CompilerServices; using System.Text; using System.Windows.Forms; using static PKHeX.Core.MessageStrings; @@ -2299,18 +2297,3 @@ private void PB_MarkCured_Click(object sender, EventArgs e) CB_PKRSStrain.DroppedDown = true; } } - -public static class MoveDisplayState -{ - [MethodImpl(MethodImplOptions.AggressiveInlining)] - public static Bitmap? GetMoveImage(bool isIllegal, PKM pk, int index) - { - if (isIllegal) - return Resources.warn; - - if (MoveInfo.IsDummiedMove(pk, index)) - return Resources.hint; - - return null; - } -} diff --git a/PKHeX.WinForms/Controls/SAV Editor/SlotChangeManager.cs b/PKHeX.WinForms/Controls/SAV Editor/SlotChangeManager.cs index b07d5e582..88454a396 100644 --- a/PKHeX.WinForms/Controls/SAV Editor/SlotChangeManager.cs +++ b/PKHeX.WinForms/Controls/SAV Editor/SlotChangeManager.cs @@ -49,7 +49,7 @@ public void MouseClick(object? sender, MouseEventArgs e) { if (sender is null) return; - if (!Drag.Info.DragDropInProgress) + if (!Drag.Info.IsDragDropInProgress) SE.ClickSlot(sender, e); } @@ -58,7 +58,7 @@ public void MouseUp(object? sender, MouseEventArgs e) if (sender is null) return; if (e.Button == MouseButtons.Left) - Drag.Info.LeftMouseIsDown = false; + Drag.Info.IsLeftMouseDown = false; Drag.Info.Source = null; } @@ -68,7 +68,7 @@ public void MouseDown(object? sender, MouseEventArgs e) return; if (e.Button == MouseButtons.Left) { - Drag.Info.LeftMouseIsDown = true; + Drag.Info.IsLeftMouseDown = true; Drag.MouseDownPosition = Cursor.Position; } } @@ -79,8 +79,8 @@ public void QueryContinueDrag(object? sender, QueryContinueDragEventArgs e) return; if (e.Action != DragAction.Cancel && e.Action != DragAction.Drop) return; - Drag.Info.LeftMouseIsDown = false; - Drag.Info.DragDropInProgress = false; + Drag.Info.IsLeftMouseDown = false; + Drag.Info.IsDragDropInProgress = false; } public void DragEnter(object? sender, DragEventArgs e) @@ -92,7 +92,7 @@ public void DragEnter(object? sender, DragEventArgs e) else if (e.Data is not null) // within e.Effect = DragDropEffects.Move; - if (Drag.Info.DragDropInProgress) + if (Drag.Info.IsDragDropInProgress) Drag.SetCursor(((Control)sender).FindForm(), Drag.Info.Cursor); } @@ -144,7 +144,7 @@ private void HandleMovePKM(PictureBox pb, bool encrypt) // Create a temporary PKM file to perform a drag drop operation. // Set flag to prevent re-entering. - Drag.Info.DragDropInProgress = true; + Drag.Info.IsDragDropInProgress = true; // Prepare Data Drag.Info.Source = GetSlotInfo(pb); @@ -163,7 +163,7 @@ private void HandleMovePKM(PictureBox pb, bool encrypt) // Keep it to 20 seconds; Discord upload only stores the file path until you click Upload. int delay = external ? 20_000 : 0; DeleteAsync(newfile, delay); - if (Drag.Info.DragIsParty) + if (Drag.Info.IsDragParty) SE.SetParty(); } @@ -219,7 +219,7 @@ private bool TryMakeDragDropPKM(PictureBox pb, ReadOnlySpan data, string n Drag.Info.CurrentPath = newfile; var result = pb.DoDragDrop(new DataObject(DataFormats.FileDrop, new[] { newfile }), DragDropEffects.Copy); var external = Drag.Info.Destination is null || result != DragDropEffects.Link; - if (external || Drag.Info.SameLocation) // not dropped to another box slot, restore img + if (external || Drag.Info.IsDragSameLocation) // not dropped to another box slot, restore img { pb.Image = img; pb.BackgroundImage = LastSlot.OriginalBackground; @@ -254,7 +254,7 @@ private void HandleDropPKM(PictureBox pb, DragEventArgs? e, DropModifier mod) e.Effect = mod == DropModifier.Clone ? DragDropEffects.Copy : DragDropEffects.Link; // file - if (Drag.Info.SameLocation) + if (Drag.Info.IsDragSameLocation) { e.Effect = DragDropEffects.Link; return; @@ -345,7 +345,7 @@ private bool TrySetPKMDestination(PictureBox pb, DropModifier mod) TrySetPKMSource(mod); // Copy from temp to destination slot. - var type = info.DragIsSwap ? SlotTouchType.Swap : SlotTouchType.Set; + var type = info.IsDragSwap ? SlotTouchType.Swap : SlotTouchType.Set; Env.Slots.Set(info.Destination!.Slot, pk, type); Drag.ResetCursor(pb.FindForm()); return true; @@ -364,7 +364,7 @@ private bool TrySetPKMSource(DropModifier mod) return true; } - var type = info.DragIsSwap ? SlotTouchType.Swap : SlotTouchType.Set; + var type = info.IsDragSwap ? SlotTouchType.Swap : SlotTouchType.Set; var pk = dest.ReadCurrent(); Env.Slots.Set(Drag.Info.Source!.Slot, pk, type); return true; diff --git a/PKHeX.WinForms/Controls/Slots/CryPlayer.cs b/PKHeX.WinForms/Controls/Slots/CryPlayer.cs index c432bdb87..c401cd745 100644 --- a/PKHeX.WinForms/Controls/Slots/CryPlayer.cs +++ b/PKHeX.WinForms/Controls/Slots/CryPlayer.cs @@ -6,10 +6,21 @@ namespace PKHeX.WinForms.Controls; +/// +/// Provides functionality to play Pokémon cries using sound files. +/// public sealed class CryPlayer { + /// + /// The instance used to play sound files. + /// private readonly SoundPlayer Sounds = new(); + /// + /// Plays the cry for the specified Pokémon species and form. + /// + /// The Pokémon species and form information. + /// The entity context (game generation). public void PlayCry(ISpeciesForm pk, EntityContext context) { if (pk.Species == 0) @@ -24,6 +35,9 @@ public void PlayCry(ISpeciesForm pk, EntityContext context) catch { Debug.WriteLine("Failed to play sound."); } } + /// + /// Stops any currently playing cry. + /// public void Stop() { if (string.IsNullOrWhiteSpace(Sounds.SoundLocation)) @@ -33,6 +47,13 @@ public void Stop() catch { Debug.WriteLine("Failed to stop sound."); } } + /// + /// Gets the file path for the cry sound file for the specified Pokémon. + /// + /// The Pokémon species and form information. + /// The folder containing cry sound files. + /// The entity context (game generation). + /// The file path to the cry sound file. private static string GetCryPath(ISpeciesForm pk, string cryFolder, EntityContext context) { var name = GetCryFileName(pk, context); @@ -42,6 +63,12 @@ private static string GetCryPath(ISpeciesForm pk, string cryFolder, EntityContex return path; } + /// + /// Gets the file name for the cry sound file for the specified Pokémon. + /// + /// The Pokémon species and form information. + /// The entity context (game generation). + /// The file name for the cry sound file. private static string GetCryFileName(ISpeciesForm pk, EntityContext context) { if (pk is { Species: (int)Species.Urshifu, Form: 1 }) // same sprite for both forms, but different cries diff --git a/PKHeX.WinForms/Controls/Slots/DoubleBufferedDataGridView.cs b/PKHeX.WinForms/Controls/Slots/DoubleBufferedDataGridView.cs index 05611620e..1b61e0317 100644 --- a/PKHeX.WinForms/Controls/Slots/DoubleBufferedDataGridView.cs +++ b/PKHeX.WinForms/Controls/Slots/DoubleBufferedDataGridView.cs @@ -2,7 +2,13 @@ namespace PKHeX.WinForms.Controls; +/// +/// Provides a DataGridView with double buffering enabled to reduce flicker. +/// internal class DoubleBufferedDataGridView : DataGridView { + /// + /// Initializes a new instance of the class. + /// public DoubleBufferedDataGridView() => SetStyle(ControlStyles.OptimizedDoubleBuffer, true); } diff --git a/PKHeX.WinForms/Controls/Slots/DragManager.cs b/PKHeX.WinForms/Controls/Slots/DragManager.cs index b9c492ece..dd512d9ae 100644 --- a/PKHeX.WinForms/Controls/Slots/DragManager.cs +++ b/PKHeX.WinForms/Controls/Slots/DragManager.cs @@ -1,14 +1,35 @@ -using System.Drawing; +using System.Drawing; using System.Windows.Forms; namespace PKHeX.WinForms.Controls; +/// +/// Manages drag-and-drop operations for slot controls. +/// public sealed class DragManager { + /// + /// Gets the current slot change information for drag-and-drop operations. + /// public SlotChangeInfo Info { get; private set; } = new(); + + /// + /// Occurs when an external drag-and-drop operation is requested. + /// public event DragEventHandler? RequestExternalDragDrop; + + /// + /// Requests a drag-and-drop operation. + /// + /// The sender of the event. + /// The drag event arguments. public void RequestDD(object sender, DragEventArgs e) => RequestExternalDragDrop?.Invoke(sender, e); + /// + /// Sets the cursor for the specified form and updates the drag info. + /// + /// The form to set the cursor for. + /// The cursor to set. public void SetCursor(Form? f, Cursor? z) { if (f is not null) @@ -16,18 +37,35 @@ public void SetCursor(Form? f, Cursor? z) Info.Cursor = z; } + /// + /// Resets the cursor for the specified form to the default cursor. + /// + /// The form to reset the cursor for. public void ResetCursor(Form? sender) { SetCursor(sender, Cursors.Default); } + /// + /// Initializes the drag manager and resets the drag info. + /// public void Initialize() { Info = new SlotChangeInfo(); } + /// + /// Resets the drag manager's slot change info. + /// public void Reset() => Info.Reset(); + /// + /// Gets or sets the mouse down position for drag detection. + /// public Point MouseDownPosition { private get; set; } - public bool CanStartDrag => Info.LeftMouseIsDown && !Cursor.Position.Equals(MouseDownPosition); + + /// + /// Gets a value indicating whether a drag operation can be started. + /// + public bool CanStartDrag => Info.IsLeftMouseDown && !Cursor.Position.Equals(MouseDownPosition); } diff --git a/PKHeX.WinForms/Controls/Slots/DropModifier.cs b/PKHeX.WinForms/Controls/Slots/DropModifier.cs index a4c1bcdaf..dbe3b4859 100644 --- a/PKHeX.WinForms/Controls/Slots/DropModifier.cs +++ b/PKHeX.WinForms/Controls/Slots/DropModifier.cs @@ -1,8 +1,20 @@ namespace PKHeX.WinForms.Controls; +/// +/// Specifies the modifier for a drag-and-drop operation. +/// public enum DropModifier { + /// + /// No modifier is applied. + /// None, + /// + /// Overwrite the target slot. + /// Overwrite, + /// + /// Clone the source slot. + /// Clone, } diff --git a/PKHeX.WinForms/Controls/Slots/SlotChangeInfo.cs b/PKHeX.WinForms/Controls/Slots/SlotChangeInfo.cs index dbdcba142..5abaf73dd 100644 --- a/PKHeX.WinForms/Controls/Slots/SlotChangeInfo.cs +++ b/PKHeX.WinForms/Controls/Slots/SlotChangeInfo.cs @@ -2,35 +2,67 @@ namespace PKHeX.WinForms.Controls; +/// +/// Represents information about a slot change during drag-and-drop operations. +/// +/// The type of the cursor object. +/// The type of the image source object. public sealed class SlotChangeInfo where TCursor : class where TImageSource : class { - public bool LeftMouseIsDown { get; set; } - public bool DragDropInProgress { get; set; } - + /// + /// Gets or sets a value indicating whether the left mouse button is down. + /// + public bool IsLeftMouseDown { get; set; } + /// + /// Gets or sets a value indicating whether a drag-and-drop operation is in progress. + /// + public bool IsDragDropInProgress { get; set; } + /// + /// Gets or sets the current cursor. + /// public TCursor? Cursor { get; set; } + /// + /// Gets or sets the current file path involved in the drag-and-drop operation. + /// public string? CurrentPath { get; set; } + /// + /// Slot that is being dragged from. + /// public SlotViewInfo? Source { get; set; } + + /// + /// Slot that is being dragged to. + /// public SlotViewInfo? Destination { get; set; } + /// + /// Resets the slot change information to its default state. + /// public void Reset() { - LeftMouseIsDown = DragDropInProgress = false; + IsLeftMouseDown = IsDragDropInProgress = false; CurrentPath = null; Cursor = null; } - public bool SameLocation => (Destination is not null) && (Source?.Equals(Destination) ?? false); - - private bool SourceIsParty => Source?.Slot is SlotInfoParty; - private bool DestinationIsParty => Destination?.Slot is SlotInfoParty; + private bool IsSourceParty => Source?.Slot is SlotInfoParty; + private bool IsDestinationParty => Destination?.Slot is SlotInfoParty; /// /// Used to indicate if the changes will alter the player's party data state. /// - public bool DragIsParty => SourceIsParty || DestinationIsParty; + public bool IsDragParty => IsSourceParty || IsDestinationParty; - public bool DragIsSwap => Source is not null && Destination is not null; + /// + /// Used to indicate if the changes will involve two slots within the program. + /// + public bool IsDragSwap => Source is not null && Destination is not null; + + /// + /// Used to indicate if the changes will involve two slots within the same location. + /// + public bool IsDragSameLocation => (Destination is not null) && (Source?.Equals(Destination) ?? false); } diff --git a/PKHeX.WinForms/Controls/Slots/SlotHoverHandler.cs b/PKHeX.WinForms/Controls/Slots/SlotHoverHandler.cs index c46f92e7b..cc4efcee7 100644 --- a/PKHeX.WinForms/Controls/Slots/SlotHoverHandler.cs +++ b/PKHeX.WinForms/Controls/Slots/SlotHoverHandler.cs @@ -12,7 +12,14 @@ namespace PKHeX.WinForms.Controls; /// public sealed class SlotHoverHandler : IDisposable { + /// + /// Gets or sets the drawing configuration for the slot hover effect. + /// public DrawConfig Draw { private get; set; } = new(); + + /// + /// Gets or sets a value indicating whether the hover effect should display a glow. + /// public bool GlowHover { private get; set; } = true; private readonly SummaryPreviewer Preview = new(); @@ -23,6 +30,11 @@ public sealed class SlotHoverHandler : IDisposable private PictureBox? Slot; private SlotTrackerImage? LastSlot; + /// + /// Starts the hover animation and preview for the specified slot. + /// + /// The PictureBox representing the slot to animate. + /// The last slot tracker image to update. public void Start(PictureBox pb, SlotTrackerImage lastSlot) { var view = WinFormsUtil.FindFirstControlOfType>(pb); @@ -59,6 +71,9 @@ public void Start(PictureBox pb, SlotTrackerImage lastSlot) Preview.Show(pb, pk); } + /// + /// Stops the hover animation and restores the original slot background. + /// public void Stop() { if (Slot is not null) @@ -73,6 +88,9 @@ public void Stop() Preview.Clear(); } + /// + /// Releases all resources used by the . + /// public void Dispose() { HoverWorker.Dispose(); @@ -80,6 +98,10 @@ public void Dispose() Draw.Dispose(); } + /// + /// Updates the mouse position for the preview display. + /// + /// The current mouse location. public void UpdateMousePosition(Point location) { Preview.UpdatePreviewPosition(location); diff --git a/PKHeX.WinForms/Controls/Slots/SlotTrackerImage.cs b/PKHeX.WinForms/Controls/Slots/SlotTrackerImage.cs index 3bc21ac77..ffc186a83 100644 --- a/PKHeX.WinForms/Controls/Slots/SlotTrackerImage.cs +++ b/PKHeX.WinForms/Controls/Slots/SlotTrackerImage.cs @@ -1,12 +1,24 @@ -using System.Drawing; +using System.Drawing; namespace PKHeX.WinForms.Controls; +/// +/// Tracks the background images for a slot, including the original and current backgrounds. +/// public sealed class SlotTrackerImage { + /// + /// Gets or sets the original background image of the slot. + /// public Image? OriginalBackground { get; set; } + /// + /// Gets or sets the current background image of the slot. + /// public Image? CurrentBackground { get; set; } + /// + /// Resets the background images to null. + /// public void Reset() { OriginalBackground = CurrentBackground = null;