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:key
s 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 backdropacrylic
: An acrylic backdropacrylic_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