CategoryAxisOptions class (Graph)

The align field aligns the category-axis to bottom/right or top/left side of the view. If the chart is horizontally oriented (values go vertically, categories go horizontally) the category-axis can be aligned to bottom or top side of the view. If the chart is vertically oriented (values go horizontally, categories go vertically) the category-axis can be aligned to left or right side of the view

The default category-axis can be shown next to 0-origin of value-axis only if:

• misc.updateRangeOnScroll {number} option is 0 (specifies the time in ms to update the chart's minimum and maximum values while user scrolls the chart (0 indicates that the chart's minimum and maximum values are updated only when changing the data))
• align option is 1(exAlignCenter) or 4(exAlignVCenter)
• 0 is shown between value-axis minimum and maximum values

null {null}, aligns the category-axis to bottom/right side of the view (default)
exontrol.AlignEnum.exAlignTop {exontrol.AlignEnum} or 0 {number}, aligns the category-axis to top/left side of the view
"center" {string}, the category-axis is displayed next to 0-origin of value-axis (only if above conditions are met)

The angle field is an object of type {title, labels} that sets the rotation angle (in degrees) for the axis title and labels. The title property specifies the category-axis title, and the format property defines an expression to customize the labels shown on the category axis. By default, if angle is not set, all angles are null (automatic). For example, if the axis is vertically displayed and aligned to the left side of the control, the title is rotated 90 degrees anti-clockwise, while the labels are shown not-rotated. If the axis is aligned to the right, the title is rotated 90 degrees clockwise. The angle field can be defined using a string representation such as "45,0" or as an object such as {title: -90}, where the title and labels attributes specify the rotation angle for the title and labels, respectively.

null {null}, all angles are set on auto (by default). For instance, if the axis is vertically displayed and aligned to the left side of the control, the title is rotated 90 degree anti-clockwise, while the labels are shown not-rotated. if the axis is aligned to the right the title is rotated 90 degree clockwise.
"45,0" {string}, the title is rotated 45 degree clockwise, while the labels are not rotated
{title: -90} {string}, the title is rotated 90 degree anti-clockwise

The axisLine field defines the configuration options to show the category-axis line. The line is horizontal if the chart is horizontally oriented (values go vertically, categories go horizontally) and vertical if the chart is vertically oriented (values go horizontally, categories go vertically). The majorTicks field defines the configuration options to show the major ticks of the category-axis. The majorGridLines field defines the configuration options to show the major grid lines of the category-axis. By default, the property is null, which indicates a solid-black 1-pixel wide axis-line.

null {null}, indicates a solid-black 1-pixel wide axis-line
{color: "red", width: 2} {LineOptions}, indicates a solid-red 2-pixels wide axis-line

The categories field defines the category names. Each serie has a collection of values. Each value represents a category. If the data property of the serie has been provided as an object (not array), each property of the object represents a category. For instance, data: {"meta": 200, "whatsup": 300}, defines two category names meta and whatsup. These custom categories are shown instead of categories defined by the first category axis. The categories field can be any of the following types:

• categories {number}, the categories property could indicate:
  • a number (if the control's Data property is not set) that defines a single category-name
  • the column index from the control's Data (if the control's Data property is set), that provides the category names
• categories {string}, the categories property could indicate:
  • names separated by comma (if the control's Data property is not set) that defines the category names
  • the column name or index from the control's Data (if the control's Data property is set), that provides the category names
• categories {string[]}, array of category names

The MiscellaneousOptions.showLabelsIf option specifies the category-unit's minimum size so the category labels are visible.

"x" {string}, specifies single-category named "x" (if the control's Data property is not set), or the column named "x" within the control's Data property provides the category names (if the control's Data property is set)
"2001,<b>2002,2003" {string}, indicates three categories such as "2001", "2002" and "2003", while 2002 is displayed in bold
[2001,2002] {array}, specifies two categories such as "2001" and "2002"

The chartGridLines field defines configuration options for displaying additional grid lines and labels within the chart panel. Lines are vertical for a horizontally oriented chart (values vertical, categories horizontal) and horizontal for a vertically oriented chart (values horizontal, categories vertical). The majorGridLines field defines the options for the category-axis major grid lines. The chartGridLines field only has effect if the FormatGridLinesOptions.format field is set and produces labels. By default, chartGridLines is null, meaning no additional grid lines are shown. The FormatGridLinesOptions.format field specifies an expression to customize the labels for these additional grid lines - for example, "date(value) format 'MMM'" would show a grid line for each month with labels like Jan, Feb, Mar. The step property in FormatGridLinesOptions controls the frequency of the grid lines, such as step: 2 to display every second month. For instance, the following samples are equivalent:

chartGridLines: {format: "'' + index", color: "lightgray"}
majorGridLines: {color: "lightgray"}

In the above example, the chartGridLines option is configured to display additional grid lines with a light gray color and transarent labels. The majorGridLines option is also set to light gray, which means that the major grid lines will have the same appearance as the additional grid lines defined by chartGridLines.

null {null}, no grid lines are displayed
{format: "date(value) format `MMM`", color: "red", width: 2, step: 2} {FormatGridLinesOptions}, indicates a solid-red 2-pixels wide grid lines, every second month
{format: "((0:=date(value)) format `MMM`) + (month(=:0) = 1 ? `<br>` + (=:0 format `YYYY`) : ``)"} {FormatGridLinesOptions}, the grid-lines are shown for every month, and the label includes the year for every January

The cursorFormat field defines a format-expression to customize the tooltip shown on the category-axis when the crosshair intersects it. The CursorOptions.visible field determines whether the tooltip is displayed. The cursorFormat expression can modify the tooltip based on the original category names. By default, if CursorOptions.visible is true, the tooltip shows the original category name over the category-axis labels.

The format-expression supports predefined constants, operators and keywords as explained:

• "index" keyword defines the index of the category
• "value" keyword defines the name of the category

The name of the category can include ex-HTML tags. The tooltip is displayed as it is, if the cursorFormat field is null (undefined).

"``" {string}, no tooltip is shown on category-axis, when the crosshair intersects the category-axis
"date(value) format `MMM d, yyyy`" {string}, the tooltip displays the dates in "MMM d, yyy" format

The format field specifies an expression to customize the labels to show on category axis. The format-expression can be used to redefine the categories based on the original category names. For instance, if the categories are defined as "2014-01-02,2014-01-03,2014-01-06", the format-expression can be "value left 4" to show only the left part of the category names (the year). The format-expression can also be used to split the category-axis in groups. The split field specifies whether the categories are redefined based on the format field.

The format-expression supports predefined constants, operators and keywords as explained:

• "index" keyword defines the index of the category
• "value" keyword defines the name of the category

The name of the category is displayed as it is, if the format field is null (undefined). The name of the category can include ex-HTML tags. The "split" field specifies whether the categories are redefined based on the "format" option.

null {null}, the names of the categories are displayed as they are (format is ignored)
"``" {string}, no label is displayed on the category-axis
"date(value) format `MMM d, yyyy`" {string}, the category-axis displays the dates in "MMM d, yyy" format

The majorGridLines field defines the configuration options to show the major grid lines of the category-axis (shown in the chart panel). The lines are vertical if the chart is horizontally oriented (values go vertically, categories go horizontally) and horizontal if the chart is vertically oriented (values go horizontally, categories go vertically). The chartGridLines field defines configuration options for displaying additional grid lines and labels within the chart panel. The axisLine field defines the configuration options to show the category-axis line. The majorTicks field defines the configuration options to show the major ticks of the category-axis. By default, the property is null, which indicates no grid lines are displayed.

null {null}, no grid lines are displayed
{color: "red", width: 2, step: 2} {GridLinesOptions}, indicates a solid-red 2-pixels wide grid lines, displayed two by two

The majorTicks field defines the configuration options to show the major ticks of the category-axis. The lines are vertical if the chart is horizontally oriented (values go vertically, categories go horizontally) and horizontal if the chart is vertically oriented (values go horizontally, categories go vertically). The axisLine field defines the configuration options to show the category-axis line. The majorGridLines field defines the configuration options to show the major grid lines of the category-axis. The majorGridLines field defines the configuration options to show the major grid lines of the category-axis. By default, the property is null, which indicates a solid-black 1-pixel wide tick.

null {null}, indicates a solid-black 1-pixel wide tick
{color: "red", width: 2} {LineOptions}, indicates a solid-red 2-pixels wide tick

The mark field defines configuration options for highlighting areas in the chart or on the axis for specific categories. A mark zone is displayed only when both MarkCategoryOptions.shape and MarkCategoryOptions.applyTo are provided and valid. The mark option allows you to highlight particular categories by applying a shape to the corresponding areas on the category-axis and/or within the chart panel. The MarkCategoryOptions.applyTo field specifies which categories are highlighted, using a category index, category name, or a custom expression, while the MarkCategoryOptions.shape field defines the shape used for the highlight.

null {null}, no categories are highlighted
{shape: "red", applyTo: 10} {MarkCategoryOptions}, highlighs in red, the cateory with the index 10
[{shape: "red", applyTo: 10}, {shape: "green", applyTo: 12}] {MarkCategoryOptions[]}, highlighs in red, the cateory with the index 10 and highlighs in green, the cateory with the index 12
{shape: {fillColor: "dodgerBlue",frameColor: "blue"}, applyTo: "value=`January`"} {MarkCategoryOptions}, highlights the category labeled "January" with a dodgerBlue fill and a blue frame

The offsetLabel field defines the offset to move labels horizontally or vertically in relation to their original positions. The offsetLabel field can be defined using a number, a string or an array of numbers or strings. If the offsetLabel is a number, the labels are shown shifted to the right, relative to their original-positions. If the offsetLabel is a string and starts with a comma character (","), the labels are shown shifted to the top, relative to their original-positions. If the offsetLabel is an array of two numbers or strings, the first value indicates the horizontal shift (positive value shifts to the right, negative value shifts to the left) and the second value indicates the vertical shift (positive value shifts down, negative value shifts up). The format field specifies a format-expression to customize the labels to show on category axis.

null {null}, the labels are shown in their original-positions
8 {number}, the labels are shown shifted to the right, relative to their original-positions
",-8" {number}, the labels are shown shifted to the top, relative to their original-positions
[2,4] {number}, the labels are shown with a shift of 2 pixels to the right and 4 pixels down compared to their original positions

The overviewGridLines field defines the configuration options to show the grid lines and labels between for the overview panel. The lines are vertical if the chart is horizontally oriented (values go vertically, categories go horizontally) and horizontal if the chart is vertically oriented (values go horizontally, categories go vertically). The axisLine field defines the configuration options to show the category-axis line. The majorTicks field defines the configuration options to show the major ticks of the category-axis. The majorGridLines field defines the configuration options to show the major grid lines of the category-axis. By default, the property is null, which indicates no grid lines are displayed. The OverviewOptions.visible field determines whether the overview panel is displayed.

null {null}, no grid lines are displayed
{format: "date(value) format `MMM`", color: "red", width: 2, step: 2} {FormatGridLinesOptions}, indicates a solid-red 2-pixels wide grid lines, every second month
{format: "year(date(value))"} {FormatGridLinesOptions}, a black 1-pixel wide grid-line is shown for every year

The reverse field indicates the direction of the category axis. The data values in the chart are arranged using the following properties:

• Sort, sorts the series values in ascending or descending order
• reverse (option of CategoryAxisOptions type), reverses the position of the values as they were added (if no Sort is applied), or reverses the order produced by the Sort property (if Sort is applied)
• Order, repositions values according to their zero-based indexes in a custom sequence

The custom order is cleared when Sort or reverse property is set, leaving the Order property empty.

null {null}, by default categories are listed from left to right (chart horizontally oriented, values go vertically, categories go horizontally) and from bottom to top (chart vertically oriented, values go horizontally, categories go vertically)
true {boolean}, the category axis direction will be reversed, it shows categories from right to left (chart horizontally oriented, values go vertically, categories go horizontally), and top to bottom (chart vertically oriented, values go horizontally, categories go vertically)

The shape field defines the shape to apply on the category-axis's background. The shape can be a string expression that defines shape's name within the exontrol.Shapes.Graph or exontrol.Shapes namespace, a CSS color, a JSON string-representation of an object of exontrol.Def.Shape type or an object of {normal,hover,click,disabled} type. The normal,hover,click and disabled are objects of exontrol.Def.Shape type.

"" {string}, null {null}, no shape is applied
"red" {string}, fills the object's background in red (CSS color)
'{"fillColor": "red"}' or '{"normal":{"fillColor": "red"}}' {string}, fills the object's background in red (JSON-representation of an object of exontrol.Def.Shape type)
"xxx" {string}, indicates that exontrol.Shapes.Graph.xxx or exontrol.Shapes.xxx is applied on the object's background. If the xxx field is missing, no custom shape is applied (no default object's shape is be applied)
"Button" or exontrol.Shapes.Button {object}, applies the "Button" shape on the object as defined into exontrol.Shapes namespace (@since 5.2)

The split field specifies whether the categories are redefined based on the format field. The format field contains an expression used to customize the labels on the category axis. For example, with categories like "2014-01-02, 2014-01-03, 2014-01-06," a format expression such as "value left 4" would display only the first four characters (the year). The format expression can also be used to group categories, and the split field determines whether these redefined or grouped categories are applied.

null {null} or false {boolean}, the categories remain unsplit by default
true {boolean}, splits the category-axis in groups

The tfi field specifies the font attributes to apply on the title and labels of the category-axis. The tfi field can be defined using a string representation such as "b monospace 16" or as an object such as {bold: true, fontName: "monospace", fontSize: 16}.

The tfi field as string supports any of the following keywords (each keyword can be specified using first letters only such as "b" for "bold) separated by space characters:

• bold, displays the text in bold (equivalent of <b> tag)
• italic, displays the text in italics (equivalent of <i> tag)
• underline, underlines the text (equivalent of <u> tag)
• strikeout, specifies whether the text is strike-through (equivalent of <s> tag)
• <fontName name>, specifies the font's family (equivalent of <font name> tag)
• <fontSize size>, specifies the size of the font (equivalent of <font ;size> tag)
• <fgColor CSSColor>, specifies the text's foreground color (equivalent of <fgcolor> tag)
• <bgColor CSSColor>, specifies the text's background color (equivalent of <bgcolor> tag)
• <shaColor CSSColor;width;offset>, defines the text's shadow (equivalent of <sha color;width;offset> tag)
• <outColor CSSColor>, shows the text with outlined characters (CSScolor) (equivalent of <out color> tag)
• <graColor CSSColor;mode;blend>, defines a gradient text (equivalent of <gra color;mode;blend> tag)

Any other word within the tfi field that's not recognized as a keyword is interpreted as:

• name of the font (not a number), specifies the font's family (equivalent of <font name> tag)
• size of the font (number), specifies the size of the font (equivalent of <font ;size> tag)

The tfi field as object supports any of the following fields:

• bold {boolean}, displays the text in bold (equivalent of <b> tag)
• italic {boolean}, displays the text in italics (equivalent of <i> tag)
• underline {boolean}, underlines the text (equivalent of <u> tag)
• strikeout {boolean}, specifies whether the text is strike-through (equivalent of <s> tag)
• fontName {string}, specifies the font's family (equivalent of <font name> tag)
• fontSize {number}, specifies the size of the font (equivalent of <font ;size> tag)
• fgColor {string}, specifies the text's foreground color (CSScolor) (equivalent of <fgcolor> tag)
• bgColor {string}, specifies the text's background color (CSScolor) (equivalent of <bgcolor> tag)
• shaColor {object}, specifies an object of {color, width, offset} type that defines the text's shadow (equivalent of <sha color;width;offset> tag), where:
  • color {string}, defines the color of the text's shadow (CSScolor)
  • width {number}, defines the size of the text's shadow
  • offset {number}, defines the offset to show the text's shadow relative to the text
• outColor {string}, shows the text with outlined characters (CSScolor) (equivalent of <out color> tag)
• graColor {object}, specifies an object of {color, mode, blend} type that defines a gradient text (equivalent of <gra color;mode;blend> tag), where:
  • color {string}, defines the gradient-color (CSScolor)
  • mode {number}, defines the gradient direction as 0 (left-right), 1 (default, top-bottom), 2 (left-center-right), and 3 (top-center-bottom)
  • blend {number}, defines the gradient blend as a value between 0 and 1

CSSColor or CSS legal color values can be specified by the following methods:

• Hexadecimal colors, is specified with: #RRGGBB, where the RR (red), GG (green) and BB (blue) hexadecimal integers specify the components of the color. All values must be between 00 and FF. For example, #0000ff value is rendered as blue, because the blue component is set to its highest value (ff) and the others are set to 00.
• Hexadecimal colors with transparency, is specified with: #RRGGBBAA, where AA (alpha) value must be between 00 and FF. For example, #0000ff80 defines a semi-transparent blue.
• RGB colors, is specified with the RGB(red, green, blue) function. Each parameter (red, green, and blue) defines the intensity of the color and can be an integer between 0 and 255. For example, rgb(0,0,255) defines the blue color.
• RGBA colors, are an extension of RGB color values with an alpha channel as RGBA(red, green, blue, alpha) function, where the alpha parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque). For example, rgba(0,0,255,0.5) defines a semi-transparent blue.
• HSL colors, is specified with the HSL(hue, saturation, lightness) function, where hue is a degree on the color wheel (from 0 to 360) - 0 (or 360) is red, 120 is green, 240 is blue. saturation is a percentage value; 0% means a shade of gray and 100% is the full color. lightness is also a percentage; 0% is black, 100% is white. HSL stands for hue, saturation, and lightness - and represents a cylindrical-coordinate representation of colors. For example, hsl(240, 100%, 50%) defines the blue color.
• HSLA colors, are an extension of HSL color values with an alpha channel - which specifies the opacity of the object as HSLA(hue, saturation, lightness, alpha) function, where alpha parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque). For example, hsla(240, 100%, 50%,0.5) defines a semi-transparent blue.
• Predefined/Cross-browser color names, 140 color names are predefined in the HTML and CSS color specification. For example, blue defines the blue color.

null {null}, the tfi field is ignored
"bold monospace 16 <fg blue>" {string}, defines Monospace font of 16px height, bold and blue
{bold: true, fontName: "monospace", fontSize: 16, fgColor: "blue"} {object}, defines Monospace font of 16px height, bold and blue

The title field specifies the title of the category-axis. The title supports ex-HTML format. The title is displayed only if the title field is not null. The angle field specifies the rotation angle (in degrees) for the title and labels of the axis. By default, if angle is omitted all angles are set on null(auto). For instance, if the axis is vertically displayed and aligned to the left side of the control, the title is rotated 90 degree anti-clockwise, while the labels are shown not-rotated. if the axis is aligned to the right the title is rotated 90 degree clockwise.

null {null}, no title is shown
"lt;fgcolor blue>Years" {string}, the Years title is displayed in blue

The visible field shows or hides the category-axis (including the labels). If the visible field is null, the category-axis is visible by default (if null the visible field has no effect). The align field aligns the category-axis to bottom/right or top/left side of the view. If the chart is horizontally oriented (values go vertically, categories go horizontally) the category-axis can be aligned to bottom or top side of the view. If the chart is vertically oriented (values go horizontally, categories go vertically) the category-axis can be aligned to left or right side of the view.

null {null}, by default, the category-axis is visible (if null the visible field has no effect)
false {boolean}, hides the category-axis