WindowFrame Layouts using Themes and Stylesheets

Using a combination of Unity Theme (TSS) and Style Sheet (USS) assets you can create any User Interface

Window Framework uses the Unity theme system for display settings and supports both TSS (Unity Themes) and USS (Stylesheets) as an asset. The Unity Theme system works much like the HTML stylesheet standard with additional functionality to meet the needs of the environment. Using these two asset types together gives you a powerful tool for creating themes to meet any need and the option to set that theme at any time.

The default stylesheet comes as basic as possible so that modifications are easy. There are a few named areas that have inline styles applied in code. These are for areas such as the header label so that the text overflow is rendered in a reliable fashion. The Content section, so that wrapping is properly applied, and the Footer Toolbar, again so overflow is properly handled. These can be edited in code or new values applied after window creation. Window Framework comes with the following defined areas for styling:
.windowFrame
.windowFrameLocked
#windowFrameHeader
#windowFrameTitle
#windowFrameOptionsMenu
#windowFrameContent
#windowFrameFooter
#windowFrameFooterToolbar
#windowFrameResizeArea
#Tooltip
#Tooltip > label
#ContextMenu
#ContextMenu > Label


You may notice that most items are using named calls (#xxx) which uses the visual elements defined name to apply the style, while the first uses a standard style class call (.xxx). The window's name is set by the programmer and is unreliable for style calls so the style class is added, whereas named child sections in the code have fixed names that never change and can be relied on for existence.

Creating New Stylesheets Using UI Builder

The Window Framework is UI Builder compatible and will show as a custom control so that you can use the visual features of the interface while creating your USS Style sheets. We have included a WindowFrameworkStylingTemplate.uxml file that has a single window loaded with the default stylesheet attached as shown below, you can also take note of the window options that are available on the right hand inspector. Some of these settings need a runtime environment to work but other like size and header,footer options all work. Entering preview will even allow you to move and resize the window so you can see how your new style reacts in use without having to enter play mode.

One thing to note is that the positioning system reacts strangly in UI builder, it is due to the absolute positioning and location load system built into the custom control and should be left in the upper left selection so that the rendered window does not move around on you during UI Builder GUI updates.

The fastest way to get started would be to make a duplicate of the default stylesheet, In the project window select the WindowFrameDefault.uss file and press CTRL+D to make a duplicate. Name the new file something you will remember and take note of the path, it should be within a resource folder or a child of a resource folder.

Now from within UI Builder you can attach the new stylesheet to the document, this document is meant to be used like scratch paper because not all style elements will be applied until the file gets saved so do not use your actual game UI documents for this unless you know what your doing as it will be in constant change and may cause undesired results. After adding the new stylesheet simply delete the old reference and save the file. You can now modify the new style sheet to meet the desired look and feel. Once you are happy with your changes make sure to save again to write all USS data file changes to disk.

Theme System Layout

The Recomended Theme system layout shown here for clarity but is not a required template. While you are free to store your files anywhere you like, following some type of general standard will help you find your files later. We use the Resources folder for storage of all icons, images, stylesheets and themes as shown in the screenshot of our resources folder layout. Within the WindowFramework/Themes folder you see a sub-folder for each pre-defined theme. Each of these folders hold several Stylesheet files and one Theme file. In Unity Theme system you select the Theme asset and then you can Add all of the stylesheets that make up that theme.

The Stylesheets that make up the Theme will be added to the stylesheets that make up the global theme when applied. The Runtime Theme Asset is like a Theme Asset but has the default Unity settings applied. With our system only one is needed with it and the Text Settings Asset linked to the Default Panel Asset that is then assigned to the UI Document Component... I know its a lot to get your head around but it will hopefully become clearer as we go on.
Note: We plan on expanding our New Theme Manager Window to automate this process in future releases.

The Runtime Theme File

Creating a base Runtime Theme File is the first step, now to be clear there are two (2) types of theme files, a standard Unity Theme file and a Runtime Theme file, the only difference being that the Runtime Theme file has an @import statement that includes the default Unity stylesheet @import url("unity-theme://default"); Also, you really only need one of these files since when you have several, you get duplication in lists with references to the 'default' stylesheet. This is happens because each Runtime theme imports it as a separate instance. Now they are all imports so they are all the same file but having errant file links floating around may cause them to break later during some random cleanup of your project. There are several options at this point, you can make yet another file to hold the global styles that you can then link as an aditional import in this file, or you can place global definitions directly in the theme file itself since it is also treated as a stylesheet. We recomend you use the USS variable system and place all variable powered theme elements here along with a link to a default values style sheet.

The Standard Theme File

The Standard TSS Theme file, as stated before is the same as a runtime theme file without the @import call to the default Unity theme file. In the window framework, one (1) os these are recomended for each theme in the system. This file will also be the one listed in the Theme dropdown available in UI Builder so choose a memerable name or follow some sort of naming convention. We recomend WFW-[ThemeName]Theme for the Theme filename with [Theme] replaced with your theme name. This file will be used to link the runtime theme, current theme settings and any other items you want to include with the final theme together as shown in the recomended layout image.

Window Framework Recomended Theme Layout in Inspector

The Stylesheet File

The Standard stylesheet file is used to store the values for your USS variables, If you are unfamiliar with the variables system then check out the Unity Docs on USS Variable for more details. Placing the theme specific values here gives you a single place to edit that allows full customization.

Player Theming

This feature is currently disabled because at the time of this writing, Unity does not support the loading of Style Sheet resources at runtime. We cannot imagine that this will be the case for long so the underlying system is there just disabled and hidden in the inspector. It will create theme folders in the persistent data directory, show them in the selector and clean up on destroy so it works…
BUT, as stated before, because Unity itself will not allow the Style Sheet to be loaded at runtime, the style sheets reference is always null. We are going to get this working so we are leaving the underlying support logic in the system, just disabled for now, we will enable this feature and publish an updated as soon as we can figure out a way around the Unity limitation or, hopefully, Unity adds the load at runtime ability.