ChartSettings Module

Overview

ChartSettings provides a ready-to-use screen for configuring chart behavior and appearance. It encapsulates the core logic for composing the Chart.Settings object and enforcing parameter constraints and dependencies. It is created using a builder function and communicates through the DataSource and Delegate protocols.

Use it when you need a configurable settings UI that reflects the current chart configuration and allows users to reset or update settings.

**Note: **You can also construct your own Chart.Settings instance and pass it to the chart for greater flexibility, but you are responsible for handling constraints and any potential side effects in behavior.

Building the Screen

let settingsVC = ChartSettings.makeScreen(
  delegate: self,
  dataSource: self
)

• The function returns a fully configured UIViewController ready to present.
• The delegate receives updates and reset requests.
• The dataSource supplies current/default settings, preview data, and optionally controls which settings are visible and in what order.

Function Signature

public static func makeScreen(
  delegate: ChartSettings.Delegate,
  dataSource: ChartSettings.DataSource
) -> UIViewController

Dependencies

DataSource

Defines the protocol that supplies all input data required to render and configure the Chart Settings screen.
The DataSource is responsible for providing:

• The current and default Chart.Settings snapshots.
• The aggregation and instrument (for watermark and timezone settings).
• Candle data for chart previews.
• A flag indicating if settings have changed (to control the Reset button).
• An optional explicit layout and ordering of settings via settingsContent.

If you want to customize which settings are visible or their order, provide a custom array of ChartSettings.Section in settingsContent.
If you return nil, the default layout and ordering will be used.

See the protocol definition below for required properties.

Note: See Handled settings constraints for understanding parameters behavior if you hide part of settings.

public protocol DataSource: AnyObject {
  /// Used only to represent watermark settings.
  var aggregation: Aggregation { get }
  /// Required for timezone-related settings.
  var instrument: Instrument { get }
  /// Candles used for chart previews.
  var candles: [Candle] { get }
  /// Current chart settings snapshot.
  var settings: Chart.Settings { get }
  /// Default chart settings snapshot.
  var defaultSettings: Chart.Settings { get }
  /// Indicates whether settings were changed and if the Reset button should be shown.
  var settingsIsChanged: Bool { get }
  /// Visibility and ordering of settings parameters per section.
  /// Provide sections with items to whitelist what is visible and define display order; `nil` uses the default layout.
  var settingsContent: [ChartSettings.Section]? { get }
}

Notes:

• Provide settings and defaultSettings to reflect and reset the UI state.
• Set settingsIsChanged to true to show a Reset action.
• Use settingsContent to explicitly whitelist visible settings and define their order.
  • Pass nil for the default layout/ordering.

Delegate

Handles callbacks from the Chart Settings screen.

public protocol Delegate: AnyObject {
  /// Notifies that chart settings have changed.
  /// - Parameter newSettings: The updated snapshot of `Chart.Settings` to apply/persist.
  func settingsDidChanged(_ newSettings: Chart.Settings)
  /// Requests resetting chart settings to their default values.
  func resetSettings()
}

Implement this protocol to persist user changes (e.g., save to storage) and to handle reset requests.

Section Model and Ordering

Section models a group of settings displayed together in the UI.

public struct Section {
  public var title: String
  /// Section items. The order in the array matches the display order in the UI.
  public var items: [SettingsContent]
}

• The items array defines both the set of items and their visual order: earlier indices are displayed above later ones.
• You can supply multiple sections to structure the settings screen.

Whitelisting Visible Settings and Order

Use DataSource.settingsContent to explicitly control what is shown and in which order. For example:

let content: [ChartSettings.Section] = [
  ChartSettings.Section(
      title: "General",
      items: [
          // SettingsContent examples (conceptual):
             .timezone,
             .watermark,
             .volume
      ]
  ),
  ChartSettings.Section(
      title: "Appearance",
      items: [
          .candleStyle, 
          .colors, 
          .grid
      ]
  )
]
// Returning this array from `settingsContent` whitelists the visible items
// and enforces the UI order to match the array order.

If you return nil, the module falls back to its default layout and ordering.

Example Integration

final class MySettingsProvider: ChartSettings.DataSource {
  let aggregation: Aggregation
  let instrument: Instrument
  let candles: [Candle]
  var settings: Chart.Settings
  let defaultSettings: Chart.Settings
  var settingsIsChanged: Bool
  var settingsContent: [ChartSettings.Section]?
  init(...) {
      // Initialize the properties based on your app state
      self.settingsContent = nil // or a custom array of sections
  }
}
final class MySettingsDelegate: ChartSettings.Delegate {
  func settingsDidChanged(_ newSettings: Chart.Settings) {
      // Persist and/or apply settings
  }
  func resetSettings() {
      // Reset to defaults and refresh the screen
  }
}
// Usage
let vc = ChartSettings.makeScreen(
  delegate: MySettingsDelegate(),
  dataSource: MySettingsProvider(...)
)

Handled settings constraints

The Settings screen enforces logical dependencies between options. If a parent setting is turned off, all of its dependent sub-settings become disabled and remain off. The main rules are:

1. Trading

• Parent: Trading from chart
• Children: Show active orders, Show open positions
• Behavior: When Trading from chart is off, both Show active orders and Show open positions are disabled and off.

2. Scale

2.1 Auto-scale price axis

• Children: Fit indicators, Fit orders, Fit positions
• Behavior: When Auto-scale price axis is on, these Fit settings can be toggled. When Auto-scale price axis is off, all Fit settings are disabled and off.

2.2 Lock scale

• When Lock scale is ON:
  • Auto-scale price axis: enabled but forced OFF
  • Fit indicators: disabled and OFF
  • Fit orders and Fit positions: disabled and OFF
  • Invert scale: enabled but forced OFF
  • Scale type: forced to Regular
• Additionally, Lock scale is unavailable (disabled) for non-regular scale types: Percent and Logarithmic.

3. Scale type behavior

The availability and default state of certain settings depend on the selected Scale type:

Scale Settings	Regular	Percent	Logarithmic
Auto-scale price axis	enable and on	disable and off	enable and on
Fit indicators	enable and on	disable and off	enable and on
Fit orders	enable and off	disable and off	enable and off
Fit positions	enable and off	disable and off	enable and off
Invert scale	enable and off	enable and off	enable and off
Lock scale	enable and off	disable and off	disable and off

4. Session alignment

• Align data with session start can be turned on only when Extended hours is off. If Extended hours is on, Align data with session start is disabled and off.

5. Events

• Parent: Events on chart
• Children: Dividends, Corporate actions, Earnings, etc.
• Behavior: When Events on chart is off, all sub-settings are disabled and off.

Best Practices

• Keep settings as the single source of truth; update it when the user changes a value.
• Use settingsIsChanged to accurately reflect whether a reset is necessary.
• Prefer explicit settingsContent when you need fine-grained control over visibility and order.
• Group related items into meaningful sections to improve scanability.