Table of Contents

Styling

XAML Styling

XAML resources can be loaded via the styles key in the YAML/JSON configuration. Each path should be a path to a XAML file. Paths must be absolute (e.g. C:\Users\user\.whim\resources\styles.xaml) or relative to the .whim directory (e.g. resources\styles.xaml).

For example:

styles:
  user_dictionaries:
    - resources/styles.xaml

Whim uses XAML resources to style the appearance of certain user interfaces such as the Bar Plugin. By default, Whim loads its resources from Defaults.xaml.

Loading custom dictionaries

You can overwrite parts or all of the default resources by loading a custom resource dictionary. For example, the following will load .whim/Resources.xaml and merge it with the default dictionary.

// Load resources in "Resources.xaml"
string file = context.FileManager.GetWhimFileDir("Resources.xaml");
context.ResourceManager.AddUserDictionary(file);

There is no need to provide a "complete" dictionary. Any x:key that isn't specified in the user dictionary, falls back to its default value.

Resource keys

Currently, the following x:keys can be set by the user. A template for creating custom styles from scratch can be found here.

Style keys

These keys can be used to apply arbitrary styles to certain elements such as the root panel of the status bar.

<Style x:Key="bar:root_panel" TargetType="RelativePanel" />             <!-- Root panel -->
<Style x:Key="bar:left_panel" TargetType="StackPanel" />                <!-- Left sub panel -->
<Style x:Key="bar:center_panel" TargetType="StackPanel" />              <!-- Center sub panel -->
<Style x:Key="bar:right_panel" TargetType="StackPanel" />               <!-- Right sub panel -->
<Style x:Key="bar:focused_window:text_block" TargetType="TextBlock" />  <!-- Focused window widget -->
<Style x:Key="bar:date_time:text_block" TargetType="TextBlock" />       <!-- Date-time widget -->
<Style x:Key="bar:active_layout:button" TargetType="Button" />          <!-- Active layout widget -->
<Style x:Key="bar:tree_layout:button" TargetType="Button" />            <!-- Tree layout widget -->
<Style x:Key="bar:workspace:button" TargetType="Button" />              <!-- Workspace widget -->
<Style x:Key="bar.battery.stack_panel" TargetType="StackPanel" >        <!-- StackPanel wrapper around the battery widget -->
<Style x:Key="bar:battery:font_icon" TargetType="FontIcon" />           <!-- The font icon to use for the battery widget !-->
<Style x:Key="bar:battery:text_block" TargetType="TextBlock" />         <!-- The text block for the battery widget !-->

For example, the following resource file defines a custom background color of the bar and reduces its margins and padding:

<ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <Style x:Key="bar:root_panel" TargetType="RelativePanel">
        <!-- The color is a hex color, with the final two bytes being alpha (transparency). -->
        <Setter Property="Background" Value="#2e344080" />
        <Setter Property="Margin" Value="0" />
        <Setter Property="Padding" Value="2" />
    </Style>

</ResourceDictionary>

Bar height

The bar:height key is a special key that is used to communicate to Whim the desired height of the status bar. For instance the following sets the bar height to 28.

<Style x:Key="bar:height" TargetType="RelativePanel">
    <Setter Property="Height" Value="28" />
</Style>

Notes:

  • The corresponding style must not contain any property other than Height.
  • This setting is overwritten if Height is explicitly set in BarConfig - this may be required in some monitor configurations - tracked in #887
  • The actual height of the bar may differ from the specified one due to overflowing elements.
Note

The scaling of the bar and its child elements depends on various Windows settings, which can lead to overflows and cropping.

For example, the font size is scaled by Window's "Accessibility / Text size" setting, which may change the appearance of the bar - see here.

Special color keys

XAML in WinUI does not support "trigger styles" in a user dictionary. Thus, there is no direct way for us to define styling for scenarios like button hover or disabled. As a workaround, Whim defines the following color keys which can be used to overwrite the system resources in Microsoft.UI.Xaml.Controls.

<Color x:Key="bar:active_workspace:background" />                       <!-- Active workspace background color -->
<Color x:Key="bar:active_workspace:foreground" />                       <!-- Active workspace foreground color -->
<Color x:Key="bar:hover:background" />                                  <!-- Mouse-over button background color -->
<Color x:Key="bar:hover:foreground" />                                  <!-- Mouse-over button foreground color -->

Backdrops

Different Whim windows can support custom backdrops. They will generally be associated with a backdrop key in the YAML/JSON configuration. The following backdrops are available:

  • none: No backdrop
  • acrylic: An acrylic backdrop
  • acrylic_thin: A more transparent Acrylic backdrop - based on the Acrylic backdrop
Type Description WinUI Documentation
none No backdrop N/A
acrylic A translucent texture that blurs the content behind it. Acrylic material
acrylic_thin A more transparent version of the Acrylic backdrop. N/A
mica An opaque, dynamic material that incorpoates theme and the desktop wallpaper. Mica has better performance than Acrylic. Mica material
mica_alt A variant of Mica with stronger tinting of the user's background color. Mica alt material

Backdrops Configuration

Property Description
type The type of backdrop to use.
always_show_backdrop By default, WinUI will disable the backdrop when the window loses focus. Whim overrides this setting. Set this to false to disable the backdrop when the window loses focus. 
backdrop:
  type: acrylic
  always_show_backdrop: true
Edit this page