CoolMon 2 : SDKGeneral

General Plugin

A general plugin will serve up information for CM2 by exporting one or more sensors to CM2, when writing this type of plugin you must give some thought to what you want to make available for CM2 to poll. It would also be wise to think about how many polling sensors you want. What parameter each of these will require in order to function. In theory you can export just one sensor sending different information back depending entirely on parameters. But it would be smart (and easier for the user to use) if you export a sensor for every major thing and then use parameters for minor thing about it, say altering data, this could for example be rounding a number.


The Functions
Function SetParentHandle(Handle: THandle)...
Some plugin might need a handle to the parent form in order to push message boxes etc. This you can get in the function, it will be ran when your plugin is loaded. Just remember to save the value.

Function GetSensorCount(OUT SensorCount: Integer)...
Provide the sensor count your plugin exports.

Function GetSensorNameOnly(Index: Integer; OUT SensorName: PChar; OUT SensorStyle: Byte)...
A quick informative function ran at start up, you must provide the “SensorName?” and “SensorStyle?” for the sensor at “index”. If you sensor returns a Numeric value set sensor style to “0”, if it returns a Non-Numeric value set it to “1” or if it’s unknown return “2”. The last one should only be used for sensors which output type is determined by parameters.

Function GetSensor(Index: Integer; Parameters: PChar; OUT SensorName: PChar; OUT SensorStyle: byte; OUT SensorString: PChar; OUT SensorValue: Double)...
The actual function used when CM2 is polling a sensor.
Index is the sensor CM2 is polling
parameters are of course the parameters passed. Since CM2 has to send multiple parameters using only one string it will be send like this “aName=aValue|Min=0|Max=100”, then you will have to cut it down into relevant bits.
Now to the “OUT” properties
SensorName = The sensor name
SensorStyle = 0 if the result is a Number, 1 if it’s Non-numeric – Unknown (2) is not allowed in the actual polling of the sensor.
SensorString = The result if it’s Non-numeric
SensorValue = The result if it’s numeric
The Default and Optional Lists
The GetDefault, GetDefaultCount, GetOptional and GetOptionalCount are used to pass information about the various parameters.

You will have to provide it for a certain sensor, which will be passed in “Index”. The Default list are the parameters that the sensor MUST have in order to function properly and the optional list is what can be used but aren’t crucial to the sensor

Other than that the lists works just like the info list, except they also have a description item which of course should be used to inform the user of what exactly that parameter will do.

Function GetDefaultCount(SensorIndex: Integer; OUT DefaultCount: Integer)...
Provide the Default parameter count for the sensor at “sensorindex”.

Function GetDefault(SensorIndex: Integer; Index: Integer; OUT Name: Pchar; OUT Value: PChar; OUT Description: PChar)...
Provide the list item at “Index” for the sensor at “SensorIndex”. “Name” is the name of the parameter, “Value” is the default value for the parameter and “Description” is a small description of the parameter.

Function GetOptionalCount(SensorIndex: Integer; OUT OptionalCount: Integer)...
Provide the Optional parameter count for the sensor at “sensorindex”.

Function GetOptional(SensorIndex: Integer; Index: Integer; OUT Name: Pchar; OUT Value: PChar; OUT Description: PChar)...
Provide the list item at “Index” for the sensor at “SensorIndex”. “Name” is the name of the parameter, “Value” is the default value for the parameter and “Description” is a small description of the parameter.

Using the Editor Support Interface
You can extend your plugin to take advantage of the features in the WYSIWYG editor. To do that you must implement the Editor Support interface (for General Plugins) into your plugin. In order to do that you must export the following functions.

Function ShowSensor(Index: Integer; OUT ShowAt: Byte)...
This function will allow you to hide a sensor from the editor. For example sensors you want to use for debugging your plugin. Index will refer to the sensor number, ShowAt will either be

saDesignTime - The sensor will show in the editor
saRunTimeOnly - The sensor will not show in the editor

Function ObjIns(SensorIndex: Integer; ParameterName: PChar; OUT ValueType: Byte; OUT ValueRange: PChar)...
The function will allow you to take advantage of the object inspector (OI) in the WYSIWYG editor.

SensorIndex - Then Index of sensor in question
ParameterName - The name of the parameter to which the valuetype and Valuerange must be supplied
ValueType
ValueRange
This depends on what the Valuetype is

The following only works in ICM2EditorSupport20

Menu Items in the editor
In Outlaw Ed you can create custom menuitems in the popupmenu for your plugin. (IE. For General plugins :: When the user selects a created sensor (from your plugin)in the content listview on the OI window and and brings up the popupmenu). You can put in whatever you feel is necessary in the menu, but the return value must be valid CML, this will be added under the parameter segment of the sensor item clicked on.

To work with the menuitems there are 3 functions that you need to master.

Function GetMenuCount(SensorIndex: Integer; OUT MenuCount: Byte)...
This will be used when Outlaw Ed needs to know how many menuitems you want to add to the contentmenu. Just return the value in MenuCount.

NB: The menu items can be different depending on the SensorIndex, SensorIndex tells you what sensor Outlaw Ed needs the menu items count for.

Function GetMenuItem(SensorIndex: Integer; Index: Byte; OUT MenuTitle: PChar; OUT MenuHint: PChar)...
This is used to get the specific menu item informtion. SensorIndex is the sensor selected in Outlaw Ed, Index is the item needed, MenuTitle is the title (caption) that will appear on your custom menuitem and MenuHint is what will appear on the statusbar in the main window as help text.

Function OnMenu(SensorIndex: Integer; Index: Byte; OUT ResultString: PChar)...
This one is triggered, when the user clicks the custom menuitem. SensorIndex is the sensor selected in Outlaw Ed, Index is the menuitem that was clicked, ResultString here you can add CML code to extend the users config. If you do not wish to do so, leave it empty.

Custom Property Editors
As a new thing, you can in Outlaw Ed make your own property editors. Property Editors are what pops up when the user clicks the "..." button in the object inspector. By default file, font, color etc. are hardcoded into the editor, but if you feel you need something a little more advanced, you can write your own. So when the users clicks the "..." button it will launch a property editor from your plugin to help guide the user through the setup. To get Outlaw Ed to display the "..." button in the first place you need to return the value vtEditor (IE. 7) in the ObjIns function.

Function OnEditor(SensorIndex: Integer; ParameterName: PChar; FullParameterValues: PChar; OUT Value: PChar)...
This is the function that is ran when the user clicks the "..." button on the OI parameter field. You yourself must design the dialogs and show them.
SensorIndex is the sensor selected in Outlaw Ed, ParameterName is the parameter the user is working on and thus what parameter you need to display your property editor, FullParameterValues this is a list of all parameters (with values) currently associated to the sensor, it's supplied if you require information from another parameter to help work the Property Editor (Eg. if your sensor does something within a file and you need the filename to provide your options). Value this will hold the value to ParameterName and you must pass your new value back when your Property editor is done.