C++ plugin API

Brian edited this page May 14, 2013 · 7 revisions
Clone this wiki locally

Plugin functions

Rainmeter expects that a plugin exports one or more of the following functions:

  • Initialize

    Called by Rainmeter when a measure is created (i.e. when Rainmeter is launched or when a skin is refreshed).

    void Initialize(void** data, void* rm)

    • data: Pointer to a pointer, where you may allocate and store measure-specific data.
    • rm: Internal pointer that should only passed to the Rm* functions (e.g. RmReadString(rm, ...))
  • Reload

    Called by Rainmeter when the measure settings are to be read directly after Initialize. This function must be exported. If DynamicVariables=1 is set on the measure, Reload is called on every update cycle.

    void Reload(void* data, void* rm, double* maxValue)

    • data: Pointer to whatever *data was set to in Initialize.
    • rm: Internal pointer that should only passed to the Rm* functions (e.g. RmReadString(rm, ...))
    • maxValue: Pointer to a double that can be assigned to (if needed) for the default maximum value for the measure (e.g. use *maxValue = 100.0; when the measure will return values between 0.0 and 100.0). Using maxValue = 0.0; will cause the maximum value to be determined from the (highest) return value in Update. Do not set maxValue unless necessary.
  • Update

    Called by Rainmeter when a measure value is to be updated (i.e. once on each update cycle). Return the new value.

    double Update(void* data)

    • data: Pointer to whatever *data was set to in Initialize.
  • GetString

    Called when a string representation of the value is needed (possibly multiple times during each update cycle). Return a pointer to a null-terminated string only if it differs from the numerical value. For example, return a pointer to a null-terminated string if you want to return 56.0 in Update and "Fifty-six" in GetString. Do not simply return a string version of 56.0 (i.e. L"56.0"). Otherwise return NULL (or don't export the function at all) and let Rainmeter handle the number to string conversions.

    LPCWSTR GetString(void* data)

    • data: Pointer to whatever *data was set to in Initialize.
  • ExecuteBang

    Called by Rainmeter when a !CommandMeasure bang is sent to the measure. This can be used to change some data within the measure, or to interact with another application. A good example of using this function can be found in the NowPlaying plugin.

    void ExecuteBang(void* data, LPCWSTR args)

    • data: Pointer to whatever *data was set to in Initialize.
    • args: String containing the arguments to parse.
  • Finalize

    Called by Rainmeter when a measure is about to be destroyed. Perform cleanup here. This function must be exported.

    void Finalize(void* data)

    • data: Pointer to whatever *data was set to in Initialize.

Rainmeter functions

Plugins can import and use the following functions.

Note: Only RmLog is thread-safe. No other function should be used outside of the main thread.

Note: Functions that expect a rm parameter should not be called outside of Initialize or Reload.

  • RmReadString

    Returns a string representation of an option.

    LPCWSTR RmReadString(void* rm, LPCWSTR option, LPCWSTR 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.
  • RmReadPath

    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.

    __inline LPCWSTR RmReadPath(void* rm, LPCWSTR option, LPCWSTR defValue)

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

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

    __inline double RmReadDouble(void* rm, LPCWSTR option, double defValue)

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

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

    __inline int RmReadInt(void* rm, LPCWSTR option, int defValue)

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

    Returns the name of the current measure.

    __inline LPCWSTR RmGetMeasureName(void* rm)

  • RmGetSkin

    Returns an internal pointer to the current skin.

    __inline void* RmGetSkin(void* rm)

  • RmGetSettingsFile

    Returns the settings file.

    __inline LPCWSTR RmGetSettingsFile()

  • RmGetSkinName

    Returns the name of the skin.

    __inline LPCWSTR RmGetSkinName(void* rm)

  • RmGetSkinWindow

    Returns the HWND of the skin window.

    __inline HWND RmGetSkinWindow(void* rm)

  • RmExecute

    Executes a command.

    void RmExecute(void* skin, LPCWSTR command)

    • skin: Pointer to current skin (obtained from RmGetSkin).
    • command: Bang to execute.
  • RmLog Logs message.

    __inline void RmLog(int level, LPCWSTR message)

    • level: Log level (LOG_ERROR, LOG_WARNING, LOG_NOTICE, or LOG_DEBUG). LOG_DEBUG messages are logged only when Rainmeter is in debug mode.
    • message: Message to be logged.