Appendix O: User Interface Themes

= Appendix O: User Interface Themes =

The graphics used for the SageTV user interface and some other settings are loaded as theme sets, via the Select the User Interface Theme option in Detailed Setup: Advanced Settings. SageTV installs with the Standard theme.

Additional user created themes may be found on the SageTV online forums at forums.sagetv.com/forums or may be available via Theme category in the Plugin Manager.

== Adding Custom Images to an Existing Theme ==

If all you want to do is change a few images without creating an entirely new theme, then simply add the new images to the User Images subdirectory of an existing theme directory, naming the files the same as the filenames of the images being replaced. After adding images to that subdirectory, reload the current theme via the Select the User Interface Theme option in Detailed Setup: Advanced Settings. Note: If existing images in that subdirectory have been changed, you may need to restart SageTV to see the new images in the user interface.

It is better to place your custom images in the User Images subdirectory instead of in the theme’s base directory because the files in the base directory will be replaced when a SageTV update is installed (if replacing files in the Standard theme) or when a theme plugin update is installed (if replacing files in a custom theme). The files in the User Images subdirectory are not replaced by the SageTV installer. If a custom theme replaces files in that subdirectory, inform the theme’s author so the author’s custom files can be placed in the proper location.

Creating a New Theme
To create an entirely new theme, simply create a new directory under the '''\SageTV\STVs\SageTV7\Themes''' directory, using the name of your new theme. You can change one or more UI image files by placing new versions of images in the custom theme directory and you can create a theme.properties file to change one or more properties. If an image file or a property setting is not found, the one from the default Standard theme will automatically be used.

Exceptions:

The ProgressBar.png files must be a full set of 5, #1-5.

If you change the weather icons, you have to provide a full set and use theme.properties in the custom theme directory to specify the offset path from where the current STV is located to the weather icons.

As the default UI changes, new graphics are being put in the theme directories, but those are not the only images you can place in your own theme -- you can change almost any image found in the  \SageTV\STVs\SageTV7 or Standard theme directories. When loading a theme, each image is searched for by checking the current theme directory and its “User Images” subdirectory, the default theme directory and its “User Images” subdirectory, then the STV's directory. However, not all images in the STV directory are currently in use by the default STV.

'''Additional Theme Notes: '''

See the theme.properties file in the default Standard theme directory for additional comments about various theme settings. The first section of the file documents the possible theme settings.

To determine which images are being used and where they are loaded from, check the debug log for a list of themed images. Debug logging can be enabled via the Debug Logging option in Detailed Setup: Advanced Settings.

If a custom theme contains an image file named preview.jpg, that will be the preview image shown in the theme selection dialog when the theme is highlighted; see the Select the User Interface Theme option.

In the new theme’s custom theme.properties, add a property line named Description/=, where ThemeName is the name of the new theme, followed by a short description of the theme. Users will see this description in the theme selection dialog when the theme is highlighted.

The focus highlight images are actually drawn behind the regular button backgrounds or fill colors, so it works better if the button background images are semi-transparent.