Chart content that represents data using a single horizontal or vertical rule.
You can use `RuleMark` to plot a horizontal or vertical rule in your chart.
### Show Range with Rule Marks
To create a horizontal line at a `y` position from `xStart` to `xEnd` you use the ``init(xStart:xEnd:y:)`` or
``init(xStart:xEnd:y:)``. To create a vertical line at an `x` position from `yStart` to `yEnd` you use
``init(x:yStart:yEnd:)`` or ``init(x:yStart:yEnd:)``. The example below uses the `Pollen` structure and the
``init(xStart:xEnd:y:)`` to map horizontal lines that span from the value of the `startDate` to the value of the `endDate` for x positions to
a pollen `source` property's y position:
```swift
struct Pollen {
var source: String
var startDate: Date
var endDate: Date
init(startMonth: Int, numMonths: Int, source: String) {
self.source = source
let calendar = Calendar.autoupdatingCurrent
self.startDate = calendar.date(from: DateComponents(year: 2020, month: startMonth, day: 1))!
self.endDate = calendar.date(byAdding: .month, value: numMonths, to: startDate)!
}
}
var data: [Pollen] = [
Pollen(startMonth: 1, numMonths: 9, source: "Trees"),
Pollen(startMonth: 12, numMonths: 1, source: "Trees"),
Pollen(startMonth: 3, numMonths: 8, source: "Grass"),
Pollen(startMonth: 4, numMonths: 8, source: "Weeds")
]
var body: some View {
Chart(data) {
RuleMark(
xStart: .value("Start Date", $0.startDate),
xEnd: .value("End Date", $0.endDate),
y: .value("Pollen Source", $0.source)
)
}
}
```
### Annotate a chart with rule mark
You can annotate a chart with horizontal or vertically spanning rules. This allows viewers to easily compare values over a range to a
constant value. Use the ``init(xStart:xEnd:y:)-444cp`` initializer to represent a constant `y` value or ``init(x:yStart:yEnd:)-6zemd`` for a constant `x` value.
To span the plotting area of a chart with a line, omit the optional start and end parameters and plot a constant value. The example below
results in a line that spans the chart horizontally at the y position of 9000:
```swift
struct DepartmentProfit {
var department: String
var profit: Double
}
var data: [DepartmentProfit] = [
DepartmentProfit(department: "Production", profit: 15000),
DepartmentProfit(department: "Marketing", profit: 8000),
DepartmentProfit(department: "Finance", profit: 10000)
]
var body: some View {
Chart
ForEach(data) {
BarMark(
x: .value("Department", $0.department),
y: .value("Profit", $0.profit)
)
}
RuleMark(y: .value("Break Even Threshold", 9000))
.foregroundStyle(.red)
}
}
```
### RuleMark in Chart3D
To plot a rule in a 3D chart, use the ``init(x:y:z:)`` initializer.
The rule extends along the axis that you provide a range for, and is positioned at the single points you specify for the other two axes.
> Important: A 3D rule mark requires one parameter to be a numeric range and the other two parameters to be single numeric values.
For example, the following `Chart3D` shows three rule marks. Each mark extends along one axis and is fixed at `0` on the other two.
```swift
Chart3D {
// A rule that extends along the x-axis
RuleMark(
x: .value("x", -0.5..<0.5),
y: .value("y", 0),
z: .value("z", 0)
)
.foregroundStyle(.red)
// A rule that extends along the y-axis
RuleMark(
x: .value("x", 0),
y: .value("y", -0.5..<0.5),
z: .value("z", 0)
)
.foregroundStyle(.green)
// A rule that extends along the z-axis
RuleMark(
x: .value("x", 0),
y: .value("y", 0),
z: .value("z", -0.5..<0.5)
)
.foregroundStyle(.blue)
}
```
nonisolated init<Y>(x: CGFloat? = nil, yStart: PlottableValue<Y>, yEnd: PlottableValue<Y>) where Y : Plottable
Creates a vertical rule mark with a fixed x position and y interval encoding.
- Parameters:
- x: The x position. If `x` is `nil`, the rule will be centered horizontally by default.
- yStart: The value plotted with y start.
- yEnd: The value plotted with y end.
### Discussion
Use this initializer to create a vertical rule at y positions from `yStart` to `yEnd` for a single x position:
```swift
Chart(data) {
RuleMark(
yStart: .value("Start Date", $0.startDate),
yEnd: .value("End Date", $0.endDate)
)
}
```
See ``RuleMark`` for the setup of the structure containing the `startDate`, `endDate`, and `source`
properties.
nonisolated init<X>(x: PlottableValue<X>, yStart: CGFloat? = nil, yEnd: CGFloat? = nil) where X : Plottable
Creates a vertical rule mark with value plotted with x.
- Parameters:
- x: The value plotted with x.
- yStart: The y start position. If `yStart` is `nil` the rule will start at the leading edge of the plotting area.
- yEnd: The y end position. If `yEnd` is `nil` the rule will end at the trailing edge of the plotting area.
### Discussion
Use this initializer to create a vertical rule across a chart's plotting area at an x position:
```swift
Chart {
ForEach(data) {
BarMark(
x: .value("Profit", $0.profit),
y: .value("Department", $0.department)
)
}
RuleMark(x: .value("Break Even Threshold", 9000))
.foregroundStyle(.red)
}
```
See the first code example in ``RuleMark`` for the setup of the structure that contains `department` and `profit` properties.
nonisolated init<X, Y>(x: PlottableValue<X>, yStart: PlottableValue<Y>, yEnd: PlottableValue<Y>) where X : Plottable, Y : Plottable
Creates a vertical rule mark with an x encoding and y interval encoding.
- Parameters:
- x: The value plotted with x.
- yStart: The value plotted with y start.
- yEnd: The value plotted with y end.
### Discussion
Use this initializer to create a vertical line at y positions from `yStart` to `yEnd` to an x position:
```swift
Chart(data) {
RuleMark(
x: .value("Pollen Source", $0.source),
yStart: .value("Start Date", $0.startDate),
yEnd: .value("End Date", $0.endDate)
)
}
```
See ``RuleMark`` for the setup of the structure that contains the `startDate`, `endDate`, and `source`
properties.
nonisolated init<Y>(xStart: CGFloat? = nil, xEnd: CGFloat? = nil, y: PlottableValue<Y>) where Y : Plottable
Creates a horizontal rule mark that plots a value on y.
- Parameters:
- xStart: The x start position. If `xStart` is `nil` the rule will start at the leading edge of the plotting area.
- xEnd: The x end position. If `xEnd` is `nil` the rule will end at the trailing edge of the plotting area.
- y: The value plotted with y.
### Discussion
Use this initializer to create a horizontal rule across a chart's plotting area at a y position:
```swift
Chart {
ForEach(data) {
BarMark(
x: .value("Department", $0.department),
y: .value("Profit", $0.profit)
)
}
RuleMark(y: .value("Break Even Threshold", 9000))
.foregroundStyle(.red)
}
```
See the first code example in ``RuleMark`` for the setup of the structure that contains the `department` and `profit` properties.
nonisolated init<X>(xStart: PlottableValue<X>, xEnd: PlottableValue<X>, y: CGFloat? = nil) where X : Plottable
Creates a horizontal rule mark that plots values on its x interval.
- Parameters:
- xStart: The value plotted with x start.
- xEnd: The value plotted with x end.
- y: The y position. If `y` is `nil`, the rule will be centered vertically by default.
### Discussion
Use this initializer to create a horizontal rule at x positions from `xStart` to `xEnd` for a single y position:
```swift
Chart(data) {
RuleMark(
xStart: .value("Start Date", $0.startDate),
xEnd: .value("End Date", $0.endDate)
)
}
```
See the second code example in ``RuleMark`` for the setup of the structure that contains the `startDate`, `endDate`, and `source`
properties.
nonisolated init<X, Y>(xStart: PlottableValue<X>, xEnd: PlottableValue<X>, y: PlottableValue<Y>) where X : Plottable, Y : Plottable
Creates a horizontal rule mark that plots values on its x interval and on y.
- Parameters:
- xStart: The value plotted with x start.
- xEnd: The value plotted with x end.
- y: The value plotted with y.
### Discussion
Use this initializer to create a horizontal rule at x positions from `xStart` to `xEnd` to a y position:
```swift
Chart(data) {
RuleMark(
xStart: .value("Start Date", $0.startDate),
xEnd: .value("End Date", $0.endDate),
y: .value("Pollen Source", $0.source)
)
}
```
See the second code example in ``RuleMark`` for the setup of the structure that contains the `startDate`, `endDate`, and `source`
properties.
Skipped declarations
1 declarations were excluded from these bindings. Each reason comes from the generator or the iOS SDK compiler.
RuleMark.init(x:y:z:)
This protocol needs associated types that cannot yet cross the bridge.
