From ed9f17e6c4bd0d662895767f3f92802d92dad5b3 Mon Sep 17 00:00:00 2001 From: dnesov Date: Tue, 24 Jun 2025 22:46:35 +0200 Subject: [PATCH] Add documentation to IElement, Anchor and UIElement. --- Voile/Source/UI/Anchor.cs | 55 +++++++++++++++++++++++++++++++++++- Voile/Source/UI/IElement.cs | 36 +++++++++++++++++++++-- Voile/Source/UI/UIElement.cs | 7 +++++ 3 files changed, 95 insertions(+), 3 deletions(-) diff --git a/Voile/Source/UI/Anchor.cs b/Voile/Source/UI/Anchor.cs index b601caf..a2b13c8 100644 --- a/Voile/Source/UI/Anchor.cs +++ b/Voile/Source/UI/Anchor.cs @@ -2,23 +2,76 @@ using System.Numerics; namespace Voile.UI; +/// +/// Specifies predefined anchor points used to position UI elements relative to their parent container. +/// public enum Anchor { + /// + /// Anchors the element to the top-left corner of the parent. + /// TopLeft, + + /// + /// Anchors the element to the top-center of the parent. + /// TopCenter, + + /// + /// Anchors the element to the top-right corner of the parent. + /// TopRight, + + /// + /// Anchors the element to the center-left edge of the parent. + /// CenterLeft, + + /// + /// Anchors the element to the exact center of the parent. + /// Center, + + /// + /// Anchors the element to the center-right edge of the parent. + /// CenterRight, + + /// + /// Anchors the element to the bottom-left corner of the parent. + /// BottomLeft, + + /// + /// Anchors the element to the bottom-center of the parent. + /// BottomCenter, + + /// + /// Anchors the element to the bottom-right corner of the parent. + /// BottomRight, Fill } - +/// +/// Provides extension methods for calculating anchored positions of UI elements. +/// public static class AnchorExtensions { + /// + /// Calculates the offset position for an element based on the specified . + /// + /// The anchor mode to use. + /// The absolute position of the parent container (top-left corner). + /// The bounding rectangle of the parent container. + /// The size of the element being anchored. + /// + /// A representing the local offset position where the element should be placed inside the parent. + /// + /// + /// The result is the relative offset from the parent's origin, not a global position. + /// public static Vector2 Calculate(this Anchor anchor, Vector2 parentPosition, Rect parentRect, Rect elementRect) { var size = new Vector2(elementRect.Width, elementRect.Height); diff --git a/Voile/Source/UI/IElement.cs b/Voile/Source/UI/IElement.cs index 5e1caf7..5b27df9 100644 --- a/Voile/Source/UI/IElement.cs +++ b/Voile/Source/UI/IElement.cs @@ -1,9 +1,11 @@ using System.Numerics; -using Voile.Input; using Voile.Rendering; namespace Voile.UI; +/// +/// Represents a basic UI element with position and size information. +/// public interface IElement { /// @@ -16,6 +18,9 @@ public interface IElement public Rect Size { get; set; } } +/// +/// Represents a UI element that can contain child elements. +/// public interface IParentableElement { /// @@ -34,6 +39,10 @@ public interface IParentableElement public void RemoveChild(UIElement child); } +/// +/// Represents a UI element that can provide a minimum size constraint.
+/// Implement this interface if your UI element is expected to be resizeable. +/// public interface IResizeableElement { /// @@ -42,10 +51,13 @@ public interface IResizeableElement public abstract Rect MinimumSize { get; } } +/// +/// Represents a UI element that supports updates when its state changes. +/// public interface IUpdatableElement { /// - /// Specifies if this element's properties have changed, making it necessary to update it. + /// Gets a value indicating whether the element's state has changed and needs to be updated. /// public bool Dirty { get; } /// @@ -58,6 +70,9 @@ public interface IUpdatableElement void MarkDirty(); } +/// +/// Represents a UI element that can be rendered to the screen. +/// public interface IRenderableElement { /// @@ -77,6 +92,9 @@ public interface IRenderableElement public void DrawSize(RenderSystem renderer); } +/// +/// Represents a UI element that can receive and process user input. +/// public interface IInputElement { /// @@ -90,9 +108,23 @@ public interface IInputElement void Input(UIInputContext action); } +/// +/// Represents a UI element that supports positional anchoring within a parent. +/// public interface IAnchorableElement { + /// + /// Gets or sets the anchor point relative to the parent container. + /// public Anchor Anchor { get; set; } + /// + /// Gets or sets an additional offset to apply after anchoring, in pixels. + /// public Vector2 AnchorOffset { get; set; } + /// + /// Applies the current anchor settings based on the parent's position and size. + /// + /// The parent's top-left global position. + /// The bounding rectangle of the parent container. public void ApplyAnchor(Vector2 parentPosition, Rect parentRect); } \ No newline at end of file diff --git a/Voile/Source/UI/UIElement.cs b/Voile/Source/UI/UIElement.cs index 29306ba..316ab4f 100644 --- a/Voile/Source/UI/UIElement.cs +++ b/Voile/Source/UI/UIElement.cs @@ -3,6 +3,9 @@ using Voile.Rendering; namespace Voile.UI; +/// +/// Base class for all UI elements. +/// public abstract class UIElement : IElement, IRenderableElement, IResizeableElement, IUpdatableElement, IAnchorableElement { public bool Visible { get; set; } = true; @@ -43,6 +46,10 @@ public abstract class UIElement : IElement, IRenderableElement, IResizeableEleme public virtual void MarkDirty() => _dirty = true; + /// + /// Sets a parent element for this . + /// + /// Element to parent this to. public void SetParent(UIElement parent) { _parent = parent;