CellOnClick
Release: |
4.6 • 5.0 • 5.1 • 5.2 • 5.3 • 5.4 • 6.0 • 6.1 • 6.2 • 6.3 • 6.4 • 6.5 |
---|
CellOnClick( expr )
A cell format predicate that specifies an expression to be evaluated when a user double-clicks on a table cell (for example in a result table). This can be configured from within a computed cell format in the Cell Format Expression attribute. The expression «expr» is allowed to have side-effects, such as assignments to global variables, in the same way an OnClick or OnChange expression can.
Use this function when you want to enable do some custom action when a user double-clicks on a particular cell in a result table. This behaves similarly to having a Button inside a table.
CellOnClick in row or column header cells
If you want to respond to clicks in a row header cell or column header cell, as with any other cell format predicate, you'll need to use CellSpan and specify the index and «header». For example
CellSpan( PlantType, CellOnClick( DoClickOnPlant(Self), header:true ) )
where PlantType
is an index, and DoClickOnPlant
is a UDF with one parameter.
Coordinates of the cell
New to Analytica 5.2
In some cases, you may want to know the coordinates of the cell that was clicked from within «expr». In most cases, the coordinate of the cell is the value of each index of the table at that cell. This is available within «expr» by simply referring to the index by name in a value context. For example, when In1
is an index, the expression
MsgBox(In1)
would normally show an array of values. But from within «expr», CellOnClick(MsgBox(In1))
would show the single index element from In1
corresponding to the cell that was clicked. All indexes appearing in the table, whether horizontal or vertical indexes, or a slicer index with a single value selected, behaves in this fashion.
To keep your Cell Format Expression manageable, you'll probably want to put your logic inside a UDF, and have «expr» call your UDF. Your UDF might accept two parameters such as DoClick( I : Index ; vi )
. Notice the first parameter in a call is in index context, the second parameter is in a value context, so only the second parameter passed is subject to the automatically slicing to the coordinates of the clicked cell. Hence, your Cell Format Expression might contain
CellOnClick( DoClick( In1, In1 ) )
When your UDF refers to «I
», it gets the full index value, which is no longer restricted to the coordinates of the clicked cell. This is why you need to pass it in with the second non-index parameter, so that «vi» provides the value.
If the user clicks in a totals cell, say totaled across index In1
, then In1
is not restricted to a single value, and the local variable totalIndexes
contains the index handle. You can test whether you are in In1
's total using
SetContains(\totalIndexes,Handle(In1))
Finally, when the result table includes one or more comparison variables, the user might click in a comparison variable column. The identify of this column is in a local variable named comparisonColumn
. If the click was not in a comparison column (i.e., it is in the main value's column(s)), then comparisonColumn
is Null. Note that comparisonColumn
for comparison variable will be a handle, but it can also be a parsed expression term.
Local Variables
(New to Analytica 5.2)
From within «expr», you can make use of the pre-defined locals (VertIndex
, HorizIndex
, ViewMode
, ComparisonIndex
, VertIndexes
, HorizIndexes
, andSlicersSetToTotal
) that are also available from within the Cell Format Expression attribute. In addition, there are two more provided, totalIndexes
and comparisonColumn
. You can also use the value of any local you declared in your Cell Format Expression that was in lexical scope at the point were the CellOnClick predicate appears. And you can declare additional locals inside «expr».
The index-valued locals such as HorizIndex
, VertIndex
and ComparisonIndex
contain either Null or a handle to the index. These are not aliases of the index, so you can use them as if they were the index identifier itself (they can't be aliases since there might not be a horizontal or vertical index, so they might be null). So if you refer to their value, it'll be of type handle. If you want the coordinate at the horizontal index in any pivot, use e.g.,
LocalAlias hVal := HorizIndex Do hVal;
But, you need to be careful about the case where the table has no horizontal index, in which case HorizIndex
will be Null. You could protect yourself from this case using and If in «expr» such as
However, this causes «expr» to get kind of long. A better way is to put the if outside of your CellOnClick predicate, such as
If HorizIndex<>Null Then CellOnClick( LocalAlias hVal := HorizIndex Do DoColClick(HorizIndex, hVal) )
where DoColClick
is a UDF with Parameters ( h : Handle ; v )
or ( I : Index ; v )
.
The local totalIndexes
is always a list of handles to indexes, which are the indexes that are summed over in the cell that was clicked on. Is may be a zero-length index.
The local comparisonColumn
contains the handle or parsed expression term that appears in the column header above the cell that was clicked on when the user clicks in a cell depicting a comparison variable. When the user clicks in a cell depicting the main value, this is Null.
Continuing with default response
The return value of «expr» communicates whether the click was handled. Any value other than False (0), including Null, means that the processing of the click is complete, and any other handling of the click should not occur. False means that handling is not complete and the default processing of the click should continue.
When a cell in a result table contains a handle, the default behavior in the absence of a CellOnClick handler is to jump to the variable pointed to by the handle. Normally, by handling the CellOnClick, you override this with your own «expr», so that the hyperlink is not followed (unless your code follows it by calling e.g., ShowWindow). Similarly, when the cell contains a reference, double clicking will open a result window to the value pointed to by the reference. In some cases, you may want to have the default still run after your handler finishes. This will occur when your «expr» returns False. If it returns any other value (including Null), the default behavior is not executed.
Examples
With the following Cell Format Expression, when the user double-clicks on any cell in the I='b'
row of the result table, the user interface will open the influence diagram for the module Mo1
.
If I='b' Then CellOnClick( ShowWindow( Handle(Mo1), 'Diagram' ) )
When the user clicks on any cell in the table, a message box shows the value at full precision.
CellOnClick( MsgBox( NumberToText(Self,fullPrecision:true) ) )
History
CellOnClick was introduced in Analytica 5.0.
Access to local variables and the coordinate of the cell clicked from within the «expr» expression were added in Analytica 5.2.
Enable comment auto-refresher