CoolMon 2 : SDKVisual
Visual Plugin
Visual plugins are what they sound like; they are the plugin that will actually serve up the information to the user. As oppose to general plugins everything in visual plugins are parameter driven. Colour, layout, style etc. everything must be driven by parameters. This also means that there is a lot of parameter interpreting work when writing a visual plugin.Furthermore visual plugins can handle events, CoolMon 2 will pass on any events triggered within a visual plugins rectangle. In order to write event code in your plugins you must use the interface ICM2VisPlug2.
The functions
Function SetDC(CONST NewDC: THandle)...
Should the plugin for some reason be required to draw on a different form/surface then this function will be called to give your plugin a new hDC.
Function SetDimensions(Left, Top, Width, Height : Integer)...
This will give you the four values that give your plugin the rectangle within it must draw.
Function SetConfigString(NewConfigString: PChar)...
Called upon creating the visual object and again if one of the parameter values has changed. The string will contain multiple parameters formed like this.
“aName=aValue|Min=0|Max=100”
Function Redraw...
Called when, CM2 needs your plugin to redraw. It’s called right after an update or when the entire parent form needs to redraw, for what ever reason.
Function Update...
Called when, the value is updated. If Sensorstyle is “0” then the value is numeric and you updated value is in “NewValue” if the sensorstyle is “1” you’re value is non-numeric and should be extracted from the “NewString”. If Sensorstyle is anything else your plugin would be wise to trigger an error. Do this by returning “E_FAIL” as the function result.
The Default and Optional Lists
The GetDefault, GetDefaultCount, GetOptional and GetOptionalCount are used to pass information about the various parameters.
The Default list are the parameters that the plugin MUST have in order to function properly and the optional list is what can be used but aren’t crucial to the plugin.
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(OUT DefaultCount: Integer)...
Provide the Default parameter count.
Function GetDefault(Index: Integer; OUT Name: Pchar; OUT Value: PChar; OUT Description: PChar)...
Provide the list item at “Index”. “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(OUT OptionalCount: Integer)...
Provide the Optional parameter count.
Function GetOptional(Index: Integer; OUT Name: Pchar; OUT Value: PChar; OUT Description: PChar)...
Provide the list item at “Index”. “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 Visual Plugins) into your plugin. In order to do that you must export the following functions.
Function ObjIns(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.
ParameterName
The name of the parameter to which the valuetype and Valuerange must be supplied
ValueType
- 0 = Unknown.
- 1 = Fixed, causes the OI to present a dropdown list.
- 2 = Range, will cause the OI to only accept a number between the range you define.
- 3 = Color, OI will only accept a color value.
- 4 = Font, OI will present a dropdown list with fonts
- 5 = Files, OI will present a file dialog
- 6 = FontEx*, OI will present a font dialog
- 7 = Editor, OI will present a custom property editor. (Only supported in ICM2EditorSupportVis20)
ValueRange
This depends on what the Valuetype is
- 0 = set it to an empty string
- 1 = send your fixed values, separated with a line break eg. “Item1|Item2|…|…|…”
- 2 = like above but first minimum value then line break followed by the maximum value eg. “0|255”
- 5 = can be used to make a file filter - “Bmp|jpg|jpeg|png”
- 6 = None
* - FontEx type will store a full font in a string. This is the syntax
name,size,bold on/off (1/0),italic on/off (1/0),Underline on/off (1/0),Strikeout On/Off (1/0)
eg.
Arial,10,1010
That would be a Arial font size 10 which the OEM charset and Bold and underline turned on.
Color is not included since there's only 16 colors to choose from in the fontdialog.
The following only works in ICM2EditorSupportVis20
Menu Items in the editor
In Outlaw Ed you can create custom menuitems in the popupmenu for your plugin. (IE. For Visual plugins :: When the user selects a Visual object and brings up the contentmenu. 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 Content segment of the Visual Object clicked on.
To work with the menuitems there are 3 functions that you need to master.
Function GetMenuCount(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.
Function GetMenuItem(Index: Byte; OUT MenuTitle: PChar; OUT MenuHint: PChar)...
This is used to get the specific menu item informtion. 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(Index: Byte; OUT ResultString: PChar)...
This one is triggered, when the user clicks the custom menuitem. 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(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.
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, it's a standard "=|=|=" string) currently associated to the Visual Object, 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.
Writing in events
One of the most anticipated things in CM2 is the usage of events, this will really be where CM2 will set it self apart from other similar programs. Events like executing a standard windows command can be done by using a tag in the CML so you don't need to write in code to execute a windows command. The event code you should write in would be plugin extending events. Such as a where a leftclick would expand or collapse a dropdown panel. It's all controlled by the following function.
Function OnEvent(Sender: Pchar; EventType: Byte; ModKeys: Byte; X, Y: Integer; Var CallBack: Pchar)...
This function is only supported in the ICM2VisPlug2 interface so you will need to use the ICM2Visplug2 interface instead of the ICM2VisPlug in your plugin. Now for the explanation
Sender
Currently this one isn't used. But the plan is to use this as a plugin sender when you send an event to other plugin than the one clicked.
EventType
This is the type of event that has been triggered
- etUnknown – Unknown event
- etDblClick – Doubleclick
- etMouseDownLeft – Left mouse button is pressed
- etMouseDownRight – Right mouse button is pressed
- etMouseDownMiddle – Middle mouse button is pressed
- etMouseUpLeft – Left mouse button is released
- etMouseUpRight – Right mouse button is released
- etMouseUpMiddle – Middle mouse button is released
- etMouseWheelAny – Mouse scrollwheel is pushed in either direction
- etMouseWheelUp – Mouse scrollwheel is pushed forward
- etMouseWheelDown – Mouse scrollwheel is pushed backwards
- etMouseMove – Mouse is moving within plugin area.
ModKeys
Used to track modifier keys when the event is triggered.
- mksUnknown – Unknown modifier state
- mksNone – No modifier keys where pressed
- mksShift – Shift pressed
- mksAlt – Alt pressed
- mksCtrl – Control pressed
- mksAltShift – Alt and Shift are pressed
- mksAltCtrl – Alt and Control are pressed
- mksCtrlShift – Control and shift are pressed
- mksAltCtrlShift – Alt, Control and Shift are pressed
- mksAny – It doesn't matter what combo is pressed. This one is in theory only used in the CML when writing event code.
X
The X coordinate, relative to the form, the event occurred
Y
The Y coordinate, relative to the form, the event occurred
CallBack
This will allow you to send a command back to CM2 for further processing. The following CallBack commands are supported
- Repaint – Will cause CM2 to redraw the visual object.
To ease the use of embedded events for the end-user. As of core 0620 embedded events no longer needs to be setup in the CML config file they are executed automaticly by CM2, however in order to prevent usage of unnessecary CPU power, plugins will have to tell CM2 what events it would like sent.
You will need to embed the interface "CM2VisPlug3" in order to use this feature.
Function NotifyOnEvent(Var EventList: Cardinal)...
EventList is a cardinal which using flags will allow you to tell CoolMon which event you would like to be informed about.
- noeDblClick = 1;
- noeMouseDownLeft = 2;
- noeMouseDownRight = 4;
- noeMouseDownMiddle = 8;
- noeMouseUpLeft = 16;
- noeMouseUpRight = 32;
- noeMouseUpMiddle = 64;
- noeMouseWheelAny = 128;
- noeMouseWheelUp = 256;
- noeMouseWheelDown = 512;
- noeMouseMove = 1024;
eg. (Pascal syntax)
EventList := +noeDblClick +noeMouseMove +noeMouseWheelAny;
Above line will cause CoolMon to notify incase of the following events
- Double Click
- Mouse Move (over visual object)
- Mouse wheel moved in any direction