It is currently March 28th, 2024, 5:02 pm

The Power of @include

Tips and Tricks from the Rainmeter Community
Post Reply
User avatar
smurfier
Moderator
Posts: 1931
Joined: January 29th, 2010, 1:43 am
Location: Willmar, MN

The Power of @include

Post by 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.

Note: I will be using the terms Parent and Child in this thread. When I speak of the Parent I am referring to the skin which called the @included while the term Child will mean the actually file we are calling.

Using @include

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

The second being the file that you're including.

Code: Select all

[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 numeric identifiers.

Code: Select all

@include=SomeFile.inc
@include2=SomeOtherFile.inc
@include3=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.

Code: Select all

[Variables]
Theme=SomeTheme
@include=#Theme#/SomeFile.inc
Understanding @include
What Rainmeter does when it reaches an @include line is that it reads the Child file then places it's contents at the bottom of the Parent skin.

Example:
SomeFile.inc

Code: Select all

[Background]
Meter=Image
H=30
W=40
YourSkin.inc

Code: Select all

@include=SomeFile.inc

[Foreground]
Meter=Image
H=20
W=30
X=5r
Y=5r
This would not work as intended as the [Background] meter would be placed after the [Foreground] meter. We can fix this by using one of @includes rules.
Manual wrote:The included file is read at the position where the @include is defined so the values from the included file with the same name as those from the .ini file will overwrite the values from previous sections and vice versa.
What this means is that if we place just the section name (in our case [Background]) of the meter or measure where we want it to be in the Parent skin, that is where that meter or measure will be.

Code: Select all

@include=SomeFile.inc

[Background]

[Foreground]
Meter=Image
H=20
W=30
X=5r
Y=5r
This fixes our issue as the contents of the [Background] section in the Child file are now placed under the same section in the skin.

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

Code: Select all

[Variables]
BackgroundImage=SomeImage.inc
HideBackground=0
Skin.ini

Code: Select all

@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.

Code: Select all

[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.

LeftMouseUpAction=[!WriteKeyValue Variables Page 2][!Refresh]

The method is exactly the same for using Stylesheets. Instead of containing meters a style sheet contains Meter Styles which define the look and feel of your skin.
User avatar
KreAch3R
Posts: 608
Joined: February 7th, 2011, 7:27 pm
Location: Thessaloniki, GR

Re: The Power of @include

Post by KreAch3R »

Very easy to read and contains some hard-to-find-together piece of info. Well done. :)
Post Reply