Text List Programming
A Text List Object can include program code, just like any other object (see Form Object Code). This code is triggered when the Text List Object is clicked.

To try out the code, switch to Data Mode and click on the list.

Usually the code will need to know which item was selected. There’s no special function for that, the code can simply access the field or variable that was set up for the text list selection, in this case destinationChoice. If the Text List displays multiple columns, the selected value will have tabs in it – in this case, the code uses the tabarray( function to extract just the city name from the selected value, then displays that name in an alert using the alertsheet statement.

If the code needs to know the exact row and column that were clicked, use the info(“matrixrow”) and info(“matrixcolumn”) functions.

#### Click/Release Option

Normally the program doesn’t trigger when you click the mouse button on the list, but when you click and then release.

To make the program code trigger immediately when the list is clicked, uncheck the Click/Release option. There are two situations where you need to do this – when you want to make a pop-up button appear, and when you want to drag a column, row or cell from the list.

#### Pop-Up Menu

To display a pop-up menu when the list is clicked, use the popupclick statement.

Make sure the Click/Release option is turned off (see previous section). When the list is clicked, a pop-up menu of airlines will appear.

#### Checking for Modifiers

The code can use the info(“modifiers”) function to check to see if it should work differently due to modifier keys or double clicks. This example only pop-ups up the menu when the mouse is right-clicked (or a trackpad is two-finger clicked) – all other clicks are ignored.

#### Clicks in the List Header

So far we’ve only talked about clicking in the body of the list. If you enable the Allow Header Clicks option, the procedure code will also be triggered by clicking on the header.

If this option is enabled, the code will need to use the info(“matrixclickedframe”) function to check whether the click was in the header or the body of the list.

The code can also use the info(“matrixrow”) function, which will return 0 if the click is in the header. It can also use the info(“matrixcolumn”) function to see which column of the header was clicked in.

#### Dragging to Rearrange List Order

If the Text List formula is just a variable, with no other functions or operators, it is very easy to program the list so that the items can be rearranged by dragging and dropping. To illustrate this, we’ll assume that the database contains a procedure that initializes a variable named CurrentFares with the current airfares to be displayed in a list.

Our Text List Object will use this variable as the source of data for the list.

Since the Text List formula is just a variable, only one line of code is needed to enable rearranging the list by dragging on it – the dragarrayorder statement.

With everything set up (you must also make sure the Click/Release option is turned off), you can now switch to Data Mode and rearrange the airfares simply by clicking and dragging.

Note: This example actually contains a mistake – the example form contains a search widget associated with the list (see Text List Searching). Searching is incompatible with dragging to rearrange the list. If you try to drag items in a list that has only a subset of items visible, the results are not reliable.

If the Text List formula is more complicated than just a single variable, the dragarrayorder statement will not work. However, you can still set up drag rearranging with a slightly more complicated procedure, using the dragwithinmatrix and arrayrelocate statements. However, if the Text List is linked to a database (see Text List Database Integration), it cannot be rearranged by dragging items.

See Also

- Displaying Data in a Grid -- fundamentals of displaying data in a grid (Text List/Matrix).
- Matrix Clicking -- handling clicks in a Matrix Object.
- Matrix Constructor -- quickly creating a Matrix Object from a template.
- Matrix Database Integration -- synchronizing a Matrix Object with a database.
- Matrix Geometry -- customizing the size and geometry of Matrix Object elements.
- Matrix Header and Horizontal Scrolling -- setting up a custom header for a Matrix Object grid.
- Matrix Object -- displaying a grid of items with a custom arrangement.
- Matrix Object Frame -- setting up the arrangement of items within a Matrix Object.
- Text List Appearance -- customizing the appearance of a Text List Object.
- Text List Constructor -- quickly creating a Text List Object from a template.
- Text List Database Integration -- synchronizing a Text List Object with a database.
- Text List Multiple Columns -- displaying multiple columns in a Text List Object
- Text List Object -- displaying a grid of text.
- Text List Searching -- searching within a Text List Object.
- Text List Selection -- selecting items in a Text List Object.

History

Version | Status | Notes
10.0 | New | New in this version.