Rename FocusHandler -> FocusModel, improve docs

Closes #186.

5 files changed, 30 insertions, 26 deletions

diff --git a/src/main/java/io/github/cottonmc/cotton/gui/impl/client/FocusElements.java b/src/main/java/io/github/cottonmc/cotton/gui/impl/client/FocusElements.java
index fc2fa42..0f6a5e3 100644
--- a/src/main/java/io/github/cottonmc/cotton/gui/impl/client/FocusElements.java
+++ b/src/main/java/io/github/cottonmc/cotton/gui/impl/client/FocusElements.java
@@ -10,7 +10,7 @@ import io.github.cottonmc.cotton.gui.widget.WPanel;
 import io.github.cottonmc.cotton.gui.widget.WWidget;
 import io.github.cottonmc.cotton.gui.widget.data.Rect2i;
 import io.github.cottonmc.cotton.gui.widget.focus.Focus;
-import io.github.cottonmc.cotton.gui.widget.focus.FocusHandler;
+import io.github.cottonmc.cotton.gui.widget.focus.FocusModel;
 import org.jetbrains.annotations.Nullable;
 
 import java.util.ArrayList;
@@ -33,10 +33,10 @@ public final class FocusElements {
 	}
 
 	private static Stream<FocusElement<?>> fromFoci(WWidget widget) {
-		@Nullable FocusHandler<?> focusHandler = widget.getFocusHandler();
-		if (focusHandler == null) return Stream.empty();
+		@Nullable FocusModel<?> focusModel = widget.getFocusModel();
+		if (focusModel == null) return Stream.empty();
 
-		return focusHandler.foci().map(focus -> new LeafFocusElement(widget, focus));
+		return focusModel.foci().map(focus -> new LeafFocusElement(widget, focus));
 	}
 
 	public sealed interface FocusElement<W extends WWidget> extends Element {
@@ -52,7 +52,7 @@ public final class FocusElements {
 
 				if (focus != null) {
 					widget.requestFocus();
-					((FocusHandler<Object>) widget.getFocusHandler()).setFocused((Focus<Object>) focus);
+					((FocusModel<Object>) widget.getFocusModel()).setFocused((Focus<Object>) focus);
 				}
 			} else {
 				widget.releaseFocus();
@@ -63,9 +63,9 @@ public final class FocusElements {
 		@Override
 		public boolean isFocused() {
 			if (widget.isFocused()) {
-				FocusHandler<Object> focusHandler = (FocusHandler<Object>) widget.getFocusHandler();
-				if (focusHandler != null) {
-					return focusHandler.isFocused((Focus<Object>) focus);
+				FocusModel<Object> focusModel = (FocusModel<Object>) widget.getFocusModel();
+				if (focusModel != null) {
+					return focusModel.isFocused((Focus<Object>) focus);
 				}
 			}
 
diff --git a/src/main/java/io/github/cottonmc/cotton/gui/widget/WItemSlot.java b/src/main/java/io/github/cottonmc/cotton/gui/widget/WItemSlot.java
index ff7548c..972dbd0 100644
--- a/src/main/java/io/github/cottonmc/cotton/gui/widget/WItemSlot.java
+++ b/src/main/java/io/github/cottonmc/cotton/gui/widget/WItemSlot.java
@@ -23,7 +23,7 @@ import io.github.cottonmc.cotton.gui.impl.client.NarrationMessages;
 import io.github.cottonmc.cotton.gui.widget.data.InputResult;
 import io.github.cottonmc.cotton.gui.widget.data.Rect2i;
 import io.github.cottonmc.cotton.gui.widget.focus.Focus;
-import io.github.cottonmc.cotton.gui.widget.focus.FocusHandler;
+import io.github.cottonmc.cotton.gui.widget.focus.FocusModel;
 import io.github.cottonmc.cotton.gui.widget.icon.Icon;
 import org.jetbrains.annotations.Nullable;
 
@@ -96,7 +96,7 @@ public class WItemSlot extends WWidget {
 	private int hoveredSlot = -1;
 	private Predicate<ItemStack> filter = ValidatedSlot.DEFAULT_ITEM_FILTER;
 	private final Set<ChangeListener> listeners = new HashSet<>();
-	private final FocusHandler<Integer> focusHandler = new FocusHandler<>() {
+	private final FocusModel<Integer> focusModel = new FocusModel<>() {
 		@Override
 		public boolean isFocused(Focus<Integer> focus) {
 			return focusedSlot == focus.key();
@@ -439,8 +439,8 @@ public class WItemSlot extends WWidget {
 
 	@Nullable
 	@Override
-	public FocusHandler<?> getFocusHandler() {
-		return focusHandler;
+	public FocusModel<?> getFocusModel() {
+		return focusModel;
 	}
 
 	@Override
diff --git a/src/main/java/io/github/cottonmc/cotton/gui/widget/WWidget.java b/src/main/java/io/github/cottonmc/cotton/gui/widget/WWidget.java
index 25c9767..a240cd6 100644
--- a/src/main/java/io/github/cottonmc/cotton/gui/widget/WWidget.java
+++ b/src/main/java/io/github/cottonmc/cotton/gui/widget/WWidget.java
@@ -11,7 +11,7 @@ import io.github.cottonmc.cotton.gui.GuiDescription;
 import io.github.cottonmc.cotton.gui.impl.VisualLogger;
 import io.github.cottonmc.cotton.gui.widget.data.InputResult;
 import io.github.cottonmc.cotton.gui.widget.data.ObservableProperty;
-import io.github.cottonmc.cotton.gui.widget.focus.FocusHandler;
+import io.github.cottonmc.cotton.gui.widget.focus.FocusModel;
 import org.jetbrains.annotations.Nullable;
 import org.lwjgl.glfw.GLFW;
 
@@ -429,15 +429,19 @@ public class WWidget {
 	public void tick() {}
 
 	/**
-	 * Returns the focus handler of this widget. The focus
-	 * handler provides the focusable areas of this widget,
-	 * and applies cycling through them.
+	 * Returns the focus model of this widget. The focus
+	 * model provides the focusable areas of this widget,
+	 * and handles switching through them.
 	 *
-	 * @return the focus handler, or {@code null} if not available
+	 * <p>If this widget {@linkplain #canFocus() can focus}, it should return
+	 * a nonnull focus model. The default implementation returns
+	 * {@link FocusModel#simple FocusModel.simple(this)} when the widget can be focused.
+	 *
+	 * @return the focus model, or {@code null} if not available
 	 * @since 7.0.0
 	 */
-	public @Nullable FocusHandler<?> getFocusHandler() {
-		return canFocus() ? FocusHandler.simple(this) : null;
+	public @Nullable FocusModel<?> getFocusModel() {
+		return canFocus() ? FocusModel.simple(this) : null;
 	}
 
 	/**
diff --git a/src/main/java/io/github/cottonmc/cotton/gui/widget/focus/FocusHandler.java b/src/main/java/io/github/cottonmc/cotton/gui/widget/focus/FocusModel.java
index f3b569e..615f686 100644
--- a/src/main/java/io/github/cottonmc/cotton/gui/widget/focus/FocusHandler.java
+++ b/src/main/java/io/github/cottonmc/cotton/gui/widget/focus/FocusModel.java
@@ -12,7 +12,7 @@ import java.util.stream.Stream;
  * @param <K> the focus key type
  * @since 7.0.0
  */
-public interface FocusHandler<K> {
+public interface FocusModel<K> {
 	/**
 	 * Checks if a focus is focused in the target widget.
 	 * If the target widget is not focused itself, none of its foci should have focus.
@@ -38,14 +38,14 @@ public interface FocusHandler<K> {
 	Stream<Focus<K>> foci();
 
 	/**
-	 * Creates a simple focus handler for a focusable widget.
-	 * The focus handler provides the whole widget area as its only focus area.
+	 * Creates a simple focus model for a focusable widget.
+	 * The focus model provides the whole widget area as its only focus area.
 	 *
 	 * @param widget the widget
-	 * @return the focus handler
+	 * @return the focus model
 	 */
-	static FocusHandler<?> simple(WWidget widget) {
+	static FocusModel<?> simple(WWidget widget) {
 		Rect2i widgetArea = new Rect2i(0, 0, widget.getWidth(), widget.getHeight());
-		return new SimpleFocusHandler(widget, widgetArea);
+		return new SimpleFocusModel(widget, widgetArea);
 	}
 }
diff --git a/src/main/java/io/github/cottonmc/cotton/gui/widget/focus/SimpleFocusHandler.java b/src/main/java/io/github/cottonmc/cotton/gui/widget/focus/SimpleFocusModel.java
index 76b0cc1..4144f0a 100644
--- a/src/main/java/io/github/cottonmc/cotton/gui/widget/focus/SimpleFocusHandler.java
+++ b/src/main/java/io/github/cottonmc/cotton/gui/widget/focus/SimpleFocusModel.java
@@ -6,7 +6,7 @@ import org.jetbrains.annotations.Nullable;
 
 import java.util.stream.Stream;
 
-record SimpleFocusHandler(WWidget widget, Rect2i area) implements FocusHandler<@Nullable Void> {
+record SimpleFocusModel(WWidget widget, Rect2i area) implements FocusModel<@Nullable Void> {
 	@Override
 	public boolean isFocused(Focus<@Nullable Void> focus) {
 		return widget.isFocused();