InsertCategory
PowerScript function
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
|
1 |
controlname.InsertCategory ( categoryvalue, categorynumber ) |
|
Argument |
Description |
|---|---|
|
controlname |
The name of the graph into which you want to insert a |
|
categoryvalue |
A value that is the category you want to insert. The |
|
categorynumber |
The number of the category before which you want to |
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:
|
1 |
gr_data.InsertCategory("Qty", 0) |
is equivalent to:
|
1 |
gr_data.AddCategory("Qty") |
Examples
These statements insert a category called Macs before the category
named PCs in the graph gr_product_data:
|
1 2 3 4 5 |
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:
|
1 2 3 |
catnum = gr_mail.InsertCategory(13:00, 0) catnum = gr_mail.InsertCategory(12:00, 0) catnum = gr_mail.InsertCategory(13:00, 0) |
See also