CellSpan

CellSpan( I, fmt, pos..., header )

Used to identify a rectangular region in a cell format specification, and to specify whether the indicated «fmt» applies to totals rows or columns, header or cells.

When creating your own Computed cell formats in the Cell Format Expression attribute, you can use CellSpan to apply formats to row and column header cells, or to totals rows and columns.

Internally, it is used to represent the selected region when formats are changed from the Cell format dialog. In this context, it appears in the Att_CellFormat attribute, and is automatically spliced when the elements of a table index changes.

Parameters

«I»: A table index.
«fmt»: A cell format predicate, or an expression that computes a cell format.
«pos»; (optional) A list of position pairs along the index «I». A position of 0 identifies the Totals column (as does a position of IndexLength(I)+1), otherwise the positions should be integers between 1 and IndexLength(I). For each pair, the span applies from the first position through the last position inclusive. When the number of positions is odd, the last singleton identifies a single position.
«header»: Specifies whether «fmt» applies to the row/column header cells for «I», the body cells, or both. When omitted, it applies to both. When True it applies only to header cells. And when False it applies only to body cells.

Examples

The text in the first row along index J shall be in bold face.

CellSpan( J, CellFont(bold:true), 1)

Note that the bold here applies to both the header and the body cells (although headers are bold by default, so this wouldn't be noticeable). The effect is identical to

CellSpan( J, CellFont(bold:true), 1, 1)

Apply a fill to the cells along index J from its 3rd position to its 7th position, body cells only.

CellSpan( J, CellFill( 'Yellow' ), 3, 7, header:false )

Center-align the header elements of J.

CellSpan( J, CellAlignment('Center'), header:True )

Set the border that divides the totals row or column along index I from the rest of the body.

CellSpan( J, CellBorder('Double',,'Near',I), 0 )

Set the fill color for the 3rd, 5th and 7th columns along I, both body and header.

CellSpan( I, CellFill('LightGreen'), 3, 3, 5, 5, 7, 7 )

Nesting

CellSpans are nested to identify a 2-D rectangular region.

CellSpan(I,
    CellSpan(J,
        CellFormats(
              CellNumberFormat('Percent'),
              CellFill('yellow',0.2),
              CellBorder('solid',1,'both',I,J,'blue')
        )
     ,2,4)
,2,4)

:

When to use IF-THEN instead

You can use CellSpan in your own Computed cell formats to specify when your formats apply to header cells, totals, or just body cells, as well as to delineate ranges within the body of the table where your format applies. For the last case, you can accomplish the same using IF-THEN-ELSE on the index. For example,

If 3<=@I<=7 Then CellFill( 'Red', 0.2 )

is the same as

CellSpan( I, CellFill( 'Red', 0.2 ), 3, 7, header:false)

As a general rule, it is preferable to use If-Then-Else in your Computed cell formats when the only purpose of CellSpan would be to select a range of cells. The reason for the preference has to do with how your logic will adapt to changes that might occur to the index in the future. Since you If statement is likely to capture the logic behind why you are applying the formats you are, it is likely to remain valid, and hence more adaptable, to future changes. To this point, CellSpan calls in the Cell Format Expression attribute are not spliced when the index changes (they are spliced in the Att_CellFormat attribute). Hence, if elements are inserted or deleted from your index, the formats will stay in the same position, rather than following the element labels. In comparison, an If statement such as:

If CashFlowLineItem='Expenses' Then CellFill('LightBlue')

stays with the 'Expenses' row as other line items are inserted or deleted. These recommendations don't apply to uses of CellSpan to address header cells or totals columns. For example, to include the header cell in the previous fill example, you would need to use a CellSpan as follows.

If CashFlowLineItem='Expenses' Then CellSpan(CashFlowLineItem, CellFill('LightBlue'))

But the key here is that you aren't using the «pos» parameter.

Comparison variables

In result tables containing comparison variables, you cannot reach the comparison variable columns with CellSpan. A separate predicate function, CellComparisonFormat exists for that purpose.