S22 Overriding the standard Navigator

S22 Overriding the standard Navigator (SDK 3.3.x)

This article shows how to override the standard project navigator in SDKs of version 3.3.x.

Notes

The solution presented in this article is for CODESYS V3.3.x. It will not work with older versions of CODESYS.

Idea

In the Automation Platform, there is a central implementation of a so-called NavigatorControl, accessible through the interface _3S.CODESYS.NavigatorControl.INavigatorControl. This control is able to display the contents of an arbitrary project in the Object Manager by specifying its project handle and the GUID of the structured view (The explanation of structured views goes beyond this article). The out-of-the-box functionality of NavigatorControl comprises amongst other things:

For each object in the project, it displays a node. The node hierarchy reflects the underlying structured view.
For each single node, the object's icon and name are displayed.
If the navigator control is not set to read-only, clipboard and DnD functionality is available.
The control contains a toolbar with four buttons: Perform action, Sort order, Sort by, and Find. The latter three ones are completely implemented, while the first one triggers an event that can be consumed by the using code.

And it has got two interesting extension points:

For the rendering of a node, a callback can be specified ("rendering callback")
For the appearance of a node, another callback can be specified ("filter callback")

So how is NavigatorControl used for the project navigators in CODESYS? Four plug-in classes utilize that control in the way we see it day-to-day:

A view factory that creates the "Devices" view. It implements _3S.CODESYS.Core.Views.IViewFactory, creates an instance of the navigator control using the Component Manager, and sets the two callbacks. The filter callback makes sure that only devices and their children are displayed, and the rendering callback does all the visual gimmicks mentioned above.
Another view factory that creates the "POUs" view. Quite the same, however the filter callback is tuned so that it returns all the other objects that are not displayed by the "Devices" view.
A command called "Devices" (typically in the "View" menu) that opens or activates the "Devices" view.
A similar command called "POUs", accordingly.

The first idea would be to implement the factories all on ourselves, but this is not a good idea because the existing factories contain lots of code that is not part of the NavigatorControl and which we do not want to reimplement. Obviously the rendering and filter callbacks themselves, which contain lots of fine-tuned logic, but also other stuff like double-click handling, right-click handling, reaction to primary project changes, and so on.

So we must opt for another way. The magic word is delegation. Delegation is always a good design choice when somebody want to inherit from existing functionality but is not allowed to (as it is the case in Automation Platform: it is strictly forbidden to statically reference a plug-in in order to derive from a class implemented there). In our concrete case we can implement our own view factory implementation, but delegate most of the calls to the existing implementation in CODESYS. For the callbacks, we put our own implementations, but remember the existing ones so that we can delegate all aspects to the original implementation that we are not interested in. And one detail must also be considered: The existing menu commands to open or activate the navigator view must be overridden so that they redirect to our own view factory.

Solution

Let's take the "Devices" view for a detailed investigation of the idea. All things mentioned here are analogously transferable for the "POUs" view. First of all, we create our own implementation of the _3S.CODESYS.Core.Views.IViewFactory interface.

[TypeGuid("{33BE776C-385E-4550-9B14-464DC9BCAAA9}")] public class MyDeviceNavigatorFactory : IViewFactory {}

In the constructor, we create an instance of the original implementation. Therefore, we need the type GUID of the implementing class, but thanks to the type list file that is shipped with the Automation Platform SDK, this GUID can be quickly found.

_originalViewFactory = ComponentManager.Singleton.CreateInstance(GUID_DEVICENAVIGATORFACTORY) as IViewFactory;

With the member _originalViewFactory, most of the methods and properties of IViewFactory can be simply implemented by delegation, e.g. the Name property:

public string Name { get { return _originalViewFactory.Name; } }

The only method where we want to change the existing implementation is the Create method. First of all, we let the original implementation create the NavigatorControl, but then we assign our own callbacks to the control. Each of the two callbacks can have an additional transparent data object, which we use to transport the information of the original callbacks (as we do not want to reimplement the callbacks completely; rather we want the original implementations do the donkeywork and just change the things we additionally want). Just look at the code:

public IView Create()
{
    INavigatorControl originalControl = OriginalNavigatorFactory.Create() as INavigatorControl;
    if (originalControl != null)
    {
        originalControl.SetAppearance(
            originalControl.SmallIcon,
            originalControl.LargeIcon,
            originalControl.Caption,
            originalControl.DefaultDockingPosition,
            originalControl.PossibleDockingPositions,
            new NavigatorRenderingCallback(RenderingCallback),
            new MyRenderingCallbackData(originalControl.RenderingCallback, originalControl.RenderingCallbackData));
        originalControl.SetContent(
            originalControl.ProjectHandle,
            originalControl.StructuredViewGuid,
            new NavigatorControlFilterCallback(FilterCallback),
            new MyFilterCallbackData(originalControl.Callback, originalControl.CallbackData));
    }
    return originalControl;
}

...

class MyRenderingCallbackData
{
    internal readonly NavigatorRenderingCallback OriginalCallback;
    internal readonly object OriginalCallbackData;

    internal MyRenderingCallbackData(NavigatorRenderingCallback originalCallback, object originalCallbackData)
    {
        OriginalCallback = originalCallback;
        OriginalCallbackData = originalCallbackData;
    }
}

class MyFilterCallbackData
{
    internal readonly NavigatorControlFilterCallback OriginalCallback;
    internal readonly object OriginalCallbackData;

    internal MyFilterCallbackData(NavigatorControlFilterCallback originalCallback, object originalCallbackData)
    {
        OriginalCallback = originalCallback;
        OriginalCallbackData = originalCallbackData;
    }
}

You see, we inherit most of the original, but we put in our own callback methods. As callback data, we provide the original callback method and data object so that we can delegate in our delegate, like so:

internal static void RenderingCallback(
    INavigatorControl control,
    IMetaObjectStub mos,
    object data,
    ref string stText,
    ref Color foreColor,
    ref Color backColor,
    ref FontStyle fontStyle,
    ref Icon[] decoratingIcons)
{
    MyRenderingCallbackData myData = data as MyRenderingCallbackData;
    Debug.Assert(myData != null);
    myData.OriginalCallback(control, mos, myData.OriginalCallbackData, ref stText, ref foreColor, ref backColor, ref fontStyle, ref decoratingIcons);
}

internal static bool FilterCallback(INavigatorControl control, IMetaObjectStub mos, object data)
{
    MyFilterCallbackData myData = data as MyFilterCallbackData;
    Debug.Assert(myData != null);
    return myData.OriginalCallback(control, mos, myData.OriginalCallbackData);
}

So far, we have got an implementation of a navigator that does exactly the same things like the existing implementation in CoDeSys, but with two points in our very own code where we can influence the appearance of each node to any extend we like. (Okay, to be honest, the icon of an object cannot be changed, but it can be decorated with any number of additional icons, but anything else can be changed or supplemented at will.)

The second part of our solution deals with the necessity to override the existing view commands so that they are redirected to our implementation. The concept of command overriding is basically covered in another article (Basics: Overriding Standard Commands), so let's skip this stuff here. It is implemented in the sample solution, and it might be pretty self-explanatory.

Running the sample

Download the attached sources.
If not already done, set the environment variable %APCOMMON% to the Common directory of your CoDeSys installation. (This is the directory where CoDeSys.exe, IPMCLI.exe, and IPM.exe are installed.)
Start Visual Studio and open the solution NavigatorOverride.sln.
Depending on your installation, you must correct some references to interface components, so that they point into the Interface Binaries folder in your Automation Platform SDK installation.
Build the sample. The plug-in will be automatically installed.
Use IPM.exe in order to add the plug-in Sample: Navigator Override to one of your version profiles.
Start CoDeSys, ignore the message about the missing plug-in key, close the navigators and reopen them by executing the corresponding commands in the "View" menu.

The sample implementation appends the object GUID of all objects to the node text, highlights all POU objects with a yellow background, and hides all objects which name starts with "hide". Please make sure that you uninstall that plug-in again at a later time, our you'll never see objects that start with "hide" any more!

Best practices

When using the sample code in any serious development, please make sure that you exchange all type GUIDs and the plug-in GUID by GUIDs generated on your machine.
Rendering and filter callbacks are called very often, so they must perform very fast!
If you need to get a readable copy of an object in order to render or filter it correctly, it is highly recommended that you check whether this object is already loaded, and do nothing if this is not the case. Otherwise, the lazy load mechanism during loading a project will be broken because the painting routines will then indirectly force an immediate load of the objects. You can observe the good implementation in practice: if you open a large project, then on the first appearance POUs are only displayed with their name, but once the lazy load mechanism starts (take a look at the status bar), one after the other POU node is decorated with the POU kind. Mostly however, it is enough to check the ObjectType property of the meta object stub that is passed into the callback methods.

NavigatorOverride_3.3.x.zip

11 KB