Creating Themes

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. 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 to start with to avoid lots of "missing required color" errors.

Theme File Structure

Theme files have the following top-level structure:

{
  "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 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 in Qt CSS syntax via the styleSheet key, like so:

{
  "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:

{
  "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.

{
  "palette": {
    "Window": "...",
    "WindowText": "...",
    "Base": "...",
    "AlternateBase": "...",
    "ToolTipBase": "...",
    "ToolTipText": "...",
    "Text": "...",
    "Button": "...",
    "ButtonText": "...",
    "BrightText": "...",
    "Link": "...",
    "Highlight": "...",
    "HighlightedText": "...",
    "Light": "..."
  }
}

See Qt's documentation 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, the theming engine provides the ability to blend colors by passing an array of blending functions and arguments in prefix notation in place of a color:

{
  "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:

{
  "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

1. addressColor - Used to highlight memory addresses, e.g. 0x100003c5b
2. registerColor - Used to highlight register names in code views, e.g. rax
3. numberColor - Used to highlight number literals in code view, e.g. 0xf0
4. codeSymbolColor - Used to highlight local function names in code views, e.g. sub_100003c50
5. dataSymbolColor - Used to highlight data symbols in code views, e.g. data_100003e2c
6. stackVariableColor - Used to highlight stack variables in code views, e.g var_8
7. importColor - Used to highlight imported function names in code views, e.g. printf
8. stringColor - Used to highlight string literals in code views, e.g. "Hello, world!"
9. typeNameColor - Used to highlight user-defined type names in code views, e.g. my_struct
10. fieldNameColor - Used to highlight structure member names in code views
11. keywordColor - Used to highlight keywords in code views, e.g. for in HLIL
12. uncertainColor - Used to highlight uncertain data in code views, such as variable types with low confidence
13. annotationColor - Used to highlight annotations, such as hints and comments
14. opcodeColor - Used to highlight instruction opcodes in code views

Graph View

1. graphBackgroundDarkColor - Used as the bottom-right gradient stop in the graph view background

2. graphBackgroundLightColor - Used as the upper-left gradient stop in the graph view background

   For a flat background, set both colors to the same value, like they are in the image above. For a diagonal gradient, assign a unique color to each.
   
   

3. graphNodeDarkColor - Used as the bottom gradient stop in graph node backgrounds

4. graphNodeLightColor - Used as the upper gradient stop in graph node backgrounds

5. 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.
   
   

6. trueBranchColor - Used to color branches taken when a comparison is true

7. falseBranchColor - Used to color branches taken when a comparison is false
8. unconditionalBranchColor - Used to color branches that are always taken
9. altTrueBranchColor - Same as trueBranchColor, but used when color blind mode is enabled
10. altFalseBranchColor - Same as falseBranchColor, but used when color blind mode is enabled
11. 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

1. linearDisassemblyFunctionHeaderColor - Used as the background for function headers in linear view
2. linearDisassemblyBlockColor - Used as the background for function bodies in linear view
3. linearDisassemblyNoteColor - Used as the background color for note blocks in linear view, such as the info block found at the start of linear view
4. linearDisassemblySeparatorColor - Used as the separator/border color between major elements in linear view

Hex View

1. backgroundHighlightDarkColor - Used as the background color for bytes of value 0x00

2. backgroundHighlightLightColor - Used as the background color for bytes of value 0xFF

   Each byte in hex view is given a background color based on its value. Values in between 0x00 and 0xFF will use a color interpolated between the two colors above.
   
   

3. alphanumericHighlightColor - Used to highlight alphanumeric characters in hex views, takes precedence over printableHighlightColor

4. printableHighlightColor - Used to highlight printable characters in hex views

Script Console

1. scriptConsoleOutputColor - Used to color normal output in the console
2. scriptConsoleWarningColor - Used to color warnings in the console
3. scriptConsoleErrorColor - Used to color errors in the console
4. scriptConsoleEchoColor - Used to color user input in the console

Highlighting

1. blackStandardHighlightColor
2. blueStandardHighlightColor
3. cyanStandardHighlightColor
4. greenStandardHighlightColor
5. magentaStandardHighlightColor
6. orangeStandardHighlightColor
7. redStandardHighlightColor
8. whiteStandardHighlightColor
9. yellowStandardHighlightColor