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

Overview

The Lyrion Music Server software comes equipped with a number (currently five) 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.

Input modes will generally have a valueRef parameter. This will reference the current value of the input. It is a reference so that variables in the calling mode (or elsewhere in the program) can be directly modified by the input mode. Variables not directly modifiable by means of a reference can be modified in the callback function, or in an onChange function, if available to 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. It can also be supplied as the string "upper" to refer to @numberLettersUpper.
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, resulting in the empty 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 remaining 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: 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. The mode is not actually changed by this function, so all mode parameters are still available.

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 it does not already match. This is done through a sequential search of the supplied listRef. If the list is of significant size and a faster search method is available, it is recommended that the calling mode use that method to supply the listIndex parameter.

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). If valueRef is not being used to update a variable outside the input mode, it is recommended to leave it undefined, and allow it to be initialized by the input mode.

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.
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.
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.
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"
Some combination of the letters C, V, and I, or the empty string. The C indicates that the client object should be passed to the function, the V indicates that the internal value should be passed, and the I indicates that the index of the current item should be passed. The arguments will always come in the order C, then V, then I, skipping arguments which do not appear.
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. A value of L indicates that a lookup function, supplied in lookupRef determined the sort order. Any other value, or no supplied value, means that the list will be treated as unsorted.
lookupRef
Default: undef
Lookup function reference, as used by Slim::Buttons::Common::numberScroll(). Takes an index and returns a value for that index.

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. The mode is not actually changed by this function, so all mode parameters are still available.

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
By default, generated when the play button is pressed.
add
By default, generated when the add button is pressed.
search
By default, generated when the search button is pressed.
left
Generated when the cursor is moved left from the leftmost position.
right
Generated when the cursor is moved right from the rightmost position.
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. The mode is not actually changed by this function, so all mode parameters are still available.

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.
handleLeaveMode
Default: undef
If set and true then the exit callback handler function will be invoked whenever the mode is left. This is most useful if the mode wants to exit if another mode is pushed.
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.
trackValueChanges
Default: undef
Allow the value referenced by valueRef to be modified externally and to track such changes before applying up/down changes.
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.
cursor
Default: undef
Places a visible cursor at the specified position.
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.Bar mode. The mode is not actually changed by this function, so all mode parameters are still available.

[% PROCESS helpfooter.html %]