Description
Inserts a data point in a series of a graph. You can specify the category for the data point or its position in the series. Does not apply to scatter graphs.
Applies to
Graph controls in windows and user objects. Does not apply to graphs within DataWindow objects, because their data comes directly from the DataWindow.
Syntax
controlname.InsertData ( seriesnumber, datapoint, datavalue {, categoryvalue } )
|
Argument |
Description |
|---|---|
|
controlname |
The name of the graph in which you want to insert data into a series. |
|
seriesnumber |
The number that identifies the series in which you want to insert data. |
|
datapoint |
The number of the data point before which you want to insert the data. |
|
datavalue |
The value of the data point you want to insert. |
|
categoryvalue (optional) |
The category for this data value on the category axis. The datatype of categoryvalue should match the datatype of the category axis. In most cases, you should include categoryvalue. Otherwise, an uncategorized value will be added to the series. |
Return value
Integer. Returns the number of the data value if it succeeds and -1 if an error occurs. If any argument's value is null, InsertData returns null.
Usage
When you specify datapoint without specifying categoryvalue, InsertData inserts the data point in the category at that position, shifting existing data points to the following categories. The shift may cause there to be uncategorized data points at the end of the axis.
When you specify categoryvalue, InsertData ignores the position in datapoint and puts the data point in the specified category, replacing any data value that is already there. If the category does not exist, InsertData creates the category at the end of the axis.
To modify the value of a data point at a specified position, use ModifyData.
Scatter graphs
To add data to a scatter graph, use Syntax 2 of AddData.
Equivalent syntax
If you want to add a data point to the end of a series or to an existing category in a series, you can use AddData instead, which requires fewer arguments.
InsertData and ModifyData behave differently when you specify datapoint to indicate a position for inserting or modifying data. However, they behave the same as AddData when you specify a position of 0 and a category. All three modify the value of a data point when the category already exists. All three insert a category with a data value at the end of the axis when the category does not exist.
When you specify a position as well as a category, and that category already exists, InsertData ignores the position and modifies the data of the specified category, but ModifyData changes the category label at that position.
This statement:
gr_data.InsertData(1, 0, 44, "Qty")
is equivalent to:
gr_data.ModifyData(1, 0, 44, "Qty")
and is also equivalent to:
gr_data.AddData(1, 44, "Qty")
When you specify a position, the following statements are not equivalent:
-
InsertData ignores the position and modifies the data value of the Qty category:
gr_data.InsertData(1, 4, 44, "Qty")
-
ModifyData changes the category label and the data value at position 4:
gr_data.ModifyData(1, 4, 44, "Qty")
Examples
Assuming the category label Jan does not already exist, these statements insert a data value in the series named Costs before the data point for Mar and assign the data point the category label Jan in the graph gr_product_data:
integer SeriesNbr, CategoryNbr
// Get the numbers of the series and category.
SeriesNbr = gr_product_data.FindSeries("Costs")
CategoryNbr = gr_product_data.FindCategory("Mar")
gr_product_data.InsertData(SeriesNbr, &
CategoryNbr, 1250, "Jan")These statements insert the data value 1250 after the data value for Apr in the series named Revenues in the graph gr_product_data. The data is inserted in the category after Apr, and the rest of the data, if any, moves over a category:
integer SeriesNbr, CategoryNbr
// Get the number of the series and category.
CategoryNbr = gr_product_data.FindCategory("Apr")
SeriesNbr = gr_product_data.FindSeries("Revenues")
gr_product_data.InsertData(SeriesNbr, &
CategoryNbr + 1, 1250)See also
