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.

Creating Window Framework Themes in Unity 6
Recommended Creation Workflow

Creating themes is a straight forward process even though there are several steps involved.
We plan on automating this process from the Theme Manager Window in future versions.
Important Note: Unity Theme Stylesheet references tend to break if you move or rename a stylesheet file. For this reason you should pick a location in your project for your themes and sick with it. Unity may fix this in future versions but as of the time of this writing, it is a problem. Altering the data IN the files are fine but location and name need to be consistant or you will get stylesheet import errors and have to re-link your Stylesheets within the ThemeStylesheet asset.

1. Create a Themes folder for your project

   In order to keep your themes independant of the asset you want to create a place to hold your themes. We recomend Assets/Resources/Themes as this location would be outside of the asset and descriptive of its purpose based on location but you can use any folder that best suits your project layout. The only major requirments being that:

   1. Your themes folder should NOT be within the WindowFramework assets folder so that future updates do not effect your data.
   2. Your themes folder be placed within a Resources folder so that Resources.Load() calls can operate properly

2. Decide to use our Runtime or Your Own

   The runtime theme assets apply the styles using the settings in the individual 'Themes' and therefor require additional considerations.
   This tutorial is focused on Creating Themes but we wanted to point out this important step.
   
   If you want your system to have instant access to any updates we make to our theme design then you can use the Default Runtime panel settings and theme files provided by the asset. We are going to make every effort to keep the theme system consistant going forward but sometimes things must be changed so please keep that in mind.
   
   If you want to have your own or have an exisitng runtime and want to use ours as a starting point then you can read about The Window Frame Controller Scene Object for instructions on creating one or linking the needed files to your existing asset, or use the following images as reference.
   Files to Copy when making your own Runtime
   
   When making your own Runtime, copy the files shown, rename them and link them as shown in the images
   
3. Create a Default Theme Sub-Folder
   Create a sub-folder in Themes to hold your new theme, for this example we will use: MyProjectDefaultTheme

   
4. Create Theme File
   Create a new ThemeStylesheet within the folder you created, sor this example we will use: WFW-MyProjectDefaultTheme
   We recomend the WFW prefix so it is easy to find in later lists but any suiable prefix will work.

   
5. Copy Template
   Make a duplicate of the Default Theme Settings USS file by selecting the WFW-DefaultThemeSettings.uss file and pressing CTRL+D to make a copy, the new file will have a 1 added to the end.

   
6. Move Copied Template file
   Move the duplicated file to your new themes folder so that it stays orginized and out of the asset folder.

   
7. Rename Copied Template
   Rename File to match your new theme name, for this example it will be: WFW-MyProjectDefaultThemeSettings

   

8. Link the files in the Theme Stylsheet

   Select the WFW-MyProjectDefaultTheme file and look in the inspector. your will need to link all the files needed to make up a usable theme as shown in the image, using this example. Note that the WFW-DefaultRuntimeTheme in inherited, this is required so that all the base styling applications are loaded. The Settings file we coppied has only the values that are needed by the Runtime file. Make sure to click Apply to save the data file (Unity stylesheets settings made in the inspector are not dynamically updated) Once everything is linked up you will be able to see your new theme in the UI Bulder Themes dropdown list but you will still need a data file to use it in the Window Framework at runtime. One more thing to note is that Unity Theme StyleSheets do not like being moved OR having the linked files moved, if they are the links break and have to be recreated. We have decided to make our runtime theme location and naming a static part of our asset going forward so that you can build integrations with reasonible reliability that the files will be there.
   

• Modifying Theme Settings

  Themes have lots of available settings and more can be added by you as needed to meet the needs of your layout design. We recommend you use and expand on the USS variable system that we have established, but you are free to modify or even replace as needed. The setting file (WFW-MyProjectDefaultThemeSettings.uss is following project setup) is the only file that you should need to modify. if has been organized with the coloring options all placed at the top of the file but there are many available setting thoughout the file. Each section has been labeled with a comment header so you can find the area you are looking for.
  
  We have established a named convention for our variable names that follows the following pattern:
  [ElementName]__[USS-Styling-Option]
  SO for the windowFrame border width you would use:
  –windowFrame__border-width: 5px; // effect all borders
  –windowFrame__border-top-width: 5px; // effect top border only
  
  If major changes are wanted in the base layout that are outside of nornal cascading options then you may need to look at making a new runtime theme setup that is independent of the framework (like the general theme separation). You can do this by replication of the Runtime folder in the Window Frameworks default Theme Folder to you own, making sure to update file links as necessary.
  Please Note: Some of the setting's the the runtime styling file that are hard coded and are REQUIRED for proper window operation, be VERY CARFULL when modifying this file or its settings.
  Modification of the base theme settings should not be needed since USS cascades like HTML stylesheets so new settings can be added almost anywhere providing the load order is correct and the controller has options for load order and additional global stylesheets or theme files.
  Default Theme Settings File in Code View
  

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, 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.
One thing to note is that the positioning system reacts strangely 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. When in Preview mode, movement and resizing work so you can full test your theme and style layouts, this also extends to many of the minor UI related functions. In the Demo for example, when in Preview mode the menu system works as expected, pages are instantiated into the preview and all non-runtime related values work as they would at runtime. Any of your custom window types can be setup to allow this functionality and the UXMLBasedDemoWindow.cs file in the Demo/Scripts folder can be used as an example of creating window frames as a partial class UXML Element.

Using UI Builder and a Code Editor to edit Theme Values

The Theme system uses variables meaning that if you use our recommended template as a starting point, you have access to the needed items to style window frames, tooltips and context menus. With the linking abilities of the theme system you can expand these themes to meet any need. You can edit these variable in UI Builder as it does have the capability however it is still a little clumsy to use, We are sure this will get better in time but for now we have found that using your code editor to change variable values and UI Builder to view the results. One nice thing in UI Builder is that when you save your file in the code editor the display updates automatically and both Rider and Visual Studio editors have color pickers along with validators for values.

Global Styles Theme -or- Stylesheet Asset
Optional

The Optional Global Stylesheet can be a Unity Theme or Stylesheet asset file. By using a Unity Theme asset (TSS) you can add all your smaller stylesheets that are used regardless of theme, things like fixed element layouts for example. The theme system will automatically apply the stylesheet defined in the Global Theme asset either before or after the rest of the theme style sheets are loaded based on the selected Global Load Order. This choice can be helpful if you are having value over-right issues and while you could use the runtime theme to link these files, you would loose the load order functionality.