Plugins - HowTo

NOTE: After GOverlay 1.5, for the 3.5'' Device, check the new examples on the Plugins folder of GOverlay. The plugin system has been rewritten for 3.5''.

We will be creating a demo plugin with one element to display a text on screen that will say "Hello World" or "Bye World" depending on what the user selected on the element configuration.
The user will also be able to append some text to this textstring by writing it in his plugin options.

Create a new project on your Visual Studio as "Class Library" and make sure the .NET Framework is 3.5 or lower.

Set your Application Asembly name to "DemoPlugin" and Root Namespace to "GOverlayPlugin.Demo"

1. Define the basic functions with your plugin name and description

The plugins work thru a couple of functions that interact with GOverlay, you must define them all for the plugin to work with GOverlay.

First, you have to add the interfaces.dll in your project as a reference, once done, you have to implement the plugin in your project and define the basic functions that will inform GOverlay whats our plugin about:

Implements GOverlayPlugin.Interfaces.IPlugin
Private objHost As GOverlayPlugin.Interfaces.IHost

   Public Sub Initialize(ByVal Host As GOverlayPlugin.Interfaces.IHost) Implements GOverlayPlugin.Interfaces.IPlugin.Initialize
        objHost = Host
   End Sub

   Public ReadOnly Property Name() As String Implements GOverlayPlugin.Interfaces.IPlugin.Name
        'Return your plugin name
            Return "Demo Plugin"
        End Get
   End Property

   Public ReadOnly Property Display() As String Implements GOverlayPlugin.Interfaces.IPlugin.Display
        'Return the display this plugin belongs to
            Return "lcdsys"
        End Get
   End Property

   Public ReadOnly Property Description() As String Implements GOverlayPlugin.Interfaces.IPlugin.Description
        'Return the description of this plugin
            Return "This is a demo plugin"
        End Get
   End Property

2. Define the CallBack function

First define the CallBack function that will be used in the next versions of GOverlay.

Function CallBack(method As String) As Hashtable Implements GOverlayPlugin.Interfaces.IPlugin.CallBacks
        'Not available Yet
End Function

3. Create your own custom ComboBoxes for use with your plugin

Now you must define the function that will hold your custom ComboBoxes
This ComboBoxes will be available for your plugin configuration and for your elements configuration.
We will need a ComboBox to select if the plugin will display a text "Hello World" or a text "Bye World", you can define it in here as:

Function ComboBoxes() As Hashtable Implements GOverlayPlugin.Interfaces.IPlugin.ComboBoxes
        'Create custom ComboBox for your configuration to use
        Dim boxes As New Hashtable
        Dim myboxOptions As New Hashtable
        'Set each one of the Combobox options as value, Display Name
        myboxOptions.Add("text1", "Display Hello World")
        myboxOptions.Add("text2", "Display Bye World")

        'Add the combobox options as the combobox "DEMO.textSelector"
        boxes.Add("DEMO.textSelector", myboxOptions)
        Return boxes
End Function
Now goverlay will be able to display a ComboBox when requested that will have two options "Display Hello World" and "Display Bye World" and will report the result as "text1" or "text2" when the user picks one.
This ComboBox will be called as "DEMO.textSelector".

4. Create your plugin options

Now you need to define the options your plugin will have, this options will be configured when the user decides to enable your plugin and will be available for all the added sensors.

Public Function PluginOptions(pluginCurrentOptions As Hashtable) As Hashtable Implements GOverlayPlugin.Interfaces.IPlugin.PluginOptions
        'Set the options the user will have when going to the plugins tab and clicking on your plugin
        'The availalbe option_type are the same as CreateOptions function
        Dim options As New Hashtable
        'Option: option_index as integer, option_data as ArrayList
        'Option_Data: option_type as string, option_label as string, option_name as string (no spaces, no _)
        options.Add(0, New ArrayList({"ComboYesNo", "Append Text", "appendyesno"}))
        options.Add(1, New ArrayList({"Text", "Append to the text", "append"}))
        Return options
End Function
So now when the user goes to enable the plugin, he will also see a selection to select if he will want to append a text to our "Hello World" or "Bye World" text and a box with a textbox to enter any text named "Append to the text".

5. Set the default plugin options

Now that we have options we are going to use, we must define the default values in case the user doesnt change anything, we do so in our SetDefaultOptions function.
By default the user will be appending no text to the 'Hello World" or "Bye World".

Public Function PluginOptionsDefault() As Hashtable Implements GOverlayPlugin.Interfaces.IPlugin.PluginOptionsDefault
        'Set the default values you want to have on plugin, if the user doesnt change any option, he will have this settings
        Dim options As New Hashtable
        options("appendyesno") = "No"
        options("append") = ""
        Return options
End Function
We define our previously created options with their default values, since we had one option named "appendyesno", we also define it in here with the default value for a ComboYesNo, in this case, the value will be "No".
We also define our second created option "append" with the default value of an empty string.

6. Set your available elements/sensors

Now we will tell goverlay the available elements the user will have to select to add to his screen, in this case the user will just have one and we will name it "Hello World", but if the user selected to append a text to our hello world, we will also show that text, this will show how to access your plugin options.

Function AvailableSensors(pluginOptions As Hashtable) As Hashtable Implements GOverlayPlugin.Interfaces.IPlugin.AvailableSensors
        'Create the list of the sensors/elements this plugin has
        'You can access your pluginOptions here as pluginOptions(your_option)    

        'Options: SensorTag, Sensor Display-Name
        Dim sensors As New Hashtable

        Dim moretext = ""
        If pluginOptions("appendyesno") = "Yes" Then
             moretext = pluginOptions("appendtext")
        End If

        sensors.Add("DEMO.helloworld", "Hello World: " & moretext )
        Return sensors
End Function
So we created a new element for the user to select named "Hello World:"  if the user selected not to append any text on your plugin options (this would be the default) or it will show "Hello World: MyText" if the user selected to append a text and wrote "MyText" on the plugin options appendtext box.
This element will have the ID as "DEMO.helloworld" to use it later on.

7. Configure your elements options

After the user selects our element from the list of available elements, the element will be added to the display-emulator of GOverlay, and if the user clicks on this new added element, he will have some options to configure, we will define them here.

Public Function CreateOptions(sensorId As String, elementData As Hashtable) As Hashtable Implements GOverlayPlugin.Interfaces.IPlugin.CreateOptions
        'Set the options the user will have when clicking on the element
        Dim options As New Hashtable
        If sensorId = "DEMO.helloworld" Then
            'Option: option_index as integer, option_data as ArrayList
            'Option_Data: option_type as string, option_label as string, option_name as string (no spaces, no _), help text
            options.Add(0, New ArrayList({"ColorBasic", "Color of the Text", "color", "Pick a color for your text"}))
            options.Add(1, New ArrayList({"DEMO.textSelector", "Text to Display", "textSelected", "Do you want to display HelloWorld or ByeWorld?"}))
        End If

        Return options

End Function

What we did here is to first check that the user is using the element "DEMO.helloworld" because we might have some other elements added and we want to define the configuration individually.
Then we added two element options, one to select the color the text will have on the screen and other to select if the user wants to display "Hello World" or "Bye World", remember that additionaly we will be appending a text if the user selected it on the plugin options.

8. Configure your elements options

As we did with our plugin options, we also have to define the default options for our element because the user might not configure it as well.

Public Function SetDefaultOptions(sensorId As String, elementData As Hashtable) As Hashtable Implements GOverlayPlugin.Interfaces.IPlugin.SetDefaultOptions
        'Set the default values you want to have on your sensor when its created, if the user doesnt change any option, he will have this settings

        If sensorId = "DEMO.helloworld" Then
            elementData("width") = 100
            elementData("height") = 41
            elementData("color") = 0
            elementData("textSelected") = "text1"
            elementData("width") = 50   'There must be at least one width and height set, otherwise the element wont show on the display-emulator window because it has no size
            elementData("height") = 50
        End If

        Return elementData
End Function
As we did before, we first check that the element is "DEMO.helloworld" to again check that the element we will be setting the default configuration is the proper element, if we have more, we should also check it in here to apply the configuration to the proper element.
An important note is that we ALWAYS need to set a width and height option, otherwise our newly added element will not be visible on the display-emulator.

So we add a width of 100 pixels, a height of 41 pixels and set the default color to zero, this is a White color, so by default the text displayed on the LCD will be white.
We also set our "textSelected" option as "text1" (Remember we defined a ComboBox on the step 3 that would either have the value "text1" if the user wanted to show "Hello World" or "text2" if the user wanted to show "Bye World") so by default this element will show "Hello World".

9. Draw on the screen

This is where all the magic happens, we will now draw on the screen what the user wanted to draw, it should either be:
"Hello World" if the user selected to draw Hello World (selected in the element options) without any appended text (selected in the plugin options)
"Hello World: MyText" if the user selected to draw Hello World (selected in the element options) with appended text (selected in the plugin options)
"Bye World" if the user selected to draw Bye World (selected in the element options) without any appended text (selected in the plugin options)
"Bye World: MyText" if the user selected to draw Bye World (selected in the element options) with appended text (selected in the plugin options)

Public Function DisplayOnLCD(sensorId As String, elementData As Hashtable, pluginOptions As Hashtable, cacheRuns As Integer) As ArrayList Implements GOverlayPlugin.Interfaces.IPlugin.DisplayOnLCD
'Draw on the screen

        If sensorId = "DEMO.helloworld" Then
            Dim x = elementData("x")    'grab X position of the element
            Dim y = elementData("y")    'grab Y position of the element

            Dim commandList As New ArrayList()
            Dim textToDraw as String = ""
            If elementData("textSelected") = "text1" Then
                textToDraw = "Hello World"
                textToDraw = "Bye World"
            End if

            If pluginOptions("appendyesno") = "Yes" then
                textToDraw = textToDraw & pluginOptions("append")
            End if

            'Draw Text (command as string, x as integer, y as integer, text as string, reserve_width as integer, unused as bool, unused as bool, unused as integer, basic_color as integer
            commandList.Add(New ArrayList({"text", x, y, textToDraw, 0, False, False, 0, elementData("color") }))

        End if
End Function
So once again, we first check if the element GOverlay asks to draw is our "DEMO.helloworld" element, if this is correct, what we do first is to grab the X and Y position of this element, this position matches where the user moved the box on the display-emulator.
Then we check what the user selected on his element configuration to see if he wants to draw "Hello World" or "Bye World", and after that we check if in the plugin options the user selected to append any text.

Our final step is to request GOverlay to draw all this on the screen, to do that we create a new command to draw text, we tell GOverlay on what position on the screen we will draw the text, then specify the actual text , we tell GOverlay not to reserve any space (we will not clear the line where the text is being draw) and we will use the color the user selected.

10. Checking if all worked alright

Now we can build our plugin, make sure we put the DLL in the Plugins folder of GOverlay and restart GOverlay.
We should check the GOverlay LOG tab to see if the plugin was intialized or there was any error.
We should see something like this:

7/13/2013 10:29:16 AM:Plugin Name: Demo Plugin for display: lcdsys
7/13/2013 10:29:16 AM:Plugin found: C:\GOverlay\Plugins\DemoPlugin.dll: GOverlayPlugin.DemoPlugin.Class1
7/13/2013 10:29:16 AM:Plugins - Checking: C:\GOverlay\Plugins\DemoPlugin.dll
As you can see, goverlay found our DLL in our folder, then found it was a proper plugin and got the plugin Name, so all went alright.
We should go to the Plugins tab on GOverlay and find our plugin there, we can enable it and also set our "Append text" options.
Then we can go to our OnWindows tab and we should find our plugin in there and be able to add it to the display, then we can select the added element and configure the options of color and if we want to display HelloWorld or ByeWorld

Always check the GOverlay LOG tab to see if there was any error.