constructlineitems
constructlineitems
TEMPLATE

The constructlineitems statement creates a grid of line items.

Parameters

This statement has one parameter:

template – dictionary that contains options for constructing the line item grid (see discussion below).

Description

This statement creates a grid of line items in the current form. In its simplest form it will create a basic grid of Text Editor Objects.

    constructlineitems ""

The template parameter allows you to customize how form elements are generated. You can specify which line item fields are included and in what order, the size, alignment, etc. Each item can have tags that customize the generated grid, and there are tags for overall options as well. These tags are discussed below.

Keep in mind that this statement generates regular form objects, just as if you had created them manually. Once the objects are generated, you can manipulate these objects in Graphics Mode any way you like.

### Line Item Fields

To specify which line item fields should be included in the generated form, simply include a carriage return delimited list of the fields. Use the Ω suffix instead of specific field numbers. This example will generate 4 columns of text editor objects (the number of rows will depend on the number of line item fields in your database).

    constructlineitems
        "QuantityΩ"+cr()+
        "ItemΩ"+cr()+
        "PriceΩ"+cr()+
        "AmountΩ"

The width and alignment of each column in the grid will be determined automatically from the first corresponding line item field in the data sheet. In the example above, the width and alignment of the first column will match the Quantity1 field in the data sheet, the width and alignment of the second column will match the Item1 field, etc. You can customize the width and alignment of columns with special tags, described below.

### Tags

To customize the generated form objects you can include one or more tags. Like HTML tags, these tags start and end with `<` and `>` characters. Some tags need to be attached to a specific line item field, for example to specify the width and alignment of a column. Other tags should be placed at the top of the template and control overall specifications – for example the font and text size.

### Line Item Column Options

There are six properties that can be customized for each line item column: width, alignment, title, editability, color and background. The following sections describe each of these properties.

#### Width

To customize the width of a column, use the `<width:dimension>` tag on the same line as the line item field name. The width is 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`).

    constructlineitems
        "QuantityΩ<width:30>"+cr()+
        "ItemΩ<width:3.8 inch>"+cr()+
        "PriceΩ<width:4 cm>"+cr()+
        "AmountΩ<width:4 cm>"

The width can also be expressed in characters by using the `c` suffix. When this option is used the width will be calculated as 0.7 times the font height, multiplied by the number of characters (so the number of characters that can be displayed is approximate). The advantage of this option is that it will automatically scale depending on the height of the text.

    constructlineitems
        "QuantityΩ<width:5c>"+cr()+
        "ItemΩ<width:40c>"+cr()+
        "PriceΩ<width:10c>"+cr()+
        "AmountΩ<width:12c>"

If the width tag is left off for any field, it will default to the width of the first corresponding line item field in the data sheet.

#### Alignment

The alignment is normally set automatically from the data sheet, but the `<alignment>` tag can be used to specify a different alignment. The available options are left, right and center.

    constructlineitems
        "QuantityΩ<align:center><width:5c>"+cr()+
        "ItemΩ<width:40c>"+cr()+
        "PriceΩ<width:10c>"+cr()+
        "AmountΩ<width:12c>"

#### Column Title

Usually the line item field name is used as the title of each column (without the Ω suffix), or the field title if it has one. If you want to specify a different title, use the `<title>` tag, like this:

    constructlineitems
        "QuantityΩ<align:center><width:5c><title:Qty>"+cr()+
        "ItemΩ<width:40c>"+cr()+
        "PriceΩ<width:10c>"+cr()+
        "AmountΩ<width:12c>"

#### Non-Editable Columns

By default, all of the columns in the line item grid can be edited. However, you can use the `<editable:no>` tag to specify that one or more (or even all) columns will be display only, no data entry allowed. These columns will be created as Text Display Objects instead of Text Editor Objects.

For example, if the Price and Amount fields are automatically generated with a relational join and formula, you probably don’t want these fields to be edited manually. This can be achieved with this template:

    constructlineitems
        "QuantityΩ<align:center><width:5c>"+cr()+
        "ItemΩ<width:40c>"+cr()+
        "PriceΩ<width:10c><editable:no>"+cr()+
        "AmountΩ<width:12c><editable:no>"

#### Column Text Color

Normally all text in the line item grid is displayed in black. However, you can use the `<color>` tag to specify a different color on a column-by-column basis. The color can be specified as hexadecimal red-green-blue values (for example `0000FF` for blue), or as a color name (use info(“colornames”) for a list of available colors). This template will cause both the Price and Amount columns to be displayed with green text.

    constructlineitems
        "QuantityΩ<align:center><width:5c><title:Qty>"+cr()+
        "ItemΩ<width:40c>"+cr()+
        "PriceΩ<width:10c><color:green>"+cr()+
        "AmountΩ<width:12c><color:00FF00>"

#### Column Background

Normally the line item grid has no background (which usually means the grid appears on a white background, unless there is some sort of color object below the grid). To specify a different background for a column, use the `<background:>` tag. The color can be specified as hexadecimal red-green-blue values (for example `F0F0FF` for light blue), or as a color name (use info(“colornames”) for a list of available colors). This template will cause both the Price and Amount columns to be displayed with a light green background.

    constructlineitems
        "QuantityΩ<align:center><width:5c><title:Qty>"+cr()+
        "ItemΩ<width:40c>"+cr()+
        "PriceΩ<width:10c><background:F4FFF4>"+cr()+
        "AmountΩ<width:12c><background:F4FFF4>"

The background can also be a gradient, see Text Object Background Color/Gradient to learn more.

### Text Appearance (Font and Size)

By default, all text in the line item grid appears using the standard system font, in standard size (13 points).

To customize the font, use the `<font:>` tag. Use the `<size:>` tag to customize the size. The size can be expressed as regular, small or mini (13pt, 11pt or 10pt), or you can specify any numeric value (in points). This example creates the grid in 15 point Gill Sans.

    constructlineitems
        "<font:Gill Sans><size:15>"+cr()+
        "QuantityΩ<width:5c>"+cr()+
        "ItemΩ<width:40c>"+cr()+
        "PriceΩ<width:10c>"+cr()+
        "AmountΩ<width:12c>"

### Cell Borders, Spacing & Padding

The line item grid normally has each element tightly packed, with a border around each element, but both of these attributes can be customized, as well as the padding between the border and the text.

The `<border:>` option specifies what type of border appears around each element: bezel, line or none (the default is bezel if there is no `<border:>` tag). If the bezel option is chosen, the bezel is always dark gray, no matter what the text color and background are set to. If the line option is chosen, the line color matches the text color, and the stroke width can be modified in the inspector panel (you can even make a dashed border).

The `<spacing:>` option adds padding between the cells. This option is normally specified in points, but can also be specified in inches or centimeters.

This example creates a line item grid with no borders, with an extra 4 points between each cell both vertically and horizontally. (You can also use the `<verticalspacing:>` and `<horizontalspacing:>` tags to specify different spacing in each direction.)

    constructlineitems
        "<border:none><spacing:4>"+cr()+
        "QuantityΩ<width:5c>"+cr()+
        "ItemΩ<width:40c>"+cr()+
        "PriceΩ<width:10c>"+cr()+
        "AmountΩ<width:12c>"

To increase the padding between the text and the border there are 4 padding tags: `<toppadding:>`, `<bottompadding:>`, `<leftpadding:>` and `<rightpadding:>`. All padding values are normally set to zero (minimum). If you increase the top or bottom padding, the height of the rows will increase. This example slightly increases the top and bottom padding, creating a more “airy” grid.

    constructlineitems
        "<toppadding:2><bottompadding:1>"+cr()+
        "QuantityΩ<width:5c>"+cr()+
        "ItemΩ<width:40c>"+cr()+
        "PriceΩ<width:10c>"+cr()+
        "AmountΩ<width:12c>"

### Header Appearance

The constructor generates a header of Text Display Objects at the top of the grid which displays the column titles. (If you don’t want this header, simply remove it afterwards in Graphics Mode.) By default the titles are displayed centered above each column in black text.

To customize the alignment of the titles, use the `<titlealign:>` tag. The available options are left, right, center and field. The field option aligns each title the same as the data in the corresponding field. In this example the Qty title will be centered, the Item title will be aligned to the left, and the Price and Amount titles will be aligned to the right (assuming these fields are right aligned in the data sheet).

    constructlineitems
        "<titlealign:field>"+cr()
        "QuantityΩ<align:center><width:5c><title:Qty>"+cr()+
        "ItemΩ<width:40c>"+cr()+
        "PriceΩ<width:10c><color:green>"+cr()+
        "AmountΩ<width:12c><color:00FF00>"

If the alignment is set to center, however, all four titles will be centered, no matter how the data is aligned in each column (this is the default).

    constructlineitems
        "<titlealign:center>"+cr()
        "QuantityΩ<align:center><width:5c><title:Qty>"+cr()+
        "ItemΩ<width:40c>"+cr()+
        "PriceΩ<width:10c><color:green>"+cr()+
        "AmountΩ<width:12c><color:00FF00>"

To display the titles in a color other than black, use the `<titlecolor:>` tag. The color can be specified as hexadecimal red-green-blue values (for example `0000FF` for blue), or as a color name (use info(colornames") for a list of available colors).

    constructlineitems
        "<titlecolor:royalblue>"+cr()
        "QuantityΩ<align:center><width:5c><title:Qty>"+cr()+
        "ItemΩ<width:40c"+cr()+
        "PriceΩ<width:10c><color:green>"+cr()+
        "AmountΩ<width:12c><color:00FF00>"

To change the background for the titles, use the `<titlebackground:>` tag. The color can be specified as hexadecimal red-green-blue values (for example `F0F0FF` for light blue), or as a color name (use info(“colornames”) for a list of available colors). This example will display the titles as white text on a black background, i.e. inverted.

    constructlineitems
        "<titlebackground:black><titlecolor:white>"+cr()+
        "QuantityΩ<align:center><width:5c><title:Qty>"+cr()+
        "ItemΩ<width:40c>"+cr()+
        "PriceΩ<width:10c><color:green>"+cr()+
        "AmountΩ<width:12c><color:00FF00>"

The background can also be a gradient, see Text Object Background Color/Gradient to learn more.

### Line Numbers

If you add the tag `<linenumbers:yes>` to the template, Panorama will add a column displaying line numbers to the left of the other columns. By default this column will be 3 characters wide (`3c`), but you can also explicitly specify the width, for example `<linenumbers:4c>` or `<linenumbers:0.5">`.

The line number color and background can be customized with the `<linenumbercolor:>` and `<linenumberbackground:>` tags. The color can be specified as hexadecimal red-green-blue values (for example `F0F0FF` for light blue), or as a color name (use info(“colornames”) for a list of available colors). This example displays a 4 character wide line number column on a powder blue background.

    constructlineitems
        "<titlebackground:bluebezel>"+cr()+
        "<linenumbers:4c><linenumberbackground:powder blue>"+cr()+
        "QuantityΩ<align:center><width:5c><title:Qty>"+cr()+
        "ItemΩ<width:40c>"+cr()+
        "PriceΩ<width:10c><color:green>"+cr()+
        "AmountΩ<width:12c><color:00FF00>"

The background can also be a gradient, see Text Object Background Color/Gradient to learn more.

### Partial Line Item Grid

Normally all line items in the database are constructed. Use the `<firstitem:number>` and/or `<lastitem:number>` lastitem tags if you want to only generate a subset of line items. For example, suppose the database has 40 line items. If you want to generate only the first ten, add this tag:

    <lastitem:10>

If you want to generate only lines 15 thru 25, add both tags:

    <firstiem:15><lastitem:25>

Note: If you specify line items that don’t exist, Panorama will generate only the specified items that do exist. For example, if the database only had 20 line items, then the tags abovve would only generate items 15 thru 20.

### Text Editing Options

These options allow you to customize how text editing works for the line item fields.

#### Initial Insertion Point

When you tab into a line item field, Panorama normally selects all the text in the field automatically (so that typing clears out whatever was already in the field). The `<insertionpoint:>` tag overrides this behavior.

    <insertionpoint:start>
    <insertionpoint:end>
    <insertionpoint:all>

#### Focus Ring

Panorama normally displays a blue “focus ring” around the field currently being edited. If you don’t want this ring, use the `<focusring:no>` tag.

#### Terminate Editing When Return Is Pressed

Line Item fields are normally set up so that pressing the Return key completes editing. If you don’t want this, use the `<terminatereturn:no>` tag. This allows carriage returns to be inserted into a line item field.

#### Pop Up Editing

If the `<popupediting:yes>` tag is included, the generated Text Editor objects will have the Popup Editing option enabled. This makes data editing work as it does in the Data Sheet, with a pop-up window for editing instead of editing text directly in the form window.

See Also

- constructformdataeditors -- creates a column of form elements for editing data fields (or variables).
- constructlistmatrix -- creates a text list or matrix in the current form.
- constructmailinglabel -- creates the form elements for printing mailing labels.
- constructreport -- creates a report in the current form.
- constructtabpanel -- creates a tab panel in the current form.
- formconstructordialog -- opens a generic form constructor dialog.
- newsearchgadget -- creates a search gadget in the current form.

History

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