Difference between revisions of "OnGraphClick"

Revision as of 01:00, 23 September 2020

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 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.

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", "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).
coord: The coordinate (by IndexValues) of the data point that was clicked on, or null in the click was not on a datum. 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 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 falls on a data point, the locals coord and coordPos provide the index coordinates of the data point. coord has the IndexValues whereas 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).

When the click is on a line segment between two data points, or in a filled area between two data points, coord and coordPos also have a second index named endPt with index values [1,2]. So coord[.endPt=1] contains the coordinates of the first (usually leftmost) end point of the segment and coord[.endPt=2] contains the coordinates of the second (usually rightmost) end point of the segment. The two endpoint coordinates will differ only on the common index. The local balloonText will be a 1-D array indexed by the same endPt index with two text values. You can modify either or both, or set one to null if you want only a single balloon to display.

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.

@@ Line 19: / Line 19: @@
 * <code>'''click_x'''</code> and <code>'''click_y'''</code>: The pixel coordinates of the mouse click relative to the top-left corner.
 * <code>'''dim'''</code>: 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).
-* <code>'''coord'''</code>: The coordinate (by [[IndexValue]]s) of the data point that was clicked on, or <code>null</code> in the click was not on a datum. This is a one-dimensional array indexed by <code>dim</code>. The cell corresponding to the index in <code>dim</code> contains the value of the index.
+* <code>'''coord'''</code>: The coordinate (by [[IndexValue]]s) of the data point that was clicked on, or <code>null</code> in the click was not on a datum. When a single data point is clicked on, this is a one-dimensional array indexed by <code>dim</code>. The cell corresponding to the index in <code>dim</code> contains the value of the index. When a line segment is clicked on, this is a 2-dimensional array, the <code>.endPt</code> dimension has values <code>[1,2]</code> give the coordinates of each end point. When dat is not clicked on, it is null.
-* <code>'''coordPos'''</code>: The coordinate (by positions) of the data point that was clicked on, or <code>null</code> in the click was not on a datum. This is a one-dimensional array indexed by <code>dim</code>. The cell corresponding to the index in <code>dim</code> contains the position within the given index.
+* <code>'''coordPos'''</code>: Same as <code>coord</code> except that the array cells contain the 1-based index positions instead of index labels.
-* <code>'''coord2'''</code> and <code>'''coordPos2'''</code>: Used only when a user clicks on a line segment, and not directly on a data point. In that case, these hold the coordinate of the second point of the segment.
 * <code>'''balloonText'''</code>: 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.
 * <code>'''info'''</code>: This is the same as for [[OnGraphDraw]].
@@ Line 35: / Line 34: @@
 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 falls on a data point, the locals <code>coord</code> and <code>coordPos</code> provide the index coordinates of the data point. <code>coord</code> has the [[IndexValue]]s whereas <code>coordPos</code> has the positions along the indexes.
+When the click falls on a data point, the locals <code>coord</code> and <code>coordPos</code> provide the index coordinates of the data point. <code>coord</code> has the [[IndexValue]]s whereas <code>coordPos</code> has the positions along the indexes.  The local <code>balloonText</code> 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).
-When the click is on a line segment between two data points, or in a filled area between two data points, <code>coord</code> and <code>coordPos</code> contain one end of the segment and <code>coord2</code> and <code>coordPos2</code> contain the coordinates of the other point.  The two coordinates will differ only by the common index.
+When the click is on a line segment between two data points, or in a filled area between two data points, <code>coord</code> and <code>coordPos</code> also have a second index named <code>endPt</code> with index values <code>[1,2]</code>.  So <code>coord[.endPt=1]</code> contains the coordinates of the first (usually leftmost) end point of the segment and <code>coord[.endPt=2]</code> contains the coordinates of the second (usually rightmost) end point of the segment.  The two endpoint coordinates will differ only on the common index.  The local <code>balloonText</code> will be a 1-D array indexed by the same <code>endPt</code> index with two text values. You can modify either or both, or set one to null if you want only a single balloon to display.
 When the click in the plot area doesn't land on any data, then <code>coord</code> and <code>coordPos</code> are [[Null]]. You should test for this using <code>[[IsNull]](coord)</code> rather than <code>coord=Null</code>, since the later tests individual cells in an array for null which isn't what you want.