Lists Tutorial
Lists are table-like structures that allow the user to select a row, column, or cell. Grids are the same but also allow for input (and are described in section 1.5). They are made of rows and columns. Outputting to lists is done with Print Fields and inputting from them is done with Input Fields. Information in lists can be sorted alphabetically by clicking on a column heading, which affects the appearance on the screen but does not change the order of the original file with the information.
There are three steps for creating lists or grids: 1. Create a header 2. Populate the list or grid 3. Allow user activity
1. The header
When creating a list or grid, it's recommended that you create a header row with titles for each column, as seen in the example. Headers are created with the following syntax, using Print Fields:
00010 print fields "2,2,list 10/80,headers": (MAT HEADINGS$,MAT WIDTHS,MAT FORMS$)
The parameters are:
print or input fields “row,col, LIST rows/size,HEADERS”:(input or output list)
row and col specify where the list begins, LIST means we're creating a list. rows/size specify how many rows are included and how wide the whole list will be in columns. If your list has more rows than are described here, BR will automatically add a scroll bar to view them. HEADERS means that this is the headers row.
The HEADINGS$, WIDTHS, and FORMS$ arrays contain the information needed for the header row. HEADINGS$ might include things such as: “Name”, “Address”, and “Order #”; WIDTHS gives the number of columns of the screen that each column should take up: 10, 10, 6; and FORMS$ tells whether each is a string or numeric variable, its size, and may include attributes such as alignment: “cc 15”, “cc 15”, “n 6”.
Let's work through an example together:
First, set up the header:
00002 dim headings$(3),widths(3),forms$(3) 00003 data "Item","Color","ID number" 00004 read mat headings$ 00005 data 12,12,12 00006 read mat widths 00007 data "c 12","c 12","n 5" 00008 read mat forms$ 00009 print fields "2,2,list 10/36,headers": (Mat Headings$,Mat Widths,Mat Forms$)
and run this! You'll see the header printed at the top of your screen.
2. Populating the list
To populate the list, the syntax looks like this:
print fields "2,2,list 10/80,=r": (mat FirstName$, mat LastName$,mat Address$,mat City$,mat state$,mat zipcodes$,mat shipmethod$,mat item1,mat item2,mat item3)
Notice how the “2,2,list 10/80, part is the same as the headers line example. This tells BR that you are filling in the same list. The equal sign is a primary flag.
In order to fill a list there are three possible primary flags:
| = | Replace any previous data |
| + | Add to any previously populated data (this allows loading in chunks) |
| - | Insert data ahead of previously populated data (4.16+) |
And the R is a secondary flag, for which there are four options:
| R | Load one row at a time (the default) |
| C | Load one column at a time - This is for loading multiple columns of the same data type |
| L | Provide the FKEY (see INPUT below) or Enter interrupt if the user presses up arrow or page up in the first field, or down arrow or page down in the last field. Note that this is not specified in the individual field leading attributes. |
| S | Single click to activate an Enter or FKEY event (otherwise a double click is required) (4.17+) |
The arrays in parenthesis after the colon contain the information which will be displayed in your list.
In our working example, we'll use our list data and mat Item$, mat Color$, mat idnum to populate the list, as follows:
00011 ! .! provide sample info for list 00012 dim item$(5),color$(5),idnum(5) 00013 data "Door","Frame","Rim","Handle","Padding","Black","Grey","Red","Lime","Sky Blue",1234,5556,7889,5378,1596 00014 read mat item$: read mat color$: read mat idnum 00015 ! 00016 ! .! populate list 00017 print fields "2,2,list 10/36,+r": (Mat Item$, Mat Color$, Mat Idnum)
3. Allowing User Activity
With lists, the only possible activity is selection. But there are several ways to select things, including by row, column, or cells. This could be useful for your computer to record selections to a file or for the user to choose something from a large list. Input Fields is used for this task, as in the following example, which will record which row is selected:
00018 input fields "2,2,list 10/36,rowsub,selone": selection
Go ahead and add this line to your sample program.
The first part remains the same again, but here we have the parameters ROWSUB and SELONE. ROWSUB records the row subscript of the selected row, and the SELONE specifies that only one row can be selected. Other parameters for the first include: RowCnt, Row, Colcnt, and Sort_Order for the first parameter, and for the second: Sel, All, Cur, Range, and Cell_Range. Refer to the wiki for details on each.
There are two optional parameters not shown here: Fkey and Nowait. FKEY means that an FKEY event should be triggered when a selection is made by double clicking or pressing the Enter key in navigation mode. Nowait simply means that it does not wait for user input.
If you run your program now, it will let you select a row (press enter to exit for now).
But what should we do with that selection?
One option would be to display which row the user selected. Add the following line to your program:
00019 print selection
Now when you exit the list view, it will display the subscript of the row you selected. This information could be saved or used to reference a line for editing or printing in another program.
Exercise 1.4
Earlier in this chapter, we created a data file called ORDERS.int to record information about our customers and their orders. Run this program several times so that you have some records in your file to work with.
Now, write a new program that accesses that file and prints all the information to a list. Allow the user to select a row.
You will have to follow the steps above, and add lines for dealing with the data file:
- Print the headers.
- Open the file.
- Read the data file into arrays and use them to populate the list.
- Allow users to select a row and print the subscript of that row.
- Provide an exit button when complete.
Refer to Sample program: Samplist.br in the solutions if you get stuck.
Next: Grids
Back: Table of Contents