Module 04_NumPadEntry
Numpad Entry utility for profile customization.
This is an actor class that implements functionality for having a numpad that is used to enter a number. The parameters for customizing its appearance will be discussed here. For an example, see Docs/ThemerDocs/Examples/Example_Actors/NumPadEntry.lua
This actor handles input, so it has to be used a bit differently from normal actors. Instead of just putting it inside an ActorFrame like normal, you must follow these steps: 1. Call the function "newnumpadentry" and store the result in a local variable. This creates the NumPadEntry that will handle the logic and input of entering a number. Ex:
local entry_pad= new_numpad_entry(params)
2. Call the "create_actors" function of the NumPadEntry you created and put the actors it returns inside your ActorFrame. Ex:
Def.ActorFrame{ entry_pad:create_actors(params) }
3. Set up an input callback for recieving input and pass it to the NumPadEntry you created. Check the return value of the handle_input function to see when the player has finished entering the number. Ex:
local function input(event) if event.type ~= "InputEventType_Release" then local entry_done= entry_pad:handle_input(event.button) end end
4. If handle_input returns true, the player has finished entering the number and you can do something with the value. Each NumPadEntry sets its "done" field to true when the player hits the done button. Ex: -- (continued from above)
if entry_done then Trace("Player entered value: " .. entry_pad.value) end
Params explanation:
"params" is a table containing the parameters used to customize NumPadEntry.
Almost all parameters are optional except for the Name.
Some parameters are interdependent, so if you include one, you should include the ones it is interdependent with to make sure they make sense together.
The parameters can be passed to either newnumpadentry() or to create_actors().
Parameters passed to createactors() are combined with the parameters passed to newnumpad_entry().
If the same parameter is passed to both, the one passed to createactors() overrides the one passed to newnumpad_entry().
NumPadEntry is like an ActorFrame, you can put actors in params and they will be inside it, drawn before (under) everything else.
You can also include custom commands for the NumPadEntry actor and they will be part of the actor returned by create_actors().
Some parameters are custom actors that fill a role. They must support certain commands that will be used to carry out their role. Parameter listing: { Name= "foo", -- A unique string you will recognize later.
-- buttonpositions, rows, and columns are used to positioning the -- buttons and moving the cursor. Each set of "rows" number of entries -- in buttonpositions will be considered one row, and the cursor will -- be wrapped to the beginning/end of the row or moved to a new row or -- column as appropriate when input is handled.
-- Optional. A table of positions for the buttons. Each position is a -- table containing the x, y, and optional z of that button. button_positions= {{x, y, z}, {x, y, z}, ...}, rows= 4, -- Optional. The number of rows on the pad. columns= 4, -- Optional. The number of columns on the pad.
-- Optional. The button that the cursor starts on. The default is the -- button in the middle of the pad. cursor_pos= 5,
donetext= "&start;", -- Optional. The text used for the "Done" button. backtext= "←", -- Optional. The text used for the -- "Backspace" button.
-- Optional. The values of the buttons. One of them should have -- donetext as a value and one should have backtext as a value. The -- default is for a standard 12 button numpad, numbers 0-9, done, and -- backspace. buttonvalues= {7, 8, 9, 4, 5, 6, 1, 2, 3, 0, donetext, back_text},
-- buttonpositions, buttonvalues, rows, columns, and cursor_pos are -- all interdependent. If you pass one, you should pass them all.
-- Optional. The amount to multiply by when adding a digit. digitscale= 10, -- Optional. If the player tries to set the value above this amount, -- InvalidValueCommand will be played on the actor. Default allows any -- value. maxvalue= 300, -- Optional. When the current value is above this, the cursor will be -- moved to the done button. Default is to never automatically move the -- cursor. autodonevalue= 100,
-- Optional. The various default actors will use this font if a -- specific for the actor is not passed in and they are not replaced by -- custom actors. Default is "Common Normal". Font= "Common Normal",
-- Commands: These are some commands that are recommended, but not -- required.
-- Optional. You can pass an InitCommand to set the position and stuff. InitCommand= function() end,
-- Optional. InvalidValueCommand will be executed when the player tries -- to enter an invalid value. params is a table containing the value. -- The default plays the common invalid sound. InvalidValueCommand= function(self, params) Trace(params[1]) end,
-- Optional. EntryDoneCommand will be executed when the player presses -- the done button. params is a table containing the value. The -- default does nothing. EntryDoneCommand= function(self, params) Trace(params[1]) end,
-- Actors: These are the optional custom actors you can provide to -- change the appearance of each part of the numpad. -- Each of them has a default that can be customized in minor ways, or -- you can provide a full actor to replace the default.
-- Optional. The color the default cursor will use. Unused if you pass -- in a custom cursor. cursor_color= Color.black, -- Optional. The actor used for the cursor. Should have the Move and -- Fit commands. Default is a simple quad that moves and changes its -- width. -- When a cursor movement occurs, MoveCommand will be executed, followed -- by FitCommand. Both are executed by playcommand so they can be -- passed parameters. Default Move and Fit commands do nothing. cursor= Def.Quad{
-- param is the position to move to. Be sure to avoid a tween -- overflow. MoveCommand= function(self, param) end, -- param is the actor for the button the cursor is moving to. FitCommand= function(self, param) end,
}, -- Required. Where the cursor should be placed in the ActorFrame of the -- numpad. "first" means the cursor will be placed first, and thus -- under all the buttons. "last" means the cursor will be placed last, -- and thus above all the buttons. nil means no cursor. cursor_draw= "first",
-- Optional. The font used by the default button actor. Unused if you -- pass in a custom button actor. buttonfont= "Common Normal", -- Optional. The color used by the default button actor. Unused if you -- pass in a custom button actor. Default is White. buttoncolor= Color.White, -- Optional. A template for the actor that will be used for each button. -- This template will be duplicated for each button. -- Do not provide a name in the button template, each button will be -- named uniquely by the numpad like this: Name= "num"..index -- Do not attempt to do any positioning in the InitCommand for your -- button actor, positioning will be handlded by the numpad, using the -- positions provided in button_positions. -- GainFocus, LoseFocus, and Press are optional commands for handling -- their respective events. button= Def.BitmapText{
InitCommand= cmd(diffuse, Color.White), -- SetCommand is executed after InitCommand to set the value for the -- button. param is a table containing a value from button_values. SetCommand= function(self, param) self:settext(param[1]) end, -- GainFocusCommand is executed when the cursor moves onto the button. GainFocusCommand= cmd(diffuse, Color.Red), -- LoseFocusCommand is executed when the cursor moves off the button. LoseFocusCommand= cmd(diffuse, Color.White), -- PressCommand is executed when the button is pressed. PressCommand= cmd(stoptweening; linear,.1; zoom,2; linear.1; zoom,1)
},
-- Optional. The position to place the default value text at. Position -- is a table of x, y, and optional z. Unused if you pass in a custom -- value actor. valuepos= {0, -48}, -- Optional. The font to use for the default value actor. valuefont= "Common Normal", -- Optional. The color for the default value text. Unused if you pass -- in a custom value actor. Default is White. value_color= Color.White, -- Optional. The actor used for displaying the value the player has -- entered so far. Default is a simple BitmapText. value= Def.BitmapText{
Font= "Common Normal", -- InitCommand should set the position you want if you pass a custom -- actor. InitCommand= cmd(xy, 0, -48), -- SetCommand will be executed when a button is pressed and the value -- is changed. param is a table containing the new value. SetCommand= function(self, param) self:settext(param[1]) end
},
-- Optional. The position to place the default prompt actor at. -- Position is a table of x, y, and optional z. promptpos= {0, -72}, -- Optional. The font to use for the default prompt actor. promptfont= "Common Normal", -- Optional. The color used by the default prompt actor. promptcolor= Color.White, -- Optional. The text used by the default prompt actor. Default is "". prompttext= "", -- Optional. The actor to use for displaying the prompt. Any actor you -- want. It should support a Set command if the NumPadEntry is on a -- screen where it will be reused for different numbers. prompt= Def.BitmapText{
Font= "Common Normal", -- InitCommand should set the position you want if you pass a custom -- actor. InitCommand= cmd(xy, 0, -48), -- SetCommand will be executed when a button is pressed and the value -- is changed. param is a table containing the new value. SetCommand= function(self, param) self:settext(param[1]) end
}, }