UICheckBox Theming Parameters
The UICheckBox theming block id is 'check_box'.
Colours
UICheckBox accepts the following colour parameters in a 'colours' block:
"normal_bg" - The background colour of the checkbox in its normal state.
"normal_border" - The border colour of the checkbox in its normal state.
"hovered_bg" - The background colour of the checkbox when it is being hovered over.
"hovered_border" - The border colour of the checkbox when it is being hovered over.
"disabled_bg" - The background colour of the checkbox when it is disabled.
"disabled_border" - The border colour of the checkbox when it is disabled.
"selected_bg" - The background colour of the checkbox when it is checked or indeterminate.
"selected_border" - The border colour of the checkbox when it is checked or indeterminate.
"normal_text" - The colour of the check symbol when the checkbox is in its normal state.
"hovered_text" - The colour of the check symbol when the checkbox is being hovered over.
"disabled_text" - The colour of the check symbol when the checkbox is disabled.
"selected_text" - The colour of the check symbol when the checkbox is checked or indeterminate.
"normal_text_shadow" - The colour of the check symbol's shadow in normal state.
"hovered_text_shadow" - The colour of the check symbol's shadow when hovered.
"disabled_text_shadow" - The colour of the check symbol's shadow when disabled.
"selected_text_shadow" - The colour of the check symbol's shadow when checked or indeterminate.
Font
UICheckBox accepts the following font parameter in a 'font' block:
"name" - The name of the font to use for the check symbol. Defaults to the UI theme's default font.
"size" - The size of the font to use for the check symbol.
"bold" - Whether the font should be bold.
"italic" - Whether the font should be italic.
You only need to specify locations if this is the first use of this font name in the GUI.
Images
UICheckBox accepts images specified in the theme via an 'images' block. The checkbox supports both single-image and multi-image modes for enhanced visual effects.
Single Image Mode (Legacy)
For simple checkboxes with one image per state, use these parameters:
"normal_image" - The image displayed in the checkbox's 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.
"premultiplied" - Optional parameter to declare that a loaded image already contains premultiplied alpha and does not need premultiplying. Set to "1" to enable, "0" to disable (default).
"hovered_image" - The image displayed in the checkbox's hovered state. Uses the same sub-parameters as normal_image.
"selected_image" - The image displayed in the checkbox's checked/indeterminate state. Uses the same sub-parameters as normal_image.
"disabled_image" - The image displayed in the checkbox's disabled state. Uses the same sub-parameters as normal_image.
Multi-Image Mode
For more complex checkboxes with multiple images per state and precise positioning control, use these parameters:
"normal_images" - A list of images for the normal state. Each image has the following parameters:
"id" - A unique identifier for this image.
"path" - The string path to the image to be displayed. OR
"package" - The name of the python package containing this resource.
"resource" - The file name of the resource in the python package.
"layer" - The layer number for rendering order (lower numbers render first).
"position" - Optional tuple of (x, y) values between 0.0 and 1.0 representing relative position. Defaults to (0.5, 0.5) for center.
"premultiplied" - Optional parameter to declare that a loaded image already contains premultiplied alpha.
"hovered_images" - A list of images for the hovered state. Uses the same parameters as normal_images.
"selected_images" - A list of images for the checked/indeterminate state. Uses the same parameters as normal_images.
"disabled_images" - A list of images for the disabled state. Uses the same parameters as normal_images.
Image Positioning Notes: - The "position" parameter accepts values between 0.0 and 1.0 for both x and y coordinates. - (0.0, 0.0) represents top-left, (1.0, 1.0) represents bottom-right. - If no position is specified, the image will be centered (0.5, 0.5). - Images are rendered in layer order (lowest layer number first), allowing precise control over visual composition. - If a state doesn't specify images, it will fall back to the normal state images. - Both modes work alongside the traditional text-based check symbols.
Miscellaneous
UICheckBox 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 checkbox. Defaults to 1.
"shadow_width" - The width in pixels of the shadow behind the checkbox. Defaults to 2.
"border_overlap" - The amount of overlap between the border and the background. Defaults to 1.
"check_symbol" - The symbol to display when the checkbox is checked. Defaults to "✓".
"indeterminate_symbol" - The symbol to display when the checkbox is in indeterminate state. Defaults to "−".
"text_offset" - The distance in pixels between the checkbox and its text label. Defaults to 5.
"tool_tip_delay" - Time in seconds before the checkbox's tool tip (if it has one) will appear. Default is "1.0".
Sub-elements
The UICheckBox contains a UILabel for its text, so you can use the block ID 'check_box.label' to style the text label.
There is more information on theming the label at UILabel Theming Parameters.
Example
Here are examples of checkbox blocks in JSON theme files using the parameters described above.
Single Image Mode Example:
1 {
2 "check_box":
3 {
4 "colours":
5 {
6 "normal_bg": "#25292e",
7 "normal_border": "#AAAAAA",
8 "hovered_bg": "#35393e",
9 "hovered_border": "#B0B0B0",
10 "disabled_bg": "#25292e",
11 "disabled_border": "#808080",
12 "selected_bg": "#193784",
13 "selected_border": "#8080B0",
14 "normal_text": "#c5cbd8",
15 "hovered_text": "#FFFFFF",
16 "disabled_text": "#6d736f",
17 "selected_text": "#FFFFFF",
18 "normal_text_shadow": "#10101070",
19 "hovered_text_shadow": "#10101070",
20 "disabled_text_shadow": "#10101070",
21 "selected_text_shadow": "#10101070"
22 },
23 "font":
24 {
25 "name": "fira_code",
26 "size": "14",
27 "bold": "0",
28 "italic": "0"
29 },
30 "images":
31 {
32 "normal_image": {
33 "package": "data.images",
34 "resource": "checkbox_states.png",
35 "sub_surface_rect": "0,0,16,16"
36 },
37 "hovered_image": {
38 "package": "data.images",
39 "resource": "checkbox_states.png",
40 "sub_surface_rect": "16,0,16,16"
41 },
42 "selected_image": {
43 "package": "data.images",
44 "resource": "checkbox_states.png",
45 "sub_surface_rect": "32,0,16,16"
46 },
47 "disabled_image": {
48 "package": "data.images",
49 "resource": "checkbox_states.png",
50 "sub_surface_rect": "48,0,16,16"
51 }
52 },
53 "misc":
54 {
55 "shape": "ellipse",
56 "shape_corner_radius": "3",
57 "border_width": "2",
58 "shadow_width": "2",
59 "border_overlap": "1",
60 "check_symbol": "✓",
61 "indeterminate_symbol": "−",
62 "text_offset": "8",
63 "tool_tip_delay": "1.5"
64 }
65 }
66 }
Multi-Image Mode Example:
1 {
2 "check_box":
3 {
4 "colours":
5 {
6 "normal_text": "#c5cbd8",
7 "hovered_text": "#FFFFFF",
8 "disabled_text": "#6d736f",
9 "selected_text": "#FFFFFF"
10 },
11 "font":
12 {
13 "name": "fira_code",
14 "size": "14"
15 },
16 "images":
17 {
18 "normal_images": [
19 {
20 "id": "checkbox_base",
21 "path": "images/checkbox_base.png",
22 "layer": 0
23 },
24 {
25 "id": "checkbox_border",
26 "path": "images/checkbox_border.png",
27 "layer": 1
28 }
29 ],
30 "hovered_images": [
31 {
32 "id": "checkbox_base",
33 "path": "images/checkbox_base.png",
34 "layer": 0
35 },
36 {
37 "id": "checkbox_border",
38 "path": "images/checkbox_border.png",
39 "layer": 1
40 },
41 {
42 "id": "hover_glow",
43 "path": "images/checkbox_glow.png",
44 "layer": 2
45 }
46 ],
47 "selected_images": [
48 {
49 "id": "checkbox_base_selected",
50 "path": "images/checkbox_base_selected.png",
51 "layer": 0
52 },
53 {
54 "id": "checkbox_border",
55 "path": "images/checkbox_border.png",
56 "layer": 1
57 },
58 {
59 "id": "check_mark",
60 "path": "images/checkbox_check.png",
61 "layer": 2
62 }
63 ],
64 "disabled_images": [
65 {
66 "id": "checkbox_base_disabled",
67 "path": "images/checkbox_base_disabled.png",
68 "layer": 0
69 }
70 ]
71 },
72 "misc":
73 {
74 "shape": "rounded_rectangle",
75 "shape_corner_radius": "3",
76 "border_width": "2",
77 "shadow_width": "2",
78 "check_symbol": "✓",
79 "indeterminate_symbol": "−",
80 "text_offset": "8",
81 "tool_tip_delay": "1.5"
82 }
83 }
84 }