The constructlistmatrix statement creates a text list or matrix in the current form.
Parameters
This statement has one parameter:template – template that contains options for constructing a text list or matrix (see discussion below).
Description
This statement creates a Text List object in the current form. It can also create a skeletal Matrix object. The Text List can have single or multiple columns. The list can display information from a database or from an independent data source.
This example creates a three column searchable list.
constructlistmatrix |||<rows:20>
Quantity<width:7c><align:center>
Item<width:25c><search>
Price<width:10c><align:right>
|||
There are about a dozen options you can specify in the template, each of which is described below.
To specify a list with multiple columns, list each column name on a separate line. Here is an example for a list with 3 columns.
Quantity
Item
Price
If the column name is the same as a field in the database, the column will have the same width an alignment as that field. If the column name is not a field name, a default width will be used. You can override the width and alignment with the <width:dimension> and <align:option> tags.
Quantity<width:75><align:center>
Item<width:250>
Price<width:100><align:right>
Normally the width is expressed in points (one point is 1/72nd of an inch). By adding a c prefix to the dimension, you can specify the width in characters. Since different characters have different widths (a W is wider than an I, for example), this is an approximate measurement. Depending on what characters are being displayed, you might be able to display more or less than the exact number of characters specified. In this example the three columns have widths of 7 characters, 25 characters, and 10 characters.
Quantity<width:7c><align:center>
Item<width:25c>
Price<width:10c><align:right>
The nice thing about specifying widths in “characters” is that the widths will automatically adjust if you change the size of the text. You may have to fiddle a bit to get something that works well at all the text sizes you want to use, but it is usually possible.
If you add the tag <resizablecolumns:yes> anywhere in the template, the user will be able to resize the columns by dragging on the column header (on the line in between the columns). This tag will make all the columns resizable, you cannot do this on a column by column basis.
You can also specify a formula for the column. If you do that, you will usually want to specify a column title with the <title:name> tag, as shown in this example. (If you don’t specify a title, the formula will be used as the title.)
Quantity
upper(Item)<title:Item>
Price
pattern(ListPrice-Price,"$#.,##")<title:Discount>
Note: You can only use column formulas when displaying data directly from a database, not from an independent data source.
If you want a column to be searchable, include the <search> tag on the line that specifies the column. In this example, the Item column is searchable.
Quantity
Item<search>
Price
If you put the <search> tag on a line that doesn’t specify a column, then all columns will be searchable, as shown in this example.
<search>
Quantity
Item
Price
Note: If the data source isn’t a database (see below), only the general search option can be used, not the column specific search.
So far we’ve talked about columns and column related options. These are specified one per line, starting with the name or formula, then with one or more options, like this.
column<column option>
column<column option><column option>
column<column option>
column<column option>
In addition to column options, you can also specify a number of general options. These should be specified on separate lines from the column specifications (however, you can have multiple general options on a single line).
<generaloption>
<generaloption><generaloption>
<generaloption>
<generaloption>
column<column option>
column<column option><column option>
column<column option>
column<column option>
The rest of this page describes the various general options that are available.
This statement normally creates Text List objects. However, if the template includes a <matrix:frame> tag, it will create a Matrix object instead. The tag parameter, frame, is the name that will be used for the frame object. If this is omitted, the frame object won’t have a name (which is fine as long as there is only one matrix on the form).
The default height for rows in the matrix is 24 points. This can be customized with the <rowheight:distance> tag. The height defaults to points, but can also be expressed in inches or centimeters.
Here is an example of a template that generates a Matrix object:
constructlistmatrix |||
<matrix><rows:6><rowheight:48>
Quantity<width:7c><align:center>
Item<width:25c><search>
Price<width:10c><align:right>
|||
You don’t have to specify columns, but if you do, Panorama will automatically create Text Display objects inside the frame to display these columns. Of course you can rearrange these after the matrix is created, and/or add additional objects or remove these objects.
There are two possible sources for the data that is displayed in the list or matrix: a database, and a fixed data source (either a formula or fixed values). If you don’t specify a data source, the current database will be used.
Use the <database:name> tag if you want to use a different database as the data source. The specified database must be open (Panorama will warn you if it isn’t).
<database:Price List>
The <values:datum> tag specifies a fixed list of data values as the data source. The default data separator is a comma, so this will cause the list to display a fixed list of six items.
<values:Apple,Orange,Pear,Grapes,Strawberry,Lemon>
Use the ¬ symbol (Option-L) to separate each item into multiple columns. This will create a two column list with fruit and prices.
<values:Apple¬0.25,Orange¬0.50,Pear¬0.75,Grapes¬0.20,Strawberry¬0.65,Lemon¬0.50>
Fruit<width:20c>
Price<align:right><width:7c>
What if your data contains , or ¬ symbols? You can change the separators with the <colsep:char> and <rowsep:char> tags.
<values:Los Angeles, CA-California|Denver, CO-Colorado|Chicago, IL-Illinois>
<colsep:-><rowsep:|>
City<width:20c>
State<width:20c>
You can also separate the data into separate <value> tags instead of one combined <values> tag.
<value:Los Angeles, CA|California>
<value:Denver, Co|Colorado>
<value:Chicago:IL|Illinois>
<colsep:|>
City<width:20c>
State<width:20c>
If the data values aren’t fixed, but need to be calculated with a formula, use the <formula> tag. In this example a list of fruit and prices is contained in a variable named fruitList (in comma separated format).
<formula:csvtotsv(fruitList)>
Fruit<width:20c>
Price<align:right><width:7c>
When an item is clicked it is selected. If the data source is a database, by default Panorama will jump to the record that corresponds to the item.
Another option is to use the <selection:variable> tag to create a variable to hold the selected choice. This will work with any data source.
<selection:fruitChoice>
Using the <code:program> tag you can set up a program that will run when an item is clicked.
<code:message "You picked "+fruitChoice>
The code can be self contained or it can call a separate procedure with the call statement.
If a matrix object is being generated, the code will default to matrixclick if no code is supplied. This allows any code associated with objects in the matrix frame to run when you click on them.
The options in this section allow you to change how generated objects are laid out. A number of the options below allow you to specify measurements values – height, width, etc. These values are normally expressed in points (1 point = 1/72 inch) but you can also specify values in inches (1 in or 2.5 inch or 0.75") or centimeters (20 cm).
The default size for the generated list of matrix is 500 points wide by 334 points high. Use the <width:measurement> tag to specify a different width. This example creates an object that is 6 inches wide.
<width:6">
Keep in mind that to set the overall object width, the <width> tag must not be on the same line as a column specification. A <width> tag that is part of a column specification sets the width for that column, not the entire object. This example shows the <width> tag being used both ways:
<width:6">
Quantity<width:75><align:center>
Item<width:250>
Price<width:100><align:right>
There are two ways to set the object height. First, you can use the <height:dimension> tag to directly set a specific height, like this:
<width:6"><height:4">
Quantity<width:75><align:center>
Item<width:250>
Price<width:100><align:right>
Alternatively, you can use the <rows:count> tag to set the height indirectly. Use this tag to specify the number of rows to display, and Panorama will automatically calculate the correct absolute height based on the font size being used.
<width:6"><rows:15>
Quantity<width:75><align:center>
Item<width:250>
Price<width:100><align:right>
You can change both the font and size of the generated list object. Changing the size is more common, to do that use the <size:points> tag. Normally you would do this just once at the top. You can specify the size as regular (13 points), small (11 points) or mini (10 points).
<size:small>
Or, you can also specify the exact size numerically.
<size:18>
Use the <font:name> tag to change the font. If this tag is omitted, the system font will be used.
<width:6"><rows:15><font:Tekton><size:regular>
Quantity<width:75><align:center>
Item<width:250>
Price<width:100><align:right>
The generated list or matrix object always has a vertical scroll bar. Use the <horizontalscroll:yesno> tag if you also want a horizontal scroll bars. Use the <thinscroll:yesno> option to make the scroll bars narrower (both vertical and horizontal).
Text lists and matrixes generated by this statement normally default to an alternating row background color pattern. You can use the <grid:horizontal,dashed,vertical,alternating> tag to customize how rows are differentiated. You can one or more of these keywords to customize (Note: these keywords can be abbreviated as horz, dash, vert, and alt).
<grid:alternating> ☞ rows have alternating background colors
<grid:horizontal> ☞ rows are separated by a solid line
<grid:dashed> ☞ rows are separated by a dashed line
<grid:vertical> ☞ columns are separated by a solid line
You can also combine two or more of these options, like this (the separator can be commas and/or spaces):
<grid:horizontal,vertical>
If the template contains the tag <richtext:yes>, the Text List can contain styled rich text (bold, italic, color, etc.). This option does not affect Matrix objects.
If you’ve defined one or more columns, the Text List object will automatically display column headers, otherwise it won’t. You can override this with the <header:yes/no> tag.
The <tooltip:text> tag specifies any text that appears when the mouse hovers over the list or matrix object.
If the template contains any <search> tags, Panorama will automatically create a “search widget” above the list or matrix object. This object normally uses the same text size as the main object, but you can customize this with the <searchsize:height> tag, where the height can be regular (13 points), small (11 points), mini (10 points) or a custom numerical size.
<searchsize:small>
The search widget is normally 200 points wide, but you can customize the width with the <searchwidth:distance> tag.
<searchwidth:4">
If the distance is full, the search widget will be the same width as the Text List or Matrix object.
<width:5"><rows:24>
<searchwidth:full>
The search widget normally displays a generic prompt of Search when empty, but you can use the <searchprompt:text> tag to specify a more specific prompt (or no prompt at all).
<searchprompt:Search Books>
The default margin between the bottom of the search widget and the top of the list or matrix object is 6 points. You can customize this distance with the <searchmargin:distance> tag.
If the template contains one or more <search> tags, Panorama will automatically add a progress display below the list or matrix object. This displays the number of items that match the search, for example 42 of 786. You can use the <progress:option> tag to customize this display, or eliminate it entirely. To eliminate it entirely, use the tag <progress:no>.
To customize the progress display, you must supply a template. This template must include the keywords $FOUND and $ALL (case sensitive) where you want the # of matching items and the total number of items to appear. Here is an example:
<progress:Search result: $FOUND books (out of $ALL)>
The text displaying the progress is displayed over a white to gray gradient. You can customize this gradient with the <progressgradient:color,color> tag. This example displays a white to light blue gradient:
<progressgradient:FFFFFF,CCCCFF>
If you want a solid background, specify just one color, like this light green background:
<progressgradient:CCFFCC>
See Also
History
| Version | Status | Notes |
| 10.0 | New | New in this version. |