diff --git a/topics/en/changelog.adoc b/topics/en/changelog.adoc index abecbd2..810331f 100644 --- a/topics/en/changelog.adoc +++ b/topics/en/changelog.adoc @@ -4,6 +4,7 @@ This topic contains the following sections: +* <> * <> * <> * <> @@ -20,6 +21,16 @@ This topic contains the following sections: * <> * <> +[[Ref_26_1]] + +== 26.1 (2026) + +=== New Chart Features + +==== Range Bar Series + +Added `RangeBarSeries` to `{DataChartName}` so you can render low-to-high ranges as horizontal bars by combining a `CategoryYAxis` with a `NumericXAxis`. For more information, see link:datachart-category-range-bar-series.html[Range Bar Series]. + [[Ref_25_2_111]] == 25.2.111 (March 2026) @@ -758,4 +769,4 @@ This feature includes a new filter syntax that is OData-like that you can use wi The following documentation describes the various ways that you can apply the highlight filter to the chart controls: - link:datachart-highlight-filter.html[{DataChartName} Highlight Filter] -- link:categorychart-highlight-filter.html[{CategoryChartName} Highlight Filter] \ No newline at end of file +- link:categorychart-highlight-filter.html[{CategoryChartName} Highlight Filter] diff --git a/topics/en/datachart-category-range-bar-series.adoc b/topics/en/datachart-category-range-bar-series.adoc new file mode 100644 index 0000000..36f7981 --- /dev/null +++ b/topics/en/datachart-category-range-bar-series.adoc @@ -0,0 +1,158 @@ +//// +|metadata| +{ + "name": "datachart-category-range-bar-series", + "controlName": ["{DataChartName}"], + "tags": ["Application Scenarios","Charting","How Do I"], + "guid": "f0cd173a-e80d-47d8-a96b-577b30d9ecdc", + "buildFlags": [], + "createdOn": "2026-05-21T00:00:00Z" +} +|metadata| +//// + += Range Bar Series + +This topic explains, with code examples, how to use the link:{DataChartLink}.RangeBarSeries.html[RangeBarSeries] in the link:{DataChartLink}.{DataChartName}.html[{DataChartName}]™ control. + +== Overview + +The topic is organized as follows: + +* <> +* <> +* <> +* <> +* <> +* <> + +[[Introduction]] +== Introduction + +Range Bar Series belongs to a group of link:datachart-category-series-overview.html[Category Series] and it is rendered using a collection of horizontal bars that show the difference between two values of a data point. This type of series emphasizes the amount of change between low values and high values in the same data point or compares multiple items. Range values are represented on the x-axis (NumericXAxis) and categories are displayed on the y-axis (CategoryYAxis). The link:{DataChartLink}.RangeBarSeries.html[RangeBarSeries] is the vertical counterpart to the link:{DataChartLink}.RangeColumnSeries.html[RangeColumnSeries] in the same way that the link:{DataChartLink}.BarSeries.html[BarSeries] is the vertical counterpart to the link:{DataChartLink}.ColumnSeries.html[ColumnSeries]. For more conceptual information and supported types of axes, refer to the link:datachart-category-series-overview.html[Category Series] and link:datachart-axes.html[Chart Axes] topics. + +[[DataRequirements]] +== Data Requirements + +While the {DataChartName} control allows you to easily bind it to your own data model, make sure to supply the appropriate amount and type of data that the series requires. If the data does not meet the minimum requirements based on the type of series that you are using, an error is generated by the control. Refer to the link:datachart-series-requirements.html[Series Requirements] and link:datachart-category-series-overview.html[Category Series] topics for more information on data series requirements. + +The following is a list of data requirements for the `RangeBarSeries` type: + +* The data model must contain at least two numeric data columns for rendering the range between the values. +* The data model may contain an optional string or date time field for labels. +* The data source should contain at least one data item. + +[[DataRenderingRules]] +== Data Rendering Rules + +The `RangeBarSeries` renders data using the following rules: + +* Each row with two data values specified as the link:{DataChartLink}.RangeCategorySeries{ApiProp}LowMemberPath.html[LowMemberPath] and link:{DataChartLink}.RangeCategorySeries{ApiProp}HighMemberPath.html[HighMemberPath] properties of the data mapping is drawn as a separate horizontal bar representing the difference between these data values. +* The string or date time column that is mapped to the `Label` property of data mapping on the y-axis is used as the category labels. If the data mapping for `Label` is not specified, default labels are used. +* Category labels are drawn on the y-axis. Data values are drawn on the x-axis. +* When rendering, multiple series of the `RangeBarSeries` type will get rendered in clusters where each cluster represents a data point. The first series in the `Series` collection of the {DataChartName} control renders at the bottom of the cluster. Each successive series is rendered above the previous series. For more information, refer to the link:datachart-multiple-series.html[Multiple Series] topic. + +[[DataBindingExample]] +== Data Binding Example + +The following code snippet shows how to bind the link:{DataChartLink}.RangeBarSeries.html[RangeBarSeries] object to a sample of category data (which is available for download from the link:resources-sample-energy-data.html[Sample Energy Data] resource). Refer to the data requirements section of this topic for information about data requirements for the `RangeBarSeries`. + +ifdef::win-forms[] +*In C#:* +[source,csharp] +---- +var data = new EnergyDataSource(); +var xAxis = new NumericXAxis(); +var yAxis = new CategoryYAxis(); +yAxis.DataSource = data; +yAxis.Label = "{Country}"; + +var series1 = new RangeBarSeries(); +series1.DataSource = data; +series1.HighMemberPath = "Coal"; +series1.LowMemberPath = "Oil"; +series1.Title = "Coal vs Oil"; +series1.XAxis = xAxis; +series1.YAxis = yAxis; + +var series2 = new RangeBarSeries(); +series2.DataSource = data; +series2.HighMemberPath = "Hydro"; +series2.LowMemberPath = "Nuclear"; +series2.Title = "Hydro vs Nuclear"; +series2.XAxis = xAxis; +series2.YAxis = yAxis; + +var chart = new {DataChartName}(); +chart.Axes.Add(xAxis); +chart.Axes.Add(yAxis); +chart.Series.Add(series1); +chart.Series.Add(series2); +---- + +*In Visual Basic:* +[source,vb] +---- +Dim data As New EnergyDataSource() +Dim xAxis As New NumericXAxis() +Dim yAxis As New CategoryYAxis() +yAxis.DataSource = data +yAxis.Label = "{Country}" + +Dim series1 As New RangeBarSeries() +series1.DataSource = data +series1.HighMemberPath = "Coal" +series1.LowMemberPath = "Oil" +series1.Title = "Coal vs Oil" +series1.XAxis = xAxis +series1.YAxis = yAxis + +Dim series2 As New RangeBarSeries() +series2.DataSource = data +series2.HighMemberPath = "Hydro" +series2.LowMemberPath = "Nuclear" +series2.Title = "Hydro vs Nuclear" +series2.XAxis = xAxis +series2.YAxis = yAxis + +Dim chart As New {DataChartName}() +chart.Axes.Add(xAxis) +chart.Axes.Add(yAxis) +chart.Series.Add(series1) +chart.Series.Add(series2) +---- +endif::win-forms[] + +[[SeriesProperties]] +== Series Properties + +The `RangeBarSeries` supports the same low/high value mapping behavior as other range series and also provides the following commonly used properties: + +[options="header", cols="a,a"] +|==== +|Property |Description + +|`HighMemberPath` +|Specifies the data column that contains the high value for each horizontal range bar. + +|`LowMemberPath` +|Specifies the data column that contains the low value for each horizontal range bar. + +|`RadiusX` and `RadiusY` +|Specify the corner radius applied to the rendered bars. + +|`LowMemberAsLegendLabel` and `HighMemberAsLegendLabel` +|Specify custom labels for the low and high values displayed by the Data Legend. + +|`LowMemberAsLegendUnit` and `HighMemberAsLegendUnit` +|Specify custom units for the low and high values displayed by the Data Legend. +|==== + +[[RelatedContent]] +== Related Content + +* link:datachart-axes.html[Axes] +* link:datachart-category-bar-series.html[Bar Series] +* link:datachart-category-range-column-series.html[Range Column Series] +* link:datachart-category-range-area-series.html[Range Area Series] +* link:datachart-series-requirements.html[Series Requirements] diff --git a/topics/ja/changelog.ja-JP.adoc b/topics/ja/changelog.ja-JP.adoc index c95e314..2ba8b70 100644 --- a/topics/ja/changelog.ja-JP.adoc +++ b/topics/ja/changelog.ja-JP.adoc @@ -4,6 +4,7 @@ このトピックは、以下のセクションで構成されます。 +* <> * <> * <> * <> @@ -20,6 +21,16 @@ * <> * <> +[[Ref_26_1]] + +== 26.1 (2026 年) + +=== 新しいチャート機能 + +==== 範囲棒シリーズ + +`RangeBarSeries` が `{DataChartName}` に追加され、`CategoryYAxis` と `NumericXAxis` を組み合わせて、安値から高値までの範囲を横棒として描画できるようになりました。詳細は、link:datachart-category-range-bar-series.html[範囲棒シリーズ] を参照してください。 + [[Ref_25_2_111]] == 25.2.111 (2026 年 3 月) @@ -755,4 +766,4 @@ image:images/chart-highlight-filter.png[] 次のドキュメントでは、チャート コントロールに強調表示フィルターを適用するさまざまな方法について説明します。 - link:datachart-highlight-filter.html[{DataChartName} 強調表示フィルター] -- link:categorychart-highlight-filter.html[{CategoryChartName} 強調表示フィルター] \ No newline at end of file +- link:categorychart-highlight-filter.html[{CategoryChartName} 強調表示フィルター] diff --git a/topics/ja/datachart-category-range-bar-series.ja-JP.adoc b/topics/ja/datachart-category-range-bar-series.ja-JP.adoc new file mode 100644 index 0000000..d467372 --- /dev/null +++ b/topics/ja/datachart-category-range-bar-series.ja-JP.adoc @@ -0,0 +1,158 @@ +//// +|metadata| +{ + "name": "datachart-category-range-bar-series", + "controlName": ["{DataChartName}"], + "tags": ["Application Scenarios","Charting","How Do I"], + "guid": "b6f72554-ae23-4b95-a2ea-6d3ae4a097cf", + "buildFlags": [], + "createdOn": "2026-05-21T00:00:00Z" +} +|metadata| +//// + += 範囲棒シリーズ + +このトピックは、コード例を示して、link:{DataChartLink}.rangebarseries.html[RangeBarSeries] を link:{DataChartLink}.{DataChartName}.html[{DataChartName}]™ コントロールで使用する方法を説明します。 + +== 概要 + +トピックは以下のとおりです。 + +* <> +* <> +* <> +* <> +* <> +* <> + +[[Introduction]] +== 概要 + +範囲棒シリーズは、link:datachart-category-series-overview.html[カテゴリ シリーズ] のグループに属し、データ ポイントの 2 つの値の差を示す横棒のコレクションを使用して描画します。このタイプのシリーズは、同一データ ポイントにおける安値と高値の差を強調したり、複数の項目を比較したりする場合に便利です。範囲の値は x 軸 (NumericXAxis) に表され、カテゴリは y 軸 (CategoryYAxis) に表示されます。link:{DataChartLink}.rangebarseries.html[RangeBarSeries] は、link:{DataChartLink}.rangecolumnseries.html[RangeColumnSeries] の縦方向版であり、link:{DataChartLink}.barseries.html[BarSeries] が link:{DataChartLink}.columnseries.html[ColumnSeries] の縦方向版である関係と同様です。シリーズの他のタイプとサポートされる軸の詳細は、link:datachart-category-series-overview.html[カテゴリ シリーズ] と link:datachart-axes.html[チャート軸] のトピックを参照してください。 + +[[DataRequirements]] +== データ要件 + +{DataChartName} コントロールは固有のデータ モデルに簡単にバインドできますが、そのシリーズが必要とする適切な量と型のデータを必ず指定してください。使用しているシリーズの種類に基づいた最小要件をデータが満たさない場合、コントロールはエラーを生成します。データ シリーズ要件の詳細は、link:datachart-series-requirements.html[シリーズ要件] および link:datachart-category-series-overview.html[カテゴリ シリーズ] を参照してください。 + +以下は、`RangeBarSeries` タイプのデータ要件の一覧です。 + +* データ モデルには、値の間の範囲を描画するために少なくとも 2 つの数値データ列が必要です。 +* データ モデルには、ラベル用の文字列または日時フィールドを任意で含めることができます。 +* データ ソースには少なくとも 1 つのデータ項目が必要です。 + +[[DataRenderingRules]] +== データ描画の規則 + +`RangeBarSeries` は以下の規則を使用してデータを描画します。 + +* データ マッピングの link:{DataChartLink}.RangeCategorySeries{ApiProp}LowMemberPath.html[LowMemberPath] および link:{DataChartLink}.RangeCategorySeries{ApiProp}HighMemberPath.html[HighMemberPath] プロパティで指定された 2 つのデータ値をもつ各行は、これらの値の差を表す個別の横棒として描画されます。 +* y 軸上のデータ マッピングの `Label` プロパティにマップされる文字列または日時の列は、カテゴリ ラベルとして使用されます。`Label` のデータ マッピングが指定されない場合、デフォルトのラベルが使用されます。 +* カテゴリ ラベルは y 軸上に描かれ、データ値は x 軸上に描かれます。 +* 描画時には、複数の `RangeBarSeries` シリーズは各クラスターが 1 つのデータ ポイントを表すクラスターとして描画されます。{DataChartName} コントロールの `Series` コレクションの最初のシリーズはクラスターの下側に描画され、後続のシリーズはその上に描画されます。詳細は、link:datachart-multiple-series.html[複数シリーズ] のトピックを参照してください。 + +[[DataBindingExample]] +== データ バインディング例 + +以下のコード スニペットは、link:{DataChartLink}.rangebarseries.html[RangeBarSeries] オブジェクトをカテゴリ データ サンプル (link:resources-sample-energy-data.html[エネルギー データのサンプル] リソースからダウンロード可能) にバインドする方法を示します。`RangeBarSeries` のデータ要件の詳細は、このトピックのデータ要件セクションを参照してください。 + +ifdef::win-forms[] +*C# の場合:* +[source,csharp] +---- +var data = new EnergyDataSource(); +var xAxis = new NumericXAxis(); +var yAxis = new CategoryYAxis(); +yAxis.DataSource = data; +yAxis.Label = "{Country}"; + +var series1 = new RangeBarSeries(); +series1.DataSource = data; +series1.HighMemberPath = "Coal"; +series1.LowMemberPath = "Oil"; +series1.Title = "Coal vs Oil"; +series1.XAxis = xAxis; +series1.YAxis = yAxis; + +var series2 = new RangeBarSeries(); +series2.DataSource = data; +series2.HighMemberPath = "Hydro"; +series2.LowMemberPath = "Nuclear"; +series2.Title = "Hydro vs Nuclear"; +series2.XAxis = xAxis; +series2.YAxis = yAxis; + +var chart = new {DataChartName}(); +chart.Axes.Add(xAxis); +chart.Axes.Add(yAxis); +chart.Series.Add(series1); +chart.Series.Add(series2); +---- + +*Visual Basic の場合:* +[source,vb] +---- +Dim data As New EnergyDataSource() +Dim xAxis As New NumericXAxis() +Dim yAxis As New CategoryYAxis() +yAxis.DataSource = data +yAxis.Label = "{Country}" + +Dim series1 As New RangeBarSeries() +series1.DataSource = data +series1.HighMemberPath = "Coal" +series1.LowMemberPath = "Oil" +series1.Title = "Coal vs Oil" +series1.XAxis = xAxis +series1.YAxis = yAxis + +Dim series2 As New RangeBarSeries() +series2.DataSource = data +series2.HighMemberPath = "Hydro" +series2.LowMemberPath = "Nuclear" +series2.Title = "Hydro vs Nuclear" +series2.XAxis = xAxis +series2.YAxis = yAxis + +Dim chart As New {DataChartName}() +chart.Axes.Add(xAxis) +chart.Axes.Add(yAxis) +chart.Series.Add(series1) +chart.Series.Add(series2) +---- +endif::win-forms[] + +[[SeriesProperties]] +== シリーズ プロパティ + +`RangeBarSeries` は、他の範囲シリーズと同じ low/high 値マッピングをサポートし、さらに次のプロパティを使用できます。 + +[options="header", cols="a,a"] +|==== +|プロパティ |説明 + +|`HighMemberPath` +|各横棒の高値を含むデータ列を指定します。 + +|`LowMemberPath` +|各横棒の安値を含むデータ列を指定します。 + +|`RadiusX` および `RadiusY` +|描画される棒の角丸半径を指定します。 + +|`LowMemberAsLegendLabel` および `HighMemberAsLegendLabel` +|Data Legend に表示される安値と高値のカスタム ラベルを指定します。 + +|`LowMemberAsLegendUnit` および `HighMemberAsLegendUnit` +|Data Legend に表示される安値と高値のカスタム単位を指定します。 +|==== + +[[RelatedContent]] +== 関連コンテンツ + +* link:datachart-axes.html[軸] +* link:datachart-category-bar-series.html[棒シリーズ] +* link:datachart-category-range-column-series.html[範囲柱状シリーズ] +* link:datachart-category-range-area-series.html[範囲領域シリーズ] +* link:datachart-series-requirements.html[シリーズ要件]