@Include Guide

Tip by Brian and Smurfier

While @include is a simple tool it is powerful as well. It can be used to make skin code shorter by stripping out longer code into shorter files. Repetitive code used in multiple skins can be managed with one file. It can even be used to load different code when you open a skin.

Using @include

There are several rules to using @include. The first is the @include call.

[Section]
@include=SomeFile.inc

Note: The @include call must be made within a section. Authors have generally used the [Rainmeter] or [Variables] sections when appropriate.

The second being the file that you're including.

[Variables]
SomeVariable=AValue

The file being used with @include must be formatted in the INI format, meaning that it has all the appropriate [sections] followed by Key=Value pairs. This includes using the [Variables] section.

If you want to include more than one file, they need to be listed with unique identifiers.

@include=SomeFile.inc
@include2=SomeOtherFile.inc
@includeAnotherInclude=YetAnotherFile.inc
...

While it is not required to use the .inc extension it is highly recommended. This prevents the file from appearing in Rainmeters list as a skin.

We can also use a variable to define an @include. The only caveat is that variable cannot be dynamic.

[Variables]
Theme=SomeTheme
@include=#Theme#/SomeFile.inc

Understanding @include

When Rainmeter reaches an @include line, it reads the given file, placing all unique options into any existing sections, then places the remainder of the included file after the section in which it was called.

SomeFile.inc

[Background]
Meter=Image
H=30
W=40
[String]
Text=This Won't Work

YourSkin.ini

[Variables]
@include=SomeFile.inc
[Foreground]
Meter=Image
H=20
W=30
X=5r
[String]
Meter=String
Text=This line will remain.

This would place the Background section before the Foreground section. Since the String section already exists in the main file, then any existing options won't be changed. In this case, the Text line will still read "This line will remain."

Practical Use: Skin Settings

The most common use of @include is to allow users to change the settings used by a skin in a separate file.

Settings.inc

[Variables]
BackgroundImage=SomeImage.png
HideBackground=0

Skin.ini

@include=Settings.inc
[Background]
Meter=Image
ImageName=#BackgroundImage#
Hidden=#HideBackground#

Practical Use: Pages and Stylesheets

Two of the other major uses of @include are easily switching between different pages of a skin and creating Stylesheets for your skins. Both of these uses take advantage of the fact that we can use Variables to define an @include.

Creating different pages is as easy as putting each page in it's own file and naming them in a sequence. Then in the Parent skin we need to define a variable that we will use to change the page.

[Variables]
Page=1
@include=Pages\PageNum#Page#.inc

In the parent skin we can change the page using the !WriteKeyValue bang. Just remember that after changing the Page variable we need to refresh the skin so that the new page will be loaded.

[!WriteKeyValue Variables Page 2][!Refresh]

The method is exactly the same for using Stylesheets. Instead of containing meters a style sheet contains MeterStyles which define the look and feel of your skin.