api.html

---
layout: docs
permalink: developers/plugin/csharp/api/
title: 'C# API Overview'
---
<p>This is an overview of the functions available in the C# Rainmeter API. All the functions are behind a Rainmeter.API wrapper which is created using the <code>rm</code> IntPtr.</p>

<dl>
	<dt id="ReadString"><code>ReadString</code> <small><code>string ReadString(string option, string defValue, bool replaceMeasures = true)</code></small></dt>
	<dd>
		<p>Returns a string representation of an option.</p>
		<p>
			<ul>
				<li><code>option</code> : Option name to be read from the measure.</li>
				<li><code>defValue</code> : Default value for the option if it is not found or invalid.</li>
				<li><code>replaceMeasures</code> : If true, replaces section variables in the returned string.</li>
			</ul>
		</p>
		<h3>Example:</h3>
``` cs
internal void Reload(Rainmeter.API rm, ref double maxValue)
{
	// The following will replace regular variables and
	//  section variables in the 'Value' option.
	string value = rm.ReadString("Value", "DefaultValue");

	// The following will only replace regular variables,
	//  but NOT section variables like [MeasureNames].
	string action = rm.ReadString("Action", "", false);
}
```
	</dd>
	
		<dt id="ReadStringFromSection"><code>ReadStringFromSection</code> <small><span style="font-size: 0.85em;"><code>string ReadStringFromSection(string section, string option, string defValue, bool replace = true)</code></span></small></dt>
	<dd>
		<p>Returns a string representation of an option from a section.</p>
		<p>
			</p><ul>
				<li><code>section</code> : Section name to read the option from.</li>
				<li><code>option</code> : Option name to be read from the measure/meter.</li>
				<li><code>defValue</code> : Default value for the option if it is not found or invalid.</li>
				<li><code>replace</code> : If true, replaces section variables in the returned string.</li>
			</ul>
		<p></p>
		<h3>Example:</h3>
``` cs
internal void Reload(Rainmeter.API rm, ref double maxValue)
{
	// The following will replace regular variables and
	//  section variables in the 'Value' option.
	string value = rm.ReadStringFromSection("Section","Option", "DefaultValue");

	// The following will only replace regular variables,
	//  but NOT section variables like [MeasureNames].
	string action = rm.ReadStringFromSection("Section", "Action", "", false);
}
```
	</dd>
	
	<dt id="ReadInt"><code>ReadInt</code> <small><code>int ReadInt(string option, int defValue)</code></small></dt>
	<dd>
		<p>Retrieves the option defined in the skin file and converts it to an integer.</p>
		<p>
			<ul>
				<li><code>option</code> : Option name to be read from the measure.</li>
				<li><code>defValue</code> : Default value for the option if it is not found, invalid, or a formula could not be parsed.</li>
			</ul>
		</p>
		<h3>Example:</h3>
``` cs
internal void Reload(Rainmeter.API rm, ref double maxValue)
{
	int value = rm.ReadInt("Value", 20);
}
```
	</dd>
	
<dt id="ReadIntFromSection"><code>ReadIntFromSection</code> <small><code>int ReadIntFromSection(string section, string option, int defValue)</code></small></dt></code></small></dt>
	<dd>
		<p>Retrieves the option defined in a section and converts it to an integer.</p>
		<p>
			</p><ul>
				<li><code>section</code> : Section name to read the option from.</li>
				<li><code>option</code> : Option name to be read from the measure/meter.</li>
				<li><code>defValue</code> : Default value for the option if it is not found, invalid, or a formula could not be parsed.</li>
			</ul>
		<p></p>
		<h3>Example:</h3>
``` cs
internal void Reload(Rainmeter.API rm, ref double maxValue)
{
	int value = rm.ReadIntFromSection("Section", "Option", 20);
}
```
	</dd>
	
	<dt id="ReadDouble"><code>ReadDouble</code> <small><code>double ReadDouble(string option, double defValue)</code></small></dt>
	<dd>
		<p>Retrieves the option defined in the plugin measure in the skin file and converts it to a double type.</p>
		<p>
			<ul>
				<li><code>option</code> : Option name to be read from the plugin measure.</li>
				<li><code>defValue</code> : Default value for the option if it is not found, invalid, or a formula could not be parsed.</li>
			</ul>
		</p>
		<h3>Example:</h3>
``` cs
internal void Reload(Rainmeter.API rm, ref double maxValue)
{
	double value = rm.ReadDouble("Value", 20.0);
}
```
	</dd>
	<dt id="ReadDoubleFromSection"><code>ReadDoubleFromSection</code> <small><code>double ReadDoubleFromSection(string section, string option, double defValue)</code></small></dt>
	<dd>
		<p>Retrieves the option defined in any section and converts it to a double type.</p>
		<p>
			</p><ul>
				<li><code>section</code> : Section name to read the option from.</li>
				<li><code>option</code> : Option name to be read from the measure/meter.</li>
				<li><code>defValue</code> : Default value for the option if it is not found, invalid, or a formula could not be parsed.</li>
			</ul>
		<p></p>
		<h3>Example:</h3>
``` cs
internal void Reload(Rainmeter.API rm, ref double maxValue)
{
	double value = rm.ReadDoubleFromSection("Section", "Option", 20.0);
}
```
	</dd>

	</dd>
	<dt id="ReadPath"><code>ReadPath</code> <small><code>string ReadPath(string option, string defValue)</code></small></dt>
	<dd>
		<p>Retrieves the option defined in the skin file and converts a relative path to a absolute path.</p>
		<p>
			<ul>
				<li><code>option</code> : Option name to be read from the measure.</li>
				<li><code>defValue</code> : Default value for the option if it is not found or invalid.</li>
			</ul>
		</p>
		<h3>Example:</h3>
``` cs
internal void Reload(Rainmeter.API rm, ref double maxValue)
{
	string path = rm.ReadPath("MyPath", "C:\\");
}
```
	</dd>
	<dt id="Execute"><code>Execute</code> <small><code>void Execute(IntPtr skin, string command)</code></small></dt>
	<dd>
		<p>Executes an <a href="/manual/skins/option-types/#Action">action</a>.</p>
		<p>
			<ul>
				<li><code>skin</code> : Pointer to current skin (see <a href="!plugin/csharp/api/#GetSkin">GetSkin</a>).</li>
				<li><code>command</code> : Action to execute.</li>
			</ul>
		</p>
		<h3>Example:</h3>
``` cs
internal double Update(IntPtr data)
{
	Measure measure = (Measure)data;

	// 'mySkin' stored previously in the Initialize function
	API.Execute(mySkin, L"[!SetVariable SomeVar 10]");

	return 0.0;
}
```
	</dd>
	<dt id="ReplaceVariables"><code>ReplaceVariables</code> <small><code>string ReplaceVariables(string str)</code></small></dt>
	<dd>
		<p>Returns a string, replacing any variables (or section variables) within the inputted string.</p>
		<p>
			<ul>
				<li><code>str</code> : String with unresolved variables.</li>
			</ul>
		</p><h3>Example:</h3>
``` cs
internal double Update()
{
	string myVar = ReplaceVariables("#MyVar#").ToUpperInvariant();

	if (myVar == "SOMETHING") { return 1.0; }
	return 0.0;
}
```
	</dd>
	<dt id="GetMeasureName"><code>GetMeasureName</code> <small><code>string GetMeasureName()</code></small></dt>
	<dd>
		<p>Retrieves the name of the measure.</p>
		<h3>Example:</h3>
``` cs
internal void Initialize(Rainmeter.API rm)
{
	myName = GetMeasureName();  // declare 'myName' as a string in class scope
}
```
	</dd>
	<dt id="GetSkin"><code>GetSkin</code> <small><code>IntPtr GetSkin()</code></small></dt>
	<dd>
		<p>Retrieves an internal pointer to the current skin.</p>
		<h3>Example:</h3>
``` cs
internal void Initialize(Rainmeter.API rm)
{
	mySkin = GetSkin();  // declare 'mySkin' as a IntPtr in class scope
}
```
	</dd>
	<dt id="GetSkinName"><code>GetSkinName</code> <small><code>string GetSkinName()</code></small></dt>
	<dd>
		<p>Retrieves full path and name of the skin.</p>
		<h3>Example:</h3>
``` cs
internal void Initialize(Rainmeter.API rm)
{
	// declare 'skinName' as a string in class scope
	skinName = GetSkinName();
}
```
	</dd>
	<dt id="GetSkinWindow"><code>GetSkinWindow</code> <small><code>IntPtr GetSkinWindow()</code></small></dt>
	<dd>
		<p>Returns a pointer to the handle (HWND) of the skin window.</p>
		<h3>Example:</h3>
``` cs
internal void Initialize(Rainmeter.API rm)
{
	// declare 'skinWindow' as a IntPtr in class scope
	skinWindow = GetSkinWindow();
}
```
	</dd>
	<dt id="GetSettingsFile"><code>GetSettingsFile</code> <small><code>string GetSettingsFile()</code></small></dt>
	<dd>
		<p>Retrieves a path to the Rainmeter data file (Rainmeter.data).</p>
``` cs
internal void Initialize(Rainmeter.API rm)
{
	// declare 'rmDataFile' as a string in global scope
	if (rmDataFile == null) { rmDataFile = GetSettingsFile(); }
}
```
	</dd>
	<dt id="Log"><code>Log</code> <small><code>void Log(LogType type, string message)</code></small></dt>
	<dd>
		<p>Sends a message to the Rainmeter log.</p>
		<p>
			<ul>
				<li><code>type</code> : Log level (<a href="https://github.com/rainmeter/rainmeter-plugin-sdk/blob/master/API/RainmeterAPI.cs#L80-L86">API.LogType.Error, API.LogType.Warning, API.LogType.Notice, or API.LogType.Debug</a>)</li>
				<li><code>message</code> : Message to be logged.</li>
			</ul>
		</p>
		<h3>Example:</h3>
``` cs
API.Log(API.LogType.Notice, "I am a 'notice' log message with a source");
```
	</dd>
	<dt id="LogF"><code>LogF</code> <small><code>void LogF(LogType type, string format, params string[] args)</code></small></dt>
	<dd>
		<p>Sends a formatted message to the Rainmeter log.</p>
		<p>
			<ul>
				<li><code>type</code> : Log level (<a href="https://github.com/rainmeter/rainmeter-plugin-sdk/blob/master/API/RainmeterAPI.cs#L80-L86">API.LogType.Error, API.LogType.Warning, API.LogType.Notice, or API.LogType.Debug</a>)</li>
				<li><code>format</code> : Formatted message to be logged, follows <a href="https://learn.microsoft.com/dotnet/standard/base-types/composite-formatting">composite formatting</a>.</li>
				<li><code>args</code> : Comma separated list of arguments referenced in the formatted message.</li>
			</ul>
		</p>
		<h3>Example:</h3>
``` cs
string notice = "notice";
API.LogF(API.LogType.Notice, "I am a '{0}' log message with a source", notice);
```
	</dd>
</dl>