rgame 0.2.0 → 0.3.0

data/lib/rgame/engine/ui/menu.rb

@@ -3,20 +3,102 @@
 module RGame
   module Engine
     module UI
-      # A vertical list of things to choose from, navigated by keyboard or
-      # controller.
+      # Buttons to choose from, navigated by keyboard or controller.
       #
-      #   menu = layer.add_node(UI::Menu.new(item_width: 220, item_height: 44))
-      #   menu.add_item('Resume').on_activated { close }
-      #   menu.add_item('Quit').on_activated   { game.close }
+      #   menu = layer.add_node(UI::Menu.new(layout: UI::Column.new(item_width: 220, item_height: 44)))
+      #   menu.add(UI::PanelButton.new(label: 'Resume')).on_activated { close }
+      #   menu.add(UI::PanelButton.new(label: 'Quit')).on_activated   { game.close }
       #
       # ## Focus is the whole design
       #
-      # With no pointer there is no hover, so something has to own *which
-      # control is focused* and how the directions move it. That is this class,
-      # and everything else about a menu follows from it: an item draws
-      # differently because it is focused, and `ui_confirm` activates the focused
-      # one.
+      # With no pointer there is no hover, so something has to own *which button
+      # is focused*. That is this class, and everything else about a menu
+      # follows from it: a button draws differently because it is focused, and
+      # `ui_confirm` activates the focused one.
+      #
+      # ## The menu holds buttons; it does not build them
+      #
+      # What a button looks like is the button's business — any UI::Button
+      # subclass, shipped or written by the game, goes in through `add`. The menu
+      # never picks a look, so one menu can hold a panel button next to a game's
+      # own.
+      #
+      # ## Two questions are handed off, and one is kept
+      #
+      # A list and a radial wheel are the same menu. What differs is **where the
+      # buttons sit** and **how input moves focus**, so those two are passed in:
+      #
+      # | | Answers | Shipped |
+      # |---|---|---|
+      # | `layout:` | where each button goes, its size, and the bounds of them all | UI::Column, UI::Row, UI::Ring |
+      # | `navigation:` | which button this frame's input focuses | UI::Stepping (default), UI::Pointing, or nil |
+      #
+      # What stays here is what every menu does the same way: holding the
+      # buttons, passing `ui_confirm` to the focused one as a press and a
+      # release — when that activates is the button's `activate_on:` — and
+      # passing each button's `hotkey` to that button, focused or not. A
+      # navigation cannot forget to do either, because it is never asked to.
+      #
+      # ## A menu with no navigation
+      #
+      # `navigation: nil` says input never moves focus: the menu focuses nothing
+      # when a button is added, so `ui_confirm` has nothing to act on. What
+      # focuses a button then is the game calling `focus` — which confirm then
+      # acts on, as it would for any navigation.
+      #
+      # ## A menu acts only on a press it saw start
+      #
+      # A menu takes no press until it has seen `ui_confirm` up, and no hotkey
+      # press on a button until it has seen that hotkey up since the button was
+      # added. A menu opened from `on_activated` — a submenu — is controlled
+      # later in the same tick, while the key that opened it is still down, and
+      # would otherwise read the same press edge again and activate its own
+      # button with it.
+      #
+      #   wheel = UI::Menu.new(x: 320, y: 240, navigation: UI::Pointing.new,
+      #                        layout: UI::Ring.new(radius: 120, item_width: 96, item_height: 30))
+      #
+      # ## A scope for its buttons' keys
+      #
+      # `scope:` puts a scope in front of every label given as a key, so the
+      # buttons of a title menu say `label: 'play'` and draw `title_menu.play`:
+      #
+      #   menu = UI::Menu.new(layout: column, scope: 'title_menu')
+      #   menu.add(UI::PanelButton.new(label: 'play'))                                   # title_menu.play
+      #   menu.add(UI::PanelButton.new(label: Engine::Text.new('quit', scope: 'common')))  # common.quit
+      #
+      # The menu sets it as each button is added, on a button whose
+      # `label_scope` is still nil. A label given as an Engine::Text keeps its own
+      # scope, nil included, and so does a literal. The scope reaches the
+      # buttons of this menu and nothing deeper in the tree.
+      #
+      # ## Open and closed
+      #
+      # A closed menu draws nothing — neither its own backdrop nor its buttons —
+      # and its input moves no focus and presses nothing. A menu starts open;
+      # `close` and `open` are what a pause menu toggles. Closing is not
+      # pausing: a closed menu still ticks, so a button's pressed feedback runs
+      # out while it is shut instead of waiting to be seen again.
+      #
+      # ## A menu held open by an action
+      #
+      # `trigger:` names an action that opens the menu while it is held. Letting
+      # it go activates the button focused at that moment, if any, and closes —
+      # the console quick wheel, held open by a shoulder button:
+      #
+      #   wheel = UI::RadialMenu.new(x: 320, y: 240, radius: 150, button_width: 64, trigger: :quick_menu)
+      #
+      # A menu with a trigger starts closed, and `ui_confirm` activates nothing
+      # on it: letting go is the only way to choose. Opening only happens on a
+      # press this menu saw start, like every other press, so a trigger already
+      # down when the menu appears opens nothing; and a trigger that comes up
+      # while the menu is paused closes it without choosing. `open` raises on
+      # such a menu, because a menu opened by hand would wait for the release of
+      # a press it never saw; `close` does not, and is how a game cancels a held
+      # wheel.
+      #
+      # What the world does while the menu is open is the game's to decide, from
+      # `on_opened` and `on_closed`. The menu only says when.
       #
       # ## Focus is per player, and that costs nothing
       #
@@ -29,85 +111,178 @@ module RGame
       #
       # ## What this is not
       #
-      # It is a menu, not a widget library. Items are stacked vertically at a
-      # fixed size, and that is the whole of its layout. The package this
-      # replaces positioned everything absolutely and hit-tested a mouse; none
-      # of it is a reference, and how UI should be laid out in general is still
-      # an open question — see docs/api/ui.md, "What this is not".
+      # It is a menu, not a widget library. Every button is the same size, placed
+      # by its layout, and that is the whole of its layout story — see
+      # docs/api/ui.md, "What this is not".
       class Menu < Node2D
-        # Navigation wraps: a short vertical list is quicker to use when the
-        # ends join, and every console menu does it.
-        def initialize(item_width:, item_height:, spacing: 8,
-                       style: MenuItem::STYLE, **)
+        signal :on_opened
+        # Emits the button a trigger's release activated, or nil.
+        signal :on_closed, Signal.define(:button)
+
+        # `trigger` is an action name, or nil. `scope` is a String, or nil.
+        attr_reader :buttons, :focused_index, :layout, :navigation, :trigger, :scope
+
+        # The rectangle the layout says encloses every button, relative to the
+        # menu — what a subclass draws its backdrop round. Copied on each `add`,
+        # so reading them on a draw path costs nothing.
+        attr_reader :bounds_x, :bounds_y, :bounds_width, :bounds_height
+
+        def initialize(layout:, navigation: Stepping.new, trigger: nil, scope: nil, **)
           super(**)
-          @item_width = item_width
-          @item_height = item_height
-          @spacing = spacing
-          @style = style
-          @items = []
-          @focused_index = 0
-        end
-
-        attr_reader :items, :focused_index
-
-        # Adds an item below the last one and returns it, so a caller can
-        # connect to its signal in the same line.
-        def add_item(label, enabled: true)
-          item = MenuItem.new(label: label, enabled: enabled, style: @style,
-                              x: 0, y: @items.size * (@item_height + @spacing),
-                              width: @item_width, height: @item_height)
-          @items << item
-          add_node(item)
-          refocus
-          item
-        end
-
-        def focused = @items[@focused_index]
-
-        # Moves focus by `delta`, skipping anything disabled, and wrapping. Does
-        # nothing at all if no item can take focus.
-        def focus_by(delta)
-          return if @items.empty?
-
-          index = @focused_index
-          @items.size.times do
-            index = (index + delta) % @items.size
-            next unless @items[index].enabled?
-
-            focus(index)
-            return
-          end
+          @scope = scope&.to_s&.freeze
+          @layout = layout
+          @navigation = navigation
+          @trigger = trigger
+          @open = trigger.nil?
+          @buttons = []
+          @bounds_x = @bounds_y = @bounds_width = @bounds_height = 0
+          @focused_index = nil
+          @confirm_seen_up = false
+          @trigger_seen_up = false
+          @hotkey_seen_up = []
+          navigation&.attach(self)
+        end
+
+        # Adds a button, gives it the menu's `scope` unless it has a
+        # `label_scope` already, re-arranges them all, and returns it, so a
+        # caller can connect to its signal in the same line. Raises TypeError for
+        # anything that is not a UI::Button.
+        def add(button)
+          raise TypeError, "a Menu holds UI::Button instances, not #{button.class}" unless button.is_a?(Button)
+
+          button.label_scope = @scope if @scope && button.label_scope.nil?
+          @buttons << button
+          @hotkey_seen_up << false
+          add_node(button)
+          @layout.arrange(@buttons)
+          @bounds_x, @bounds_y, @bounds_width, @bounds_height = @layout.bounds(@buttons)
+          @navigation&.on_buttons_changed
+          button
         end
 
+        # The focused button, or nil when nothing is — which under UI::Pointing
+        # is whenever the stick is at rest.
+        def focused = @focused_index && @buttons[@focused_index]
+
+        # Focuses the button at `index`, or nothing for nil. Only the buttons
+        # whose focus actually changes are told. It does not check `enabled?`:
+        # which buttons may take focus is the navigation's rule, and a disabled
+        # button cannot be activated whatever holds it.
         def focus(index)
+          previous = focused
           @focused_index = index
-          @items.each_with_index { |item, i| item.focused = (i == index) }
+          current = focused
+          previous.focused = false if previous && !previous.equal?(current)
+          current&.focused = true
+        end
+
+        def open? = @open
+
+        # Opens the menu, lets the navigation forget the last opening, and emits
+        # `on_opened`. Nothing if already open. Raises on a menu with a trigger,
+        # which only its trigger opens.
+        def open
+          raise "this menu is opened by holding #{@trigger.inspect}, not by #open" if @trigger
+          return if @open
+
+          open_now
         end
 
+        # Closes the menu without activating anything and emits `on_closed` with
+        # nil. Nothing if already closed.
+        def close
+          close_with(nil) if @open
+        end
+
+        # Draws nothing while closed.
+        def draw(renderer, view)
+          super if @open
+        end
+
+        # A trigger's press first, so an opening's first frame already reads the
+        # stick; then navigation, so a focus change and a confirm on the same
+        # frame confirm the newly focused button; then every hotkey; then
+        # confirm, on a menu with no trigger; and a trigger's release last, so it
+        # chooses what this frame focused.
         def on_control(actions)
-          focus_by(-1) if actions.pressed?(:ui_up)
-          focus_by(1) if actions.pressed?(:ui_down)
+          trigger_edge = control_trigger(actions) if @trigger
+          open_now if trigger_edge == :press
+          return unless @open
 
-          current = focused
-          return if current.nil?
+          @navigation&.on_control(actions)
+          press_hotkeys(actions)
+          @trigger ? release_trigger(trigger_edge) : confirm(actions)
+        end
 
-          current.pressed = actions.held?(:ui_confirm)
-          current.activate if actions.pressed?(:ui_confirm)
+        # Lets the navigation count time, then does what every node does.
+        def update(dt)
+          @navigation&.update(dt) unless @paused
+          super
         end
 
         private
 
-        # Keeps focus on something usable as items arrive: the first item to be
-        # added takes it, and a disabled first item hands it on.
-        def refocus
-          return if focused&.enabled?
+        def open_now
+          @open = true
+          @navigation&.on_opened
+          on_opened_signal.emit
+        end
+
+        def close_with(button)
+          @open = false
+          on_closed_signal.emit(button)
+        end
+
+        def control_trigger(actions)
+          edge = press_edge(actions, @trigger, @trigger_seen_up)
+          @trigger_seen_up = !actions.held?(@trigger)
+          edge
+        end
+
+        def release_trigger(edge)
+          case edge
+          when :release then close_with(focused&.activate)
+          when :missed_release then close_with(nil)
+          end
+        end
+
+        def confirm(actions)
+          edge = press_edge(actions, :ui_confirm, @confirm_seen_up)
+          @confirm_seen_up = !actions.held?(:ui_confirm)
+          button = focused
+          pass_edge(button, edge, :confirm) if button
+        end
 
-          @items.each_with_index do |item, index|
-            next unless item.enabled?
+        def press_hotkeys(actions)
+          index = 0
+          while index < @buttons.size
+            button = @buttons[index]
+            hotkey = button.hotkey
+            if hotkey
+              edge = press_edge(actions, hotkey, @hotkey_seen_up[index])
+              @hotkey_seen_up[index] = !actions.held?(hotkey)
+              pass_edge(button, edge, :hotkey)
+            end
+            index += 1
+          end
+        end
+
+        def press_edge(actions, action, seen_up)
+          if actions.pressed?(action)
+            :press if seen_up
+          elsif actions.released?(action)
+            :release
+          elsif !actions.held?(action)
+            :missed_release
+          end
+        end
 
-            return focus(index)
+        def pass_edge(button, edge, source)
+          case edge
+          when :press then button.press(source)
+          when :release then button.release(source)
+          when :missed_release then button.cancel_press(source)
           end
-          focus(0)
         end
       end
     end

data/lib/rgame/engine/ui/navigation.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module UI
+      # How a Menu turns a player's input into focus. The base of UI::Stepping
+      # and UI::Pointing, and the class to subclass for a third way.
+      #
+      #   class Cycling < UI::Navigation
+      #     def on_control(actions)
+      #       menu.focus((menu.focused_index.to_i + 1) % menu.buttons.size) if actions.pressed?(:ui_right)
+      #     end
+      #   end
+      #
+      # A navigation only decides **which button is focused**. Confirming the
+      # focused button, pressing it and firing its signal are the Menu's,
+      # and the same for every navigation, so a subclass cannot forget them.
+      #
+      # ## One per menu
+      #
+      # A navigation may keep state about the menu it drives — UI::Pointing keeps
+      # the last direction read — so it belongs to exactly one. Handing the same
+      # instance to a second Menu raises, rather than leaving two menus quietly
+      # sharing one pointer. Build a fresh one for each menu; the constructor
+      # default already does.
+      class Navigation
+        attr_reader :menu
+
+        # Called by Menu when it is built with this navigation.
+        def attach(menu)
+          if @menu && !@menu.equal?(menu)
+            raise ArgumentError, "this #{self.class} already navigates another menu — build one per menu"
+          end
+
+          @menu = menu
+        end
+
+        # Reads this frame's actions and moves focus with `menu.focus`. Called
+        # before the Menu handles `ui_confirm`, so a focus change and a confirm on
+        # the same frame activate the newly focused button.
+        def on_control(actions); end
+
+        # Called after a button is added, for a navigation that has an opinion
+        # about where focus starts.
+        def on_buttons_changed; end
+
+        # Called by Menu on each update while the menu is not paused, for a
+        # navigation that counts time. Time enters here and nowhere else.
+        def update(dt); end
+
+        # Called by Menu when it opens, for a navigation holding state that
+        # belongs to one opening — UI::Pointing forgets its aim.
+        def on_opened; end
+      end
+    end
+  end
+end

data/lib/rgame/engine/ui/nine_slice_style.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module UI
+      # A button background drawn from a UI atlas: one nine-slice element per
+      # state, stretched over the button's whole slot.
+      #
+      #   style = UI::NineSliceStyle.new(idle: :button_idle, focused: :button_focus,
+      #                                  pressed: :button_pressed, disabled: :button_disabled)
+      #   menu.add(UI::TextButton.new(label: 'Play', style: style))
+      #
+      # Every state is required, so an atlas missing its disabled element is a
+      # missing keyword where the style is built rather than a lookup failure the
+      # first frame a button is disabled.
+      #
+      # A style is anything answering `draw(renderer, state, width, height)` in
+      # the button's local space, drawing at `z: 0` or below so the button's own
+      # content, at `z: 1`, stays on top. This one draws at the nine-slice
+      # default of 0.
+      #
+      # A style may also answer `content_color(state)`: the colour a button's
+      # label or icon should take over that state's background, or nil to keep
+      # the button's own. Art is the game's, so this one cannot know what reads
+      # on it and always answers nil — PanelButton's dark label is chosen for
+      # the shipped atlas instead.
+      class NineSliceStyle
+        # The element name drawn for each state, keyed by `idle`, `focused`,
+        # `pressed` and `disabled`.
+        attr_reader :elements
+
+        def initialize(idle:, focused:, pressed:, disabled:)
+          @elements = { idle: idle, focused: focused, pressed: pressed, disabled: disabled }.freeze
+        end
+
+        # A copy with some elements replaced — a game whose atlas differs from
+        # the shipped one in a single state names only that state.
+        #
+        #   UI::PanelButton::STYLE.with(focused: :my_glow)
+        def with(**changes) = self.class.new(**@elements, **changes)
+
+        def content_color(_state) = nil
+
+        def draw(renderer, state, width, height)
+          renderer.nine_slice(@elements.fetch(state), 0, 0, width, height)
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/ui/option_button.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module UI
+      # A menu row whose value is chosen from a list, moved with `ui_left` and
+      # `ui_right`.
+      #
+      #   quality = menu.add(UI::OptionButton.new(label: 'shadows', values: %i[off low high]))
+      #   quality.on_changed { |value| settings.shadows = value }
+      #
+      # It draws `Label        < value >`, and the chevrons appear only where
+      # there is somewhere to go — which is the only feedback a player gets that
+      # they have reached an end of the list.
+      #
+      # ## Values move by clamping, while focus wraps
+      #
+      # `Menu` wraps focus at the ends, and this deliberately does not. A list of
+      # menu buttons has no magnitude, so joining its ends only makes a short list
+      # quicker to get around. A list of *values* usually does have one — volume,
+      # difficulty, a resolution — and wrapping turns "one louder" at the top of
+      # the range into silence. Every settings screen a player has used clamps,
+      # so this does too.
+      #
+      # ## A caption is a key, unless it is a Text
+      #
+      # `display` turns a value into what is drawn for it: a key, which the
+      # button makes an Engine::Text of under its `label_scope` just as it does
+      # the label, or a `Text`, used as it is. The default makes a Symbol value
+      # its own key and anything else a literal, so `%i[off low high]` reads
+      # the keys `off`, `low` and `high`, and `[0, 50, 100]` draws the numbers:
+      #
+      #   UI::OptionButton.new(label: 'volume', values: [0, 50, 100],
+      #                        display: ->(percent) { Engine::Text.literal("#{percent}%") })
+      #
+      # `display` is called for the whole list in the constructor. Doing it in
+      # `on_draw` instead would allocate a String every frame for every row on
+      # screen, which is what `Game/NoInterpolationInHotPath` refuses — and the
+      # values themselves are what a game acts on, so they cannot simply be
+      # stored as text.
+      #
+      # A caption `Text` with variables shows the values its last `with` was
+      # given, as a label does.
+      #
+      # The value column is as wide as the widest caption. It is measured again
+      # whenever any caption's String changes — a locale switch, a new scope, a
+      # `with` with new values — which a draw notices by object identity, so a
+      # switch to longer captions widens it and an unchanged draw measures
+      # nothing.
+      class OptionButton < PanelButton
+        # Emits the newly selected value, which is the only thing a listener
+        # wants; `index` is available on the button for anything that needs it.
+        signal :on_changed, Signal.define(:value)
+
+        LEFT_CHEVRON = '<'
+        RIGHT_CHEVRON = '>'
+
+        PADDING = 12
+        GAP = 8
+
+        DISPLAY = ->(value) { value.is_a?(Symbol) ? value : Text.literal(value.to_s) }
+
+        def initialize(label:, values:, index: 0, display: DISPLAY, **)
+          super(label: label, **)
+          @values = values.to_a.freeze
+          shown = @values.map { |value| display.call(value) }
+          @captions = shown.map { |caption| text_for(caption) }.freeze
+          @keyed_captions = @captions.reject.with_index { |_caption, at| shown[at].is_a?(Text) }.freeze
+          @measured = Array.new(@captions.size)
+          @index = @values.empty? ? 0 : index.clamp(0, @values.size - 1)
+        end
+
+        attr_reader :values, :index
+
+        def value = @values[@index]
+
+        # The Engine::Text drawn for the current value, or nil for an empty list.
+        def caption = @captions[@index]
+
+        # Scopes the captions `display` gave as keys along with the label.
+        def label_scope=(scope)
+          super
+          @keyed_captions.each { |caption| caption.scope = label_scope }
+        end
+
+        # Selects `value` if the list holds it, and says whether it did. A game
+        # restoring a saved setting does not have to know where in the list it
+        # sits, and a value that is no longer offered — an old save, a list that
+        # changed between versions — leaves the button where it was rather than
+        # raising.
+        def value=(value)
+          found = @values.index(value)
+          @index = found if found
+        end
+
+        # Moves the selection by `delta`, clamped. Returns the button when it
+        # actually moved and nil otherwise, so a caller can tell "pressed at the
+        # end of the list" from "changed" without comparing values.
+        #
+        # Disabled and empty are both nil for the same reason `activate` is:
+        # a caller never has to check first.
+        def adjust(delta)
+          return nil unless enabled?
+          return nil if @values.empty?
+
+          moved = (@index + delta).clamp(0, @values.size - 1)
+          return nil if moved == @index
+
+          @index = moved
+          on_changed_signal.emit(value)
+          self
+        end
+
+        private
+
+        def draw_foreground(renderer)
+          y = label_y(renderer)
+          color = current_label_color
+          renderer.text(@label, PADDING, y, z: 1, color: color) if @label
+          draw_value(renderer, y, color)
+        end
+
+        def draw_value(renderer, y, color)
+          return if @values.empty?
+
+          chevron = renderer.text_width(RIGHT_CHEVRON)
+          right = width - PADDING - chevron
+          column = column_width(renderer)
+          left = right - GAP - column - GAP - chevron
+
+          renderer.text(LEFT_CHEVRON, left, y, z: 1, color: color) if @index.positive?
+          renderer.text(RIGHT_CHEVRON, right, y, z: 1, color: color) if @index < @values.size - 1
+
+          text = caption.to_s
+          centred = left + chevron + GAP + ((column - renderer.text_width(text)) / 2)
+          renderer.text(text, centred, y, z: 1, color: color)
+        end
+
+        def column_width(renderer)
+          return @column_width if captions_measured?
+
+          @column_width = 0
+          @captions.each_with_index do |caption, at|
+            @measured[at] = caption.to_s
+            width = renderer.text_width(@measured[at])
+            @column_width = width if width > @column_width
+          end
+          @column_width
+        end
+
+        def captions_measured?
+          at = 0
+          while at < @captions.size
+            return false unless @captions[at].to_s.equal?(@measured[at])
+
+            at += 1
+          end
+          true
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/ui/panel_button.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module UI
+      # A UI::TextButton on a nine-slice: the shipped atlas's button, one element
+      # per state, with a dark label.
+      #
+      #   resume = menu.add(UI::PanelButton.new(label: 'resume'))
+      #   resume.on_activated { cutscene.close }
+      #
+      #   menu.add(UI::PanelButton.new(label: 'save_game', enabled: false))
+      #   menu.add(UI::PanelButton.new(label: 'load', style: UI::PanelButton::STYLE.with(idle: :mine)))
+      #
+      # `STYLE` names the element drawn for each state — which is why the shipped
+      # atlas has one for each of the four. It differs from a TextButton only in
+      # its defaults; every one of them can still be passed.
+      class PanelButton < TextButton
+        STYLE = NineSliceStyle.new(idle: :button_idle, focused: :button_focus,
+                                   pressed: :button_pressed, disabled: :button_disabled)
+
+        LABEL_COLOR = Util::Color.new(46, 34, 24)
+        DISABLED_LABEL_COLOR = Util::Color.new(120, 110, 100)
+
+        def initialize(label:, style: STYLE, label_color: LABEL_COLOR,
+                       disabled_label_color: DISABLED_LABEL_COLOR, **)
+          super
+        end
+      end
+    end
+  end
+end