===== BarChart =====

com.ergotech.vib.graphics.javascript.charting.BarChart

==== Image Examples ====

| {{:mistudio:graphics:charts:pasted:20260701-181734.png?40|BarChart in the graphics palette}} | {{:mistudio:graphics:charts:pasted:20260701-181816.png?200|BarChart graphic example}} |
| //BarChart in the graphics palette.// | //BarChart graphic example.// |

==== Overview ====

The BarChart graphic is a chart graphic used to display data as vertical bars.

BarChart is commonly used to compare values across categories, indexes, timestamps, or multiple data series.

The current BarChart uses chart configuration properties such as **Series**, **YAxis**, **Use2DInput**, and optional reference line settings.

==== Common Uses ====

  * Comparing values
  * Displaying grouped data
  * Showing values by category or index
  * Displaying multiple bar series
  * Building dashboards with live or test data
  * Showing array or table-style data visually
  * Displaying reference lines such as center, upper, or lower limit lines

==== Input Behavior ====

BarChart can receive input through **valueInput** or through individual bar input ports, depending on the **Use2DInput** setting.

When **Use2DInput** is checked, BarChart uses **valueInput** for array-style or two-dimensional chart data.

When **Use2DInput** is unchecked, BarChart uses individual bar input ports such as `bar_0`, `bar_1`, and additional ports based on the configured series.

The input can come from a data source, Constant, BroadcastServer, or another logic component.

For full chart behavior, BarChart works best with table-style or array-style data sources.

Common test data sources include:

  * **TwoDimensionalDataSource**
  * **ArrayDataSource**

**TwoDimensionalDataSource** is useful for testing x/y values, timestamps, and multiple data columns.

**ArrayDataSource** is useful for simpler bar chart testing.

==== Output Behavior ====

BarChart is used as a display graphic.

BarChart does not provide a default user-input output workflow.

==== BarChart-Specific Behavior ====

BarChart displays data using one or more configured bar series.

BarChart-specific settings include:

  * **Name** Sets the name of the BarChart graphic.
  * **CenterLine** Configures an optional center reference line.
  * **High Value** Sets the high value used for chart scaling or range behavior.
  * **LclLine** Configures an optional lower control limit reference line.
  * **Low Value** Sets the low value used for chart scaling or range behavior.
  * **Series** Configures the chart bar series.
  * **UclLine** Configures an optional upper control limit reference line.
  * **Use2DInput** Controls the chart input mode. When checked, the chart uses **valueInput** for array-style or two-dimensional data. When unchecked, the chart uses individual bar input ports such as `bar_0`, `bar_1`, and additional ports based on the configured series.
  * **Use Color** Controls whether incoming colors are used when supported.
  * **UseTooltip** Controls whether chart tooltips are shown.
  * **YAxis** Configures the chart y-axis.
  * **Bad Qual. Indicator** Controls the indicator used when bad quality data is received.
  * **Visible** Controls whether the BarChart is shown.
  * **Warning Qual. Indicator** Controls the indicator used when warning or transitional quality data is received.

==== Logic Ports ====

The visible Logic Editor ports depend on the **Use2DInput** setting.

When **Use2DInput** is checked, BarChart uses this port:

  * **valueInput**

Use **valueInput** with **TwoDimensionalDataSource** or **ArrayDataSource** when the chart should receive array-style or two-dimensional chart data through one connection.

When **Use2DInput** is unchecked, BarChart uses individual bar input ports such as:

  * **bar_0**
  * **bar_1**

The available bar input ports depend on the chart configuration and the configured series.

Use individual bar input ports when each bar series should be updated from a separate scalar data source.

==== Series Configuration ====

BarChart uses the **Series** property to define the bar series displayed on the chart.

A series controls how one group of bars appears on the chart.

The Series editor includes a live preview and grouped settings for appearance, layout, axis selection, and animation.

When a data source provides multiple data columns, matching series should be configured so each column can display as a separate bar series.

For example, if a TwoDimensionalDataSource provides multiple Y columns, the BarChart should have matching bar series configured for those values.

==== Adding a Bar Series ====

To add another bar series:

  - Select the BarChart graphic in the Design Editor.
  - In the Basic properties, open the **Series** property editor.
  - Click the **+** button in the Series editor.
  - Configure the new bar series.
  - Set the bar appearance, layout spacing, Y-axis assignment, and animation setting.
  - Click **OK** to save the series settings.

{{:mistudio:graphics:charts:pasted:20260706-185913.png?500|BarChart Series editor}}

//BarChart Series editor with preview, appearance, layout, axis, and animation settings.//

==== Bar Series Settings ====

The Series editor includes these sections:

  * **Preview** Shows a preview of the configured bar series.
  * **Appearance** Controls the visual style of the bars.
  * **Layout** Controls spacing between bars and bar categories.
  * **Axis** Selects which Y-axis the bar series uses.
  * **Animation** Controls whether animation is enabled for the bar series.

The **Appearance** section includes:

  * **Bar Color** Sets the color of the bar series.

The **Layout** section includes:

  * **Bar Gap** Sets the spacing between bars in the same category.
  * **Bar Category Gap (%)** Sets the spacing between bar categories as a percentage.

The **Axis** section includes:

  * **Y Axis** Selects which Y-axis the bar series uses.

The **Animation** section includes:

  * **Animation** Controls whether the bar series uses animation.

==== Multiple Series Behavior ====

When using multiple data columns, each visible bar group needs a matching configured series.

For example:

<code>
One Y column   = one bar series
Two Y columns  = two bar series
Three Y columns = three bar series
</code>

If the chart only has one configured series, extra data columns can fail to appear as separate bar groups.

==== Two-Dimensional Data Behavior ====

TwoDimensionalDataSource is the main test data source for BarChart.

With timestamp behavior enabled on the data source, the chart can display time-based bar data.

With timestamp behavior disabled, the first data column can be used as the x-axis, and additional columns can be used as y-series data.

Multiple y-series require matching entries in the **Series** configuration.

Use **TwoDimensionalDataSource** with **Use2DInput** checked and connected to **valueInput**.

==== Array Data Behavior ====

ArrayDataSource can be used for simpler BarChart testing.

Array data is useful when a simple set of bar values needs to be displayed.

Use **ArrayDataSource** with **Use2DInput** checked and connected to **valueInput**.

For full x/y behavior, timestamp behavior, or multiple data columns, use **TwoDimensionalDataSource**.

==== Individual Bar Inputs ====

When **Use2DInput** is unchecked, BarChart uses individual bar input ports such as `bar_0`, `bar_1`, and additional ports based on the configured series.

These ports allow scalar data sources to update individual bar series.

For example:

<code>
SineServer -> bar_0
RandomBoolean -> bar_1
Constant -> bar_2
</code>

This mode is useful when each bar should be updated from a separate source.

==== Reference Lines ====

BarChart includes optional reference line properties:

  * **CenterLine**
  * **LclLine**
  * **UclLine**

These properties are used for chart reference lines such as center, lower control limit, and upper control limit lines.

Reference line settings are chart configuration values and should be edited through the chart property controls.

==== Notes ====

Use BarChart when values should be compared as bars.

Use **TwoDimensionalDataSource** for full chart testing with x/y values, timestamps, and multiple columns.

Use **ArrayDataSource** for simpler bar chart testing.

Use **Use2DInput** checked with **valueInput** for array-style or two-dimensional chart data.

Use **Use2DInput** unchecked with individual bar inputs when each bar series should receive a separate scalar value.

Use numeric or array-style data sources with BarChart. String data sources are not appropriate for numeric chart input.

LineChart is better for trend-style line displays. PieChart and DoughnutChart are better for slice-style displays.

==== Related Pages ====

  * [[mistudio:design_editor:start|MIStudio Design Editor]]
  * [[mistudio:design_editor:charts:start|Charts]]
  * [[mistudio:design_editor:charts:linechart|LineChart]]
  * [[mistudio:design_editor:charts:bigdatalinechart|BigDataLineChart]]
  * [[mistudio:design_editor:charts:piechart|PieChart]]
  * [[mistudio:getting_started:test_data_sources|Using Test Data Sources]]
  * [[mistudio:getting_started:connect_data_source_to_graphic|Connecting a Data Source to a Graphic]]