Revamped Integration process

UI Polish Article Featured Image Revamped Integration process | integration
Graphically polished UI and optimized code
June 19, 2014

Revamped Integration process

Integration Pipeline Featured Image Revamped Integration process | integration

The process of integrating AddIn’s UI elements into TKMap’s UI is simply called Integration. TKMap uses a system inspired by SharpDevelop’s AddIn-system. Code and UI-Design was separated into two areas. The code is only written in the AddIn’s library file (DLL) and the UI gets designed via a XML file. This file is called the IntegrationDescription. It contains all data of the AddIn, from simple meta-data like the title over to the complete UI.

I came to the decision because it was really ugly creating all the controls in code. You got a mass of text which only creates the controls but you also need a lot to implement their logic. Now with the ID (Integration Description) you don’t have to mess around with all this. You only define your controls, define their properties and watch TKMap’s splash screen for a second until it has integrated your whole AddIn’s UI. Of course this file can get really huge proportional to the size of the AddIn. And of course XML files with a few hundred lines can get a bit messy, too.

But there were several reasons why I wanted to use this method. The first one is the separated structure. This improves the workflow and helps organizing (at least a bit). The next thing is, that it can be extremly difficult as well as confusing when you have to create hierarchies. And that’s something you will have to do if you want to add UI elements to the Backstage or Ribbon menu. With XML you got a clear vision over your hierarchy. The third reason is the automation. Integrating UI elements always requires things like images or icons. Or you may have to translate the element. The Integration Pipeline of TKMap helps you a lot in these cases. There are several features which make this process unbelievable easy.

As comparison between code and XML version of creating an UI element with automatic translation and icon:

And here the corresponding C# code:

You see, it’s messy code. Moreover it’s not recommended using the UIHosts manually. It is possible to do this so, but that’s only recommended for people who know how to use it (yes, there will be a tutorial sometime). It’s a lot easier and nicer to do this in the XML file. And something like setting the icon is, as you see, faster done in XML because of the Pipeline. It automatically loads the resource with this one single line. And there are even more possible expressions. Another one would be @ref:id. With that one you can reference objects from the current integration context. This means, all objects which are already created. This is useful for Ribbon menus contextual groups. The only rule is that the groups are placed above the tabs. That’s because the pipeline runs trough the file from the top to the bottom and references will only work for objects which already exist. In this case, you create a group object with a special id. Afterwards you create a tab and assign to it’s “Group” property the corresponding group.

As short information what the integration context is: There are three UIHosts. One for the Backstage menu, one for the Ribbon menu and one for the statusbar. Each one has it’s own context. You can’t use objects which are intended to extend a different UIHost. But for this I already planned something which will be implemented sometime in the future. It will probably be possible, no worries.

Pretty easy, huh? You see that some things like assigning a SolidColorBrush is not the nicest thing. For this I already planned some optimizations for such special, often used types. Maybe a short expression or something similiar. But you can do nearly everything with this file. Since yesterday even Constructors are supported. So if your object has a constructor you can use, then do this by using the <ConstructorParam>-tag. Objects can be created in every tag, as these samples show. In <Set>-tags as well as in <ConstructorParam>-tags. Controls which support control collections like a Grid are supported too, of course. But for these it requires (currently) to define <MetaTag>-tags which state clearly that these controls support childs. Sadly the name of the property for child elements is not always the same. For this reason you have to define the “SubControlProperty” metadata. Default is “Children”.

Moreover the whole pipeline is very generous about mistakes. It supports basic datatypes like string, int, bool, double and so on by default. So you don’t have to write it explicitly in type-attributes. Normally it requires to write system:Int32. But int does the trick. It even tries to define the type by itself. If you wrote 3.292323 it automatically detects it as double. It always uses the most common type. Instead of float it prefers double. Instead of long int. It’s highly recommended to explicitly state the data-type to reduce the risk of errors. Also the pipeline has a lot of defaults set. You may have noticed that the <Translate>-tag was placed inside a <Set>-tag, but there was no property name specified. Here comes the pipeline’s intelligence. If there is neither a property name nor a explicit dependency property name specified, then it uses the most common default: “HeaderProperty”. If there is only a property name specified, it just applies “Property” to it, because normally the dependency propertiy’s name is the same as the normal property’s one, just with “Property” at the end of its name. If you explicitly append a property-attribute to the <Translate>-tag, then it uses this defined name as dependency property. Pretty neat, isn’t it? Of course everything can change. And a few things will change over time. It’s just an overview about the feature-richness of the pipeline.

By the way, the current description of the main AddIn (the Studio) takes ~150ms for reading out the AddIn’s metadata and checking it’s requirements. The integration process takes about ~690ms for about 30 objects. That’s quite much, but you must keep in mind that this process is currently completely unoptimized. It’s asynchronous, though.


So that’s enough about the Integration Pipeline for now. And hey, that’s the first really detailed technical information about TKMap. Please leave a comment what you think about this system. If you guys got some questions about it, send me an e-mail or comment here. I’ll answer your questions in the next post then.

Zap out.

HTML Snippets Powered By :