OnGraphClick

A feature proposed for Analytica 5.5

** This page is under construction **

OnGraphClick

The OnGraphClick attribute holds an expression that is evaluated when an end-user clicks the mouse on the variable's result graph. Information about where the click occurred is passed to your expressiono through several local variables that are set before the expression is evaluated. Before you can enter an OnGraphClick expression, you'll need to make the attribute visible in the Attributes dialog.

Return value: Your expression needs to return true if you want the normal processing of the mouse click to continue. It should return false if you want to suspend the normal processing. If you suspend processing of the click, then datum balloons won't show, key items won't toggle, and zooming by dragging a rubber band rectangle won't work (unless you hold the shift key while dragging).

One example usage for OnGraphClick is to set input variables in the model based on what the user clicks on. Another use case would be to add a data point where a user clicks.

You should keep in mind that User-defined functions can be used in the attribute. Hence, if you implement your logic in a UDF, you can very easily reuse it across multiple graphs. You can even put it in a library to share across different models.

Special local variables

Several local variables are set so that your expression can figure out what was clicked on. The set of locals that are meaningful depends on which part of the graph the user clicked.

• where: Indicates which part of the graph was clicked on. Possible values are: "plotArea", "datum" (on a single point or bar in the plot area), "segment" (on a line segment or filled area), "key", "axisTitle", "axisLabels" and "background".
• click_x and click_y: The pixel coordinates of the mouse click relative to the top-left corner.
• dim: An index used when specifying a data coordinate. The elements are handles of the indexes that are present in the graph (a subset of all the indexes, depending on what's clicked on).
• endPt: An index used when specifying the coordinates of both ends of a data segment. It has the index values [1,2].
• coord: The coordinate (by IndexValues) of the data point that was clicked on, or null in the click was not on a datum on segment. When a single data point is clicked on, this is a one-dimensional array indexed by dim. The cell corresponding to the index in dim contains the value of the index. When a line segment is clicked on, this is a 2-dimensional array, the .endPt dimension has values [1,2] give the coordinates of each end point. When dat is not clicked on, it is null.
• coordPos: Same as coord except that the array cells contain the 1-based index positions instead of index labels.
• balloonText: Contains the text that will be displayed in a datum balloon (when the click is on a data point). You can modify this to change the text that appears in the balloon.
• info: This is the same as for OnGraphDraw.
• roles: This is the same as for OnGraphDraw.

The information in coord and coordPos is redundant, but both are included since it is sometimes more convenient to use one or the other. If an index might have duplicates (which should be avoided in general), then only coordPos uniquely identifies the coordinate.

Clicking on a data point or bar

You can test for the case where the user clicks on a single datum (data point or bar) using If where="point" Then ….

The locals coord and coordPos are 1-D arrays, indexed by dim, and provide the index coordinates of the data point. The local coord has the IndexValues whereas the local coordPos has the positions along the indexes. The local balloonText contains the text that will be displayed in the data balloon and in this case will be scalar text, and you can change the text (but it must remain scalar text). If you set balloonText to Null or "", then the balloon won't appear.

Clicking on a segment or filled area

You can test for the case where the user clicks on a line segment (between points) or in a filled area in a filled area line chart, using

If where="segment" Then …

The locals coord and coordPos are 2-dimensional, indexed by endPt and dim, where index endPt := [1,2]. So coord[.endPt=1] contains the coordinates of the end point of the segment closest to the mouse click, and coord[.endPt=2] contains the coordinates of the segment end point furthest from the click. The two endpoint coordinates will differ only on the common index. The local balloonText is a 1-D array indexed by the same endPt index and contains two text values. You can modify either or both, or set one to null if you want only a single balloon to display. For example, this shows only one data point balloon (the closest one) when you click on a line segment instead of the dual balloons:

If where="segment" Then

balloonText := If endPt=1 Then balloonText Else Null

Clicking in the plot area

The plot area is the rectangle bounded by and contained within the horizontal and vertical axes.

You can test for this case using If where="plotArea" Then ….

When you click in the plot area, the click may fall either on a data point (which includes within the bar area in a bar chart), on a line segment between two data points (which includes in the fill area in a filled line chart), or on the background of the plot area.

When the click in the plot area doesn't land on any data, then coord and coordPos are Null. You should test for this using IsNull(coord) rather than coord=Null, since the later tests individual cells in an array for null which isn't what you want.

Clicking in a key

This case occurs if you click in the bounding rectangle of a key. A graph can have multiple keys at one time (e.g., a color key, symbol key and symbol size key). A single key may also combine multiple roles when the same dimension is mapped to multiple graphing roles.

You can test for this case using If where="key" Then ….

When an index is assigned to the key, dim will have a single item, a handle to that index. If in addition, the user clicks on a key item, the label for that item appears in coord and the position of that item in the index appears in coordPos. If the click was not on a key item, then the single item in <coord>coord is null and the single item in coordPos is 0.

When a value is assigned to the key, ** TBD ***

Clicking on an axis title

You can test for this case using If where="axisTitle" Then ….

Clicking in the axis label area

You can test for this case using If where="axisLabels" Then ….

Clicking on the background

The background is any area outside of the plot area rectangle, outside of any key, and outside of the axis title or label areas.

You can test for this case using If where="background" Then ….

The locals dim, coord and coordPos are null.

Side-effects

Your expression will generally be useful due to side-effects, such as:

• Setting a user input, thus allowing the user to select a value by clicking on the graph
• Writing something to a file (again, what is written can be selected by what is clicked)
• Providing additional information in a message box.

Some other possibilities that are not currently possible (or at least not easily), listed here as enhancement ideas:

• Changing the graph pivot, thus "zooming" into a particular dimension.
• Customizing the text that appears in a data point balloon.

See Also

• OnGraphDraw