Document the auto focus behaviour added to FocusableUserWidget

doc/FocusableUserWidget.md

@@ -0,0 +1,24 @@
+# FocusableUserWidget
+
+You can use this as a base class for your widgets instead of User Widget, in 
+order to optionally get some automatic  focus behaviour. 
+
+Checking the "Enable Automatic Focus" box opts into this behaviour, and whenever
+this widget is added to the viewport it will automatically be given focus *if*
+its priority is equal or higher to anything else on screen right now. You set
+the "Automatic Focus Priority" member to a value and the highest wins.
+
+When a widget with auto focus enabled is removed from the viewport while it has 
+the focus, it triggers the focus system to automatically give focus to the
+highest priority widget still in the viewport.
+
+This makes it easier to make UIs with several independent elements, which can
+supersede each other, but you need to have a reliable focus chain. By enabling
+this option on all your dialogs (it's automatically enabled on [Menus](Menus.md))
+and setting priorities accordingly, you can ensure that focus is reliably 
+transferred without having to do it manually in all combinations of sequences.
+
+## See Also
+
+* [Focusable Panel](FocusablePanel.md)
+* [Menus](Menus.md)

doc/Widgets.md

@@ -33,6 +33,12 @@ Several custom widgets are supplied to assist with some common challenges:
   which can apply the "Hovered" style to itself when focused (very important
   for gamepad navigation).
 
+* [Focusable User Widget](FocusableUserWidget.md)
+
+  A base class to use as an alternative to plain UserWidget if you want this
+  widget to have the option to automatically gain focus. This is a good base class
+  for dialogs or other systems which are navigable by gamepad or keyboard.
+
 * [Focusable Panel](FocusablePanel.md)
 
   A Panel widget which can make sure that something is selected when a