[% 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:
- 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.
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 %]