diff --git a/AGENTS.md b/AGENTS.md index 4298de6180..609948763c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,31 +1,74 @@ # Repository Guidelines -## Recent Tooling Mistakes To Avoid +## Always -- Do not combine `cmd.exe` variable assignment and use in the same command line. `%VAR%` is expanded before `set` takes effect, which created a stash named `"%STASH_MSG%"`. Correct example: `git stash push -m "3493-followup" -- .` -- Do not pass complex PowerShell through `cmd.exe` with unescaped `$variables`; `cmd.exe` can strip or alter the command before PowerShell sees it. Correct example: run PowerShell directly with `$path = Join-Path (Get-Location) 'AGENTS.md'; Get-Content -LiteralPath $path -Raw`. -- Do not build long `git commit -m` commands when the body contains tokens such as `--check`; argument parsing can treat body text as options. Correct example: write the message to a temp file and run `git commit -F `. -- Do not rely on shell quotes for `gh` arguments with spaces when the wrapper has already mishandled them. Correct example: use a JSON input file with `gh api ... --input ` or a PowerShell argument array. -- Do not try to rename an existing stash with `git stash store -m`; stash display names may still come from the original stash commit. Correct example: re-apply the stash, then create a fresh `git stash push -m "3493-followup" -- .` if the label matters. -- Do not over-escape regex patterns for `rg`. A pattern like `msbuild\\.exe` can search for the wrong text. Correct example in PowerShell: `$pattern = 'msbuild\.exe'; $root = 'Scripts'; rg -n $pattern $root --glob '*.cmd'`. -- Do not use `findstr` quoted path experiments for ordinary file reads or searches. Correct example: `$path = 'Scripts\VS2022\rebuild-build-nightly.cmd'; Select-String -LiteralPath $path -Pattern 'nightly.proj'`. +Before considering a task complete: + +- Build the affected project if instructed. +- Treat new analyzer warnings as part of the build unless they already existed. +- Update TestForm when adding a feature. +- Update Changelog.md for completed features and bug fixes. +- Add developer documentation for substantial new features. + +## Shell Guidelines + +- Prefer PowerShell for shell commands. +- Use cmd.exe only when reproducing Windows batch behavior. +- Use PowerShell cmdlets instead of findstr where possible. +- Avoid relying on cmd.exe variable expansion for complex commands. +- For complex Git operations, prefer temporary files or PowerShell arrays over long quoted command lines. ## Environment - OS: Windows -- Shell: Use PowerShell for agentic shell calls. Use `cmd.exe` only when invoking or reproducing Windows batch-script behavior. - Tools: Visual Studio 2022 (v17) and appropriate .NET SDKs starting with `net472` -- Build scripts are Windows `.cmd` files under `Scripts/` -- Do not run build scripts unless instructed to do so +- Build scripts are Windows `.cmd` files under `Scripts/`; do not run them unless explicitly instructed (see **Build, Test, and Development Commands**) ## Project Structure & Module Organization - `Source/Krypton Components`: Core libraries (`Krypton.Toolkit`, `Krypton.Ribbon`, `Krypton.Navigator`, `Krypton.Workspace`, `Krypton.Docking`) and the solution `Krypton Toolkit Suite 2022 - VS2022.sln` -- `Source/Krypton Components/TestForm`: WinForms sample app used to validate changes +- `Source/Krypton Components/TestForm`: WinForms sample app used to validate changes; add or extend demos here when features or bugs are completed (see **TestForm Demos**) - `Source/TestHarnesses`: Small repro/test harnesses (e.g., `ThemeSwapRepro`) - `Scripts/`: Build and packaging scripts; `run.cmd` (root) launches an interactive menu; scripts live under `Scripts/VS2022/`, `Scripts/Current/`, `Scripts/Build/` (e.g., `build-stable.cmd`, `build-canary.cmd`, `build-nightly.cmd`, `build.proj`) - `Bin/`: Build outputs by configuration (e.g., `Bin/Debug`) - `Documents/`, `Assets/`, `Logs/`: Docs, images, and build logs +- `Documents/Changelog/Changelog.md`: User-facing release notes for completed bugs and features +- `Documents/Development/`: In-depth developer guides for completed features (APIs, architecture, usage); not listed in `Documents/Changelog/Changelog.md` or `Scripts/ModernBuild/README.md` + +## Architecture + +- `Krypton.Toolkit` contains the shared infrastructure. +- `Krypton.Ribbon` depends on `Krypton.Toolkit`. +- `Krypton.Navigator` depends on `Krypton.Toolkit`. +- Rendering flows through the palette and renderer abstractions. +- New controls should integrate with the palette system rather than hardcoding appearance. + +## Editing Philosophy + +- Make the smallest change that correctly solves the task. +- Preserve existing formatting and coding style. +- Do not refactor unrelated code. +- Do not rename identifiers unless requested. + +## Public API + +### Compatibility + +- New code must remain compatible with `net472`. +- Do not use language features newer than C# 7.3 unless the project already conditionally supports them. + +### Stability + +- Preserve binary compatibility unless explicitly instructed otherwise. +- Avoid changing public or protected member signatures unless explicitly requested. +- Do not rename public types or namespaces. +- Preserve designer serialization compatibility. + +## Performance + +- Avoid unnecessary allocations in paint paths. +- Avoid creating disposable GDI objects inside tight rendering loops. +- Reuse existing rendering infrastructure whenever possible. ## Build, Test, and Development Commands @@ -55,25 +98,191 @@ ## C# Rules -- Surgical edits: preserve structure, identifiers, and existing comments; avoid adding defensive checks unless asked +- Preserve the existing nullable reference type annotations and context (`enable` is set at project level). +- Do not enable or disable nullable in individual files unless requested. - No unneeded `try/catch` blocks if there's no catch handling - Idioms: use null-propagation and object/collection initializers where consistent -- Fix compiler, analyzer, and IDE warnings in new or modified code before handing work back - Prefer switch expressions for simple value/type dispatch that only returns a value; keep switch statements for complex control flow or side effects -- Compatibility: ensure changes build for `net472` and C# 7.3 - WinForms: `UseWindowsForms=true`; prefer designer-friendly patterns and keep partial classes tidy - WinForms designer: keep object declarations at file bottom; initialize in `*.Designer.cs` `InitializeComponent()` +- Do not manually edit generated `*.Designer.cs` files unless the task specifically requires it. - Constraint: do not use `yield return` inside `catch` blocks +## Code Documentation Guidelines + +When asked to review or document code, add comments only where they help a maintainer understand **non-obvious** behavior. Do not narrate what the code already says. + +### What to comment + +- **Class-level summaries** for types that participate in a larger model (composite trees, state machines, store/restore flows, drag hosts). Name sibling types and the role of the class in the hierarchy. +- **Inline comments** at decision points for: + - Multi-step algorithms (store-then-restore, orphan handling, greedy layout shrink) + - Propagation (`PropogateAction`, `StartUpdate`/`EndUpdate`, reverse child iteration) + - State machines and message-filter / focus edge cases + - Drag-drop choreography (hidden float window reuse, target priority, placeholder pages) + - XML persistence quirks (element order, attribute meaning, misnamed APIs, buffer length) + - Geometry or ordering that is not obvious from property names (z-order, hot vs draw rects, remainder path parsing) +- **Brief region comments** above enum groups that act as a catalog for a subsystem (e.g. propagation actions). + +### What not to comment + +- Obvious boilerplate (`// This constructor creates an instance of X`, `// Return the result`, restating parameter names). +- Every public member when XML documentation already describes intent adequately. +- **Event Args**, **Resources**, **Designer** / **`.Designer.cs`**, and other thin property-bag or generated files unless logic is non-trivial. +- Large blocks of unchanged legacy code unrelated to the task. + +### Style + +- Keep comments **clear and concise** — one or two sentences; prefer plain language over jargon. +- Preserve existing comments and XML docs; extend or clarify them surgically rather than replacing wholesale. +- Use `///` XML summaries for types and public API; use `//` for inline implementation notes. +- In XML, use `` and `...` to link related types and enum values. +- Match surrounding voice (this codebase often uses short `//` notes inside `switch` arms and multi-step flows). + +### Prioritization (large modules) + +For substantial packages (e.g. `Krypton.Docking`), work in this order: + +1. Root orchestrator and base abstractions (manager, element base, definitions/enums). +2. Core implementation layers (space/edge/group elements, primary controls). +3. Specialized flows (auto-hidden slide, drag targets, persistence load/save). +4. Thin subclasses and adapters last — often a one-line class summary is enough. + +Validate documentation-only changes with a targeted `dotnet build` of the affected project when practical. + +## Feature Developer Documentation + +When a **new feature** is completed (not bug fixes or refactors unless they introduce a substantial new capability), add a **comprehensive developer guide** as a Markdown file under `Documents/Development/`. + +### When to write + +- New public APIs, components, designer support, build/packaging features, or user-facing subsystems. +- Skip for trivial fixes, comment-only changes, and internal refactors with no new surface area. + +### What to include + +Each guide should be **in-depth** and **maintainer-focused**, covering as applicable: + +- **Overview** — problem solved, scope, and which package(s) own the feature. +- **Architecture** — key types, relationships, and data/control flow (diagrams welcome). +- **Public API** — classes, interfaces, enums, events, and extension points with signatures and behavior. +- **Usage** — minimal code or designer steps; common integration patterns. +- **Configuration / persistence** — settings, XML, flags, or MSBuild properties if relevant. +- **Edge cases** — threading, TFM differences, breaking changes, migration notes. +- **Validation** — how to exercise the feature in `TestForm` or a harness (link to the demo form registered in `StartScreen`). + +### TestForm demo + +When the feature warrants user-visible validation, add or update a demo per **TestForm Demos** and reference it here. + +### File conventions + +- Location: `Documents/Development/` +- Name: descriptive kebab or Pascal-style title, e.g. `Krypton-Docking-Developer-Guide.md` or `Visual-Studio-Templates-Developer-Guide.md`. +- One feature (or cohesive subsystem) per file; cross-link related guides when helpful. +- CRLF, UTF-8; match tone and structure of existing repo docs. + +### Do not list in these files + +- **Do not** add changelog entries or release notes for these guides in `Documents/Changelog/Changelog.md`. +- **Do not** add references or index entries for these guides in `Scripts/ModernBuild/README.md`. + +Changelog and ModernBuild README stay focused on user-facing release history and build tooling respectively. Developer guides are discovered via `Documents/Development/` and code cross-references only. + +## Changelog + +When a **bug fix** or **feature** is completed, add an entry to `Documents/Changelog/Changelog.md` in the same change set (or immediately before merge). + +### When to update + +- **Resolved** — bug fixes, regressions, and defect corrections tied to an issue. +- **Implemented** — new features, enhancements, and new public capability. +- Skip changelog updates for comment-only work, internal refactors with no user-visible effect, and `Documents/Development/` guide files (those are separate from release notes). + +### Where to add + +- Append to the **current in-progress release** section at the top of the file (the first `##` heading after the table of contents), e.g. `## 2026-11-xx - Build 2611 (V110 Nightly) - November 2026`. +- Add new bullets **after** the section heading, before older entries in that section (newest first within the section). +- If no suitable section exists yet, follow the heading pattern used by adjacent releases and add a table-of-contents link. + +### Entry format + +Match existing style: + +```markdown +* Resolved [#1234](https://github.com/Krypton-Suite/Standard-Toolkit/issues/1234), Short user-facing summary of the fix. +* Implemented [#5678](https://github.com/Krypton-Suite/Standard-Toolkit/issues/5678), Short user-facing summary of the feature. + * To use, you will need to download the `Krypton.Standard.Toolkit` NuGet package, as this control is part of the `Krypton.Toolkit.Utilities` assembly. +* Implemented [#9012](https://github.com/Krypton-Suite/Standard-Toolkit/issues/9012), **[Breaking Change]** Summary of what broke and what consumers must update. +``` + +- Prefix with `Resolved` or `Implemented` (same verbs as existing entries). +- Link the GitHub issue when one exists (`[#NNNN](https://github.com/Krypton-Suite/Standard-Toolkit/issues/NNNN)`). +- If the change is **breaking** for consumers (API removal/rename, behavior change requiring migration, assembly/namespace moves), insert `**[Breaking Change]**` immediately after the issue link comma and before the summary. +- If the feature lives in `Krypton.Toolkit.Utilities.csproj` or `Krypton.Navigator.Utilities.csproj`, append the indented NuGet sub-bullet shown in the example above (`To use, you will need to download the Krypton.Standard.Toolkit NuGet package…`). Use the matching assembly name (`Krypton.Toolkit.Utilities` or `Krypton.Navigator.Utilities`). +- One line per item; use indented sub-bullets only when extra user-facing detail is needed (see existing entries). +- Write for **consumers** of the toolkit (what changed and why it matters), not implementation detail—that belongs in `Documents/Development/` or code comments. + +### Do not add to the changelog + +- Entries for developer guides under `Documents/Development/`. +- References to `Scripts/ModernBuild/README.md` or build-script internals unless the change is user-facing. + +## TestForm Demos + +`Source/Krypton Components/TestForm` (`TestForm.csproj`) is the primary interactive validation app. When a **feature** is completed, add a **comprehensive demo** or **extend an existing demo** so maintainers and reviewers can exercise the capability without reading source first. + +### When to add or update + +- **Features** — new controls, APIs, designer behavior, themes, dialogs, or subsystems: add or expand a demo. +- **Bug fixes** — add a minimal repro when none exists; extend an existing demo when the fix changes observable behavior worth regression-testing. +- Skip demos for comment-only work, pure refactors, or changes with no UI/API surface. + +### Registration + +- Register every new form in `StartScreen.AddButtons()` via `CreateButton(heading, description)`. +- Heading: short title (often includes issue number for bug demos). +- Description: what to try, expected outcome, and which scenarios are covered. +- Follow existing naming: `BugNNNNShortNameDemo` for issue repros; `FeatureNameDemo` or `FeatureNameTest` for broader showcases. + +### Demo content + +A good demo is **comprehensive** for its scope: + +- Exercises the main API paths, properties, events, and theme/palette switches relevant to the change. +- Includes short on-form instructions (labels or a read-only text block) so manual steps are obvious. +- Uses `KryptonForm` and Krypton controls for the host unless the scenario requires otherwise. +- Keeps designer-friendly structure: logic in `*.cs`, layout in `*.Designer.cs` `InitializeComponent()`. + +### Krypton vs standard WinForms + +Where the feature is a **Krypton replacement or wrapper** for a built-in control (or parity/behavior is the point), provide a **side-by-side comparison** when practical: + +- Place native WinForms control(s) and Krypton control(s) in the same form (e.g. split columns in a `TableLayoutPanel`), matching size, text, and interaction where possible. +- Label each side clearly (e.g. “Native TextBox” / “KryptonTextBox”). +- Document what should match and what is intentionally different. +- See existing patterns: `Bug3342KryptonTextBoxResizeFlickerDemo`, `KryptonFolderBrowserDialogDemo`, `AccessibilityTest`, `Bug3343RichTextBoxEditLossDemo`. + +Skip the comparison when there is no meaningful WinForms equivalent (e.g. ribbon-only or docking-only features). + +### Project conventions + +- Add new `.cs` / `.Designer.cs` / `.resx` files to `TestForm.csproj` if not picked up automatically. +- Reference `Krypton.Toolkit.Utilities` / `Krypton.Navigator.Utilities` when the demo targets those assemblies. +- Run: `dotnet run --project ".\Source\Krypton Components\TestForm\TestForm.csproj" -c Debug` + ## Testing Guidelines - No formal unit test suite. Validate changes via `TestForm` scenarios and harnesses under `Source/TestHarnesses` - When fixing a bug, add/adjust a minimal repro in `TestForm` or a harness and describe manual steps in the PR +- When completing a **feature**, add or update a comprehensive demo in `TestForm` per **TestForm Demos** (include Krypton vs WinForms comparison where appropriate) +- When completing a bug fix or feature, update `Documents/Changelog/Changelog.md` per **Changelog** in this file ## Commit & Pull Request Guidelines - Commits: short, imperative subject; reference issues/PRs (e.g., `Fix autosizing (#2433)` or `2439 V100 datecell autosizing`) - PRs: clear description, linked issues, screenshots/gifs for UI changes, notes on breaking changes/TFM impact +- Completed bugs and features: update `Documents/Changelog/Changelog.md` (see **Changelog** above); add or update a `TestForm` demo for features (see **TestForm Demos**); add a `Documents/Development/` guide when the feature warrants in-depth maintainer docs. - Do not add routine validation noise to commit messages or PR descriptions. Mention checks only when they are essential context, unusual, failed, or specifically requested. ## Security & Configuration Tips diff --git a/Documents/Development/README.md b/Documents/Development/README.md new file mode 100644 index 0000000000..eb399e37df --- /dev/null +++ b/Documents/Development/README.md @@ -0,0 +1,15 @@ +# Development Guides + +In-depth, maintainer-focused documentation for completed features lives in this folder. + +Each guide covers architecture, public APIs, usage, and validation. See **Feature Developer Documentation** in the repository root `AGENTS.md` for authoring rules. + +These guides are **not** indexed in `Documents/Changelog/Changelog.md` or `Scripts/ModernBuild/README.md`. + +## Guides + +_Add a row when a new guide is added._ + +| Guide | Summary | +|-------|---------| +| _(none yet)_ | | diff --git a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonAutoHiddenGroup.cs b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonAutoHiddenGroup.cs index a37813adeb..bdc212bc95 100644 --- a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonAutoHiddenGroup.cs +++ b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonAutoHiddenGroup.cs @@ -13,7 +13,7 @@ namespace Krypton.Docking; /// -/// Extends the KryptonNavigator to work as a docking auto hidden group control. +/// Tab strip for auto-hidden pages on one edge. Disposes itself when the last tab is removed. /// [ToolboxItem(false)] [DesignerCategory("code")] diff --git a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonAutoHiddenPanel.cs b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonAutoHiddenPanel.cs index 3d29e7dea1..d5be439654 100644 --- a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonAutoHiddenPanel.cs +++ b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonAutoHiddenPanel.cs @@ -13,7 +13,8 @@ namespace Krypton.Docking; /// -/// Extends the KryptonPanel to work as a panel for hosting KryptonAutoHiddenGroup controls. +/// Edge strip that stacks tab controls. Preferred size accounts +/// for group stacking along the dock orientation. /// [ToolboxItem(false)] [DesignerCategory("code")] diff --git a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonAutoHiddenProxyPage.cs b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonAutoHiddenProxyPage.cs index 010330042e..f311309dd9 100644 --- a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonAutoHiddenProxyPage.cs +++ b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonAutoHiddenProxyPage.cs @@ -13,7 +13,9 @@ namespace Krypton.Docking; /// -/// Acts as a proxy for a KryptonPage inside an auto hidden group. +/// Tab entry in an auto-hidden group that mirrors a single instance also +/// hosted in the slide-out dockspace. The proxy supplies group-tab chrome; is the +/// content shown when the tab is selected. Unwrapped by PropogatePageState for unique-name lookup. /// [ToolboxItem(false)] [DesignerCategory("code")] diff --git a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonAutoHiddenSlidePanel.cs b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonAutoHiddenSlidePanel.cs index e1804b090e..3fa24040bd 100644 --- a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonAutoHiddenSlidePanel.cs +++ b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonAutoHiddenSlidePanel.cs @@ -17,7 +17,9 @@ namespace Krypton.Docking; /// -/// Extends the KryptonPanel to work as a panel for hosting the display of a sliding in/out page. +/// Animated slide-out host for auto-hidden content. State machine: +/// Hidden → SlidingOut → Showing → SlidingIn → Hidden. dismisses the panel +/// when focus or the mouse leaves the slide/dockspace area; separator drag resizes against client minimums. /// [ToolboxItem(false)] [DesignerCategory("code")] @@ -28,6 +30,7 @@ public class KryptonAutoHiddenSlidePanel : KryptonPanel, #region Static Fields private const int SLIDE_MINIMUM = 27; + // int.MaxValue advances the full distance each tick (instant slide); 16 would animate incrementally. private const int SLIDE_DISTANCE = int.MaxValue; // = 16; private const int SLIDE_INTERVAL = 15; private const int CLIENT_MINIMUM = 22; @@ -160,7 +163,7 @@ public KryptonAutoHiddenSlidePanel(Control control, DockingEdge edge, KryptonAut // Do not show ourselves until we are needed Visible = false; - // Add a Button that is not showing and used to push focus away from the dockspace + // Off-screen focus sink so keyboard focus leaves the slide dockspace when sliding in. _dummyTarget = new Button { Location = new Point(-200, -200), @@ -702,7 +705,7 @@ private void CalculateStartAndEnd() var slideSize = new Size(separatorPreferred.Width + dockspacePreferred.Width, separatorPreferred.Height + dockspacePreferred.Height); - // Find the maximum allowed size based on the owning control client area reduced by a sensible minimum + // Clamp slide size to remaining client area minus tab strips on other edges. Size innerSize = _control.ClientRectangle.Size; innerSize.Width -= CLIENT_MINIMUM; innerSize.Height -= CLIENT_MINIMUM; diff --git a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonDockableNavigator.cs b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonDockableNavigator.cs index ed6c21ef23..f0641fb54e 100644 --- a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonDockableNavigator.cs +++ b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonDockableNavigator.cs @@ -13,7 +13,7 @@ namespace Krypton.Docking; /// -/// Extends the KryptonNavigator to work within the docking framework. +/// Designer-facing navigator wired into ; forwards docking events. /// [ToolboxBitmap(typeof(KryptonDockableWorkspace), "ToolboxBitmaps.KryptonDockableNavigator.bmp")] public class KryptonDockableNavigator : KryptonNavigator diff --git a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonDockableWorkspace.cs b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonDockableWorkspace.cs index 00119de624..f65c5f4f4b 100644 --- a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonDockableWorkspace.cs +++ b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonDockableWorkspace.cs @@ -13,7 +13,7 @@ namespace Krypton.Docking; /// -/// Extends the KryptonWorkspace to work within the docking framework. +/// Designer-facing workspace wired into ; enables tab context menus. /// [ToolboxBitmap(typeof(KryptonDockableWorkspace), "ToolboxBitmaps.KryptonDockableWorkspace.bmp")] public class KryptonDockableWorkspace : KryptonSpace diff --git a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonDockspace.cs b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonDockspace.cs index e9f380d6f6..fe999d80b4 100644 --- a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonDockspace.cs +++ b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonDockspace.cs @@ -13,7 +13,7 @@ namespace Krypton.Docking; /// -/// Extends the KryptonWorkspace to work within the docking edge of a control. +/// Visible docked workspace on a control edge. Store name "Docked" routes placeholder clears. /// [ToolboxItem(false)] [DesignerCategory("code")] diff --git a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonDockspaceSeparator.cs b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonDockspaceSeparator.cs index b2d2bd9fc8..cc66234890 100644 --- a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonDockspaceSeparator.cs +++ b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonDockspaceSeparator.cs @@ -13,7 +13,8 @@ namespace Krypton.Docking; /// -/// Extends the KryptonSeparator so work between dockspace entries on a control edge. +/// Resize grip between stacked controls on one edge. +/// Dock/orientation are derived from the parent edge and whether the grip faces inward. /// [ToolboxItem(false)] [DesignerCategory("code")] diff --git a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonDockspaceSlide.cs b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonDockspaceSlide.cs index 878e74b27b..d90e730194 100644 --- a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonDockspaceSlide.cs +++ b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonDockspaceSlide.cs @@ -13,7 +13,7 @@ namespace Krypton.Docking; /// -/// Extends the KryptonWorkspace to work within the docking edge of a control. +/// Dockspace hosted inside the auto-hidden slide panel. Page drag is disabled; content moves via pin/float requests. /// [ToolboxItem(false)] [DesignerCategory("code")] diff --git a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonFloatingWindow.cs b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonFloatingWindow.cs index 02900ba307..3cd302fb49 100644 --- a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonFloatingWindow.cs +++ b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonFloatingWindow.cs @@ -12,7 +12,10 @@ namespace Krypton.Docking; -/// Extends the KryptonForm to act as a floating window within the docking framework. +/// +/// Top-level floating frame. Caption drag raises so +/// can reposition the window during a page drag operation. +/// [ToolboxItem(false)] [DesignerCategory("code")] [DesignTimeVisible(false)] diff --git a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonFloatspace.cs b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonFloatspace.cs index 63e31df3f7..74ce11b88a 100644 --- a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonFloatspace.cs +++ b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonFloatspace.cs @@ -13,7 +13,7 @@ namespace Krypton.Docking; /// -/// Extends the KryptonWorkspace to work within the docking floating window. +/// Workspace inside a floating window. Store name "Floating"; pin action is disabled. /// [ToolboxItem(false)] [DesignerCategory("code")] diff --git a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonSpace.cs b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonSpace.cs index 875ef98906..7269b88096 100644 --- a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonSpace.cs +++ b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonSpace.cs @@ -13,7 +13,8 @@ namespace Krypton.Docking; /// -/// Extends the KryptonWorkspace with common functionality shared by various docking implementations. +/// Workspace base for dockspace, floatspace, and filler hosts. Caches per-cell button specs and focus +/// state because docking chrome (close, pin, dropdown) is attached outside the workspace cell model. /// public abstract class KryptonSpace : KryptonWorkspace { @@ -24,7 +25,7 @@ public abstract class KryptonSpace : KryptonWorkspace protected class CellToCachedState : Dictionary { }; /// - /// State cached per-cell within the workspace. + /// Per-cell docking chrome and focus tracking; keyed by cell because specs are not on KryptonWorkspaceCell. /// protected class CachedCellState { @@ -321,7 +322,7 @@ public override void WritePageElement(XmlWriter xmlWriter, KryptonPage page) if (page != null) { - // If this is a store page then recreate as a store page type + // Attribute S marks a persisted placeholder; recreate as KryptonStorePage with this host's store name. if (CommonHelper.StringToBool(XmlHelper.XmlAttributeToText(xmlReader, @"S"))) { page = new KryptonStorePage(page.UniqueName, _storeName); diff --git a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonStorePage.cs b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonStorePage.cs index 1e1da95903..245c243a23 100644 --- a/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonStorePage.cs +++ b/Source/Krypton Components/Krypton.Docking/Control Docking/KryptonStorePage.cs @@ -13,7 +13,9 @@ namespace Krypton.Docking; /// -/// Acts as a placeholder for a KryptonPage so that it can be restored to this location at a later time. +/// Invisible placeholder left at the original tab/cell index while the real page is shown elsewhere. +/// scopes clears (ClearDockedStoredPages, etc.) so only the matching +/// host removes its placeholder when the page returns or is discarded. /// [ToolboxItem(false)] [DesignerCategory("code")] diff --git a/Source/Krypton Components/Krypton.Docking/Dragging/DockingDragManager.cs b/Source/Krypton Components/Krypton.Docking/Dragging/DockingDragManager.cs index 7d5573bb80..958c286a66 100644 --- a/Source/Krypton Components/Krypton.Docking/Dragging/DockingDragManager.cs +++ b/Source/Krypton Components/Krypton.Docking/Dragging/DockingDragManager.cs @@ -15,7 +15,8 @@ namespace Krypton.Docking; /// -/// Manage a docking dragging operation. +/// Docking-specific drag manager: tracks a during page moves, +/// filters Win32 messages for float-window caption drag, and clears temporary store pages on dispose. /// public class DockingDragManager : DragManager, IFloatingMessages, diff --git a/Source/Krypton Components/Krypton.Docking/Dragging/DockingDragTargetProvider.cs b/Source/Krypton Components/Krypton.Docking/Dragging/DockingDragTargetProvider.cs index 6070f18ca8..5bfe8e15d0 100644 --- a/Source/Krypton Components/Krypton.Docking/Dragging/DockingDragTargetProvider.cs +++ b/Source/Krypton Components/Krypton.Docking/Dragging/DockingDragTargetProvider.cs @@ -13,7 +13,8 @@ namespace Krypton.Docking; /// -/// Provides the set of drag targets relevant to the set of pages being moved. +/// Collects drop targets from the docking tree via propagation. +/// Falls back to when no edge or cell accepts the dragged pages. /// public class DockingDragTargetProvider : IDragTargetProvider { diff --git a/Source/Krypton Components/Krypton.Docking/Dragging/DragTargetControlEdge.cs b/Source/Krypton Components/Krypton.Docking/Dragging/DragTargetControlEdge.cs index 0372dab06b..d60275b7d3 100644 --- a/Source/Krypton Components/Krypton.Docking/Dragging/DragTargetControlEdge.cs +++ b/Source/Krypton Components/Krypton.Docking/Dragging/DragTargetControlEdge.cs @@ -100,6 +100,7 @@ protected override void Dispose(bool disposing) /// Data to be dropped at destination. /// True if a match; otherwise false. public override bool IsMatch(Point screenPt, PageDragEndData? dragEndData) => true; + // Hot-rect hit testing lives in the base DragTarget; this override defers to that geometry. /// /// Perform the drop action associated with the target. @@ -149,7 +150,7 @@ public override bool PerformDrop(Point screenPt, PageDragEndData? data) // Transfer valid pages into the new dockspace if (transferPages.Count > 0) { - // Convert the incoming pages into store pages for restoring later + // Store at source before append so the drag source can remove pages without losing index. manager?.PropogateAction(DockingPropogateAction.StorePages, transferUniqueNames.ToArray()); // Create a new dockspace at the start of the list so it is closest to the control edge diff --git a/Source/Krypton Components/Krypton.Docking/Dragging/DragTargetNull.cs b/Source/Krypton Components/Krypton.Docking/Dragging/DragTargetNull.cs index fdd0baa663..45b14e1540 100644 --- a/Source/Krypton Components/Krypton.Docking/Dragging/DragTargetNull.cs +++ b/Source/Krypton Components/Krypton.Docking/Dragging/DragTargetNull.cs @@ -35,6 +35,7 @@ public DragTargetNull() /// Data to pass to the target to process drop. /// Drop was performed and the source can perform any removal of pages as required. public override bool PerformDrop(Point screenPt, PageDragEndData? data) => true; + // Returning true tells the drag source not to remove pages (no valid drop occurred). #endregion } \ No newline at end of file diff --git a/Source/Krypton Components/Krypton.Docking/Elements Base/DockingElement.cs b/Source/Krypton Components/Krypton.Docking/Elements Base/DockingElement.cs index d3a39f3581..634a7a71ec 100644 --- a/Source/Krypton Components/Krypton.Docking/Elements Base/DockingElement.cs +++ b/Source/Krypton Components/Krypton.Docking/Elements Base/DockingElement.cs @@ -15,7 +15,10 @@ namespace Krypton.Docking; /// -/// Implements base docking element functionality. +/// Root of the docking element composite tree. Each node implements and +/// forwards Propogate* requests to children; leaf nodes (spaces, groups, navigators) own the +/// actual WinForms controls. Path resolution walks down by comma-separated element names; parent lookup +/// walks up to reach . /// public abstract class DockingElement : Component, IDockingElement @@ -107,7 +110,7 @@ public string Path } else { - // Extract the remainder of the path + // Remainder keeps the leading comma so child names still parse as "Child,Grandchild" var remainder = path.Substring(comma, path.Length - comma); // Give each child a chance to resolve the remainder of the path diff --git a/Source/Krypton Components/Krypton.Docking/Elements Base/DockingElementClosedCollection.cs b/Source/Krypton Components/Krypton.Docking/Elements Base/DockingElementClosedCollection.cs index 7ac30832ec..c5b44fac94 100644 --- a/Source/Krypton Components/Krypton.Docking/Elements Base/DockingElementClosedCollection.cs +++ b/Source/Krypton Components/Krypton.Docking/Elements Base/DockingElementClosedCollection.cs @@ -13,7 +13,8 @@ namespace Krypton.Docking; /// -/// Extends base functionality by allowing a collection of child docking elements. +/// Read-only child collection surface; mutations go through protected Internal* helpers so +/// derived types control when children are added. Element names must be unique within a collection. /// public abstract class DockingElementClosedCollection : DockingElement { diff --git a/Source/Krypton Components/Krypton.Docking/Elements Base/DockingElementOpenCollection.cs b/Source/Krypton Components/Krypton.Docking/Elements Base/DockingElementOpenCollection.cs index fa54a385c8..2e2b718bcb 100644 --- a/Source/Krypton Components/Krypton.Docking/Elements Base/DockingElementOpenCollection.cs +++ b/Source/Krypton Components/Krypton.Docking/Elements Base/DockingElementOpenCollection.cs @@ -13,7 +13,8 @@ namespace Krypton.Docking; /// -/// Extends base functionality by allowing a collection of child docking elements. +/// Exposes public Add/Insert/Remove/Clear on top of the closed collection; used by the manager root +/// and where callers assemble the docking tree at runtime. /// public abstract class DockingElementOpenCollection : DockingElementClosedCollection { diff --git a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingAutoHiddenGroup.cs b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingAutoHiddenGroup.cs index 5df01dbc12..94aee88d6c 100644 --- a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingAutoHiddenGroup.cs +++ b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingAutoHiddenGroup.cs @@ -13,7 +13,8 @@ namespace Krypton.Docking; /// -/// Provides display and docking functionality for a group of auto hidden pages. +/// Element for one auto-hidden tab group. Pages appear as +/// tabs; the slide panel shows the real page in a . /// [ToolboxItem(false)] [DesignerCategory("code")] @@ -300,7 +301,7 @@ public override void PropogateAction(DockingPropogateAction action, KryptonPage[ { if (state == DockingPropogatePageState.PageForUniqueName) { - // If we have the page (stored via a proxy) then return the actual page reference (but not for a placeholder) + // Tabs hold proxies; callers need the wrapped page for store/restore and drag operations. KryptonPage? page = AutoHiddenGroupControl.Pages[uniqueName]; if (page is KryptonAutoHiddenProxyPage proxyPage) { diff --git a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingControl.cs b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingControl.cs index a9df4f1d50..f49cd9870e 100644 --- a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingControl.cs +++ b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingControl.cs @@ -15,7 +15,8 @@ namespace Krypton.Docking; /// -/// Provides docking functionality for a control instance. +/// Binds docking to a single host . Suspends layout during multi-step updates, +/// enforces after dockspace resize, and registers outer/inner edge drag targets. /// [ToolboxItem(false)] [DesignerCategory("code")] @@ -131,12 +132,13 @@ public override void PropogateAction(DockingPropogateAction action, string[]? un switch (action) { case DockingPropogateAction.StartUpdate: - // Only the first of several 'StartUpdate' actions needs actioning + // Nested StartUpdate/EndUpdate pairs only suspend layout on the outermost pair. if (_updateCount++ == 0) { Control.SuspendLayout(); - /* Place the obscuring control at the top of the z-order + /* ObscureControl overlay was retired: SuspendLayout alone avoids flicker without + hiding the client area during batch updates. Control.Controls.SetChildIndex(_obscure, 0); // Set obscuring control to take up entire client area and be made visible, this prevents @@ -203,7 +205,8 @@ public override void PropogateDragTargets(KryptonFloatingWindow? floatingWindow, // Only generate targets if we have some valid pages to transfer if (transferPages.Count > 0) { - // Generate targets for the four control edges + // Outer-edge targets (outsideEdge=true) insert new dockspaces at z-index 0; inner targets + // subdivide the remaining client rectangle when a navigator/workspace occupies the center. Rectangle screenRect = Control.RectangleToScreen(Control.ClientRectangle); var rectsDraw = SubdivideRectangle(screenRect, 3, int.MaxValue); var rectsHot = SubdivideRectangle(screenRect, 10, 20); @@ -392,7 +395,7 @@ private void OnControlSizeChanged(object? sender, EventArgs e) private void EnforceInnerMinimum() { - // Find the available inner rectangle of our containing control + // Shrink edge dockspaces greedily when docked panels consume more than InnerMinimum allows. Rectangle innerRect = DockingHelper.InnerRectangle(Control); // Do we need to adjust the left/right edge controls? @@ -487,7 +490,7 @@ private static Rectangle[] SubdivideRectangle(Rectangle area, { var length = Math.Min(area.Width / divisor, Math.Min(area.Height / divisor, maxLength)); - // Find the left, right, top, bottom, center rectangles + // Index 0-3: edge bands; index 4: center (unused for outer-edge targets). return new Rectangle[]{ new Rectangle(area.X, area.Y, length, area.Height), new Rectangle(area.Right - length, area.Y, length, area.Height), diff --git a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingDockspace.cs b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingDockspace.cs index 71c0fac72a..419cc19138 100644 --- a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingDockspace.cs +++ b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingDockspace.cs @@ -13,7 +13,8 @@ namespace Krypton.Docking; /// -/// Provides docking functionality within a control edge using a KryptonDockspace. +/// Docked host on a control edge. Raises / +/// when the last visible page in all cells disappears so the dockspace control can hide itself. /// [ToolboxItem(false)] [DesignerCategory("code")] diff --git a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingEdge.cs b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingEdge.cs index e09de34d49..cc8ffc33d4 100644 --- a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingEdge.cs +++ b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingEdge.cs @@ -13,7 +13,9 @@ namespace Krypton.Docking; /// -/// Provides docking functionality for a specific edge of a control. +/// One physical edge of a host control. Always owns paired +/// and children so pin/unpin can move pages between slide tabs +/// and visible dockspaces on the same side. /// [ToolboxItem(false)] [DesignerCategory("code")] diff --git a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingEdgeAutoHidden.cs b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingEdgeAutoHidden.cs index 6afad7c924..11887533ca 100644 --- a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingEdgeAutoHidden.cs +++ b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingEdgeAutoHidden.cs @@ -13,7 +13,9 @@ namespace Krypton.Docking; /// -/// Provides auto hidden docking functionality against a specific control edge. +/// Auto-hidden edge element: owns the tab strip () and the +/// slide-out panel that hosts the active group's dockspace. Hides the slide panel before store/remove +/// propagate actions so layout changes do not flash over an open slide. /// [ToolboxItem(false)] [DesignerCategory("code")] @@ -127,7 +129,7 @@ public override void PropogateAction(DockingPropogateAction action, string[]? un case DockingPropogateAction.RemovePages: case DockingPropogateAction.RemoveAndDisposePages: case DockingPropogateAction.StorePages: - // Ask the sliding panel to remove its display if an incoming name matches + // Dismiss an open slide before the page is stored or removed from the group. if (uniqueNames != null) { foreach (var uniqueName in uniqueNames) diff --git a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingEdgeDocked.cs b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingEdgeDocked.cs index 0d78db1085..7721242be0 100644 --- a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingEdgeDocked.cs +++ b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingEdgeDocked.cs @@ -13,7 +13,9 @@ namespace Krypton.Docking; /// -/// Provides edge docking functionality for a control using child dockspace control instances. +/// Visible docked edge: stacks controls with resize separators. +/// Z-order places the innermost dockspace closest to the host center; separator drag is wrapped in +/// to avoid layout churn. /// [ToolboxItem(false)] [DesignerCategory("code")] diff --git a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingFloating.cs b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingFloating.cs index f87890ec77..91d5bd10fd 100644 --- a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingFloating.cs +++ b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingFloating.cs @@ -13,7 +13,8 @@ namespace Krypton.Docking; /// -/// Provides docking functionality for floating windows. +/// Factory for floating tool windows owned by a single . Locates an existing +/// float host via store-page lookup before creating another window. /// [ToolboxItem(false)] [DesignerCategory("code")] diff --git a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingFloatingWindow.cs b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingFloatingWindow.cs index bc5314d623..c4e4568e2d 100644 --- a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingFloatingWindow.cs +++ b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingFloatingWindow.cs @@ -15,7 +15,8 @@ namespace Krypton.Docking; /// -/// Provides docking functionality for a floating window that contains just a dockspace. +/// Element wrapping one and its . +/// Reuses the same StartUpdate/EndUpdate suspend pattern as . /// [ToolboxItem(false)] [DesignerCategory("code")] diff --git a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingFloatspace.cs b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingFloatspace.cs index 547dd0b164..0a811ff794 100644 --- a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingFloatspace.cs +++ b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingFloatspace.cs @@ -13,7 +13,8 @@ namespace Krypton.Docking; /// -/// Provides docking functionality within a floating window using a KryptonFloatspace. +/// Floatspace inside a . Store name "Floating"; hidden windows +/// are recycled by for live drag previews. /// [ToolboxItem(false)] [DesignerCategory("code")] diff --git a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingManager.cs b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingManager.cs index bfb09ba06b..56a2c8e5de 100644 --- a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingManager.cs +++ b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingManager.cs @@ -18,7 +18,11 @@ namespace Krypton.Docking; /// -/// Manages a hierarchy of docking elements to provide docking windows functionality. +/// Manages the docking element tree for one or more host controls. Typical hierarchy: +/// Manager → (per side) → +/// / → dockspaces, +/// groups, float windows, workspaces, or navigators. Location changes store the page at its source +/// () before restoring at the target so tab order survives. /// [ToolboxItem(true)] [ToolboxBitmap(typeof(KryptonDockingManager), "ToolboxBitmaps.KryptonDockingManager.bmp")] @@ -1262,8 +1266,7 @@ public override DockingLocation FindPageLocation([DisallowNull] string uniqueNam switch (element) { - // If exists as a dockspace page... - // Find the edge the dockspace is against and return the matching docked edge + // If exists as a dockspace page, walk up to the docked-edge sibling. case KryptonDockingDockspace when element.GetParentType(typeof(KryptonDockingEdgeDocked)) is KryptonDockingEdgeDocked edge: return edge; // If exists as a auto hidden group page... @@ -1481,7 +1484,7 @@ public virtual void MakeAutoHiddenRequest([DisallowNull] string uniqueName) KryptonPage? page = PageForUniqueName(uniqueName); if (page != null) { - // Ensure all docking controls have been laid out before the change is processed + // Flush pending layout so store-page indices and control bounds are current. Application.DoEvents(); var args = new CancelUniqueNameEventArgs(uniqueName, @@ -1546,7 +1549,7 @@ public virtual void MakeDockedRequest([DisallowNull] string uniqueName) KryptonPage? page = PageForUniqueName(uniqueName); if (page != null) { - // Ensure all docking controls have been laid out before the change is processed + // Flush pending layout so store-page indices and control bounds are current. Application.DoEvents(); var args = new CancelUniqueNameEventArgs(uniqueName, @@ -1621,7 +1624,7 @@ public virtual void MakeFloatingRequest([DisallowNull] string uniqueName) KryptonPage? page = PageForUniqueName(uniqueName); if (page != null) { - // Ensure all docking controls have been laid out before the change is processed + // Flush pending layout so store-page indices and control bounds are current. Application.DoEvents(); var args = new CancelUniqueNameEventArgs(uniqueName, @@ -1696,7 +1699,7 @@ public virtual void MakeWorkspaceRequest([DisallowNull] string uniqueName) KryptonPage? page = PageForUniqueName(uniqueName); if (page != null) { - // Ensure all docking controls have been laid out before the change is processed + // Flush pending layout so store-page indices and control bounds are current. Application.DoEvents(); var args = new CancelUniqueNameEventArgs(uniqueName, @@ -1765,7 +1768,7 @@ public virtual void MakeNavigatorRequest([DisallowNull] string uniqueName) KryptonPage? page = PageForUniqueName(uniqueName); if (page != null) { - // Ensure all docking controls have been laid out before the change is processed + // Flush pending layout so store-page indices and control bounds are current. Application.DoEvents(); var args = new CancelUniqueNameEventArgs(uniqueName, @@ -3226,7 +3229,7 @@ public byte[] SaveConfigToArray(Encoding encoding) SaveConfigToStream(ms, encoding); ms.Close(); - // Return an array of bytes that contain the streamed XML + // GetBuffer() may be longer than the written XML; prefer ToArray() if exact length matters. return ms.GetBuffer(); } @@ -3322,7 +3325,7 @@ public void LoadConfigFromArray(byte[] buffer) } /// - /// Loads docking configuration information from given filename. + /// Loads docking configuration from a file path. Despite the name, this overload does not read a byte array. /// /// Name of file to read from. public void LoadConfigFromArray(string filename) @@ -3410,7 +3413,7 @@ public void LoadConfigFromXml(XmlReader xmlReader) } using var update = new DockingMultiUpdate(this); - // Create a list of all the existing pages + // Snapshot current pages, wipe hierarchy (Loading), then rebuild from KD/DGD/DM XML. var currentPages = new KryptonPageCollection(); PropogatePageList(DockingPropogatePageList.All, currentPages); @@ -4043,7 +4046,7 @@ private void InitializeManager() private static void RemoveControlStorePages(DockingElement element, string[] uniqueNames, bool autoHidden, bool docked) { - // Find the control element from the provided starting point + // Pin/unpin can leave store pages on both edges of the same control; clear both sides. KryptonDockingControl? control = element as KryptonDockingControl ?? element.GetParentType(typeof(KryptonDockingControl)) as KryptonDockingControl; // If we managed to find a docking control element to work with diff --git a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingNavigator.cs b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingNavigator.cs index a5ff6fb2c6..c50d273d3d 100644 --- a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingNavigator.cs +++ b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingNavigator.cs @@ -16,7 +16,8 @@ namespace Krypton.Docking; /// -/// Provides docking functionality by attaching to an existing KryptonDockableNavigator +/// Filler-region navigator host (center of a control). Uses store name "Filler" and the same +/// store/restore propagate pattern as . /// [ToolboxItem(false)] [DesignerCategory("code")] diff --git a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingSpace.cs b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingSpace.cs index ed0e77243f..da1763293c 100644 --- a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingSpace.cs +++ b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingSpace.cs @@ -16,7 +16,8 @@ namespace Krypton.Docking; /// -/// Base class for docking elements that manage a KryptonSpace derived class. +/// Element owning a (dockspace, floatspace, or workspace). Handles +/// page-level propagate actions against workspace cells, including store/restore via . /// [ToolboxItem(false)] [DesignerCategory("code")] @@ -91,6 +92,7 @@ public void Append(KryptonPage[]? pages) private void ObserveAutoHiddenSlideSize(KryptonPage[] pages) { + // Track the largest AutoHiddenSlideSize so a later slide-out panel can size to content. if (SpaceControl != null) { Size currentHintSize = SpaceControl.Size; @@ -257,7 +259,7 @@ public override void PropogateAction(DockingPropogateAction action, string[]? un switch (action) { case DockingPropogateAction.Loading: - // Force layout so that the correct number of pages is recognized + // Layout before clear so cell/page counts are current; second layout lets empty spaces self-remove. SpaceControl.PerformLayout(); // Remove all the pages including store pages @@ -354,7 +356,7 @@ public override void PropogateAction(DockingPropogateAction action, string[]? un } foreach (var uniqueName in uniqueNames) { - // Swap pages that are not placeholders to become placeholders + // Insert placeholder at the live page index, then remove the page (index preserved). KryptonPage? page = SpaceControl.PageForUniqueName(uniqueName); if (page is not null and not KryptonStorePage) { @@ -397,7 +399,7 @@ public override void PropogateAction(DockingPropogateAction action, string[]? un case DockingPropogateAction.ClearFloatingStoredPages: case DockingPropogateAction.ClearDockedStoredPages: case DockingPropogateAction.ClearStoredPages: - // Only process an attempt to clear all pages or those related to this docking location + // Location-specific clears ignore hosts whose ClearStoreAction does not match. if ((action == DockingPropogateAction.ClearStoredPages) || (action == ClearStoreAction)) { if (uniqueNames == null) diff --git a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingWorkspace.cs b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingWorkspace.cs index b12bf9b16e..0c33ec82cb 100644 --- a/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingWorkspace.cs +++ b/Source/Krypton Components/Krypton.Docking/Elements Impl/KryptonDockingWorkspace.cs @@ -16,7 +16,8 @@ namespace Krypton.Docking; /// -/// Provides docking functionality by attaching to an existing KryptonDockableWorkspace +/// Filler-region workspace host. Extends with workspace-specific +/// drag targets and filler store-page clearing. /// [ToolboxItem(false)] [DesignerCategory("code")] diff --git a/Source/Krypton Components/Krypton.Docking/General/Definitions.cs b/Source/Krypton Components/Krypton.Docking/General/Definitions.cs index 218ff15d98..b516ff17c7 100644 --- a/Source/Krypton Components/Krypton.Docking/General/Definitions.cs +++ b/Source/Krypton Components/Krypton.Docking/General/Definitions.cs @@ -264,6 +264,7 @@ public enum DockingCloseRequest #endregion #region Enum DockingLocation +// Values drive FindPageLocation and location-scoped store-page lookup/clear during pin/float moves. /// /// Specifies the current docking location of a page. /// @@ -321,6 +322,9 @@ public enum DockingAutoHiddenShowState #endregion #region Enum DockingPropogateAction +// Propagation bus: KryptonDockingManager and callers issue these; each element handles what applies +// locally and forwards the rest. Store*/Clear* actions cooperate with KryptonStorePage placeholders +// that preserve tab index while a page moves between docked, auto-hidden, floating, or filler hosts. /// /// Specifies a docking propogate action. /// diff --git a/Source/Krypton Components/Krypton.Docking/General/DockingHelper.cs b/Source/Krypton Components/Krypton.Docking/General/DockingHelper.cs index cf55fc3d5d..1718316ee1 100644 --- a/Source/Krypton Components/Krypton.Docking/General/DockingHelper.cs +++ b/Source/Krypton Components/Krypton.Docking/General/DockingHelper.cs @@ -62,7 +62,7 @@ public static DockStyle DockStyleFromDockEdge(DockingEdge edge, bool opposite) /// Rectangle in control coordinates. public static Rectangle InnerRectangle(Control c) { - // Start with entire client area + // Start with entire client area, then subtract each visible edge-docked child. Rectangle inner = c.ClientRectangle; // Adjust for edge docked controls diff --git a/Source/Krypton Components/Krypton.Docking/General/DockingMultiUpdate.cs b/Source/Krypton Components/Krypton.Docking/General/DockingMultiUpdate.cs index 71ed04dc68..76b7b02c7c 100644 --- a/Source/Krypton Components/Krypton.Docking/General/DockingMultiUpdate.cs +++ b/Source/Krypton Components/Krypton.Docking/General/DockingMultiUpdate.cs @@ -13,7 +13,9 @@ namespace Krypton.Docking; /// -/// Helper class used inside a 'using' statement to notify start and end of a multi-part update. +/// RAII wrapper that broadcasts / +/// so nested layout, paint, and inner-minimum +/// enforcement are deferred until a location switch or drag-drop sequence completes. /// public class DockingMultiUpdate : IDisposable { diff --git a/Source/Krypton Components/Krypton.Docking/General/ObscureControl.cs b/Source/Krypton Components/Krypton.Docking/General/ObscureControl.cs index d77ddbf146..3d85074f4d 100644 --- a/Source/Krypton Components/Krypton.Docking/General/ObscureControl.cs +++ b/Source/Krypton Components/Krypton.Docking/General/ObscureControl.cs @@ -12,6 +12,8 @@ namespace Krypton.Docking; +// Transparent overlay that suppresses child paint during batch layout; retained for reference from +// commented code in KryptonDockingControl.StartUpdate. internal class ObscureControl : Control { #region Protected diff --git a/Source/Krypton Components/Krypton.Docking/Palette/DockingManagerStrings.cs b/Source/Krypton Components/Krypton.Docking/Palette/DockingManagerStrings.cs index 4f5029679d..034b889b2e 100644 --- a/Source/Krypton Components/Krypton.Docking/Palette/DockingManagerStrings.cs +++ b/Source/Krypton Components/Krypton.Docking/Palette/DockingManagerStrings.cs @@ -13,7 +13,7 @@ namespace Krypton.Docking; /// -/// Storage for docking manager strings. +/// Localized tooltips and context-menu strings pushed to spaces via . /// public class DockingManagerStrings : Storage { diff --git a/Source/Krypton Components/Krypton.Docking/ViewDraw/ViewDrawAutoHiddenTab.cs b/Source/Krypton Components/Krypton.Docking/ViewDraw/ViewDrawAutoHiddenTab.cs index 88e5ae9454..3e844806c9 100644 --- a/Source/Krypton Components/Krypton.Docking/ViewDraw/ViewDrawAutoHiddenTab.cs +++ b/Source/Krypton Components/Krypton.Docking/ViewDraw/ViewDrawAutoHiddenTab.cs @@ -14,7 +14,7 @@ namespace Krypton.Docking; /// -/// View element that can draw an auto hidden tab based on a KryptonPage as the source. +/// Renders one auto-hidden tab from page palette state; orientation follows the dock edge. /// internal class ViewDrawAutoHiddenTab : ViewDrawButton, IContentValues