Description
Inserts a category on the category axis of a graph at the specified position. Existing categories are renumbered to keep the category numbering sequential.
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.InsertCategory ( categoryvalue, categorynumber )
|
Argument |
Description |
|---|---|
|
controlname |
The name of the graph into which you want to insert a category. |
|
categoryvalue |
A value that is the category you want to insert. The category must be unique within the graph. The value you specify must be the same datatype as the datatype of the category axis. |
|
categorynumber |
The number of the category before which you want to insert the new category. To add the category at the end, specify 0. If the axis is sorted, the category will be integrated into the existing order, ignoring categorynumber. |
Return value
Integer.
Returns the number of the category if it succeeds and -1 if an error occurs. If the category already exists, it returns the number of the existing category. If any argument's value is null, InsertCategory returns null.
Usage
Categories are discrete. Even on a date or time axis, each category is separate with no timeline-style connection between categories. Only scatter graphs, which do not have discrete categories, have a continuous category axis.
When the axis datatype is string, category names are unique if they have different capitalization. Also, you can specify the empty string ("") as the category name. However, because category names must be unique, there can be only one category with that name.
When you use InsertCategory to create a new category, there will be holes in each of the series for that category. Use AddData or InsertData to create data points for the new category.
Equivalent syntax
If you want to add a category to the end of a series, you can use AddCategory instead, which requires fewer arguments.
This statement:
gr_data.InsertCategory("Qty", 0)is equivalent to:
gr_data.AddCategory("Qty")Examples
These statements insert a category called Macs before the category named PCs in the graph gr_product_data:
integer CategoryNbr
// Get the number of the category.
CategoryNbr = FindCategory("PCs")
gr_product_data.InsertCategory("Macs", CategoryNbr)In a graph reporting mail volume in the afternoon, these statements add three categories to a time axis. If the axis is sorted, the order in which you add the categories does not matter:
catnum = gr_mail.InsertCategory(13:00, 0) catnum = gr_mail.InsertCategory(12:00, 0) catnum = gr_mail.InsertCategory(13:00, 0)
See also
