@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 |
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] |
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] |
YourSkin.ini
[Variables] |
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] |
Skin.ini
@include=Settings.inc |
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] |
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.