Skip to content

How to Make a Custom Theme for UXL Launcher

Jump to bottom
Drew Naylor edited this page Jul 5, 2018 · 70 revisions

Please note that this page isn't ready yet and it was created just to have a link in the Version 3.1 Release Candidate 1 changelog ready for people to click on for when it is ready.

This page will include info on turning on debug labels (to have an easy way to preview the theme file as it's saved), configuring the custom theme file to use to be the one the theme designer wants, what must be included in a custom theme, things that can be changed with a custom theme, and information on how the UseThemeEngineVersion XML element works in the theme engine itself.

UXL Launcher Theme Engine is currently at version 1.01.

If you just want to jump right in and figure everything out yourself and want to modify a basic, pre-existing theme, you can use the Default theme. If, however, you want to use a theme with flat buttons, you can use the Maudern theme. Otherwise, you can read on to find out how to make your own theme, or skip ahead to the part where it's described.

Supported file extensions

Although the primary file extension for UXL Launcher themes is XML, regular text files (TXT) are also officially supported. As such, these are the two extensions available as filters in the Browse for a custom theme file open dialog box window that shows up when clicking the Browse... button next to the custom theme path textbox. Other file extensions, such as JS (JavaScript) or VB (Visual Basic) may work, though it's not recommended.

Configuring your custom theme to be used

Once you've created a file to use as your custom theme (preferably with one of the supported file extensions), you'll need to configure UXL Launcher to use it. Here are the steps for doing this.

  1. Start UXL Launcher.
  2. Open the Options window from Tools>Options....
  3. Go to the Personalization tab.
  4. If it's not already enabled, click the checkbox next to Enable UXL Launcher Theme Engine (requires application restart), save your settings, and restart UXL Launcher. Afterward, go to step 2. Otherwise, continue to step 5.
  5. Choose (Custom) from the theme list dropdown box.
  6. Either paste the exact location (including the drive letter and all folders) into the custom theme path textbox below the theme list or click the Browse... button next to the textbox and browse to your custom theme file. Double-click on it to choose it.
  7. Click the Save button to save your settings.

Next, you can preview your custom theme.

Previewing your custom theme

If you would like to preview your custom theme as you save it and click a button to update to the latest changes in your theme file, you can follow the steps below. This isn't required, but it does make custom theme designing easier. You can skip this part if you want to.

  1. Create a copy of UXL-Launcher.exe.config next to the main EXE file (UXL-Launcher.exe). This can be used as a backup in case anything goes wrong during this process.
  2. Open the config file (UXL-Launcher.exe.config) in your favorite text editor, such as Notepad++.
  3. Find the XML element/tag under userSettings for the debugmodeShowLabels setting. You may need to scroll down before it's visible.
  4. Change the value property of this setting from False to True.
  5. If you also want to have theme engine output show up in the Visual Studio Immediate Window as well, change the value property of the debugmodeShowThemeEngineOutput setting from False to True. This output is rather verbose (lots of detail) and includes error messages that may be helpful in debugging your custom theme if you're having trouble with it.
  6. Save the config file (UXL-Launcher.exe.config).
  7. Restart UXL Launcher.

Once the app is restarted, you can use the Apply Chosen Theme button in the bottom-left corner of the main window to re-apply your custom theme file after making changes and saving it. Currently, themes are not re-applied when their file is updated, so clicking the button is required.

The first set of steps also enables some debug labels in the bottom-middle that show theme details such as title, description, author, version, and the version of the theme engine the theme is compatible with. Any of these labels can be double-clicked to copy their text and you can paste them into the textbox on the bottom-right that shows the full path used for launching apps if you want to quickly read them without using Notepad. Please be aware that this does have a few issues, as detailed below.

Important note on debug labels/textbox being overwritten

Please note, however, that once you do anything that updates the debug labels (such as saving settings in the Options window, reverting to default theme under View, enabling or disabling Always On Top, and clicking either of the Apply Chosen Theme or Apply Default Theme buttons) will reset the text in all the debug labels and the folder location textbox so it's not recommended to place anything important into the folder location textbox.

Making a custom theme

Minimum required elements/tags

At a minimum, all UXL Launcher themes must have at least the opening and closing root XML elements (tags) as shown below:

<UXL_Launcher_Theme>

</UXL_Launcher_Theme>

If you want to, you can copy the code above into your custom theme file to make things easier.

Custom theme info

Most theme designers will want some identifying information for their custom themes, so you can use the template below to help you with this:

<UXL_Launcher_Theme>
  <Title>(theme title; will be displayed in the Options window theme info textbox)</Title>
  <Description>(theme description. you may want to say if you don't want your theme
to be distributed or modified without your permission since there's no category for
that in the theme engine yet. this would also work for a license area, too, though
it's recommended to provide a link to the license as well if it makes sense.)</Description>
  <Version>(theme version; can be a string/doesn't have to be just a number)</Version>
  <Author>(theme author; usually your name)</Author>

  <!-- "UseThemeEngineVersion" is used to specify the version of the
  UXL Launcher Theme Engine to use in case there are changes in newer
  versions of the theme engine that designers or developers don't want
  to use. Version 1.01 is the oldest version number available and anything
  smaller than that will automatically be set to 1.01 at runtime. -->
  <UseThemeEngineVersion>1.01</UseThemeEngineVersion>
</UXL_Launcher_Theme>

If any of the theme info elements/tags are missing from the custom theme file, they'll simply be replaced with (No [element/tag] specified), with the exception of the <UseThemeEngineVersion> element/tag. This tag is described above in the template. If the version number specified is less than 1.01, then the theme engine will set it to 1.01.

Please note: In UXL Launcher 3.1 Release Candidate 1 (and probably Version 3.1 Stable since it's not that major of a bug, all things considered) and UXL Launcher Theme Engine Version 1.01, there is a bug/known issue where numbers such as 1.01.1 will crash UXL Launcher with an exception of System.InvalidCastException because it's trying to convert the value from a string to a decimal type (decimal is the only way I could get the theme engine to have a number that I can do greater than/less than comparisons with). This bug will be fixed in UXL Launcher Version 3.2 and Theme Engine Version 1.02. Please note that this particular change won't be able to be avoided as it's not part of the code dealing with how colors are pulled from the theme file.

Custom theme colors

Once you've filled out your theme info section, you can get started on the custom theme colors. You're not limited to just using basic colors like Red, Blue, or Yellow. Rather, you can also use HTML color codes such as 0xF1F1F1 (the 0x needs to be added or it won't work) or even system colors like Control (gray-ish default Windows Forms background color) or ControlText (default Windows Forms text color) or even Transparent, if you don't want to set a color for a particular control type. Any missing or invalid colors will just use the default value. Re-using the template from above (but without the theme info template; that'll be left above to reduce clutter), here's what the theme colors part looks like:

<UXL_Launcher_Theme>

	<theme_info_template_goes_here />
  
  <Theme_Colors>

	  
  </Theme_Colors>
  
</UXL_Launcher_Theme>

All the theme colors go between the <Theme_Colors> opening and closing tags, and the <theme_info_template_goes_here /> tag is where the theme info would go, but I removed it from this particular code block because it would take up too much space. The example theme code and screenshot will be available at the end of this wiki page, though. Please be aware that the resulting custom theme example might not look very good, but that's only to have each control visibly identifiable (unless it's text, in which case it'll be the color that's the most easily distinguishable from the background and might be the same in different areas.).

Now we'll get started on the actual colors!

Buttons

The first theme color in the example theme file is for buttons. An example of a button with white text (ForeColor) and maroon (similar to red) background color (BackColor) is available below. You can paste this into the custom theme colors template presented above if you want to, between the <Theme_Colors> beginning and ending tag. These buttons are just the standard Windows Forms buttons.

      <Button>
        <BackColor>Maroon</BackColor>
        <ForeColor>White</ForeColor>
      </Button>

The example theme will use the code presented above for buttons, but you could also use flat buttons if you wanted to. Nowadays, it seems like most companies want their design to be flat so that they're "modern", for some reason. Here's an example of flat buttons using the button colors from the Maudern theme. Please note that the theme engine doesn't support changing the size of flat button borders or changing the button click color at the moment (as of July 4, 2018).

The buttons from the example below will be flat with gray background color, white text, and a light gray border.

      <Button>
        <BackColor>Gray</BackColor>
        <ForeColor>White</ForeColor>
        <!-- The FlatStyle determines the "depth" of the buttons. This can be set
        to either "Flat" or "Standard". Anything else will be set to "Standard".
        Quotation marks are not supported. -->
        <FlatStyle>Flat</FlatStyle>
        <!-- Anything within the "FlatAppearance" element will only be used if
        "FlatStyle" is set to "Flat". -->
        <FlatAppearance>
          <BorderColor>LightGray</BorderColor>
        </FlatAppearance>
      </Button>

Groupboxes

The next category in the example theme is for the groupboxes. Below is an example of groupboxes with a light blue background and black text color. You can paste this into the custom theme colors template presented above if you want to, between the <Theme_Colors> beginning and ending tag and after the closing tag for <Button>. These groupboxes are just the standard Windows Forms groupboxes and the corners might look kinda bad when using background colors other than Transparent because the color extends into the area with the header.

      <GroupBox>
        <BackColor>LightBlue</BackColor>
        <ForeColor>Black</ForeColor>
      </GroupBox>

This time, there's no "Flat" option for the groupboxes, so that means it's time for the Flow Layout Panel colors.

Flow Layout Panel

On the main window for UXL Launcher, there's a single flow layout panel behind the groupboxes that is responsible for making sure the groupboxes don't get messed up when running on a HiDPI device. Below is an example of the flow layout panel with a light green background and black text color. You can paste this into the custom theme colors template presented above if you want to, between the <Theme_Colors> beginning and ending tag and after the closing tag for <GroupBox>. This flow layout panel is just the standard Windows Forms flow layout panel.

      <FlowLayoutPanel>
        <BackColor>LightGreen</BackColor>
        <ForeColor>Black</ForeColor>
      </FlowLayoutPanel>

Return to top

Clone this wiki locally