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
Get
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
Get
Return "lcdsys"
End Get
End Property
Public ReadOnly Property Description() As String Implements GOverlayPlugin.Interfaces.IPlugin.Description
'Return the description of this plugin
Get
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"
Else
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"
Else
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.