C# plugin API

Vitalij edited this page Dec 20, 2013 · 4 revisions
Clone this wiki locally

Classes

The C# plugin API is split into three classes.

  • PluginExample.Measure class - Represents a single plugin measure. Methods and members are specific to a single measure.
  • PluginExample.Plugin class - Binds the Measure class to the low-level Rainmeter C-based API.
  • Rainmeter.API class - Implements methods to query and control Rainmeter. The API.Log method is the only thread-safe function -- other methods should not be called in secondary threads.

The implementation is rather simple: Rainmeter calls methods of the Plugin class, which then finds and calls the correct Measure object. For more detailed information about the low-level C-based API, check the C++ documentation.

Plugin methods

  • Measure.Measure (constructor) and Plugin.Initialize: Called when a measure is created (i.e. when Rainmeter is launched or when a skin is refreshed). Initialize your measure object here.
  • Measure.Reload and Plugin.Reload: Called when the measure settings are to be read directly after Initialize. If DynamicVariables=1 is set on the measure, Reload is called on every update cycle (usually once per second). Read and store measure settings here. To set a default maximum value for the measure, assign to maxValue.
  • Measure.Update and Plugin.Update: Called on every update cycle (usually once per second). Return the numerical value for the measure here.
  • Measure.GetString and Plugin.GetString: Called on-demand (in other words, may be called multiple times or not at all during a update cycle). Return the string value for the measure here. Do not process data or consume CPU time in this function. In most cases, you should process data, assign the result to a string, and return it in GetString. If the plugin returns only numerical values, do not implement GetString. Check the PluginSystemVersion in the SDK for an example.
  • Plugin.Finalize: Called when the measure is destroyed. If you need to free resources, you may want to implement a Measure.Cleanup method and call it from Plugin.Finalize (instead of waiting for the destructor to fire).

API functions

Plugins can import and use the following functions.

  • API.ReadString

    Returns a string representation of an option.

    string RmReadString(string option, string defValue, bool replaceMeasures)

    • option: Option name.
    • defValue: Default value for option (returned if option is not found).
    • replaceMeasures: If TRUE, replaces [MeasureNames] in returned string.
  • API.ReadPath

    Returns a string representation of an option. If the option is an absolute path to a folder or file, it is returned as is. If the option is a relative path, a converted absolute path is returned.

    string RmReadPath(string option, string defValue)

    • option: Option name.
    • defValue: Default value for option (returned after conversion to absolute path if option is not found).
  • API.ReadDouble

    Returns a double representation of an option. If the option is a formula, the return value is the result of the parsed formula.

    double ReadDouble(string option, double defValue)

    • option: Option name.
    • defValue: Default return value (returned if option is not found or if formula could not be parsed).
  • API.ReadInt

    Returns a int representation of an option. If the option is a formula, the return value is the result of the parsed formula.

    int ReadInt(string option, int defValue)

    • option: Option name.
    • defValue: Default return value (returned if option is not found or if option is not an integer).
  • API.GetMeasureName

    Returns the name of the current measure.

    string GetMeasureName()

  • API.GetSkin

    Returns an internal pointer to the current skin.

    IntPtr GetSkin()

  • API.GetSettingsFile

    Returns the settings file.

    string GetSettingsFile()

  • API.GetSkinName

    Returns the name of the skin.

    string GetSkinName()

  • API.GetSkinWindow

    Returns the HWND of the skin window.

    IntPtr GetSkinWindow()

  • API.Execute

    Executes a command.

    void RmExecute(IntPtr skin, string command)

    • skin: Pointer to current skin (obtained from GetSkin()).
    • command: Bang to execute.
  • API.Log Logs message.

    void Log(LogType type, string message)

    • type: Log level (LogType.Error, LogType.Warning, LogType.Notice, or LogType.Debug). LogType.Debug messages are logged only when Rainmeter is in debug mode.
    • message: Message to be logged.