Class Settings

python/settings.py:31–585

:class:`Settings` provides a way to define and access settings in a hierarchical fashion. The value of a setting can \ be defined for each hierarchical level, where each level overrides the preceding level. The backing-store for setting \ values at each level is also configurable. This allows fo

from typing import List, Optional, Union

class Settings:
	"""
	:class:`Settings` provides a way to define and access settings in a hierarchical fashion. The value of a setting can \
	be defined for each hierarchical level, where each level overrides the preceding level. The backing-store for setting \
	values at each level is also configurable. This allows for ephemeral or platform-independent persistent settings storage \
	for components within Binary Ninja or consumers of the Binary Ninja API.

	Each :class:`Settings` instance has an ``instance_id`` which identifies a schema. The schema defines the settings contents  \
	and the way in which settings are retrieved and manipulated. A new :class:`Settings` instance defaults to using a value of *'default'* \
	for the ``instance_id``. The *'default'* settings schema defines all of the settings available for the active Binary Ninja components \
	which include at a minimum, the settings defined by the Binary Ninja core. The *'default'* schema may additionally define settings \
	for the UI and/or installed plugins. Extending existing schemas, or defining new ones is accomplished by calling :func:`register_group` \
	and :func:`register_setting` methods, or by deserializing an existing schema with :func:`deserialize_schema`.

	.. note:: All settings in the *'default'* settings schema are rendered with UI elements in the Settings View of Binary Ninja UI.

	Allowing setting overrides is an important feature and Binary Ninja accomplishes this by allowing one to override a setting at various \
	levels. The levels and their associated storage are shown in the following table. Default setting values are optional, and if specified, \
	saved in the schema itself.

		================= ========================== ============== ==============================================
		Setting Level     Settings Scope             Preference     Storage
		================= ========================== ============== ==============================================
		Default           SettingsDefaultScope       Lowest         Settings Schema
		User              SettingsUserScope          -              <User Directory>/settings.json
		Project           SettingsProjectScope       -              <Project Directory>/settings.json
		Resource          SettingsResourceScope      Highest        Raw BinaryView (Storage in BNDB)
		================= ========================== ============== ==============================================

	Settings are identified by a key, which is a string in the form of **'<group>.<name>'** or **'<group>.<subGroup>.<name>'**. Groups provide \
	a simple way to categorize settings. Sub-groups are optional and multiple sub-groups are allowed. When defining a settings group, the \
	:func:`register_group` method allows for specifying a UI friendly title for use in the Binary Ninja UI. Defining a new setting requires a \
	unique setting key and a JSON string of property, value pairs. The following table describes the available properties and values.

		===================   ======================================   ==================   ========   =======================================================================
		Property              JSON Data Type                           Prerequisite         Optional   {Allowed Values} and Notes
		===================   ======================================   ==================   ========   =======================================================================
		"title"               string                                   None                 No         Concise Setting Title
		"type"                string                                   None                 No         {"array", "boolean", "number", "string", "object"}
		"sorted"              boolean                                  "type" is "array"    Yes        Automatically sort list items (default is false)
		"isSerialized"        boolean                                  "type" is "string"   Yes        Treat the string as a serialized JSON object
		"enum"                array : {string}                         "type" is "string"   Yes        Enumeration definitions
		"enumDescriptions"    array : {string}                         "type" is "string"   Yes        Enumeration descriptions that match "enum" array
		"minValue"            number                                   "type" is "number"   Yes        Specify 0 to infer unsigned (default is signed)
		"maxValue"            number                                   "type" is "number"   Yes        Values less than or equal to INT_MAX result in a QSpinBox UI element
		"precision"           number                                   "type" is "number"   Yes        Specify precision for a QDoubleSpinBox
		"default"             {array, boolean, number, string, null}   None                 Yes        Specify optimal default value
		"aliases"             array : {string}                         None                 Yes        Array of deprecated setting key(s)
		"description"         string                                   None                 No         Detailed setting description
		"ignore"              array : {string}                         None                 Yes        {"SettingsUserScope", "SettingsProjectScope", "SettingsResourceScope"}
		"message"             string                                   None                 Yes        An optional message with additional emphasis
		"readOnly"            boolean                                  None                 Yes        Only enforced by UI elements
		"optional"            boolean                                  None                 Yes        Indicates setting can be null
		"hidden"              bool                                     "type" is "string"   Yes        Indicates the UI should conceal the content. The "ignore" property is required to specify the applicable storage scopes
		"requiresRestart      boolean                                  None                 Yes        Enable restart notification in the UI upon change
		"uiSelectionAction"   string                                   "type" is "string"   Yes        {"file", "directory", <Registered UIAction Name>} Informs the UI to add a button to open a selection dialog or run a registered UIAction
		===================   ======================================   ==================   ========   =======================================================================