UIButton Theming Parameters

The UIButton theming block id is 'button'.

Colours

../_images/button_colour_parameters.png

A diagram of which part of the element is themed by which colour parameter. This correspondence is the same for the parameters named for the different button states e.g. the parameter 'hovered_bg' themes the same area as 'normal_bg' when the button is in the hovered state.

UIButton makes use of these colour parameters in a 'colours' block. Most of these colours can also be a colour gradient:

  • "normal_bg" - The background colour/gradient of the button in the default state.

  • "hovered_bg" - The background colour/gradient of the button when the mouse pointer is over it.

  • "disabled_bg" - The background colour/gradient of the button when the button has been disabled (so users cannot interact with it)

  • "selected_bg" - The background colour/gradient of the button when the button has select focus.

  • "active_bg" - The background colour/gradient of the button 'mid-click', you will mostly see it while dragging things around via buttons.

  • "normal_text" - The colour/gradient of the button's text in the default state.

  • "hovered_text" - The colour/gradient of the button's text when the mouse pointer is over it.

  • "disabled_text" - The colour/gradient of the button's text when the button has been disabled (so users cannot interact with it)

  • "selected_text" - The colour/gradient of the button's text when the button has select focus.

  • "active_text" - The colour/gradient of the button's text (if any) 'mid-click', you will mostly see it while dragging things around via buttons.

  • "normal_border" - The colour/gradient of the border around the button (if it has one), in the default state.

  • "hovered_border" - The colour/gradient of the border around the button (if it has one), in the hovered state.

  • "disabled_border" - The colour/gradient of the border around the button (if it has one), in the disabled state.

  • "selected_border" - The colour/gradient of the border around the button (if it has one), in the selected state.

  • "active_border" - The colour/gradient of the border around the button (if it has one), in the active state.

  • "normal_text_shadow" - The colour of the shadow behind the button's text (if it has one), in the default state.

  • "hovered_text_shadow" - The colour of the shadow behind the button's text (if it has one), in the hovered state.

  • "disabled_text_shadow" - The colour of the shadow behind the button's text (if it has one), in the disabled state.

  • "selected_text_shadow" - The colour of the shadow behind the button's text (if it has one), in the selected state.

  • "active_text_shadow" - The colour of the shadow behind the button's text (if it has one), in the active state.

Font

UIButton accepts a font specified in the theme via a 'font' block. A 'font' block has these parameters:

  • "name" - Necessary to make a valid block. This is the name that this font goes by in the UI, if this is a new font then subsequent font instances with different styles or sizes should use the same name.

  • "locale" - Optional parameter to set this font as belonging to a particular locale only. See the Localization guide. You will need to keep repeating the locale specifier if using prototypes to make a hierarchy.

  • "size" - Necessary to make a valid block. This is the point size of the font to use on the button.

  • "bold" - Optional parameter. Set it to "1" to make this font bold.

  • "italic" - Optional parameter. Set it to "1" to make this font italic.

There are two methods to refer to font resource locations. First, using packaged resources:

  • "regular_resource - The location of this font's file with no particular style applied.

    • package - The name of the python package containing this resource - e.g. 'data.fonts'

    • resource - The file name of the resource - e.g. 'FiraCode-Regular.ttf'

  • "bold_resource" - The location of this font's file with bold style applied.

    • package - The name of the python package containing this resource - e.g. 'data.fonts'

    • resource - The file name of the resource - e.g. 'FiraCode-Bold.ttf'

  • "italic_resource" - The location of this font's file with italic style applied.

    • package - The name of the python package containing this resource - e.g. 'data.fonts'

    • resource - The file name of the resource - e.g. 'FiraMono-Italic.ttf'

  • "bold_italic_resource" - The location of this font's file with bold and italic style applied.

    • package - The name of the python package containing this resource - e.g. 'data.fonts'

    • resource - The file name of the resource - e.g. 'FiraMono-BoldItalic.ttf'

Second using paths:

  • "regular_path" - The path to this font's file with no particular style applied.

  • "bold_path" - The path to this font's file with bold style applied.

  • "italic_path" - The path to this font's file with italic style applied.

  • "bold_italic_path" - The path to this font's file with bold and italic style applied.

You only need to specify locations if this is the first use of this font name in the GUI.

Images

UIButton accepts images specified in the theme via an 'images' block. An 'images' block has these parameters:

  • "normal_image" - The image displayed in the buttons default state. It has the following block of sub-parameters:

    • "path" - The string path to the image to be displayed. OR

    • "package - The name of the python package containing this resource - e.g. 'data.images'

    • "resource - The file name of the resource in the python package - e.g. 'splat.png' - Use a 'package' and 'resource' or a 'path' not both.

    • "sub_surface_rect" - An optional rectangle (described like "x,y,width,height") that will be used to grab a smaller portion of the image specified. This allows us to create many image surfaces from one image file.

  • "hovered_image" - The image displayed in the buttons hovered state. It has the following block of sub-parameters:

    • "path" - The string path to the image to be displayed. OR

    • "package - The name of the python package containing this resource - e.g. 'data.images'

    • "resource - The file name of the resource in the python package - e.g. 'splat.png' - Use a 'package' and 'resource' or a 'path' not both.

    • "sub_surface_rect" - An optional rectangle (described like "x,y,width,height") that will be used to grab a smaller portion of the image specified. This allows us to create many image surfaces from one image file.

  • "selected_image" - The image displayed in the buttons select focused state. It has the following block of sub-parameters:

    • "path" - The string path to the image to be displayed. OR

    • "package - The name of the python package containing this resource - e.g. 'data.images'

    • "resource - The file name of the resource in the python package - e.g. 'splat.png' - Use a 'package' and 'resource' or a 'path' not both.

    • "sub_surface_rect" - An optional rectangle (described like "x,y,width,height") that will be used to grab a smaller portion of the image specified. This allows us to create many image surfaces from one image file.

  • "disabled_image" - The image displayed in the buttons disabled state. It has the following block of sub-parameters:

    • "path" - The string path to the image to be displayed. OR

    • "package - The name of the python package containing this resource - e.g. 'data.images'

    • "resource - The file name of the resource in the python package - e.g. 'splat.png' - Use a 'package' and 'resource' or a 'path' not both.

    • "sub_surface_rect" - An optional rectangle (described like "x,y,width,height") that will be used to grab a smaller portion of the image specified. This allows us to create many image surfaces from one image file.

Misc

UIButton accepts the following miscellaneous parameters in a 'misc' block:

  • "shape" - Can be one of 'rectangle', 'rounded_rectangle' or 'ellipse'. Different shapes for this UI element.

  • "shape_corner_radius" - Only used if our shape is 'rounded_rectangle'. It sets the radius, or radii, used for the rounded corners. Use a single integer to set all corners to the same radius, or four integers separated by commas to set each corner individually.

  • "border_width" - the width in pixels of the border around the button. Defaults to 1.

  • "shadow_width" - the width in pixels of the shadow behind the button. Defaults to 2.

  • "tool_tip_delay" - time in seconds before the button's tool tip (if it has one) will appear. Default is "1.0".

  • "text_horiz_alignment" - Set to "left", "right" or "center". Controls the horizontal placement of the button text, if this button has any text. Default is "center".

  • "text_vert_alignment" - Set to "top", "bottom or "center". Controls the vertical placement of the button text, if this button has any text. Default is "center".

  • "text_horiz_alignment_padding" - If horizontal alignment is set to 'left' or 'right' this value will control the buffer between the edge of the button and where we start placing the text. Default is "1".

  • "text_vert_alignment_padding" - If vertical alignment is set to 'top' or 'bottom' this value will control the buffer between the edge of the button and where we start placing the text. Default is "1".

  • "text_shadow_size" - The increased size in pixels of the text's shadow/outline. Set to "0", "1" or "2", larger than that the effect breaks down and individual letters merge together. Defaults to "0", no shadow.

  • "text_shadow_offset" - Pixel offset in horizontal (x) and vertical (y) dimensions for where the text shadow is drawn. In the format "x,y". Defaults to "0,0".

  • "state_transitions" - A block of parameters that define any fade transitions between button states. Normally buttons states visually change instantly, if you setup values here the button will instead fade from one state to the next. Transition definitions are one way, if you want to go in both directions, use two parameters. Transition parameters have this format:

    • "startstate_targetstate" - Can be set to any positive floating point value, representing the transition time in seconds.

Example

Here is an example of a button block in a JSON theme file using all the parameters described above.

button.json
 1 {
 2     "button":
 3     {
 4         "colours":
 5         {
 6             "normal_bg": "#25292e",
 7             "hovered_bg": "#35393e",
 8             "disabled_bg": "#25292e",
 9             "selected_bg": "#25292e",
10             "active_bg": "#193784",
11             "normal_text": "#c5cbd8",
12             "hovered_text": "#FFFFFF",
13             "selected_text": "#FFFFFF",
14             "disabled_text": "#6d736f",
15             "active_text": "#6d736f",
16             "normal_border": "#AAAAAA",
17             "hovered_border": "#B0B0B0",
18             "disabled_border": "#808080",
19             "selected_border": "#8080B0",
20             "active_border": "#8080B0",
21             "normal_text_shadow": "#10101070",
22             "hovered_text_shadow": "#10101070",
23             "disabled_text_shadow": "#10101070",
24             "selected_text_shadow": "#10101070",
25             "active_text_shadow": "#10101070"
26         },
27         "font":
28         {
29             "name": "montserrat",
30             "size": "12",
31             "bold": "0",
32             "italic": "1",
33             "regular_resource": {
34                  "package": "data.fonts",
35                  "resource": "Montserrat-Regular.ttf"
36             },
37             "bold_resource": {
38                  "package": "data.fonts",
39                  "resource": "Montserrat-Bold.ttf"
40             },
41             "italic_resource": {
42                  "package": "data.fonts",
43                  "resource": "Montserrat-Italic.ttf"
44             },
45             "bold_italic_resource": {
46                  "package": "data.fonts",
47                  "resource": "Montserrat-BoldItalic.ttf"
48             },
49         },
50         "images":
51         {
52             "normal_image": {
53                 "package": "data.images",
54                 "resource": "buttons.png",
55                 "sub_surface_rect": "0,0,32,32"
56             },
57             "hovered_image": {
58                 "package": "data.images",
59                 "resource": "buttons.png",
60                 "sub_surface_rect": "32,0,32,32"
61             },
62             "selected_image": {
63                 "package": "data.images",
64                 "resource": "buttons.png",
65                 "sub_surface_rect": "64,0,32,32"
66             },
67             "disabled_image": {
68                 "package": "data.images",
69                 "resource": "buttons.png",
70                 "sub_surface_rect": "96,0,32,32"
71             }
72
73         },
74         "misc":
75         {
76             "shape": "rounded_rectangle",
77             "shape_corner_radius": "10,0,0,0",
78             "border_width": "1",
79             "shadow_width": "1",
80             "tool_tip_delay": "1.0",
81             "text_horiz_alignment": "left",
82             "text_vert_alignment": "top",
83             "text_horiz_alignment_padding": "10",
84             "text_vert_alignment_padding": "5",
85             "text_shadow_size": "1",
86             "text_shadow_offset": "0,0",
87             "state_transitions":
88             {
89                 "normal_hovered": "0.5",
90                 "hovered_normal": "0.5"
91             }
92         }
93     }
94 }