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.
Controls
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 |
<span>controlname</span>.<span>InsertCategory</span> ( <span>categoryvalue</span>, <span>categorynumber</span> <span></span>) |
|
Argument |
Description |
|---|---|
|
controlname |
The name of the graph into which you |
|
categoryvalue |
A value that is the category you want |
|
categorynumber |
The number of the category before which |
Return Values
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 |
integer CategoryNbr |
|
1 |
|
1 |
// Get the number of the category. |
|
1 |
CategoryNbr = FindCategory("PCs") |
|
1 |
gr_product_data.<span>InsertCategory</span>("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 |
catnum = gr_mail.<span>InsertCategory</span>(13:00, 0) |
|
1 |
catnum = gr_mail.<span>InsertCategory</span>(12:00, 0) |
|
1 |
catnum = gr_mail.<span>InsertCategory</span>(13:00, 0) |