Control documentation (#2555)

* Added more controls documentation

Added TextBoxBase XmlDocs

* Implemented 3-state clicking on CheckBox

* Added PasswordBox documentation

* Added IsDefault/cancel for wpf users

Author: vchelaru

MonoGameGum.Tests/Forms/CheckBoxTests.cs

@@ -0,0 +1,42 @@
+using Gum.Forms.Controls;
+using Shouldly;
+using Xunit;
+
+namespace MonoGameGum.Tests.Forms;
+
+public class CheckBoxTests : BaseTestClass
+{
+    [Fact]
+    public void CheckBox_TwoState_ShouldCycleFalseTrue()
+    {
+        var checkBox = new CheckBox();
+        checkBox.IsThreeState = false;
+        checkBox.IsChecked = false;
+
+        checkBox.Visual.CallClick();
+        checkBox.IsChecked.ShouldBe(true);
+
+        checkBox.Visual.CallClick();
+        checkBox.IsChecked.ShouldBe(false);
+    }
+
+    [Fact]
+    public void CheckBox_ThreeState_ShouldCycleFalseTrueNull()
+    {
+        var checkBox = new CheckBox();
+        checkBox.IsThreeState = true;
+        checkBox.IsChecked = false;
+
+        // Cycle 1: False -> True
+        checkBox.Visual.CallClick();
+        checkBox.IsChecked.ShouldBe(true);
+
+        // Cycle 2: True -> Null (Indeterminate)
+        checkBox.Visual.CallClick();
+        checkBox.IsChecked.ShouldBe(null);
+
+        // Cycle 3: Null -> False
+        checkBox.Visual.CallClick();
+        checkBox.IsChecked.ShouldBe(false);
+    }
+}

MonoGameGum/Forms/Controls/PasswordBox.cs

@@ -37,10 +37,21 @@ protected override void SetTextFromNativeKeyboardInput(string value)
     }
 
     SecureString securePassword = new SecureString();
+
+    /// <summary>
+    /// Gets the password as a <see cref="SecureString"/>.
+    /// </summary>
     public SecureString SecurePassword
     {
         get { return securePassword; }
     }
+
+    /// <summary>
+    /// Gets or sets the password as a plain string. 
+    /// </summary>
+    /// <remarks>
+    /// For security-sensitive scenarios, consider using <see cref="SecurePassword"/> instead.
+    /// </remarks>
     public string Password
     {
         get
@@ -80,6 +91,11 @@ String SecureStringToString(SecureString value)
     // Update Gum's default to include this first:
     //public char PasswordChar { get; set; } = '●';
     private char _passwordChar = '*';
+
+    /// <summary>
+    /// Gets or sets the character used to mask the characters entered in the PasswordBox. 
+    /// The default value is an asterisk (*).
+    /// </summary>
     public char PasswordChar {
 
         get => _passwordChar;
@@ -95,6 +111,9 @@ public char PasswordChar {
         }
     }
 
+    /// <summary>
+    /// Raised when the password changes.
+    /// </summary>
     public event EventHandler PasswordChanged;
 
     protected override string DisplayedText

MonoGameGum/Forms/Controls/TextBoxBase.cs

@@ -156,10 +156,19 @@ public int CaretIndex
         }
     }
 
+    /// <summary>
+    /// A list of keys that should be ignored by this control.
+    /// </summary>
     public List<Keys> IgnoredKeys => null;
 
+    /// <summary>
+    /// Whether this control is currently capable of receiving input. Always true for TextBoxBase.
+    /// </summary>
     public bool TakingInput => true;
 
+    /// <summary>
+    /// The next control to receive focus when the user presses the tab key.
+    /// </summary>
     public IInputReceiver NextInTabSequence { get; set; }
 
     public override bool IsEnabled
@@ -179,6 +188,10 @@ public override bool IsEnabled
         }
     }
 
+    /// <summary>
+    /// The text currently displayed in the text box. This may differ from the actual
+    /// internal text (e.g. in a PasswordBox).
+    /// </summary>
     protected abstract string? DisplayedText { get; }
 
     TextWrapping textWrapping = TextWrapping.NoWrap;
@@ -349,16 +362,22 @@ public int? MaxLength
 
     /// <summary>
     /// Whether pressing the tab key inserts a tab character. If true, then
-    /// tab characters can be inserted.
+    /// tab characters can be inserted and tab navigation (moving focus to the next control) is disabled.
     /// </summary>
     public bool AcceptsTab { get; set; } = false;
 
+    /// <summary>
+    /// Returns true if tab navigation is enabled. This is the inverse of <see cref="AcceptsTab"/>.
+    /// </summary>
     public override bool IsTabNavigationEnabled => AcceptsTab == false;
 
     #endregion
 
     #region Events
 
+    /// <summary>
+    /// Raised when a controller button is pushed while the control is focused.
+    /// </summary>
     public event Action<GamepadButton> ControllerButtonPushed;
     /// <summary>
     /// Raised before new text is inserted (by typing or pasting). Set
@@ -371,6 +390,9 @@ public int? MaxLength
     /// </summary>
     public event EventHandler CaretIndexChanged;
     protected void RaiseCaretIndexChanged() => CaretIndexChanged?.Invoke(this, EventArgs.Empty);
+    /// <summary>
+    /// Raised when the selection (SelectionStart or SelectionLength) changes.
+    /// </summary>
     public event EventHandler SelectionChanged;
     protected void RaiseSelectionChanged() => SelectionChanged?.Invoke(this, EventArgs.Empty);
     protected virtual TextCompositionEventArgs RaisePreviewTextInput(string newText)
@@ -381,6 +403,9 @@ protected virtual TextCompositionEventArgs RaisePreviewTextInput(string newText)
         return args;
     }
 
+    /// <summary>
+    /// The parent input receiver for this control.
+    /// </summary>
     public IInputReceiver? ParentInputReceiver =>
         this.GetParentInputReceiver();
 

MonoGameGum/Forms/Controls/ToggleButton.cs

@@ -28,21 +28,22 @@ public class ToggleButton : ButtonBase
 
     /// <summary>
     /// Whether this toggle supports three states: checked (true), unchecked (false), and
-    /// indeterminate (null). When false, clicking cycles only between checked and unchecked.
+    /// indeterminate (null). When true, clicking the button cycles through Unchecked -> Checked -> Indeterminate.
+    /// When false, clicking cycles only between Checked and Unchecked.
     /// </summary>
     public bool IsThreeState { get; set; }
 
     private bool? isChecked = false;
 
+
     /// <summary>
     /// Gets or sets the checked state of the toggle. A value of <c>true</c> means checked,
     /// <c>false</c> means unchecked, and <c>null</c> means indeterminate.
     /// </summary>
     /// <remarks>
     /// Setting this property updates the visual state and raises <see cref="Checked"/>,
     /// <see cref="Unchecked"/>, or <see cref="Indeterminate"/> as appropriate.
-    /// The indeterminate state is only reachable programmatically — clicking the button
-    /// cycles between true and false regardless of <see cref="IsThreeState"/>.
+    /// If <see cref="IsThreeState"/> is true, clicking the button cycles through all three states.
     /// </remarks>
     public bool? IsChecked
     {
@@ -60,15 +61,15 @@ public bool? IsChecked
                 if (isChecked == true)
                 {
                     OnChecked();
-                    Checked?.Invoke(this, null);
+                    Checked?.Invoke(this, null!);
                 }
                 else if (isChecked == false)
                 {
-                    Unchecked?.Invoke(this, null);
+                    Unchecked?.Invoke(this, null!);
                 }
                 else if (isChecked == null)
                 {
-                    Indeterminate?.Invoke(this, null);
+                    Indeterminate?.Invoke(this, null!);
                 }
 
                 PushValueToViewModel();
@@ -184,13 +185,22 @@ protected virtual void OnChecked()
 
     protected override void OnClick()
     {
-        if (IsChecked == true)
+        if (IsThreeState)
         {
-            IsChecked = false;
+            if (IsChecked == false) IsChecked = true;
+            else if (IsChecked == true) IsChecked = null;
+            else IsChecked = false; // Indeterminate -> Unchecked
         }
-        else // false or indeterminte
+        else
         {
-            IsChecked = true;
+            if (IsChecked == true)
+            {
+                IsChecked = false;
+            }
+            else // false or indeterminte
+            {
+                IsChecked = true;
+            }
         }
     }
 }

docs/code/about/for-wpf-users.md

@@ -681,6 +681,7 @@ For the full list of color roles and what they affect, see the [Styling Using Ac
 | `Image` | `SpriteRuntime` |
 | `TextBlock` | `TextRuntime` |
 | `Rectangle` with `SolidColorBrush` | `ColoredRectangleRuntime` |
+| `Button.IsDefault` / `IsCancel` | Not supported (handle Enter/Esc globally in your game loop) |
 
 ## What Gum Does Not Have
 
@@ -696,6 +697,7 @@ Some WPF concepts do not exist in Gum:
 * **RelativeSource binding** -- bindings reference property names directly
 * **Measure/Arrange layout passes** -- Gum uses its own layout engine with unit types
 * **Margin / Padding properties** -- spacing is achieved through layout values, `Spacing`, and container nesting
+* **Button.IsDefault / IsCancel** -- Game UIs typically handle default/cancel actions via gamepad or global input state machines rather than localized button properties.
 
 ## Summary
 

docs/code/controls/checkbox.md

@@ -53,6 +53,25 @@ checkBox3.IsChecked = null;
 
 [Try on XnaFiddle.NET](https://xnafiddle.net/#snippet=H4sIAAAAAAAAA6tW8ix2L81VsiopKk3VUcrMyyzJTMzJrEpVslIqSyxSKC5JTM4OSMxLzVGwVchLLVcIhgtoaFrH5CHk9RxTUkLyg_LzS8ASIM3JGanJ2U75FVCtzlAuFo3OGZk5KRow9SB5GFvPsxisLzUFaArIkWhmG5FquBGy6UYoxqcl5hSjm29MqvnGyOYbo5ifV5qTY61UCwD-QP0DdAEAAA)
 
+### Three State CheckBox (IsThreeState)
+
+By default, a CheckBox only cycles between `Checked` and `Unchecked` when clicked. Setting `IsThreeState` to `true` allows the user to cycle through all three states by clicking.
+
+When `IsThreeState` is true, clicking the CheckBox follows this cycle:
+**Unchecked -> Checked -> Indeterminate -> Unchecked**
+
+The following code creates a CheckBox that supports three states:
+
+```csharp
+// Initialize
+var checkBox = new CheckBox();
+checkBox.AddToRoot();
+checkBox.Text = "Three State CheckBox";
+checkBox.IsThreeState = true;
+```
+
+[Try on XnaFiddle.NET](...)
+
 ## CheckBox Width and Height
 
 Default CheckBoxes have the following default values:

docs/code/controls/listbox.md

@@ -202,6 +202,25 @@ listBox.SelectionMode = SelectionMode.Multiple;
 
 [Try on XnaFiddle.NET](https://xnafiddle.net/#snippet=H4sIAAAAAAAAA1VPwWrDMAz9FaNTCsVk3S1hh6WHUlgZbB07LDtkjbqqOHJxZDZW-u-zmpRSH_SkJ-n56QjLfhE7KCREnELsib97KD4gkfadAm5D0yF8ToGYhBpHfwgFPFEvlf81bsQHw_iTTcqaR8Y-tu3av3gvtyxvdj5kA9g5smDQ_jaRxGLIJKm8TFjHPL-fmzstNJ9VQ5zUfKzZpDd6WAp2hjRcTWhbKft2aBvBtX_-2uNGsrPE7LwxpANUhi5bF6M60-sRmepo93S94hVdUiPPK99i-vamtqvohA4OSzj9Aw4ZK_xeAQAA)
 
+### Accessing Multiple Selections
+
+When using `SelectionMode.Multiple` or `SelectionMode.Extended`, you can access all currently selected items using the `SelectedItems` property. This property returns a `System.Collections.IList` containing the selected objects.
+
+The `SelectedObject` and `SelectedIndex` properties are still available, but they will only return the **first** item in the selection.
+
+The following code shows how to iterate over all selected items:
+
+```csharp
+// Loop through all selected items
+foreach (var item in listBox.SelectedItems)
+{
+    System.Diagnostics.Debug.WriteLine($"Selected: {item}");
+}
+
+// Check how many items are selected
+int count = listBox.SelectedItems.Count;
+```
+
 ## Reordering With Drag+Drop
 
 The `DragDropReorderMode` controls whether the user can automatically reorder `ListBoxItems` by pushing on an item and dragging it to a new location. By default this value is set to `NoReorder`, but it can be changed to enable reordering.

docs/code/controls/passwordbox.md

@@ -29,4 +29,19 @@ button.Click += (_, _) => button.Text = passwordBox.Password;
 ```
 [Try on XnaFiddle.NET](https://xnafiddle.net/#snippet=H4sIAAAAAAAACm2PTQvCMAyG7wP_Q-hpooj4cVCZoCLTm8hAhcKYtrjibGXLVBT_u92sX9Nb8rwJeXItWQBkmrjpnnQB45RXcyKkQBFE4sI1JscghkOQJCcVs6E6gwOSn2D2Jna5R-XHRG3AmKfmSuFPstTb7XoBrv7BhWAY6qBRLyYTLrYh6qjZKiSzKNjwUEWMxzqmZCxRV09TSvQ4ldk76xRRSfPJMG9y1Qcv-Bv4Ujd9Zt356D1-zqQocTl-3zQDo0hsdlBxwPar4JfB6RuP5-rXK6bukZJ1uwOuo6mUqAEAAA)
 
+## PasswordChar
+
+The `PasswordChar` property can be used to customize the character that masks the actual text entered by the user. By default, this is an asterisk (`*`).
+
+The following changes the `PasswordChar`:
+
+```csharp
+// Initialize
+var passwordBox = new PasswordBox();
+passwordBox.PasswordChar = '#';
+passwordBox.AddToRoot();
+```
+
+[Try on XnaFiddle.NET](https://xnafiddle.net/#snippet=H4sIAAAAAAAAA6tW8ix2L81VsiopKk3VUSotzsxLL1ayilYCCuqFZxalphUl5qYqxeooZeZllmQm5mRWpSpZKZUlFikUJBYXl-cXpTjlVyjYKuSllisEIEQ0NK1j8pBU6MHknDOAWm0VYkoNDIzMlSEUmlLHlJSQ_KD8_BKgIUq1ADyYlTeiAAAA)
+
 <figure><img src="../../.gitbook/assets/13_22 15 31.gif" alt=""><figcaption><p>Password entered in a PasswordBox</p></figcaption></figure>

docs/code/controls/textbox.md

@@ -98,6 +98,23 @@ panel.AddChild(textBox);
 
 <figure><img src="../../.gitbook/assets/13_09 59 12.gif" alt=""><figcaption><p>TextBox with IsReadOnly set to true responding to mouse click+drag and double-click</p></figcaption></figure>
 
+## MaxLength
+
+The `MaxLength` property can be used to restrict the number of characters that can be entered into a `TextBox`. This limit applies to both user typing and pasting. If a user attempts to type more characters than allowed, the extra characters are ignored. If a user pastes a string that would exceed the limit, the string is truncated to fit.
+
+The following code creates a `TextBox` with a `MaxLength` of 10:
+
+```csharp
+// Initialize
+var textBox = new TextBox();
+textBox.AddToRoot();
+textBox.MaxLength = 10;
+// only 10 characters show:
+textBox.Text = "abcdefghijklmnopqrs";
+```
+
+[Try on XnaFiddle.NET](https://xnafiddle.net/#snippet=H4sIAAAAAAAAA1WMsQrCMBRFfyW8SaGU2LHFQRcRdJGCg3WI5rV92iaavGhR_HcrddDxnsO5T1j6RWghZRcwguDJVB7SHfQw3pLD0qkWYR8BGWJSDT0QUrgpJxg7nttOTIXBu8iHNRpnhfmaeKZ1bjfW8h9dq26FpuK6LyfyR3wuelYEKZNEHY4ay6qm07lpjb1cnR9EBq83c7Gb4LUAAAA)
+
 ## Selection
 
 Selection can be performed programmatically or by the user using the cursor.
@@ -251,6 +268,12 @@ wrappedTextBox.TextWrapping = TextWrapping.Wrap;
 
 <figure><img src="../../.gitbook/assets/14_06 11 31.gif" alt=""><figcaption><p><code>TextWrapping.Wrap</code> causes text to wrap</p></figcaption></figure>
 
+## Enter Key Behavior
+
+The behavior of the Enter key depends on the `AcceptsReturn` property and whether the TextBox is bound to a data source.
+
+### Multi-Line Entry (AcceptsReturn)
+
 `AcceptsReturn` can be set to true to add newlines when the return (enter) key is pressed.
 
 ```csharp
@@ -267,10 +290,6 @@ wrappedTextBox.AcceptsReturn = true;
 
 <figure><img src="../../.gitbook/assets/14_06 12 55.gif" alt=""><figcaption><p>Manually adding newlines by pressing the return (enter) key</p></figcaption></figure>
 
-## Enter Key Behavior
-
-The enter key behavior can be customized for TextBoxes. By default the enter key only applies the Text property to a bound view model. The enter key can also insert multiple lines, but this is usually accompanied with a larger TextBox.
-
 ### Enter and Binding
 
 The `TextBox.Text` property can be bound to a ViewModel's property. By default this property is updated immediately when text changes but the `UpdateSourceTrigger` can be set to `UpdateSourceTrigger.LostFocus`.
@@ -299,11 +318,11 @@ mainPanel.AddChild(textBox);
 
 ## Tab Key Behavior
 
-The tab key behavior is controlled by the `AccetsTab` property. This value is false by default.
+The tab key behavior is controlled by the `AcceptsTab` property. This value is false by default.
 
 If this value is false, pressing the Tab key does not insert a tab `'\t'` character.
 
-If this value is true, pressing the Tab key inserts a tab `'\t'` character. Note that if this value is true, then tabbing to the next control by pressing tab is disabled. In other words, the TextBox keeps keeps focus after the tab key is pressed.
+If this value is true, pressing the Tab key inserts a tab `'\t'` character. Note that if this value is true, then tabbing to the next control by pressing tab is disabled. In other words, the TextBox keeps focus after the tab key is pressed. For more information on how focus navigation works, see the [Tabbing (Moving Focus)](../events-and-interactivity/tabbing-moving-focus.md) page.
 
 ## Extended Character Sets and Keyboards
 

docs/code/events-and-interactivity/tabbing-moving-focus.md

@@ -16,7 +16,13 @@ The keyboard can be used to interact with controls. Keyboards can be used to:
 * To click controls by pressing enter
 * To perform control-specific actions such as changing the value of a slider
 
-To enable gamepad control, add the following code. This code only needs to run once, so add it to your game's Initialize or other code which runs at startup.
+### Tab Key Capture (AcceptsTab)
+
+By default, the Tab key is used for navigation. However, certain controls like `TextBox` and `PasswordBox` can be configured to capture the Tab key to insert a tab character instead of moving focus.
+
+When a `TextBox` has its `AcceptsTab` property set to `true`, focus navigation via the Tab key is disabled for that control. You can still move focus using the mouse or other input methods. For more details, see the [TextBox Tab Key Behavior](../controls/textbox.md#tab-key-behavior) section.
+
+To enable keyboard tabbing, add the following code. This code only needs to run once, so add it to your game's Initialize or other code which runs at startup.
 
 ```csharp
 // Initialize