[% pageicon = 'help' %] [% pagetitle = 'Using Input Modes' %] [% techinfo = '1' %] [% PROCESS helpheader.html %]

#### Overview

The SlimServer software comes equipped with a number (currently one) of generic input modes which can be used by other modes to handle interaction with the user via the remote. This allows module writers to concentrate on what to do with the input rather than the gathering of that input.

The general method of using these input modes is to push into them from your module, setting certain parameters as desired. The most important parameter will be callback which is a reference to a function that will be called when the input session is complete, and which will then handle that input. Other parameters will vary depending on the input mode being used.

When circumstances indicate the possibility that input is complete, an exit event is generated. The callback function will be invoked to determine the action to be taken. It will be called with parameters indicating the client and the type of exit event. The input modes do not exit themselves, it is left to the callback function to decide when to leave the input mode.

It should be noted that the parameters supplied to the input modes are stored in the stack of mode parameter hashes contained in the client object. As such, all parameters will be accessible to the callback function until the input mode is left. If the mode is popped off the mode stack all parameters will be lost. Any maintenance of the parameters between entries into the input mode are the responsibility of the calling mode.

The input mode names are INPUT.modulename, where modulename is the name of the .pm file. A typical entry into the INPUT.Text mode follows:

    Slim::Buttons::Common::pushMode($client,'INPUT.Text',
    					{'callback' => \&myCallback
    					,'valueRef' => 'Some Initial String'
    					,'charsRef' => 'Upper'
    					,'numberLetterRef' => \@myNumberLetterArray
    					,'header' => string('SOME_STRING_FOR_THE_TOP')
    					});

#### The Input Modes

Text
  Handles input of arbitrary strings.
List
  Handles selection of an item from a list of options.
Tree
  Handles navigation of and selection from a tree of options.
Time
  Handles input of a time-based variable.
Bar
  Handles selection of a number from a range, using the amount a bar is filled to indicate position of the number in the range.

#### Text

##### Description

The Text input mode is used to enter arbitrary strings. It restricts characters in the string to a list of allowable characters which can be provided when entering the mode. The rightarrow symbol is used to indicate when advancing past the end of the string will generate an exit event. It is never allowed anywhere in the string other than the end. Calling modes should strip off this symbol from the end of the string prior to using the input value.

The string is scrolled to keep the cursor within the viewable area, except when the viewable area is scrolled manually. Any change in either the cursor position or the character at the cursor results in the viewable area being snapped back such that the cursor is again visable.

On entry into the mode, any characters in the initial string not within the list of allowable characters are replaced by spaces (if the space character is allowable) or are removed.

##### Parameters

The following parameters are used by the INPUT.Text mode. They are listed in the order of likelyhood to be supplied. Other parameters can be supplied for use by the callback function, but will not otherwise have any effect on the INPUT.Text behavior.

callback
  Default: none
  A code reference which is called whenever an exit event occurs. This parameter should always be supplied by the calling mode, otherwise INPUT.Text will simply perform a pop mode on an exit event, potentially losing any input. The procedure referenced should take the client object as the first parameter and the exit event type as the second.
header
  Default: "Enter Text:" (not localized)
  String to display on the top line of the display. This parameter can be interpreted in a number of ways, see above. After the value to be displayed is determined, it is then modified according to the stringHeader and headerAddCount parameters, below.
stringHeader
  Default: undef
  If set to a true value, the display value of header is passed to the `string()` function to be localized. If no localized string is defined for the value of header, it is displayed as is.
valueRef
  Default: ""
  valueRef contains a reference to the string being edited. It can initially be set to a plain string scalar, in which case it will be converted into a reference to that scalar.
charsRef
  Default: reference to internal @UpperChars array
  charsRef contains a reference to the list of allowable characters. It can be supplied as an array reference, or as the strings "upper" or "both", which are converted to references to the internal @UpperChars and @BothChars arrays, respectively.
numberLetterRef
  Default: reference to internal @numberLettersMixed array
  numberLetterRef contains a reference to the list of characters to use for number key entry. It can be supplied as an array reference, or unsupplied for the default array..
doublesizeReplace
  Default: none
  A reference to a hash of characters to replace in doublesize mode for display. This would most likely be done for custom characters which have no doublesize equivalents. The referenced hash has keys equal to the character to replace, and values equal to the character to use in doublesize mode. For example, to replace the custom character myCustom with "M" when doublesized would be `{Slim::Display::Display::symbol("myCustom") => "M"}`
charIndex
  Default: index of the current character within the charsRef array
  The index of the current character within the charsRef array. If supplied, and if cursorPos ends up at the end of the valueRef string, the character at this index will be appended to the end of valueRef, otherwise, the rightarrow will be used. This parameter will not usually need to be set on entry, but is used within the INPUT.Text mode.
cursorPos
  Default: end of initial string
  The current position of the cursor, which determines which character will be modified. This parameter will not usually need to be set on entry, but is used within the INPUT.Text mode.
displayPos
  Default: either the beginning of the string, or such that the cursor is at the rightmost position on the display.
  The position within the string at which to begin the display in single-height mode. If supplied when entering the mode it will be ignored. This parameter will not usually need to be set on entry, but is used within the INPUT.Text mode.
displayPos2X
  Default: either the beginning of the string, or such that the cursor is at the rightmost position on the display.
  The position within the string at which to begin the display in double-size mode. If supplied when entering the mode it will be ignored. This parameter will not usually need to be set on entry, but is used within the INPUT.Text mode.
rightIndex
  Default: index of rightarrow within the charsRef array
  If rightarrow is within the list of allowable characters, its index is stored in the rightIndex parameter. Otherwise, the value of rightIndex is set to -1. If supplied when entering the mode it will be ignored. This parameter will not usually need to be set on entry, but is used within the INPUT.Text mode.
parentMode
  Default: name of mode which called INPUT.Text
  This parameter is used with the passback function to let a calling mode set up its own button handling functions, which can then be mapped as desired by the user. The default is actually the first non-INPUT mode up the mode stack from the current location in order to prevent infinite recursion.

##### Exit Event Types

The callback function should handle the following event types in some way. Ignoring them is acceptable, crashing the server is not.

backspace
  Generated when the backspace function is called when the cursor is at the beginning of the string.
cursor_left
  Generated when the cursor is requested to move left, and is already at the beginning of the string.
cursor_right
  Generated when the cursor is requested to move right, and is already at the end of the string.
delete
  Generated when the delete function is called on the last character in the string.
nextChar
  Generated when the nextChar function is called and the current character is the right arrow.
scroll_left
  Generated when a scroll to the left is requested, but the beginning of the string is already being displayed.
scroll_right
  Generated when a scroll to the right is requested, but the last character of the string is already being displayed in the leftmost column of the display.
Other
  Generated by the exit function where the type is determined by the argument supplied. Usually will be a button name like play or add, but be prepared for anything.

##### Functions

up
  Changes the current character to the one preceding it in the character list. Repeat is allowed and accelerates.
down
  Changes the current character to the one following it in the character list. Repeat is allowed and accelerates.
backspace
  The current character is deleted and the cursor moved one place to the left. If that movement would place the cursor before the first position in the string, an exit event is generated with a type of backspace. This function is not designed to be used with repeat.
delete
  Similar to backspace, except the cursor is not moved. If the last character in the string is deleted, an exit event of type delete is generated. This function is not designed to be used with repeat.
nextchar
  The cursor is advanced to the next position. If the cursor was at the end of the string and the rightarrow was not the current character, then an additional character is added to the end of the string prior to moving the cursor there. The added character will be the rightarrow character if that character is in the list of allowable characters, otherwise the first character in the list is used. If the cursor was at the end and the current character was the rightarrow, then an exit event of type nextchar is generated. This function is not designed to be used with repeat.
cursor
  This function takes an argument to indicate the direction and distance to move the cursor. Use left to move the cursor left and right to move it right. The left or right may be followed by an underscore and a number indicating the distance to move in that direction. If no distance is specified, it defaults to a value of one. If the cursor was originally at either end of the string and is requested to move off the end, an exit event is generated with a type of either cursor_left or cursor_right, depending on the requested direction. Repeat is allowed, and takes place at a constant rate. The cursor stops when it hits the end under repeat, but an exit event is not generated until the button is released and pressed again.
scroll
  This function takes an argument to indicate the direction and distance to move the viewable area. Use left to move the viewable area left and right to move it right. The left or right may be followed by an underscore and a number indicating the distance to move in that direction. If no distance is specified, it defaults to a value of one. If the beginning of the viewable area was originally at either end of the string and is requested to move off the end, an exit event is generated with a type of either scroll_left or scroll_right, depending on the requested direction. Repeat is allowed, and takes place at a constant rate. The movement stops when it hits the end under repeat, but an exit event is not generated until the button is released and pressed again.
insert
  Inserts a character at the current cursor location. The character to be inserted can be supplied as an argument to the function, otherwise the first non-rightarrow character in the character list is used. Any supplied character must be in the allowed list of characters, otherwise a space character is substituted. Since the design of the button mapping mechanism does not allow for the use of the space character, the = character, or the # character within arguments, alternate representations are required. These can be specified as follows:
  - anything beginning with "sp" for the space character
  - anything beginning with "eq" for the = character
  - any of "hash", "sharp", "pound", or a string beginning with "num" for the # character
  This function is not designed to be used with repeat.
clear
  Truncates the string and adds either the rightarrow or, if the rightarrow is not in the list of characters, the first character in the list. This function is not designed to be used with repeat.
numberLetter
  This function takes an argument, which it then passes to Slim::Buttons::Common::numberLetter. The returned character is then checked against the list of allowable characters, and replaced by a space if not present. The cursor is advanced to the next character if a different button is pressed than the previous, or after an amount of time equal to the displayTextTimeout setting passes. This function is not designed to be used with repeat.
letter
  Takes an argument, which is then validated (checked against the list of characters, with similar replacements as the insert function). The current character is changed to the validated character, and the cursor advanced. This function is not designed to be used with repeat.
exit
  Takes an argument. An exit event is generated with the type being the supplied argument. If no argument is supplied, the exit event type is exit.
passback
  Executes the last button event (button plus pressing style) in the context of the parent mode (set by the parentMode parameter). This allows for parent modes to map button presses to functions without needing to modify the mapping of the INPUT.Text mode.

#### List

##### Description

The List input mode is used to select one item from a list of items. The items in the list can have different representations internally and externally. An onChange handler can be provided for immediate effects of changing position in the list.

On entry into the mode, the initial selection will depend on the supplied parameters. If valueRef is supplied, and the value it references is contained in the list referenced by the supplied listRef, then listIndex is updated to reflect the position of the supplied value. If valueRef is not supplied, or if its value does not appear in the list, it will be updated to be the value at position listIndex (if supplied and in bounds, 0 if not supplied or out of bounds).

This mode will not maintain state between invocations, so if such state information needs to be kept, it is the responsibility of the calling mode to do so.

##### Parameters

The following parameters are used by the INPUT.List mode. They are listed in the order of likelyhood to be supplied. Other parameters can be supplied for use by the callback, external display, or change handler functions, but will not otherwise have any effect on the INPUT.List behavior.

The header, externRef, and overlayRef parameters can be supplied in a number of different ways. If a scalar, it will be displayed as is. If a code reference, it will be invoked with the arguments specified in the corresponding Args parameter (header would use headerArgs etc.) and the return value will be displayed. If a hash reference, the value corresponding to the key indicated by the referenced value of valueRef will be displayed. If an array ref, the value at listIndex of the array is extracted and then interpreted as above. If the extracted value is itself an array ref, the array referenced is returned (this would most likely be the case for overlayRef, which expects an array final value).

listRef
  Default: none
  An array reference to the list of items. This parameter must be supplied or the INPUT.List mode will not be entered. This list should be the internal representations of the item values. If an array ref is supplied for externRef but not listRef, listRef will be set to the same reference as externRef.
header
  Default: "Select item:" (not localized)
  String to display on the top line of the display. This parameter can be interpreted in a number of ways, see above. After the value to be displayed is determined, it is then modified according to the stringHeader and headerAddCount parameters, below.
headerArgs
  Default: "CV"
  One of "CV", "C", "V", or "". The C indicates that the client object should be passed to the function to determine the header value, the V indicates that the internal value should be passed.
stringHeader
  Default: undef
  If set to a true value, the display value of header is passed to the `string()` function to be localized. If no localized string is defined for the value of header, it is displayed as is.
headerAddCount
  Default: undef
  If set to a true value, a string like " (X of Y)" (where the "of" is localized) is appended to the end of the header. The X is the one-based index of the current item in the list, and the Y is the total number of items in the list. This addition takes place after the header is modified by stringHeader.
externRef
  Default: none
  The value to be displayed on the bottom line of the display, see above for interpretation of this parameter. If this parameter is not supplied, it will be set to the same reference as listRef. After the value to be displayed is determined, it is then modified according to the stringExternRef parameter below.
externRefArgs
  Default: "CV"
  One of "CV", "C", "V", or "". The C indicates that the client object should be passed to the function to determine the external value, the V indicates that the internal value should be passed.
stringExternRef
  Default: undef
  If set to a true value, the display value of externRef is passed to the `string()` function to be localized. If no localized string is defined for the value of externRef, it is displayed as is.
callback
  Default: none
  A code reference which is called whenever an exit event occurs. If this parameter is not supplied, INPUT.List will perform a pop mode right on left exit event, bump right on right exit events, and a simple pop mode on other types of exit event. This behavior should be sufficient for simple list displays where nothing needs to happen on a right exit event. The procedure referenced should take the client object as the first parameter and the exit event type as the second.
valueRef
  Default: reference to copy of item in listIndex position in list
  valueRef contains a reference to the currently selected item. Typically this will be a reference to a variable local to the calling mode, so that the final value will not need to be explicitly assigned to some local variable.
listIndex
  Default: 0
  The (zero based) index of the currently selected item.
overlayRef
  Default: undef
  Strings to use as the overlay. See interpretation rules above.
overlayRefArgs
  Default: "CV"
  One of "CV", "C", "V", or "". The C indicates that the client object should be passed to the function to determine the overlay values, the V indicates that the internal value should be passed.
noWrap
  Default: undef
  Determines whether or not to wrap around the ends of the list. If set to a true value, attempts to scroll past either end of the list will result in a bump up or down animation, depending on the requested direction. When left unset, or set to a false value (the default), moving up past the beginning of the list will take you to the end of the list, and moving down beyond the end of the list will take you back to the beginning. The ends are sticky, so the wraparound will not take place while repeating.
onChange
  Default: none
  A code reference which is executed each time the currently selected item changes. It is passed arguments according to the value of onChangeArgs. Any return value will be ignored.
onChangeArgs
  Default: "CV"
  One of "CV", "C", "V", or "". The C indicates that the client object should be passed to the function, the V indicates that the internal value should be passed.
parentMode
  Default: name of mode which called INPUT.List
  This parameter is used with the passback function to let a calling mode set up its own button handling functions, which can then be mapped as desired by the user. The default is actually the first non-INPUT mode up the mode stack from the current location in order to prevent infinite recursion.
isSorted
  Default: undef
  Indicates whether the internal or external list is sorted for purposes of the numberScroll function. I indicates that the internal list is sorted and E, the external. Any other value, or no supplied value, means that the list will be treated as unsorted.

##### Exit Event Types

The callback function should handle the following event types in some way. Ignoring them is acceptable, crashing the server is not.

left
  By default, generated by a left button press. If no callback function specified, this will result in leaving the mode with the animated push to the right.
right
  By default, generated by a right button press. If no callback function specified, this will result in a bump right animation.
Other
  Generated by the exit function where the type is determined by the argument supplied. Usually will be a button name like play or add, but be prepared for anything.

##### Functions

up
  Changes the current position in the list. Repeat is allowed and accelerates.
down
  Changes the current position in the list. Repeat is allowed and accelerates.
exit
  Takes an argument. An exit event is generated with the type being the supplied argument. If no argument is supplied, the exit event type is exit.
passback
  Executes the last button event (button plus pressing style) in the context of the parent mode (set by the parentMode parameter). This allows for parent modes to map button presses to functions without needing to modify the mapping of the INPUT.List mode.

#### Tree

##### Description

Not currently implemented.

#### Time

##### Description

The Time input mode is used to enter time values. It restricts values to the allowable timeFormat as specified by the server settings. Entry of digits is automatically allocated to valid columns.

##### Parameters

The following parameters are used by the INPUT.Time mode. They are listed in the order of likelyhood to be supplied. Other parameters can be supplied for use by the callback function, but will not otherwise have any effect on the INPUT.Time behavior.

callback
  Default: none
  A code reference which is called whenever an exit event occurs. This parameter should always be supplied by the calling mode, otherwise INPUT.Time will simply perform a pop mode on an exit event, potentially losing any input. The procedure referenced should take the client object as the first parameter and the exit event type as the second.
header
  Default: "Enter Time:" (not localized)
  String to display on the top line of the display. This string is displayed as supplied, so be sure to localize any strings used.
valueRef
  Default: 0
  valueRef contains a reference to the string being edited. It can initially be set to a plain string scalar, in which case it will be converted into a reference to that scalar.
onChange
  Default: none
  A code reference which is executed each time the currently selected item changes. It is passed arguments according to the value of onChangeArgs. Any return value will be ignored.
onChangeArgs
  Default: "CV"
  One of "CV", "C", "V", or "". The C indicates that the client object should be passed to the function, the V indicates that the internal value should be passed.
cursorPos
  Default: beginning of time string
  The current position of the cursor, which determines which character will be modified. This parameter will not usually need to be set on entry, but is used within the INPUT.Time mode.
parentMode
  Default: name of mode which called INPUT.Time
  This parameter is used with the passback function to let a calling mode set up its own button handling functions, which can then be mapped as desired by the user. The default is actually the first non-INPUT mode up the mode stack from the current location in order to prevent infinite recursion.

##### Exit Event Types

The callback function should handle the following event types in some way. Ignoring them is acceptable, crashing the server is not.

play
  Generated when the backspace function is called when the cursor is at the beginning of the string.
left
  By default, generated by a left button press. If no callback function specified, this will result in leaving the mode with the animated push to the right.
right
  By default, generated by a right button press. If no callback function specified, this will result in a bump right animation.
Other
  Generated by the exit function where the type is determined by the argument supplied. Usually will be a button name like play or add, but be prepared for anything.

##### Functions

up
  Changes the current digit one higher in value. Repeat is allowed and accelerates. Rolling over will increment values to the left.
down
  Changes the current digit one lower in value. Repeat is allowed and accelerates. Rolling over will decrement values to the left.
left
  The the cursor moved one place to the left. If that movement would place the cursor before the first position in the string, an exit event is generated with a type of left. This function is not designed to be used with repeat.
right
  The cursor is advanced to the next position. If the cursor was at the end, then an exit event of type right is generated. This function is not designed to be used with repeat.
cursor
  This function takes an argument to indicate the direction and distance to move the cursor. Use left to move the cursor left and right to move it right. The left or right may be followed by an underscore and a number indicating the distance to move in that direction. If no distance is specified, it defaults to a value of one. If the cursor was originally at either end of the string and is requested to move off the end, an exit event is generated with a type of either left or right, depending on the requested direction. Repeat is allowed, and takes place at a constant rate. The cursor stops when it hits the end under repeat, but an exit event is not generated until the button is released and pressed again.
numberLetter
  This function enters a digit directly in the string. The cursor is advanced to the next character if a different button is pressed than the previous, or after an amount of time equal to the displayTextTimeout setting passes. This function is not designed to be used with repeat.
exit
  Takes an argument. An exit event is generated with the type being the supplied argument. If no argument is supplied, the exit event type is exit.
passback
  Executes the last button event (button plus pressing style) in the context of the parent mode (set by the parentMode parameter). This allows for parent modes to map button presses to functions without needing to modify the mapping of the INPUT.Time mode.

#### Bar

##### Description

The Bar input mode is used to select a value that is best represented as on a sliding scale. This may be a single direction or bi-directional slider.

On entry into the mode, the initial selection will depend on the supplied parameters. If valueRef is supplied, then the mode will begin with that value. If valueRef is not supplied, or if its value does not appear in fit withing the bounds supplied in the other parameters, the value will be assumed to be zero.

This mode will not maintain state between invocations, so if such state information needs to be kept, it is the responsibility of the calling mode to do so.

##### Parameters

The following parameters are used by the INPUT.Bar mode. They are listed in the order of likelyhood to be supplied. Other parameters can be supplied for use by the callback, external display, or change handler functions, but will not otherwise have any effect on the INPUT.Bar behavior.

The header parameter can be supplied in a number of different ways. If a scalar, it will be displayed as is. If a code reference, it will be invoked with the arguments specified in the corresponding Args parameter (header would use headerArgs etc.) and the return value will be displayed. If a hash reference, the value corresponding to the key indicated by the referenced value of valueRef will be displayed. If an array ref, the value at listIndex of the array is extracted and then interpreted as above. If the extracted value is itself an array ref, the array referenced is returned.

header
  Default: "Select item:" (not localized)
  String to display on the top line of the display. This parameter can be interpreted in a number of ways, see above. After the value to be displayed is determined, it is then modified according to the stringHeader and headerAddCount parameters, below.
headerArgs
  Default: "CV"
  One of "CV", "C", "V", or "". The C indicates that the client object should be passed to the function to determine the header value, the V indicates that the internal value should be passed.
stringHeader
  Default: undef
  If set to a true value, the display value of header is passed to the `string()` function to be localized. If no localized string is defined for the value of header, it is displayed as is.
callback
  Default: none
  A code reference which is called whenever an exit event occurs. If this parameter is not supplied, INPUT.Bar will perform a pop mode right on left exit event, bump right on right exit events, and a simple pop mode on other types of exit event. This behavior should be sufficient for simple list displays where nothing needs to happen on a right exit event. The procedure referenced should take the client object as the first parameter and the exit event type as the second.
valueRef
  Default: reference to copy of item in listIndex position in list
  valueRef contains a reference to the currently selected item. Typically this will be a reference to a variable local to the calling mode, so that the final value will not need to be explicitly assigned to some local variable.
min
  Default: 0
  Sets the minimum value allowed for selection. The slider will stop and hold at this value unless the user selects a greater value.
max
  Default: 100
  Sets the maximum value allowed for selection. The slider will stop and hold at this value unless the user selects a lesser value.
mid
  Default: 0
  Sets the midpoint reference for bi-directional sliders. Accellerated scrolling will pause at this point, and the bar will display mirrored output centred on this point.
increment
  Default: 2.5
  Determines the value increase for each step in the scrolling function.
barOnDouble
  Default: 0
  Determines the display when large fonts are used. Setting to 1 will show only the Bar on large fonts. The default of 0 shows the header line provided by the header parameter.
onChange
  Default: none
  A code reference which is executed each time the currently selected item changes. It is passed arguments according to the value of onChangeArgs. Any return value will be ignored.
onChangeArgs
  Default: "CV"
  One of "CV", "C", "V", or "". The C indicates that the client object should be passed to the function, the V indicates that the internal value should be passed.

##### Exit Event Types

The callback function should handle the following event types in some way. Ignoring them is acceptable, crashing the server is not.

left
  By default, generated by a left button press. If no callback function specified, this will result in leaving the mode with the animated push to the right.
right
  By default, generated by a right button press. If no callback function specified, this will result in a bump right animation.
Other
  Generated by the exit function where the type is determined by the argument supplied. Usually will be a button name like play or add, but be prepared for anything.

##### Functions

up
  Changes the current position in the list. Repeat is allowed and accelerates. If the bar is bi-directional, there will be a pause at the middle value
down
  Changes the current position in the list. Repeat is allowed and accelerates. If the bar is bi-directional, there will be a pause at the middle value
exit
  Takes an argument. An exit event is generated with the type being the supplied argument. If no argument is supplied, the exit event type is exit.
passback
  Executes the last button event (button plus pressing style) in the context of the parent mode (set by the parentMode parameter). This allows for parent modes to map button presses to functions without needing to modify the mapping of the INPUT.List mode.

[% PROCESS helpfooter.html %]