Added ArbSpeedMods function for a better way of setting speed modifiers. Added NotifyHandlerOfSelection to OptionRowHandler to support this. Changed exceptions thrown by OptionRowHandlerLua into log warnings because crashing out is not helpful to themers. Fixed SetEnabledForPlayers in OptionRowHandlerLua to correctly read the PlayerNumber enum. Removed silly git add Docs/Themerdocs/Examples/OptionRowHandlerLua.lua and second check for ExportOnChange.

2014-06-19 06:41:18 -06:00
parent 006fcd84a7
commit 045e9edcdd
9 changed files with 361 additions and 36 deletions
@@ -0,0 +1,110 @@
+-- This will discuss how to create an option row in lua for use on a normal options screen.
+
+-- To try out this example, copy this file to Scripts/ and add the following
+-- line to metrics.ini, on one of the options screens.  Change the "1" to an
+-- appropriate line name and make sure it's in the LineNames list for that
+-- screen.
+-- Line1="lua,FooMods()"
+
+-- When on the screen testing the example, flush the log and read it when
+-- interacting with the option row.  This example doesn't actually apply any
+-- modifiers to the player, it just prints messages to the log file so you can
+-- see what functions are being called.
+-- Make sure you test this with Player 2, Player 1 can't interact with this
+-- option row as part of the example.
+
+-- Comments explaining an element come before the element they explain.
+
+-- The function "FooMods" returns a table containing all the information the
+-- option row handler needs to build the option row.
+function FooMods()
+  return {
+		-- A string with the name of the row.  This name will be localized using
+		-- the entry in the "OptionTitles" section of the language file.
+    Name= "Foo",
+		-- A boolean controlling whether the choice affects all players.
+    OneChoiceForAllPlayers= false,
+		-- A LayoutType enum value.  "ShowAllInRow" shows all items in the row,
+		-- "ShowOneInRow" shows only the choice with focus is shown.
+		-- "ShowOneInRow" is forced if there are enough choices that they would go
+		-- off screen.
+    LayoutType= "ShowAllInRow",
+		-- A SelectType enum value.  "SelectOne" allows only one choice to be
+		-- selected.  "SelectMultiple" allows multiple to be selected.
+		-- "SelectNone" allows none to be selected.
+    SelectType= "SelectMultiple",
+		-- Optional function.  If non-nil, this function must return a table of
+		-- PlayerNumbers that are allowed to use the row.
+		EnabledForPlayers= function(self)
+			Trace("FooMods:EnabledForPlayers() called.")
+			-- Leave out PLAYER_1 just for example.
+			return {PLAYER_2}
+		end,
+		-- A table of strings that are the names of choices.  Choice names are not
+		-- localized.
+    Choices= {"a", "b", "c", "d"},
+		-- Optional table.  If non-nil, this table must contain a list of messages
+		-- this row should listen for.  If one of the messages is recieved, the
+		-- row is reloaded and the EnabledForPlayers function is called if it is
+		-- non-nil.
+		ReloadRowMessages= {"ReloadFooMods"},
+		-- LoadSelections should examine the player and figure out which options
+		-- on the row the player has selected.
+		-- self is the table returned by the original function used to create the
+		-- option row. (the table being created right now).
+	  -- list is a table of bools, all initially false.  Set them to true to
+		-- indicate which options are on.
+		-- pn is the PlayerNumber of the player the selections are for.
+    LoadSelections= function(self, list, pn)
+			Trace("FooMods:LoadSelections(" .. pn .. ")")
+      for i, choice in ipairs(self.Choices) do
+				-- Randomly set some to true just for an example.
+				if math.random(0, 1) == 1 then
+					Trace(choice .. " (" .. i .. ")" .. " set to true.")
+					list[i]= true
+				end
+      end
+    end,
+		-- SaveSelections should examin the list of what the player has selected
+		-- and apply the appropriate modifiers to the player.
+		-- Same args as LoadSelections
+    SaveSelections= function(self, list, pn)
+			Trace("FooMods:SaveSelections(" .. pn .. ")")
+      for i, choice in ipairs(self.Choices) do
+        if list[i] then
+					Trace(choice .. " (" .. i .. ")" .. " set to true.")
+				end
+      end
+    end,
+		-- Optional function.  If non-nil, this function must take 3 parameters
+		-- (self, pn, choice), and return a bool.  It is called when a player
+		-- selects an item in the row by pressing start.
+		-- self is the same as for LoadSelections.
+		-- pn is the PlayerNumber of the player that made the selection.
+		-- choice is the choice the player's cursor is on.
+		-- The return value should be true if the Choices table is changed.  If it
+		-- is true, then LoadSelections will be called to update which choices are
+		-- underlined for each player.
+		-- This function is meant to provide a way for a menu to change the text of
+		-- its choices.  If it returns true, LoadSelections will be called for each
+		-- player.  If OneChoiceForAllPlayers is true, this function will be called
+		-- for each player, which means LoadSelections will be called twice for
+		-- each player.  Well written code shouldn't have a problem with this.
+		NotifyOfSelection= function(self, pn, choice)
+			Trace("FooMods:NotifyOfSelection(" .. pn .. ", " .. choice .. ")")
+			-- Randomly decide whether to change, as an example.
+			local change= math.random(0, 3)
+			-- No change half the time, lengthen or clip strings the other half.
+			if change == 2 then
+				for i, choice in ipairs(self.Choices) do
+					self.Choices[i]= choice .. choice
+				end
+			elseif change == 3 then
+				for i, choice in ipairs(self.Choices) do
+					self.Choices[i]= choice:sub(1, 1)
+				end
+			end
+			return change >= 2
+		end
+  }
+end