Inline options on a String meter are used to add or modify character formatting features to all or part of a string displayed by the meter.
This has three primary purposes:
- Changing the inline format of part of the string. What this means is that you might have two or more FontFace, FontSize or FontColor (or other) settings in a string, without needing to use multiple meters and relative positioning.
- Adding some Direct2D character formatting features to the String meter. These include things like more robust control of the Weight of the font, new style features like Character Spacing, Oblique, Underline and Strikethrough, and control of Stretch and Typography features when used with supporting fonts.
- Support for a color Gradient on part or all of the string.
Inline options are defined by pairs of InlineSetting ... InlineSettingN and InlinePattern ... InlinePatternN options on the meter. InlineSettingN defines the character formatting setting you wish to add or change, and the matching InlinePatternN uses regular expressions to define the part of the string you wish to change. These must be matching pairs, and there may not be missing N number postfixes in InlineSetting, which start with 2.
The inline formatting is applied to the final string as it will be displayed by the meter, reflecting the value of any measures bound to the meter with MeasureNameN, any Text option on the meter, and any string manipulation applied with other meter options like StringCase, Percentual or NumOfDecimals.
While not required,
AccurateText=1 should be set in the [Rainmeter] section of the skin, to ensure that the formatting is done on fonts using proper D2D font spacing and metrics.
This takes the form of the setting name to be added, a (pipe) character, and the value for the setting.
InlineSetting=Size | 12
- Face font family name.
This uses the same values as the setting for FontFace on the meter.
- Size numeric point size.
This uses the same values as the setting for FontSize on the meter.
- Color rrr,ggg,bbb,aaa or RRGGBBAA color code.
This uses the same values as the setting for FontColor on the meter.
- Weight numeric value in the range 1-999..
The following are common values and their meanings. If the value is supported by the font family, it will be used. If not, the closest value that is supported by the font family will be used.
100 - Thin (Hairline)
200 - Extra Light (Ultra Light)
300 - Light
400 - Regular (Normal)
500 - Medium
600 - Semi Bold (Demi Bold)
700 - Bold
800 - Extra Bold (Ultra Bold)
900 - Black (Heavy)
950 - Extra Black (Ultra Black)
If the font does not support any additional weights, then 500 and below will use the font's normal weight, and 600 and above will simulate a bold effect.
- Case One of the following string case options:
Lower - All characters lower case
Upper - All characters upper case
Proper - First character of each word upper case, the balance lower case
Sentence - First character of each sentence upper case, the balance lower case
- CharacterSpacing Leading | Trailing | Minimum Advance Width
Defines the inter-character spacing for part or all of the string. Leading and Trailing may be any positive or negative integer or fractional number. The value is based on DIP (Device-Independent-Pixels), and does not have to be an integer. Minimum Advance Width must be a positive integer. Any value may be set to an asterisk * to ignore.
InlineSetting=CharacterSpacing | 2 | 2
That will increase the leading space before characters and the trailing space after characters by 2 DIP.
Uses Italic characters in part or all of the string. No parameter required. This will be simulated by Rainmeter if not supported by the font family.
Uses Oblique characters in part or all of the string. No parameter required. This will be simulated by Rainmeter if not supported by the font family.
Used to Underline characters in part or all of the string. No parameter required.
Strikethroughcharacters in part or all of the string. No parameter required.
- Shadow X Offset | Y Offset | Blur Amount | Color
Used to create a Drop Shadow on all or part of the string.
X Offset - Number of positive (right) or negative (left) pixels to offset the shadow from the string.
Y Offset - Number of positive (below) or negative (above) pixels to offset the shadow from the string.
Blur Amount - Amount of blur transition in pixels. The number of pixels used to transition the shadow from solid to fully transparent. The value is based on DIP (Device-Independent-Pixels), and does not have to be an integer.
Color - rrr,ggg,bbb,aaa or RRGGBBAA color code. The alpha component of the shadow color is multiplied with the alpha component of the string color.
InlineSetting=Shadow | 2 | 2 | 3.5 | 150,150,150,200
Note: The shadow effect does not change the size or position of the overall meter, and you should ensure that the meter is sized and positioned appropriately to display the shadow without clipping. The overall amount that the shadow effect impacts the desired meter size is a function the font size, the offset amounts and the blur amount.
- Stretch one of 9 numeric compressed / expanded values if supported by the font.
The following values can be set. If the value is supported by the font family, it will be used. If not, the closest value that is supported by the font family will be used.
1 - Ultra-Condensed
2 - Extra-Condensed
3 - Condensed
4 - Semi-Condensed
5 - Normal
6 - Semi-Expanded
7 - Expanded
8 - Extra-Expanded
9 - Ultra-Expanded
Note: There are relatively few fonts that support alternative stretch values for glyphs. In many cases the CharacterSpacing setting might be a better choice to get a similar "wide" or "compressed" effect.
- Typography one of 80 Typography codes.
Used to select alternative glyphs in a font, these must be explicitly supported by the font being used. A few common examples might be:
smcp - Small Capitals
onum - Old Style Figures
sups - Superscript
subs - Subscript
cpsp - Capital Spacing
ss01 - Stylistic Set 1
ss02 - Stylistic Set 2
Note that a few Typography codes support an additional second parameter which is a numeric index to a variant of the code. If that is required, the format
Typography | code | indexshould be used.
A full list of supported codes can be found at Font Features
- GradientColor Angle | Color ; Percentage | Color ; Percentage | ...
Defines a color gradient, at any angle, to be used on the selected text. This can consist of two or more colors as desired, with percentage points being used to define transition points for each color.
This takes the form of the Angle for the gradient in degrees, a pipe character, then a series of Color codes, a ; semi-colon, and a Percentage from 0.0 to 1.0 to define the position of the color in the text. Each series of Color ; Percentage are separated by a pipe character.
InlineSetting=GradientColor | 180 | 255,0,0,255 ; 0.0 | 0,255,0,255 ; 0.5 | 0,0,255,255 ; 1.0
That will define a gradient at 180 degrees. It will start with a color of 255,0,0,255 (red) at percentage 0.0 (the start), will transition to a color of 0,255,0,255 (green) at percentage 0.5 (50 percent), and to 0,0,255,255 (blue) at percentage 1.0 (100 percent).
While you can have as many sets of Color ; Percentage as desired, you must have a minimum of two to create a gradient. The percentage points define the point where the color will be exactly the associated color code. Think of it as the "center" of the color as it transitions toward and away from the defined color code.
Alpha transparency can be used to create a gradient fade effect on the text.
The Angle is defined as any number of degrees, with 0 or 360 starting directly to the right and rotating clockwise. This results in the following gradient directions on the text:
0 (360) - Right to Left
90 - Bottom to Top
180 - Left to Right
270 - Top to Bottom
If a string is displayed on more than one line in the meter, due either to wrapping with ClipString=2, or literal linefeed characters or #CRLF# variables being embedded in the string, any selected text that spans the linefeed will have the GradientColor setting applied to it separately on each line. Gradients will not "wrap".
Most fonts have extra space above or below (or both) the actual character "glyph" in the font. This will vary from font to font. The gradient will be applied to the entire font character including the invisible extra space, so particularly when creating gradients that are vertical in direction, some tweaking of the percentage points may be required to have the gradient position as desired on the text. Hint: Nothing says that the first point must be 0.0 and the last point must be 1.0.
Note: An alternative form of GradientColor, GradientColor1, can be used. This uses the same setting values as GradientColor, but interpolates the gradient using an alternative method of handling gamma correction. In some cases you may find this makes for a smoother or brighter gradient transition.
InlineSetting=None, no setting will be applied. This is generally going to be used with the !SetOption bang, in order to dynamically "turn off" and "turn on" a particular setting. Using a !SetOption that sets the value to "" will as always "remove" the option entirely, and as there can't be "missing" or "skipped" InlineSettingN numbers, all subsequent ones will be ignored.
- Face font family name.
InlinePattern3... A Regular Expression - Default
A Perl Compatible Regular Expression (PCRE) used to define all or part(s) of the string to which to apply the corresponding InlineSettingN.
If (parentheses) are used to capture parts of the string, then that is what the setting will be applied to. If (parentheses) are not used, then the part(s) of the string that match the regular expression will be used.
InlinePattern=.*(default) is how you would simply add or change a setting on the entire string.
The full range of PCRE regular expression functionality is supported, so the pattern can match on all or part of the meter's string value. Logical OR and AND matching can be done in the regular expression, using the
|character to support OR and Lookahead assertions
(?=..)to support AND.
Reserved characters in regular expression, which are
|must be escaped with the
\character when used as a literal in the
InLinePatternoption. If using a measure value as a section variable in the option, the :EscapeRegExp modifier can be used to properly escape reserved characters in the measure.
If the !SetOption bang is being used to dynamically "turn off" and "turn on" an InlinePattern,
InlinePattern=^$should be used to indicate "nothing", as Using a !SetOption that sets the value to "" will as always "remove" the option entirely, and this will set it to the default of
.*, or the entire string.
Using that string defined in [MeasureString], let's look at each of our InlineSetting / InlinePattern options.
InlineSetting=Weight | 700
We are starting at the beginning of the string, and (capturing) all characters until we reach a space and the word "is". That will change the Weight of the word "This" at the start of the string to Bold.
We are searching for the phrase "test string", and applying the Oblique style to it.
We are searching for the same phrase "test string", and applying the Underline style to it. So "test string" will be both Oblique and Underline.
InlineSetting4=Size | 17
We are capturing any parts of the string that are three consecutive numeric digits. This will change the font Size of both "123" and "456" to 17.
InlineSetting5=Color | 255,97,97,255
InlinePattern5=colors like (.*) and
We are capturing the part of the string that is after "colors like ", and before " and". This will change the font Color of the word "red" to 255,97,97,255.
InlineSetting6=Color | 117,199,235,255
InlinePattern6=colors like .* and (.*)\.
We are capturing the part of the string that is after "colors like ", Then after " and ". This will change the font Color of the word "blue" to 117,199,235,255.
InlineSetting7=Face | Segoe Script
InlinePattern7=colors like .* and (.*)\.
We are again capturing the part of the string that is after "colors like ", Then after " and ". This will change the font Face of the word "blue" to Segoe Script.
InlineSetting8=GradientColor | 180 | 57,204,79,255 ; 0.0 | 250,247,157,255 ; 1.0
We are defining a GradientColor for the word "GreenToYellow" that will transition from 57,204,79,255 (green) to 250,247,157,255 (yellow) at an angle of 180 degrees (left to right).