View source for CellSpan

[[category:Cell format functions]]
[[category:Analytica 5.0]]

== 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 [[Table Splicing|spliced]] when the elements of a table index changes.

=== Parameters ===
* «<code>I</code>»: A table index.
* «fmt»: A [[:category:Cell format functions|cell format predicate]], or an expression that computes a cell format.
* «pos»; (optional) A list of position pairs along the index «<code>I</code>». A position of 0 identifies the Totals column (as does a position of <code>[[IndexLength]](I)+1</code>), otherwise the positions should be integers between 1 and <code>[[IndexLength]](I)</code>. 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 <code>J</code> shall be in bold face.
:<code>[[CellSpan]]( J, [[CellFont]](bold:true), 1)</code>
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 
:<code>[[CellSpan]]( J, [[CellFont]](bold:true), 1, 1)</code>

Apply a fill to the cells along index <code>J</code> from its 3rd position to its 7th position, body cells only.
:<code>[[CellSpan]]( J, [[CellFill]]( 'Yellow' ), 3, 7, header:false )</code>

Center-align the header elements of <code>J</code>.
:<code>[[CellSpan]]( J, [[CellAlignment]]('Center'), header:True )</code>

Set the border that divides the totals row or column along index <code>I</code> from the rest of the body.
:<code>[[CellSpan]]( J, [[CellBorder]]('Double',,'Near',I), 0 )</code>

Set the fill color for the 3rd, 5th and 7th columns along <code>I</code>, both body and header.
:<code>[[CellSpan]]( I, [[CellFill]]('LightGreen'), 3, 3, 5, 5, 7, 7 )</code>

== Nesting ==

[[CellSpan]]s 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)
 
 :[[image:CellSpan_Nesting.png]]

== 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|IF-THEN-ELSE]] on the index. For example,

:<code>[[If]] 3<=@I<=7 [[Then]] [[CellFill]]( 'Red', 0.2 )</code>
is the same as 
:<code>[[CellSpan]]( I, [[CellFill]]( 'Red', 0.2 ), 3, 7, header:false)</code>

As a general rule, it is preferable to use [[If|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:

:<code>[[If]] CashFlowLineItem='Expenses' [[Then]] [[CellFill]]('LightBlue')</code>

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.

:<code>[[If]] CashFlowLineItem='Expenses' [[Then]] [[CellSpan]](CashFlowLineItem, [[CellFill]]('LightBlue'))</code>

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. 

== See Also ==
* [[Computed cell formats]]
* [[Cell format functions]]: [[CellFill]], [[CellFont]], [[CellAlignment]], [[CellNumberFormat]], [[CellBar]], [[CellOnClick]]
* [[CellComparisonFormat]]
* [[If|If-Then-Else]]
* [[Cell format dialog]]
* [[Att_CellFormat]], [[Cell Format Expression]]