Docs: Added theming guide

1 files changed, 281 insertions, 0 deletions

diff --git a/docs/dev/themes.md b/docs/dev/themes.md
new file mode 100644
index 00000000..f0c44bfc
--- /dev/null
+++ b/docs/dev/themes.md
@@ -0,0 +1,281 @@
+## Creating Themes
+
+User themes are loaded from JSON files (with the `.bntheme` extension) found in
+the `themes` or `community-themes` subdirectories of your [user
+folder](/getting-started.html#user-folder). The full path to these folders
+effectively being the following:
+
+- macOS: `~/Library/Application Support/Binary Ninja/{themes,community-themes}`
+- Windows: `%APPDATA%\Binary Ninja\{themes,community-themes}`
+- Linux: `~/.binaryninja/{themes,community-themes}`
+
+
+
+To get started, create a new `.bntheme` file in the themes folder for your
+platform. You may want to copy one of the [example
+themes](https://github.com/Vector35/binaryninja-api/tree/dev/themes) to start
+with to avoid lots of "missing required color" errors.
+
+### Theme File Structure
+
+Theme files have the following top-level structure:
+
+```json
+{
+  "name": "Example Theme",
+  "style": "Fusion",
+  "styleSheet": "...",
+  "colors": { ... },
+  "palette": { ... },
+  "disabledPalette": { ... },
+  "theme-colors": { ... }
+}
+```
+
+A description of each of these keys is as follows.
+
+#### Name
+
+The `name` key controls the theme's display name in the UI. Be sure that this is
+unique, as there cannot be multiple themes with the same name.
+
+#### Style
+
+The `style` key specifies which [Qt
+style](https://doc.qt.io/qt-6/qstyle.html#details) to use for the UI
+controls. This key should almost always be set to `"Fusion"`.
+
+#### Stylesheet
+
+Additional styling can be done by provinding a
+[stylesheet](https://doc.qt.io/qt-6/stylesheet-reference.html) in Qt CSS syntax
+via the `styleSheet` key, like so:
+
+```json
+{
+  "styleSheet": "QWidget { border-radius: 0; }"
+}
+```
+
+#### Colors
+
+The `colors` keys allows you (the theme author) to define color aliases to be
+used throughout the rest of the theme file as a shorthand for specific
+colors. For example, the following sets up two color aliases, `red` and `blue`:
+
+```json
+{
+  "colors": {
+    "red": "#ff0000",
+    "blue": [0, 0, 255]
+  }
+}
+```
+
+Notice that colors can be specified as hex strings or as a `[R, G, B]` array.
+
+#### Palette
+
+The `palette` key is the primary interface for theming Qt UI elements and
+enables customization of the main `QPalette` color roles.
+
+```json
+{
+  "palette": {
+    "Window": "...",
+    "WindowText": "...",
+    "Base": "...",
+    "AlternateBase": "...",
+    "ToolTipBase": "...",
+    "ToolTipText": "...",
+    "Text": "...",
+    "Button": "...",
+    "ButtonText": "...",
+    "BrightText": "...",
+    "Link": "...",
+    "Highlight": "...",
+    "HighlightedText": "...",
+    "Light": "..."
+  }
+}
+```
+
+See [Qt's documentation](https://doc.qt.io/qt-5/qpalette.html#ColorRole-enum)
+for more info about which each color role does.
+
+#### Disabled Palette
+
+The `disabledPalette` key is similar to the `palette` key, except it allow
+configuration of the same colors for use in disabled controls. While not
+required, providing entries for the `Button`, `ButtonText`, `Text`, and
+`WindowText` roles is highly recommended.
+
+### Theme Colors
+
+The rest of a theme's settings are in the `theme-colors` key, where colors for
+different disassembly tokens, custom UI elements, etc. are defined. See the next
+section for a list of all the customizable options.
+
+### Blending Functions
+
+In addition to [color aliases](#colors), the theming engine provides the ability
+to blend colors by passing an array of blending functions and arguments in
+[prefix notation](https://en.wikipedia.org/wiki/Polish_notation) in place of a
+color:
+
+```json
+{
+  "colors": {
+    "red": "#ff0000",
+	"blue": [0, 0, 255],
+	"purple": ["+", "red", "blue"]
+    "slightPink": ["~", "white", "red", 20],
+    "quitePink":  ["~", "white", "red", 200],
+  }
+}
+```
+
+In the example above, the **average function** (`+`) is used to create a
+`purple` color that is the avarge of `red` and `blue`. Colors can also be mixed
+in a weighted manner, using the **mix function** (`~`), which is used above to
+create the `slightPink` and `quitePink` colors by mixing `red` into `white`.
+These functions can also be chained together like in the example below, which
+mixes some `red` into `white` then averages the result with `yellow`:
+
+```json
+{
+  "colors": {
+    "red": "#ff0000",
+	"white": [255, 255, 255],
+	"yellow": "#ffff00",
+	"slightPinkYellow": ["+", "~", "white", "red", 20, "yellow"],
+  }
+}
+```
+
+### Theme Colors
+
+All of the custom colors that can be adjusted by themes (and how they are used)
+are described below.
+
+#### Tokens
+
+The following colors are used to highlight tokens in code views:
+
+- `addressColor` - Used to highlight memory addresses, e.g. `0x100003c5b`
+- `registerColor` - Used to highlight register names in code views, e.g. `rax`
+- `numberColor` - Used to highlight number literals in code view, e.g. `0xf0`
+- `codeSymbolColor` - Used to highlight local function names in code views, e.g. `sub_100003c50`
+- `dataSymbolColor` - Used to highlight data symbols in code views, e.g. `data_100003e2c`
+- `stackVariableColor` - Used to highlight stack variables in code views, e.g `var_8`
+- `importColor` - Used to highlight imported function names in code views, e.g. `printf`
+- `stringColor` - Used to highlight string literals in code views, e.g. `"Hello, world!"`
+- `typeNameColor` - Used to highlight user-defined type names in code views, e.g. `my_struct`
+- `fieldNameColor` - Used to highlight structure member names in code views
+- `keywordColor` - Used to highlight keywords in code views, e.g. `for` in HLIL
+- `uncertainColor` - Used to highlight uncertain data in code views, such as variable types with low confidence
+- `annotationColor` - Used to highlight annotations, such as hints and comments
+- `opcodeColor` - Used to highlight instruction opcodes in code views
+
+#### Graph View
+
+##### Background
+
+The graph view background is controlled by the following two colors:
+
+- `graphBackgroundDarkColor` - Used as the bottom-right gradient stop in the
+  graph view background
+- `graphBackgroundLightColor` - Used as the upper-left gradient stop in the
+  graph view background
+
+For a flat background, set both colors to the same value. For a diagonal
+gradient, assign a unique color to each.
+
+##### Nodes
+
+Node appearance can be configured with the following colors:
+
+- `graphNodeDarkColor` - Used as the bottom gradient stop in graph node backgrounds
+- `graphNodeLightColor` - Used as the upper gradient stop in graph node backgrounds
+- `graphNodeOutlineColor` - Used to color the border of graph nodes
+
+Similar to the graph background, a gradient appearance can be achieved by using
+unique colors for both background colors
+
+##### Branches
+
+The color of branches between nodes can be adjusted with the following colors:
+
+- `trueBranchColor` - Used to color branches taken when a comparison is true
+- `falseBranchColor` - Used to color branches taken when a comparison is false
+- `unconditionalBranchColor` - Used to color branches that are always taken
+- `altTrueBranchColor` - Same as `trueBranchColor`, but used when color blind
+  mode is enabled
+- `altFalseBranchColor` - Same as `falseBranchColor`, but used when color blind
+  mode is enabled
+- `altUnconditionalBranchColor` - Same as `unconditionalBranchColor`, but used
+  when color blind mode is enabled
+
+Don't forget about the alternate colors for users with color blind mode enabled!
+
+#### Linear View
+
+The appearance of linear view can be tweaked via the following colors:
+
+- `linearDisassemblyFunctionHeaderColor` - Used as the background for function
+  headers in linear view
+- `linearDisassemblyBlockColor` - Used as the background for function bodies in
+  linear view
+- `linearDisassemblyNoteColor` - Used as the background color for note blocks in
+  linear view, such as the info block found at the start of linear view
+- `linearDisassemblySeparatorColor` - Used as the separator/border color between
+  major elements in linear view
+
+#### Hex View
+
+##### Foreground
+
+Byte values corresponding to alphanumeric and printable ASCII values are given
+special highlighting controlled by the folowing colors:
+
+- `alphanumericHighlightColor` - Used to highlight alphanumeric characters in
+  hex views, takes precedence over printableHighlightColor
+- `printableHighlightColor` - Used to highlight printable characters in hex views
+
+##### Background
+
+Each byte in hex view is given a background color based on its value. The
+following two colors control the color of each extreme:
+
+- `backgroundHighlightDarkColor` - Used as the background color for bytes of
+  value `0x00`
+- `backgroundHighlightLightColor` - Used as the background color for bytes of
+  value `0xFF`
+
+Values in between `0x00` and `0xFF` will use a color interpolated between the
+two colors above.
+
+#### Script Console
+
+Different types of text inside the scripting console can be themed via the
+following colors:
+
+- `scriptConsoleOutputColor` - Used to color normal output in the console
+- `scriptConsoleWarningColor` - Used to color warnings in the console
+- `scriptConsoleErrorColor` - Used to color errors in the console
+- `scriptConsoleEchoColor` - Used to color user input in the console
+
+#### Highlighting
+
+The following colors are used when the user wishes to highlight an instruction
+or graph node:
+
+- `blueStandardHighlightColor`
+- `greenStandardHighlightColor`
+- `cyanStandardHighlightColor`
+- `redStandardHighlightColor`
+- `magentaStandardHighlightColor`
+- `yellowStandardHighlightColor`
+- `orangeStandardHighlightColor`
+- `whiteStandardHighlightColor`
+- `blackStandardHighlightColor`