Settings Repository

• Repository for storing information about the installed chart configuration and providing it in aggregated form (for passing it into the chart).
• Contains business logic with rules for enabling/disabling interdependent menu items.
• Contains a list of time zones.
• Items available on the configuration settings screen are configured within the repository.

Repository interface:

/**
* Repository for storing chart settings data.
*
* Default chart settings are set in the implementation of this interface.
*
* Methods are used when interacting with the settings screen elements.
*
* Implementation of this class is mandatory for the library to function. It is passed to [com.devexperts.dxcharts.lib.domain.DxChartsConfig].
*
* Standard implementation is [com.devexperts.dxcharts.lib.data.repo.default_repos.DefaultSettingsRepository].
*/
interface SettingsRepository {
/**
 * Method to set the value of a settings item with Boolean type by passing a value.
 */
fun toggleItem(settingsItem: SettingsScreenItem, value: Boolean)
/**
 * Method to set the value of a settings item with Boolean type by toggling the value.
 */
fun toggleItem(settingsItem: SettingsScreenItem)
/**
 * Method to set the value of a settings item with Color type.
 */
fun changeColor(settingsItem: SettingsScreenItem, value: Color)
/**
 * Method to set the value of a settings item with [HasStringRes] type (dropdown list).
 */
fun selectDropdownItem(settingsItem: SettingsScreenItem, value: HasStringRes)
/**
 * Method to retrieve the complete chart configuration considering all settings.
 */
fun getConfiguration(): ChartConfigurationData
/**
 * Gets the currently selected time zone.
 */
fun getSelectedTimezone(): Timezones.TimeZoneItem
/**
 * Sets the time zone for the chart.
 */
fun setSelectedTimezone(timeZoneItem: Timezones.TimeZoneItem)
/**
 * Defines whether the default theme is dark or light based on the provided flag.
 *
 * @param isSystemDefaultThemeIsDark `true` if the default theme should be dark, `false` if it should be light.
 */
fun defineSystemSelectedTheme(isSystemDefaultThemeIsDark: Boolean)
/**
 * Applies the default chart configuration on the first run or when resetting all settings to their default values.
 *
 * @param configuration The default [ChartConfigurationData] to be applied.
 */
fun setDefaultConfiguration(configuration: ChartConfigurationData)
/**
 * Gets the default chart settings set on the first run of the library or when resetting all settings.
 */
fun getDefaultConfiguration(): ChartConfigurationData
/**
 * Sets the list of available settings items.
 */
fun setAvailableSettingsItems(items: List<SettingsScreenItem>)
/**
 * Gets the list of available settings items.
 */
fun availableSettingsItems(): List<SettingsScreenItem>
/**
 * Gets the list of available time zones.
 */
fun availableTimezones(): List<Timezones.TimeZoneItem>
/**
 * Returns the collection of settings items that are disabled by default.
 */
fun getDefaultDisabledItems(): Collection<SettingsScreenItem>
/**
 * Sets the collection of settings items to be disabled by default.
 *
 * @param items The collection of [SettingsScreenItem] that should be disabled by default.
 */
fun setDefaultDisabledItems(items: Collection<SettingsScreenItem>)
/**
 * Gets the list of settings items that should be disabled.
 */
fun disabledSettingsItems(): Collection<SettingsScreenItem>
/**
 * Notifies that the chart aggregation has changed, leading to changes in some settings items.
 */
fun aggregationChanged(aggregation: Aggregation)
/**
 * Returns whether the trading buttons feature is enabled.
 */
fun isTradingButtonsFeatureEnabled(): Boolean
/**
 * Enables or disables the trading buttons feature.
 *
 * @param isEnabled true to enable the feature, false to disable it.
 */
fun setTradingButtonsFeatureEnabled(isEnabled: Boolean)
/**
 * Method to set the default chart settings.
 */
fun resetDefaultConfig()
}

Classes used in the repository:

• com.devexperts.dxcharts.lib.domain.SettingsScreenItem - an item in the settings list, listing all available settings options inside:

/**
 * Class for storing data about a settings item.
 *
 * @property submenu The submenu [SettingsSubmenu] where the item is located.
 * @property stringRes String resource with the name of the item for display in the UI.
 * @property type The type of settings item [SettingsItemType].
 */
enum class SettingsScreenItem(
    val submenu: SettingsSubmenu,
    @StringRes val stringRes: Int,
    val type: SettingsItemType,
) {
    CHART_TYPE(
        submenu = SettingsSubmenu.GENERAL,
        stringRes = R.string.dxcharts_settings_chart_type,
        type = SettingsItemType.Dropdown,
    ),
    HIGH_AND_LOW(
        submenu = SettingsSubmenu.GENERAL,
        stringRes = R.string.dxcharts_settings_high_and_low,
        type = SettingsItemType.Toggle
    ),
    VERTICAL_GRID(
        submenu = SettingsSubmenu.GENERAL,
        stringRes = R.string.dxcharts_settings_vertical_grid,
        type = SettingsItemType.Toggle
    ),
    HORIZONTAL_GRID(
        submenu = SettingsSubmenu.GENERAL,
        stringRes = R.string.dxcharts_settings_horizontal_grid,
        type = SettingsItemType.Toggle
    ),
    CANDLE_WICKS(
        submenu = SettingsSubmenu.GENERAL,
        stringRes = R.string.dxcharts_settings_candle_wicks,
        type = SettingsItemType.Toggle
    ),
    WATERMARK(
        submenu = SettingsSubmenu.GENERAL,
        stringRes = R.string.dxcharts_settings_watermark,
        type = SettingsItemType.Toggle
    ),
    TIMEZONE(
        submenu = SettingsSubmenu.GENERAL,
        stringRes = R.string.dxcharts_timezones_title,
        type = SettingsItemType.Timezone
    ),
    BULLISH_BODY(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_bullish_body,
        type = SettingsItemType.Color
    ),
    BEARISH_BODY(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_bearish_body,
        type = SettingsItemType.Color
    ),
    DOJI(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_doji,
        type = SettingsItemType.Color
    ),
    BULLISH_BORDER(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_bullish_border,
        type = SettingsItemType.Color
    ),
    BEARISH_BORDER(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_bearish_border,
        type = SettingsItemType.Color
    ),
    UP(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_up,
        type = SettingsItemType.Color
    ),
    DOWN(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_down,
        type = SettingsItemType.Color
    ),
    NONE(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_none,
        type = SettingsItemType.Color
    ),
    AREA(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_area,
        type = SettingsItemType.Color
    ),
    SCATTER(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_scatter,
        type = SettingsItemType.Color
    ),
    VOLUME_BULLISH(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_volume_bullish,
        type = SettingsItemType.Color
    ),
    VOLUME_BEARISH(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_volume_bearish,
        type = SettingsItemType.Color
    ),
    VOLUME_DOJI(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_volume_doji,
        type = SettingsItemType.Color
    ),
    BACKGROUND(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_background,
        type = SettingsItemType.Color
    ),
    WATERMARK_COLOR(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_watermark_color,
        type = SettingsItemType.Color
    ),
    GRID(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_grid,
        type = SettingsItemType.Color
    ),
    VALUES_ON_SCALES(
        submenu = SettingsSubmenu.COLORS,
        stringRes = R.string.dxcharts_settings_values_on_scales,
        type = SettingsItemType.Color
    ),
    TRADING_FROM_CHART(
        submenu = SettingsSubmenu.TRADING,
        stringRes = R.string.dxcharts_settings_trading_from_chart,
        type = SettingsItemType.Toggle
    ),
    SHOW_ACTIVE_ORDERS(
        submenu = SettingsSubmenu.TRADING,
        stringRes = R.string.dxcharts_settings_show_active_orders,
        type = SettingsItemType.Toggle
    ),
    SHOW_OPEN_POSITIONS(
        submenu = SettingsSubmenu.TRADING,
        stringRes = R.string.dxcharts_settings_show_open_positions,
        type = SettingsItemType.Toggle
    ),
    AUTO_SCALE_PRICE_AXIS(
        submenu = SettingsSubmenu.SCALES,
        stringRes = R.string.dxcharts_settings_auto_scale_price_axis,
        type = SettingsItemType.Toggle
    ),
    FIT_STUDIES(
        submenu = SettingsSubmenu.SCALES,
        stringRes = R.string.dxcharts_settings_fit_studies,
        type = SettingsItemType.Toggle
    ),
    FIT_ORDERS(
        submenu = SettingsSubmenu.SCALES,
        stringRes = R.string.dxcharts_settings_fit_orders,
        type = SettingsItemType.Toggle
    ),
    FIT_POSITIONS(
        submenu = SettingsSubmenu.SCALES,
        stringRes = R.string.dxcharts_settings_fit_positions,
        type = SettingsItemType.Toggle
    ),
    INVERT_SCALE(
        submenu = SettingsSubmenu.SCALES,
        stringRes = R.string.dxcharts_settings_invert_scale,
        type = SettingsItemType.Toggle
    ),
    LOCK_SCALE(
        submenu = SettingsSubmenu.SCALES,
        stringRes = R.string.dxcharts_settings_lock_scale,
        type = SettingsItemType.Toggle
    ),
    SCALE_TYPE(
        submenu = SettingsSubmenu.SCALES,
        stringRes = R.string.dxcharts_settings_scale_type,
        type = SettingsItemType.Dropdown
    ),
    SESSION_BREAKS(
        submenu = SettingsSubmenu.DATA,
        stringRes = R.string.dxcharts_settings_session_breaks,
        type = SettingsItemType.Toggle
    ),
    EXTENDED_HOURS(
        submenu = SettingsSubmenu.DATA,
        stringRes = R.string.dxcharts_settings_extended_hours,
        type = SettingsItemType.Toggle
    ),
    ALIGN_DATA_WITH_SESSION_START(
        submenu = SettingsSubmenu.DATA,
        stringRes = R.string.dxcharts_settings_align_data_with_session_start,
        type = SettingsItemType.Toggle
    ),
    PRICE_TYPE(
        submenu = SettingsSubmenu.DATA,
        stringRes = R.string.dxcharts_settings_price_type,
        type = SettingsItemType.Dropdown
    ),
    VOLUME(
        submenu = SettingsSubmenu.DATA,
        stringRes = R.string.dxcharts_settings_volume,
        type = SettingsItemType.Toggle
    ),
    EVENTS_ON_CHART(
        submenu = SettingsSubmenu.EVENTS,
        stringRes = R.string.dxcharts_settings_events_on_chart,
        type = SettingsItemType.Toggle
    ),
    DIVIDENDS(
        submenu = SettingsSubmenu.EVENTS,
        stringRes = R.string.dxcharts_settings_dividends,
        type = SettingsItemType.Toggle
    ),
    SPLITS_AND_CONSOLIDATIONS(
        submenu = SettingsSubmenu.EVENTS,
        stringRes = R.string.dxcharts_settings_splits_and_consolidations,
        type = SettingsItemType.Toggle
    ),
    EARNINGS_AND_ESTIMATES(
        submenu = SettingsSubmenu.EVENTS,
        stringRes = R.string.dxcharts_settings_earnings_and_estimates,
        type = SettingsItemType.Toggle
    ),
    CONFERENCE_CALLS(
        submenu = SettingsSubmenu.EVENTS,
        stringRes = R.string.dxcharts_settings_conference_calls,
        type = SettingsItemType.Toggle
    ),
    NEWS(
        submenu = SettingsSubmenu.EVENTS,
        stringRes = R.string.dxcharts_settings_news,
        type = SettingsItemType.Toggle
    );
    /**
     * Enumeration of available settings submenus.
     * Used for grouping settings items in the UI.
     *
     * @property stringRes String resource with the name of the submenu for display in the UI.
     */
    enum class SettingsSubmenu(@StringRes val stringRes: Int) {
        GENERAL(R.string.dxcharts_settings_submenu_general),
        COLORS(R.string.dxcharts_settings_submenu_colors),
        TRADING(R.string.dxcharts_settings_submenu_trading),
        SCALES(R.string.dxcharts_settings_submenu_scales),
        DATA(R.string.dxcharts_settings_submenu_data),
        EVENTS(R.string.dxcharts_settings_submenu_events),
    }
    /**
     * Enumeration of settings item types.
     * Used to determine the type of settings item in the UI.
     *
     * - [Dropdown] - dropdown list with selectable options
     * - [Color] - color picker
     * - [Toggle] - on/off toggle
     * - [Timezone] - timezone selection
     */
    sealed class SettingsItemType {
        data object Dropdown : SettingsItemType()
        data object Color : SettingsItemType()
        data object Toggle : SettingsItemType()
        data object Timezone : SettingsItemType()
    }
    /**
     * @property dropdownItems Options for selection in dropdown lists within settings items.
     */
    companion object {
        val dropdownItems = mapOf<SettingsScreenItem, List<HasStringRes>>(
            CHART_TYPE to ChartType.entries,
            SCALE_TYPE to ScaleType.entries,
            PRICE_TYPE to PriceType.entries,
            THEME to Theme.entries,
        )
    }

• com.devexperts.dxcharts.lib.domain.HasStringRes - interface for settings items with a dropdown list displayed on the settings screen:

  • com.devexperts.dxcharts.lib.domain.ChartType
  • com.devexperts.dxcharts.lib.domain.PriceType
  • com.devexperts.dxcharts.lib.domain.ScaleType

/**
 * Interface for data displayed on the settings screen in items with a dropdown list.
 *
 * Classes implementing this interface:
 * - [com.devexperts.dxcharts.lib.domain.ChartType]
 * - [com.devexperts.dxcharts.lib.domain.PriceType]
 * - [com.devexperts.dxcharts.lib.domain.ScaleType]
 */
interface HasStringRes {
    /**
     * Method to get StringRes with the item name
     */
    @StringRes
    fun getStringRes(): Int
}

• com.devexperts.dxcharts.lib.domain.ChartConfigurationData - data class containing all parameters for chart configuration

/**
 * Data class containing all parameters for chart configuration.
 *
 * Management parameters is happening from the settings screen.
 *
 * The full chart configuration is obtained from [com.devexperts.dxcharts.lib.data.repo.SettingsRepository].
 *
 * @param general General settings
 * @param colors Chart and data colors
 * @param trading Parameters related to trading on the chart
 * @param scales Chart scaling and axis control
 * @param data Data display on the chart
 * @param events Event display on the chart
 * @param unchangeableColors Colors that cannot be changed from the settings screen, set by the developer
 */
data class ChartConfigurationData(
    val general: General,
    val colors: Colors,
    val trading: Trading,
    val scales: Scales,
    val data: Data,
    val events: Events,
    val unchangeableColors: UnchangeableColors
) {
    data class General(
        val chartType: ChartType,
        val highAndLow: Boolean,
        val verticalGrid: Boolean,
        val horizontalGrid: Boolean,
        val candleWicks: Boolean,
        val watermark: Boolean,
        val timezone: Timezones.TimeZoneItem
    )
    data class Colors(
        val bullish: Color,
        val bearish: Color,
        val doji: Color,
        val bullishBorder: Color,
        val bearishBorder: Color,
        val area: Color,
        val scatter: Color,
        val volumeBullish: Color,
        val volumeBearish: Color,
        val volumeDoji: Color,
        val background: Color,
        val watermark: Color,
        val grid: Color,
        val valuesOnScales: Color,
        val highLowValues: Color,
        val paneResizer: Color,
        val crosstool: Color,
        val drawingsText: Color,
    )
    data class Trading(
        val tradingFromChart: Boolean,
        val showActiveOrders: Boolean,
        val showOpenPositions: Boolean
    )
    data class Scales(
        val autoScale: Boolean,
        val fitStudies: Boolean,
        val fitOrders: Boolean,
        val fitPositions: Boolean,
        val invertScale: Boolean,
        val lockScale: Boolean,
        val scaleType: ScaleType
    )
    data class Data(
        val sessionBreaks: Boolean,
        val extendedHours: Boolean,
        val alignDataWithSessionStart: Boolean,
        val priceType: PriceType,
        val volume: Boolean,
    )
    data class Events(
        val eventsOnChart: Boolean,
        val dividends: Boolean,
        val splitsAndConsolidations: Boolean,
        val earningsAndEstimates: Boolean,
        val conferenceCalls: Boolean,
        val news: Boolean
    )
    data class UnchangeableColors(
        val highlights: Highlights
    )
    companion object {
        val EMPTY = ChartConfigurationData(
            general = General(
                chartType = ChartType.CANDLE,
                highAndLow = false,
                verticalGrid = false,
                horizontalGrid = false,
                candleWicks = false,
                watermark = false,
                timezone = Timezones.TimeZoneItem(
                    name = "UTC",
                    fullName = "UTC",
                    offset = 0,
                )
            ),
            colors = Colors(
                bullish = Color(0xFF000000),
                bearish = Color(0xFF000000),
                doji = Color(0xFF000000),
                bullishBorder = Color(0xFF000000),
                bearishBorder = Color(0xFF000000),
                area = Color(0xFF000000),
                scatter = Color(0xFF000000),
                volumeBullish = Color(0xFF000000),
                volumeBearish = Color(0xFF000000),
                volumeDoji = Color(0xFF000000),
                background = Color(0xFF000000),
                watermark = Color(0xFF000000),
                grid = Color(0xFF000000),
                valuesOnScales = Color(0xFF000000),
                highLowValues = Color(0xFF000000),
                paneResizer = Color(0xFF000000),
                crosstool = Color(0xFF000000),
                drawingsText = Color(0xFF000000),
            ),
            trading = Trading(
                tradingFromChart = false,
                showActiveOrders = false,
                showOpenPositions = false,
            ),
            scales = Scales(
                autoScale = false,
                fitStudies = false,
                fitOrders = false,
                fitPositions = false,
                invertScale = false,
                lockScale = false,
                scaleType = ScaleType.REGULAR,
            ),
            data = Data(
                sessionBreaks = false,
                extendedHours = false,
                alignDataWithSessionStart = false,
                priceType = PriceType.LAST,
                volume = false,
            ),
            events = Events(
                eventsOnChart = false,
                dividends = false,
                splitsAndConsolidations = false,
                earningsAndEstimates = false,
                conferenceCalls = false,
                news = false,
            ),
            unchangeableColors = UnchangeableColors(
                highlights = Highlights(
                    afterMarket = Highlights.Highlight(
                        background = "",
                        border = "",
                        label = ""
                    ),
                    preMarket = Highlights.Highlight(
                        background = "",
                        border = "",
                        label = ""
                    ),
                    regular = Highlights.Highlight(
                        background = "",
                        border = "",
                        label = ""
                    ),
                    noTrading = Highlights.Highlight(
                        background = "",
                        border = "",
                        label = ""
                    ),
                )
            )
        )
    }
}

• com.devexperts.dxcharts.lib.data.model.Timezones.TimeZoneItem - class used to store information about a timezone.

object Timezones {
    /**
     * Constant representing the UTC timezone used in the timezone list.
     */
    val UTC = TimeZoneItem("UTC", "Etc/UTC")
    /**
     * Constant representing the Exchange timezone used in the timezone list.
     */
    val Exchange = TimeZoneItem("Exchange", "Exchange")
    /**
     * Data class used to store information about a timezone.
     *
     * @param name The display name of the timezone in the timezone list (e.g., Buenos Aires).
     * @param fullName The full name of the timezone (e.g., America/Argentina/Buenos_Aires).
     * @param offset The timezone offset relative to UTC in seconds.
     */
    data class TimeZoneItem(
        val name: String,
        val fullName: String,
        val offset: Int? = null
    )
}

Link to the default implementation of the repository - https://stash.in.devexperts.com/projects/DXCHARTS/repos/dxcharts-android/browse/dxcharts_lib/src/main/java/com/devexperts/dxcharts/lib/data/repo/default_repos/DefaultSettingsRepository.kt.

The documentation of the rules for switching items in the settings list is also located there:

• Events on Chart
• Trading from Chart
• Auto scale price axis
• Extended hours
• Scale Type

List of the names of time zones used in the library - https://stash.in.devexperts.com/projects/DXCHARTS/repos/dxcharts-android/browse/dxcharts_lib/src/main/java/com/devexperts/dxcharts/lib/data/implementation/DefaultSettingsRepository.kt#730.

Exchanging settings between mobile and web versions

If you want to exchange settings from mobile version to web version of charts, here you can find the following classes and methods for converting settings between mobile and web versions:

• com.devexperts.dxcharts.lib.domain.ChartConfigurationDataWeb - data class containing all parameters for chart configuration in the web version
• ChartConfigurationData.toWeb() - method for converting the mobile version settings to the web version settings
• ChartConfigurationDataWeb.fromWeb() - method for converting the web version settings to the mobile version settings