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
Description
Inserts a category in the RibbonBar control.
Applies to
Syntax
controlname.InsertCategory ( Long ItemHandleAfter, String Text )
controlname.InsertCategory ( Long ItemHandleAfter, RibbonCategoryItem Item )
|
Argument |
Description |
|---|---|
|
controlname |
The name of the RibbonBar control. |
|
ItemHandleAfter |
The handle of the category on the same level after which you want to insert the category. |
|
Text |
The title of the category to be inserted. |
|
Item |
A category item to be inserted. |
Return value
Long.
Returns the handle of the inserted item if it succeeds and -1 if an error occurs. If any argument's value is null, returns null.
Example 1
This example inserts the "MyCategory2" category after the "MyCategory1" category.
Long ll_Handle, ll_Handle2 ll_Handle = rbb_1.InsertCategoryFirst ( "MyCategory1" ) ll_Handle2 = rbb_1.InsertCategory ( ll_Handle, "MyCategory2" )
Example 2
This example also inserts the "MyCategory2" category after the "MyCategory1" category. It first defines a category item with various properties (including Text, Tag etc.) and then inserts it after the "MyCategory1" category.
Long ll_Handle,ll_Handle2
RibbonCategoryItem lr_Category
ll_Handle = rbb_1.InsertCategoryFirst ("MyCategory1")
lr_Category.Text = "MyCategory2"
lr_Category.Tag = "MyCategory2"
ll_Handle2 = rbb_1.InsertCategory (ll_Handle, lr_Category)
See also
