Scrolling Selection Window

Example code puts up a selection window. This use shows a title bar with red and green halves to cancel and confirm selections, and (behind line 8) red and green sliders, which are another way to cancel and confirm selections. This use of the selection window is in multi-select mode, and lines 2, 5, and 10 are all selected.

ScrollingSelectionWindow.bas is a user-defined function for RFO-BASIC! and its variants that implements a selection window. The selection window has:

• A list of entries that can be selected or unselected by tapping them.
• If there are more entries than fit on the screen at the same time, it has a scroll bar at the right edge of the screen.
• It may have a title bar at the top of the window.
• It may have sliders in the middle of the window that let the user confirm or cancel the selections.

The selection window can operate in one of two modes:

• In multi-select, the user can select any number of entries, from none at all to all of them.
• In radio button, the user can select only one entry. Selecting an entry un-selects the entry previously selected. However, at the start of radio-button operation, there might be no selected entry.

This article has instructions for the end-user, followed by instructions to the BASIC programmer on how to include the selection window in a program.

Operating instructions

Depending on how the BASIC program is coded, you may sometimes see a selection window. It will list several options that you can select. Unselected options appear unhighlighted (typically gray). Selected options appear highlighted (typically white).

Selecting

If the window is written to let you select a single option (radio-button mode), tap that line. It should brighten to indicate that it is selected. To change your mind, tap a different line. The new line will brighten and the old line will dim. Then confirm or cancel your selection, as described below.

If the window is written to let you make multi-selections, tap a line to change its state. If the option was not selected, it will brighten; if it was selected, it will dim. Again, confirm or cancel your selection, as described below.

Scrolling

The selection window can accommodate more entries than can appear in the window at once. To see different regions of the list, touch anywhere in the window, but instead of tapping, move your finger up or down before lifting it. The entire list should scroll, until you reach the end of the list in that direction.

In this case, there will also be a scroll bar at the right edge of the window. Touch this bar and drag it up or down in order to scroll the entries quickly. Drag it to the top of the window to go to the start of the list; drag it to the bottom of the window to go to the end of the list. The height of the scroll bar, and its vertical location, represents where the displayed entries are in the overall list. The scroll bar brightens up when the device is ready for you to drag it up or down.

Confirming or cancelling

The way you exit the selection window depends on how the BASIC program is written.

• There may be dim red and green circles in the middle of the window. If so, then to confirm your selection, touch the green circle (until it brightens), then drag it off the right edge of the window. To cancel your selection, touch the red circle (until it brightens), then drag it off the left edge of the window.
• The title bar at the top of the window may have red and green halves, with the "back out" and "proceed" symbols. If so, then to confirm your selection, tap the green half. To cancel your selection, tap the red half.
• In some uses of the selection window, any touch outside the window cancels your selection.

Cancelling generally undoes all your taps to the selection window. If you see the selection window again, the selections revert to the way they were the last time you saw the selection window.

Programming instructions

lsel

Present a scrolling selection window to the user

Synopsis

lsel(bp)

Description

The lsel() (list selection) function displays a window in which the user can, by tapping string legends, select and deselect options that the caller provides, then indicate that the selections are either confirmed or cancelled.

The bp parameter is a bundle pointer. The caller provides bundle elements to influence the behavior of lsel(). The caller must provide a listText element to specify the displayed text of each option. lsel() modifies bundle elements, and may create additional bundle elements, to return information to the caller. A complete list of bundle elements is set out in tables below.

The bundle gives the caller wide latitude in the appearance and function of the selection window. In particular, the caller's declaration that the selection is confirmed or cancelled is at the discretion of the calling code. The caller receives information to override this decision, or perhaps to give the user a second chance.

The numeric return value of lsel() is as follows:

• In multi-select mode, the function returns the number of options that were selected (the length of listSelected).
• In radio-button mode, the function returns the index of the selected option, or 0 if the caller did not provide a listSelected and the user tapped no option. Any selected option is also available as the first element of listSelected, and any other elements are cleared.

Bundle elements

The lsel() function uses the elements of bp to exchange information with the caller.

The use of CamelCase in this table is optional; lsel() ignores case in the names of keys of input parameters. Keys that provide output from lsel() must be matched exactly; if you passed a listselected key to lsel(), it would return values in listSelected, as shown in the table, which is a different key.

Key	Input/ Output	Meaning	Default
allowout	I	Set nonzero to let the user tap outside the selection window. This is a command to confirm the selections unless outIsCancel is also set.	0
canceled	O	Returns 1 if the user cancels the selections. Returns 0 if the user confirms the selections.	(output only)
col*	I	Keys starting with col specify colors and are set out in the next table below.	—
discarded	O	This is a pointer to a numeric list. The caller can pass a pointer to an existing list. If the user cancels the selections, the function uses this key (creating a list if not already done). The list is set to the numbers of the options that were selected when the user cancelled the selection.	(output only)
hatchDarken	I	Requires Oli-BASIC. Set it nonzero to apply a decorative soft crosshatch pattern to the darkened background.	0
listSelected	I/O	A pointer to a numeric list. If provided at input, each element is a number specifying an option to display as initially selected; otherwise, lsel() creates a list and no element is selected. If the user confirms the selections, lsel() sets the list to indicate the selected options. In radio mode, only the first list element is used, and any user selection truncates the list to a single element. If the user cancels the selections, lsel() restores the list to its contents as of the start of the function. The caller can use the list at discarded to see which options were selected when the user cancelled the selections.	—
listText	I	A string list of the text displayed as selectable options	Required
margin	I	The size (in pixels) of a margin (a zone near the edges of the window) not occupied by the option text.	0 (no margin)
margLoc	I	A string that may contain the following lowercase letters in any order: l to enable a left margin, r to enable a right margin, t to enable a top margin, b to enable a bottom margin. The margin is not visible unless margin is set nonzero.	lr
nrLines	I	The number of lines (options) to display in the window. A very low value results in large text that might not show much of the legend. A very high value results in small text that might make it hard to make selections.	15
outIsCancel	I	Set nonzero to indicate that any user tap outside the selection window is a command to cancel the selection. If x1, x2, y1, and y2 are omitted, there is no way to tap outside the window and this value is irrelevant.	0
pos	I/O	The window's vertical scroll index. It is the number of the first option shown in the window. (The first element of the list is number 1.) The caller can set this to control which options are shown initially. The function returns a value to reflect which options are shown (due to user scrolling) on return.	1
radio	I	Omitted or 0 means the window opens in multi-select mode; see the Introduction of this article. Nonzero means the window opens in radio button mode.	0
title	I	Omitted to indicate that the window has no title bar at the top. If present, it indicates a short legend displayed in the title bar (which may be the null string). If the caller sets either useCancelTitle or useOKTitle, a title bar is created, with no legend if title does not provide one.	No title bar
typeface	I	The font used for the text of selectable options and of the title bar, as you would pass to GR.TEXT.TYPEFACE.	1 (sans-serif)
typeStyle	I	The style used for the text of selectable options and of the title bar, as you would pass to GR.TEXT.TYPEFACE.	1 (no bold, no italic)
useCancelSlider	I	Set nonzero to produce a slider the user can slide to cancel the selections.	0 unless useCancelTitle is not used
useCancelTitle	I	Set nonzero to use the left half of the title bar as a zone the user can tap to cancel the selections.	0
useOKSlider	I	Set nonzero to produce a slider the user can slide to confirm the selections.	0 unless useOKTitle is not used
useOKTitle	I	Set nonzero to use the right half of the title bar as a zone the user can tap to confirm the selections.	0
x1	I	The x coordinate of the window's upper-left corner	0
x2	I	The x coordinate of the window's lower-right corner	Right edge of screen
y1	I	The y coordinate of the window's upper-left corner	0
y2	I	The y coordinate of the window's lower-right corner	Bottom of screen

Examples

1. The caller passes 2,5,10 in listSelected. The user deselects 2 and 10 and selects 7, then confirms the selection. listSelected returns the currently selected options: 5 and 7. canceled is 0.
2. The caller passes 2,5,10 in listSelected. The user deselects 2 and 10 and selects 7, then cancels the selection. listSelected is unchanged. The selected options at the time the selection was cancelled, 5 and 7, are in discarded. canceled is 1.

Selecting colors

The following bundle elements specify colors that the selection window uses. Each element is a string of exactly eight hexadecimal characters. The form is "oorrggbb" where oo specifies opacity, rr specifies red, gg specifies green, and bb specifies blue. These are all input parameters, as there is no way to change the selection window's colors from inside it.

Key	Meaning	Default
colBackground	The background color of the selection window. A typical selection is a dark color that makes entries easier to read, even the ones that are grayed out. The background color need not be totally opaque; transparency lets the previous display show through.	"80000080" (semi-opaque gray)
colBackTitle	The background color of the title bar, if there is one.	"80000000" (semi-opaque black)
colCancel	The color of the legends the user uses to cancel the selections (slider and/or half of the title bar). This color is fully opaque despite the opacity setting (first two characters).	"xxFF8000"(red)
colDarken	The color of a rectangle drawn over the entire screen before drawing the selection window. The default value specifies black at 50% opacity, which lets the previous display show through but darkens it to show that focus is on the selection window.	"80000000" (semi-opaque black)
colOK	The color of the legends the user uses to confirm the selections (slider and/or half of the title bar). This color is fully opaque despite the opacity setting (first two characters).	"xx80FF00"(green)
colScrollBar	The color of the scroll bar. The scroll bar is only visible if listText has more lines than will fit in the selection window at one time (nrLines).	"FF00FFFF" (turquoise)
colSelected	The text color of entries that are selected.	"FFFFFFFF" (white)
colText	The text color of entries that are not selected.	"FF808080" (gray)
colTitle	The text color of the title bar, if there is one. If the caller specifies useCancelTitle, then any colCancel is used instead for the left half of the title bar. If the caller specifies useOKTitle, then any colOK is used instead for the right half of the title bar.	"80FF00FF" (semi-opaque purple)

Where to get it

A ZIP file containing ScrollingSelectionWindow.bas, and testing code in ScrollingSelectionWindowTest.bas, is available on the RFO-BASIC! Forum. (See 7-Dec-20.zip in post #97.)