From 6fbc0cb923536a23d51a50356a6572ae02eab147 Mon Sep 17 00:00:00 2001
From: Greenlamp2 <44787002+Greenlamp2@users.noreply.github.com>
Date: Fri, 10 May 2024 15:25:41 +0200
Subject: [PATCH] Settings navigation, when on top to go to the bottom, and
 when on the bottom to go to the top (#605)

* fix settings top and bottom

* added some comment

* TSDoc ready + less lengthy comments
---
 src/ui/settings-ui-handler.ts | 36 +++++++++++++++++++++++++++++++----
 1 file changed, 32 insertions(+), 4 deletions(-)

diff --git a/src/ui/settings-ui-handler.ts b/src/ui/settings-ui-handler.ts
index 3ed83268e..6e40103b8 100644
--- a/src/ui/settings-ui-handler.ts
+++ b/src/ui/settings-ui-handler.ts
@@ -120,13 +120,25 @@ export default class SettingsUiHandler extends UiHandler {
     return true;
   }
 
+  /**
+   * Processes input from a specified button.
+   * This method handles navigation through a UI menu, including movement through menu items
+   * and handling special actions like cancellation. Each button press may adjust the cursor
+   * position or the menu scroll, and plays a sound effect if the action was successful.
+   *
+   * @param button - The button pressed by the user.
+   * @returns `true` if the action associated with the button was successfully processed, `false` otherwise.
+   */
   processInput(button: Button): boolean {
     const ui = this.getUi();
+    // Defines the maximum number of rows that can be displayed on the screen.
+    const rowsToDisplay = 9;
 
     let success = false;
 
     if (button === Button.CANCEL) {
       success = true;
+      // Reverts UI to its previous state on cancel.
       this.scene.ui.revertMode();
     } else {
       const cursor = this.cursor + this.scrollCursor;
@@ -137,27 +149,43 @@ export default class SettingsUiHandler extends UiHandler {
               success = this.setCursor(this.cursor - 1);
             else
               success = this.setScrollCursor(this.scrollCursor - 1);
+          } else {
+              // When at the top of the menu and pressing UP, move to the bottommost item.
+              // First, set the cursor to the last visible element, preparing for the scroll to the end.
+              const successA = this.setCursor(rowsToDisplay - 1);
+              // Then, adjust the scroll to display the bottommost elements of the menu.
+              const successB = this.setScrollCursor(this.optionValueLabels.length - rowsToDisplay);
+              success = successA && successB; // success is just there to play the little validation sound effect
           }
           break;
         case Button.DOWN:
-          if (cursor < this.optionValueLabels.length) {
-            if (this.cursor < 8)
+          if (cursor < this.optionValueLabels.length - 1) {
+            if (this.cursor < rowsToDisplay - 1) // if the visual cursor is in the frame of 0 to 8
               success = this.setCursor(this.cursor + 1);
-            else if (this.scrollCursor < this.optionValueLabels.length - 9)
+            else if (this.scrollCursor < this.optionValueLabels.length - rowsToDisplay)
               success = this.setScrollCursor(this.scrollCursor + 1);
+          } else {
+              // When at the bottom of the menu and pressing DOWN, move to the topmost item.
+              // First, set the cursor to the first visible element, resetting the scroll to the top.
+              const successA = this.setCursor(0);
+              // Then, reset the scroll to start from the first element of the menu.
+              const successB = this.setScrollCursor(0);
+              success = successA && successB; // Indicates a successful cursor and scroll adjustment.
           }
           break;
         case Button.LEFT:
-          if (this.optionCursors[cursor])
+          if (this.optionCursors[cursor]) // Moves the option cursor left, if possible.
             success = this.setOptionCursor(cursor, this.optionCursors[cursor] - 1, true);
           break;
         case Button.RIGHT:
+          // Moves the option cursor right, if possible.
           if (this.optionCursors[cursor] < this.optionValueLabels[cursor].length - 1)
             success = this.setOptionCursor(cursor, this.optionCursors[cursor] + 1, true);
           break;
       }
     }
 
+    // Plays a select sound effect if an action was successfully processed.
     if (success)
       ui.playSelect();