Theme Guide

Pygame UI Elements can pretty much all be themed in some manner. A theme is created by loading a theme file in JSON format. To load one, simply pass the path to the theme file into the UIManager when you create it. Like so:

1
 manager = pygame_gui.UIManager((800, 600), 'theme.json')

You can also theme your elements ‘on the fly’, while your pygame application is running. Just edit your theme file and save it, and you should see the UI update to reflect your changes. This is particularly helpful when trying to fiddle with colours, or visualise what the theming parameters do. You can also turn off live theming if you want to save a few CPU cycles by setting that option when you create your UI manager.

The most basic theming you can do is to set the default colours for the UI, which are the colours used if no more element specific colour is specified in the theme.

To set these you need to create a ‘defaults’ block in your JSON theme file, and a ‘colours’ sub-block within that. Then within the colours block you can start to set individual colours by their IDs. It should look something like this:

theme.json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
 {
     "defaults":
     {
         "colours":
         {
             "normal_bg":"#45494e",
             "hovered_bg":"#35393e",
             "disabled_bg":"#25292e",
             "selected_bg":"#193754",
             "dark_bg":"#15191e",
             "normal_text":"#c5cbd8",
             "hovered_text":"#FFFFFF",
             "selected_text":"#FFFFFF",
             "disabled_text":"#6d736f",
             "link_text": "#0000EE",
             "link_hover": "#2020FF",
             "link_selected": "#551A8B",
             "text_shadow": "#777777",
             "normal_border": "#DDDDDD",
             "hovered_border": "#B0B0B0",
             "disabled_border": "#808080",
             "selected_border": "#8080B0",
             "active_border": "#8080B0",
             "filled_bar":"#f4251b",
             "unfilled_bar":"#CCCCCC"
         }
     }
 }

Of course, colours are not just colours - they can also be gradients, which have a very similar syntax. Like so:

theme.json
1
2
3
4
5
6
7
8
9
{
     "defaults":
     {
         "colours":
         {
            "normal_bg":"#45494e,#65696e,90"
         }
     }
}

Where the first two (or three) parameters indicate the colours used in the gradient, separated by commas, and the last parameter indicates the direction of the gradient as an angle in degrees (from 0 to 360).

To add theming for specific UI elements you then need to add additional blocks at the same level as the ‘defaults’ block. These blocks require an ID that references which elements that they apply to. IDs have a hierarchy allowing us to reference elements that are part of other elements. To address sub-elements we join them with a full stop For example, if we wanted to theme the vertical scroll bars that are part of a text box we could use ‘text_box.vertical_scroll_bar’ as the theme ID.

The parts of a theming block ID can be made up either of their element IDs or an ‘object ID’ which is passed to the element when it is created. More specific theme IDs composed of more object IDs are preferred to ones of entirely element IDs where two or more IDs would apply to an element.

There are four general categories of theming which each have their own sub-blocks under the theme block IDs:

  • ‘colours’
  • ‘font’
  • ‘misc’
  • ‘images’

Here’s an example of adding a ‘button’ theme block to the JSON file above:

theme.json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
 {
     "defaults":
     {
         "colours":
         {
             "normal_bg":"#45494e",
             "hovered_bg":"#35393e",
             "disabled_bg":"#25292e",
             "selected_bg":"#193754",
             "dark_bg":"#15191e",
             "normal_text":"#c5cbd8",
             "hovered_text":"#FFFFFF",
             "selected_text":"#FFFFFF",
             "disabled_text":"#6d736f",
             "link_text": "#0000EE",
             "link_hover": "#2020FF",
             "link_selected": "#551A8B",
             "text_shadow": "#777777",
             "normal_border": "#DDDDDD",
             "hovered_border": "#B0B0B0",
             "disabled_border": "#808080",
             "selected_border": "#8080B0",
             "active_border": "#8080B0",
             "filled_bar":"#f4251b",
             "unfilled_bar":"#CCCCCC"
         }
     },

     "button":
     {
         "colours":
         {
             "normal_bg":"#45494e",
             "hovered_bg":"#35393e",
             "disabled_bg":"#25292e",
             "selected_bg":"#193754",
             "active_bg":"#193754",
             "dark_bg":"#15191e",
             "normal_text":"#c5cbd8",
             "hovered_text":"#FFFFFF",
             "selected_text":"#FFFFFF",
             "disabled_text":"#6d736f",
             "active_text":"#FFFFFF",
             "normal_border": "#DDDDDD",
             "hovered_border": "#B0B0B0",
             "disabled_border": "#808080",
             "selected_border": "#8080B0",
             "active_border": "#8080B0"
         },

         "misc":
         {
             "tool_tip_delay": "1.5"
         }
     }
 }

Each of the UI Elements supports different theme options, what exactly these are is detailed in the individual theming guide for each element shown below.