Plugin interface

The current plugin interface isn't very pretty, but it's useable.

Getting help

Below are the basic instructions on how to create a plugin. If you get stuck or are unsure how to do something then there's a place where plugin developers hang out:

Plugin Developer's Forum

Using a plugin

The $dll function is used to access plugins.
It's syntax is: $dll([dllname],[function_number],[parameter1],[parameter2])
An example: $dll(demo.dll,5,hello,there)
This will call "function5" in demo.dll with the parameters hello and there, and then display it's output on the display.

Writing a plugin

The source to simple demo plugins are available:

in Delphi: ZIP or just main source file
in C/C++: ZIP or just main source file
in vb.net: ZIP or just main source file
in vc++.net: ZIP or just main header file
in c#: ZIP or just main source file

A plugin is a dll that is placed in the plugins subdirectory.

Non-.net plugins

The expected prototype of the exported function is (in delphi):

Function function1(param1:pchar;param2:pchar):pchar; stdcall;

The dll need not be written in Delphi, it can be written in any language.

In C the expected prototype would be:

__declspec(dllexport) char* __stdcall function1(char *param1, char *param2);

In C++ it would be:

__declspec(dllexport) extern "C" char* __stdcall function1(char *param1, char *param2);

The important thing to remember is to use the "stdcall" calling convention.

You can have up to 10 (20 in 5.3 beta3+) functions (i.e. function1 to function20).

If your plugin has a SmartieInit function (which takes no parameters and returns nothing) then it will be called when your plugin is first loaded. If your plugin has a SmartieFini function (which takes no parameters and returns nothing) then it will be called [in 5.3beta4+] just before your plugin is unloaded.

[New for 5.3 beta 4] Data from your plugin will be refreshed upto a maximum of 3 times a second (every 300ms). If you want your plugins data to be refreshed more often (or less often) then you will need to define a new API 'GetMinRefreshInterval' which returns an integer, that defines the required minimal interval in mseconds between screen data refreshes. Smartie will then use the highest value (dll provided limit, or that of the "dll check interval" setting on the Misc tab of the settings).
The expected function prototypes are:

Delphi: Function GetMinRefreshInterval: Integer; stdcall;
C: __declspec(dllexport) int __stdcall GetMinRefreshInterval()
C++: __declspec(dllexport) extern "C" int __stdcall GetMinRefreshInterval()

.net plugins

In LCD Smartie 5.3 beta 3 and above, .net plugins are supported.

Your .net assembly/dll needs to provide a public class called "LCDSmartie" with member functions called function1, function2, etc (upto function20). You only need to provide the functions you want. They need to return a String and take two Strings as parameters.

When the plugin is loaded, an instance of that class will be created (the default constructor will be called).

To load your plugin use your dll's name in the $dll command. Smartie will automatically detect that it's a .net plugin and just work.

Expected member function prototypes:

vb.net: Public Function function1(ByVal param1 As String, ByVal param2 As String) As String
VC++.net: String __gc *function1(String *param1, String *param2)
C#: public string function1(string param1, string param2)

vb.net: Public Function GetMinRefreshInterval() As Integer
VC++.net: int GetMinRefreshInterval()
C#: public int GetMinRefreshInterval()

Tips

Tip: Although only two parameters are passed, you can use more by parsing the parameters, for example $dll(demo.dll,5,param1#param2,param3) could be used and the real 1st parameter (param1#param2) could be parsed into two parameters (param1 and param2).

Tip: Although only strings are passed, you can still use numbers. You simply convert the strings into numbers, perform your calculation and then convert the result back to a string.

Tip: Plugins can return other commands in their result string, so you can define custom characters by inserting $CustomChar(...etc into your result string.

Tip: Plugins can receive display keypad presses by using a $dll command in the command part of an action; i.e. set an action so when a specific button is pressed it calls the plugin.

Tip: Plugins can cause actions to happen, place a $dll command in the condition part of an action.

Tip: Plugins can be used in the command part of an action - the string it returns will be parsed as an action [So if the plugin returns WAPlay then winamp will play...

TIP: Catch all exceptions in your code and return a string as usual - allowing an exception to escape into Smartie's code will cause a crash.

Warning: Your dll will be called when ever the screen that references your dll is displayed and as often as the "DLL check interval" on the Misc settings tab (or your dll's limit if it's higher, which defaults to 300ms). It's wise not to do any work that will take a long period of time because the whole of smartie will be blocked until the function returns. It's best to create a thread to do the real work, and the exported function simply copys out the cached result.