PCScript

PopChart Server Reference 4.0.5

AddPopupText

Syntax graph.AddPopupText(Category, Series, Text [;Category, Series, Text]*)

Description Adds PopUp text to any data item(s) that are in the specified categor(ies) and series.

PopUp text refers to a manually created box of text that appears as a user moves their mouse pointer over a specific data item. More information about PopUp text can be found in "PopUp Text" in Chapter 7 of the PopChart Server User Guide.

Each Graph.AddPopupText method can specify any number of PopUp text boxes. The parameters for each different PopUp text item should be separated from the parameters for other PopUp text items by a semi-colon (or the item delimiter, which is specified in the Main. ItemDelimiter method).

Note: If you are loading data via the graph. LoadFile command, be sure to call AddPopUpText after you call graph. LoadFile. Otherwise, PopChart Server will be unable to associate your PopUp text with the correct data item.

Parameters Graph.AddPopupText accepts the following parameters.

Category

{ int | int-int | Category Name }

Specifies the category or categories of the data item(s) for which PopUp text will appear. This value can be an integer, a range of integers, or the name of a category that has been specified in a Graph. SetCategories method.

If the value of this parameter is an integer, it refers to the nth category listed in the Graph. SetCategories method, where n is the integer specified. So, for example, if Fred is the second category name listed in the Graph. SetCategories method, and we pass 2 as the value of the categories parameter, we are referring to the Fred category.

If you wish to access a category number that is the same as another category's name, you will need to use the pound # sign before the category number. This lets PopChart Server know that you are referring to a category number instead of a category name.

For example, if category number 5 is named 3, then the statement graph.AddPopupText(3,1,Hello) will add PopUp text to category number 5, not 3, as it assumes you are referring to the category name. However, if you include a pound # sign before the number 3—graph.AddPopUpText(#3,1,Hello)—then PopChart Server will override the category name and instead add PopUp text to category number 3.

You can denote a range of categories with an integer, followed by a hyphen, followed by another integer. The first integer represents the first category that should display PopUp text, while the last integer indicates the last category that should display PopUp text. All data items in categories between these two will also display Popup text. Line 5 of Example 5.8 illustrates how to do this.

If you choose 0 as the category number, PopUp text will be added to the appropriate series name(s) in the legend.

Because X-Y and Time graphs do not use categories, the value of this parameter for those graphs is the number of the data item in the specified data series to which you want to add PopUp text. Example 5.9 illustrates this difference.

Note: Make sure you have Sort Data turned off in your appearance file (uncheck Properties > Graph Properties > General > Sort Data) if you are going to use Popup text with X-Y and Line graphs. Otherwise, the PopUp text may appear at the wrong data point.

Series

{ int | Series Name }

Specifies the series of the data item(s) for which PopUp text will appear. This value can be an integer, a range of integers, or the name of a series that has been specified in a Graph. SetSeries method.

If the value of this parameter is an integer, it refers to the nth series listed in the Graph. SetSeries method(s), where n is the integer specified. For example, if Fruit is the name of the series described in the second Graph. SetSeries method, and we pass 2 as the value of the series parameter, we are referring to the Fruit series.

If you wish to access a series number that is the same as another series' name, you will need to use the pound # sign before the series number. This lets PopChart Server know that you are referring to a series number instead of a series name.

For example, if series number 5 is named 3, then the statement graph.AddPopupText(1,3,Hello) will add PopUp text to series number 5, not 3, as it assumes you are referring to the series name. However, if you include a pound # sign before the number 3—graph.AddPopUpText(1,#3,Hello)—then PopChart Server will override the series name and instead add PopUp text to series number 3.

A range of series is denoted by an integer, followed by a hyphen, followed by another integer. The first integer represents the first series that should display PopUp text, while the last integer indicates the last series that should display PopUp text. All data items in series between these two will also display Popup text. This works similarly to the range of categories shown in Line 5 of Example 5.8.

Text

String

The text that will appear as a user moves their mouse pointer over the specified data item(s).

You can force a new line in the PopUp text by insert a backslash and the letter n (\n) where you want the new line to occur. However, when forcing a new line in JavaScript, \n is interpreted as an escape code. You will need to use \\n in JavaScript to specify a new line.

Important: If you are sending PCScript in an HTTP Request (i.e. not the PopChart Embedder), be sure to URL-encode (see "URL Encoding" in Chapter 11 of the PopChart Server User Guide) this command, especially if the Popup text string contains spaces or other irregular characters.

Lines 5 and 6 in Example 5.8 are the same command. The first just uses category and series names, while the second uses numbers. In both cases, the text Fred is failing Math will appear as the user moves the mouse pointer over the data item in the Fred category in the Math series.

Line 7 shows how to incorporate a range of data items. Data items that are in both the Science series and categories 1-3 display the PopUp text Barney and Wilma and Fred are failing Science.

Line 8 shows how more than one PopUp text box can be added with just one Graph.AddPopupText command.

Example 5.9 shows how Graph.AddPopupText() differs for X-Y and Time graphs. In this case, the Popup text Second Red Plot Point will appear as the user moves the mouse pointer over the data point (5,10).