We (Denis Vuyka 1, Denis Vuyka 2 and myself) have completed a fully functional mindmapping application on top of G2 and have used it in the past months internally for various things. This application is, however, not a ‘product’ or anything you can buy, it’s only a proof of concept.It’s a test application, a benchmark, a toy model, a fun thing to play with and see how G2 handles various things. Much like the class designer and the database table designer I talked about earlier, it’s a way to show off the potential of G2 to you, even though I think this mindmapping application could be a stepping stone to something bigger.

This said, the development was a lot of work; the devil is in the details as everyone knows. G2 is a framework on top of which you can create an application, attach meaning to nodes and links, handle events and trigger some mechanism in the G2 core and so on, all this is conceptually quite easy. Making things smooth on the UI level, making custom controls to manipulate the data coming or going to G2 is on the other hand a tedious process of UI-design, usability testing/trying, debugging, handling special cases (large images, bad alignment of text, broken serialization due to unicode characters…) and more. This journey has been rewarding, once you have the idiosyncrasies of WPF in your fingers and can navigate blindly through G2, the whole process feels very productive.  For example, creating a thought-node which binds to some RSS and injects blog-titles into the map is fun and easy, the same for custom nodes binding to stocks & shares data (see the screenshots). Creating thought-nodes with clickable icons or showing some custom data is a no-brain activity. In fact, because the stuff shown on a node is presented through WPF’s databinding you can add pretty much anything you like to the node’s visual.

Stocks & shares

Mindmap on 'rendering'

About The Orbifold

The classic mindmapping layout.

I’ll review a bit the features of the application which obviously reflect the features and capacity of G2 as a basis for diagramming in general.

Standard features

Menu items

• Saving to the internal binary format (*.g2d) and to XML (*.xml). You can alter the generated XML and open it up again. At some point I’ll publish the XML data format but you can experiment and find out yourself as well.
• Opening diagram from binary and XML formats. Both formats support multiple pages inside a single document.
• Creating a new document (CTRL+N) will request by default if you wish to save the current document first.
• CTRL+S and CTRL+O are bound and subsequent savings will first try the current file path. If you wish to save it elsewhere you can use SaveAs (no input binding here), but all this is pretty standard.

Note that a document (a mindmapping document in this demo) consists of some metadata and one or more pages. A page is much like a sheet in Microsoft Office Excel or Visio. Internally a page is furthermore subdivided into layers but in this demo you will not be able to have mutliple layers. In fact, it’s rather difficult to conceptually give meaning to layers in a mindmapping diagram.

Multi-page tab

Page can be added through the toolbar item entitled ‘Add page’ and removed or renamed through the tabpage context menu. A document has at least one page, which means you cannot delete the page if it’s the only one in the document. See also the know issue related to the tabs below.

Cut, copy, paste and delete (CCPD) need little explanations, I guess. Mind though that when navigating the diagram with the keyboard the focus is on the text inside the shapes. This means that at that moment CCPD has its effect on the text and not on the shapes. In order to CCPD shapes the focus needs to be on the diagram level. Just use the traditional rubber-band (marching ants, selector) to select shapes (use CTRL or SHIFT to add to an existing selection) and CCPD then. In this context I need to note that if you select multiple shapes which have a parent relationship (like in the screeenshot below) the upper parent will be used and hence all children underneath will be used in the CCPD process. This system ensures that no shape becomes an orphan in the CCPD process.

Illustrating the obvious

The O2 docking environment is an in-house development based on MEF, AvalonDock and Denis’ wonderful propertygrid (though in this demo it’s been hidden). The View menu allows you to bring up the various panels of the demo. Most notably, the Output window will display internal messages or (worse) exceptions and the internal browser is just a WPF Frame (hence, wrapped IE ). The docking layout can be saved via the Tools menu and re-opened later on.

Nothing spectacular but anyway, you can select a custom background for a diagram which in some cases can really make a diagram more attractive. With WPF there are so many possibilities…

Custom diagram backgrounds

Editing the diagram metadata (author, date and title), zooming and assigning an icon can all be done through the Diagram elements panel. There is also a thumbnail view which in a later phase will allow you to navigate the diagram, but I haven’t put much focus on this lately. Zooming can also be achieve via the mousewheel and pressing the CTRL key (quite standard nowadays). To reset the zoom factor just press/click the mousewheel (yes, you can press the wheel). An addition which I have overlooked as I’m writing this is the SHIFT with the mousewheel which in most applications allows you to scroll horizontally.

Diagram elements panel

Mindmapping specific features

Besides the features which are available to every G2 diagram type (or part of the O2 environment), there are also a few things specific to mindmapping which we’ll highlight below.

Mindmapping toolbar

One of the very productive features of WPF is the possibility to style or template a control. When you select a thought-shape you can alter its appearance through the dropdown in the toolbar (see screenshot). For this demo I created some custom styles which suit different data bucket but, as I described above, the possibilities are limitless and easily implemented. Take this together with the databinding and you have a mindmapping framework for every possible (business) context.

An overview of some styles defined in the demo

• CTRL+R rotates the diagram
• CTRL+ENTER adds a child node. Some dummy text is auto-generated which eases the testing process and easily creates maps in no time. As this is some kind of ‘random book-title generator’ you can have sometimes rather strange or funny titles
• CTRL+T switches between editing the text or thought title inline and editing the body text
• CTRL+M expands/collapses the children of the selected node
• CTRL+ARROW allows you to navigate the map through the keyboard. This togheter with CTRL+ENTER makes it easy to create dummy maps in no time.

Drag-drop. If a node is selected and you dragdrop an URL it will be attached to the selected node. If you dragdrop an image from the file explorer this will create a new child node to the selected node. Nothing will be created if no node is selected!

The thought editor. The data displayed in a shape is, as said earlier, just a data bucket bound to the visual in the diagram. For example, below is the definition of the ‘Shares’ shape template wherein you can see the different data bindings. So, in effect there is just a collection of data islands which you can bind both to the shape in the diagram but also to some editor. Altering the data in one will change the data everywhere else, which demonstrates brilliantly the power of WPF’s databinding. The though editor is a dockable panel which allows to change the data island and it’s rather self-descriptive. You can add some URL’s or some files to a thought through the listviews, change the body text, add an icon or change the title inline. Obviously the whole editor would be even more useful if RTF-ed or HTML-ed but I did not want to waste too much time on this. Ultimately, it’s just plugging in some open source or commercial editor since the data bucket only cares about the string result.

The 'Shares' template

One word of warning for those thinking that adding shapes and styles is only a matter of adding properties and changing the XAML. The underestimated part behind CCPD and saving documents is the whole (de)serialization process; making sure databinding works after deserialization, picking up the styles from the assembly’s resources, disassembling the layout organization, figuring out how to maintain the mindmap hierarchy and so on. To the rescue, the data exchange pipeline (aka. G2D) inside G2 maximizes flexibility through some smart usage of Unity (as explained elsewhere on this blog) which allows us to really change the import/export of XML in a snap, embrace data changes with ease and be prolific without having to step through the (de)serialization on a low level (anymore).

Things left out

• Other types of diagrams are not possible in this demo (though the XML manipulation will not stop you from getting there).
• Saving data to a WCF endpoint or database backend.
• Dragging thought-shapes and altering the map via the mouse.
• The possibility to mix free shapes and thought-shapes.
• Layers (see also my remark above).
• Saving/opening sub-document elements.
• Active shapes (RSS shape, Google search shape and other ‘intelligent’ shapes).

All these things are possible with G2 but I think the current demo is sufficient (for now) as other diagram types need attention as well…

What’s the point?

To paraphrase my compatriot; ceci n’est pas un logiciel. It’s a demo (I’d almost say a fancy UI facade on top of) showing what can be done with G2. The diagrams I talked about in other blog postings will be integrated in the near future to complete the demo so that in the end a more ‘covering’ picture appears of what G2 is. There as been an enormous interest in G2 and Graphite in the past months but unfortunately we have not been able to deliver a downloadable demo on time. I hope this first release already satisfies a bit the hungry (customer) minds out there.

You can do as you wish with this demo, there are no constraints. Of course, any feedback is welcome. If you really have the burning wish to turn this demo in something you think is worth selling you can drop me a mail, custom solution requests and business opportunities are welcome as well.

The next download of the G2 demo wil contain the other diagramming types, but no schedule on the table for now. We are developing custom diagramming controls for customers, elaborate data visualizations in our lab, handle heaps of mails and questions, have a fulltime job next to all this and take care of our family. Acrobatic challenges at times. Most probably you’ll see signs on this site of our other projects before the next G2 drop.

Download the February G2 mindmapping demo.

Known issues

.Net v3.5 SP1 is required to run this demo. You can download all this from MSDN.

The virtual double. This occurs when you load a document and the page tab control shows a double of some page. When you click on either when the other virtual double will disappear. This is a bug in the databinding for which I was unable to find an answer or trace the cause.

Doubling of pages on load

Sub-document file types. The open/save dialogs present you alternative file extensions (*.g2s, *.g2b, *.g2p). These types are not supported in this demo, though the serialization is inside G2. These extensions allow one to save only a page, a subset of shapes or just one single shape to a file. These types are useful to load templates and re-use single shapes in other documents.

Other file types

Undo/redo. The undo/redo mechanism is not everywhere properly bound to the actions. This is not a bug in G2 but rather a badly bound UI to the underlying core. Sorry.

Semantic note: the whole nine yards: means “completely, the whole, everything.

Althoug it might look like a piece of cake to display this kind of information and it seems like a simple shift from the class shape discussed earlier, it was quite a challenge to dot it. Not so much the diagramming part but the data grid inside the shape was somewhat difficult. While there is a datagrid for WPF it would be a heavy load on the diagramming surface to include it in the shape containers. So, the only option was to create a home-made lightweight datagrid. In addition, it had to have an inline editing capability in the form of comboboxes, textboxes, checkboxes and more. Finally, I also wanted the whole shape to have different view states; totally collapsed, names only and the full datagrid view.

In the picture you can see a sample diagram with the various features;

• the User & Countries tables are ‘full’, the Credential table is in a collapsed state and the Address table shows only the names of the fields. The upper-right icon allows you to cycle through the different views. This is not mendatory, however, as the icon simply launches a routed command which can be captured anywhere and you can call the ShowCollapsed(), ShowNamesOnly and ShowFull() methods on the original source to changes the view as you like.
• the lines in bold in the grid show either the active record or the primary key(s)
• double clicking allows one to edit the fields
• the labels can contain in general the info you like and it’s a generic feature of G2 rather than part of the database related shape info.

Although I did not fully develop things, one can go the full nine yards and turn this sample into either a database visualizer or a database editor (or both) much like in SQL Server’s management studio. Using the integrated analysis service of G2 one could also traverse the diagram and create scripts or XML on top of it. Well, you got the point I guess.

Part of the work consisted in creating some smart reflection code. Fortunately, nowadays one can do things in a flash through LINQ, so this was done in no time.

Another part consisted in customizing my O2 presentation environment which has the look-and-feel of Microsoft Blend and a bit of Visual Studio as well. The code is largely based on the AvalonDock project and on Denis Vuyka’s property grid. The big challenge here was to merge and harmonize the code into one smooth framework. At some point I considered to merge some WPF composition ideas as well but due to the horrendous learning curve and the P&P’s complicated ideas around multi-targetting their framework I set the idea aside. Still, I believe that as it stands now the O2 code is well suited to develop within it a variety of (commercial) applications. See the screenshots and note, by the way, how nicely the browser and The Orbifold’s website blends into the application.

Finally, the biggest part of my efforts went into creating the ‘class shape’  or, as it’s called internally, the TreeviewShape. Let me highlight a bit the anatomy of the shape and how the serialization of it is implemented.

The shape is organized more or less like this (see also the XAML template below):

• The head consists of the colored (rounded) rectangle inside which multiple headers can be place, all of which can have a distinct icon. The icon which allows you to collapse/expand the shape is in fact a templated button. The whole head (see the TranslationHeader style below) can catch the mouse in order to move the shape around and is in fact itself a templated control.
• The body is really just a standard WPF TreeView. However, it took me an eternity to make it look OK and to position it inside the template. The reason being that the order in which one places the various XAML tags is important and there are some quirks in the WPF framework (no mouse recognition if there is no background, for instance). This said, I should underline that all of this is nothing in comparison to what it once required before WPF was among us (cfr. the class-shape in Netron in this context).

The most time-consuming part of the work is in fact the little details and the parametrization of the various XAML attributes in order to make sure that the layout works for all possible situations.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

<style TargetType="{x:Type Core:TreeviewShape}">
  <setter Property="MinWidth" Value="125"/>
  <setter Property="MinHeight" Value="28"/>
  <setter Property="SnapsToDevicePixels" Value="True"/>
  <setter Property="Template">
    </setter><setter .Value>
      <controltemplate TargetType="{x:Type Core:TreeviewShape}">
        <border BorderBrush="White"   CornerRadius="10"  Width="Auto" Height="Auto" BorderThickness="1,1,1,2" Background="White">
          <grid x:Name="PART_maingrid" DataContext="{Binding RelativeSource={RelativeSource TemplatedParent}}">
            <stackpanel Orientation="Vertical">
              <!-- PART_TranslationOverlay -->
              <core :TranslationOverlay Style="{StaticResource TranslationHeader}" x:Name="PART_TranslationOverlay" Cursor="SizeAll" />
              <treeview Margin="0,0,0,5" Style="{StaticResource xxx}" Width="Auto" Height="Auto"  x:Name="tree" />
            </stackpanel>
            <core :ConnectorDecorator x:Name="PART_ConnectorDecorator"
                         Visibility="Hidden"
                         Template="{StaticResource ConnectorDecoratorTemplate}"/>
          </grid>
        </border>
        </controltemplate><controltemplate .Triggers>
          <!--<dataTrigger Value="True" Binding="{Binding RelativeSource={RelativeSource Self},Path=IsSelected}">
                <setter TargetName="PART_ResizeDecorator" Property="Visibility" Value="Visible"/>
              -->
          <trigger Property="IsMouseOver" Value="true">
            <setter TargetName="PART_ConnectorDecorator" Property="Visibility" Value="Visible"/>
          </trigger>
          <datatrigger Value="True" Binding="{Binding RelativeSource={RelativeSource Self},Path=IsDragConnectionOver}">
            <setter TargetName="PART_ConnectorDecorator" Property="Visibility" Value="Visible"/>
          </datatrigger>
        </controltemplate>
 
    </setter>
 
</style>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

<style x:Key="TranslationHeader" TargetType="{x:Type Core:TranslationOverlay}">
  <setter Property="Background">
    </setter><setter .Value>
      <lineargradientbrush EndPoint="1,0" StartPoint="0,0">
        <gradientstop Color="#9FB6CD" Offset="0.50"/>
        <gradientstop Color="#FFF" Offset="1.0"/>
      </lineargradientbrush>
    </setter>
 
  <setter Property="Template">
    </setter><setter .Value>
      <controltemplate TargetType="{x:Type Core:TranslationOverlay}">
        <border x:Name="PART_HeaderBorder" Background="{TemplateBinding Background}" CornerRadius="10,10,0,0">
          <grid x:Name="PART_HeaderGrid" MinHeight="60" Width="184" Height="60">
            </grid><grid .ColumnDefinitions>
              <columndefinition MinWidth="50" Width="140*"/>
              <columndefinition Width="19*" MinWidth="19"/>
            </grid>
            <grid .RowDefinitions>
              <rowdefinition Height="25*"/>
              <rowdefinition Height="25*"/>
              <rowdefinition Height="25*"/>
            </grid>
            <stackpanel Grid.ColumnSpan="1" Orientation="Horizontal" Margin="0,2,0,0">
              <image x:Name="PART_HeaderIcon" Width="Auto" Height="Auto" MaxHeight="10" MaxWidth="10" Margin="5,0,0,0"/>
              <textblock x:Name="PART_Header"    Text="BezierConnection"    Foreground="#FF000000" TextTrimming="CharacterEllipsis" TextWrapping="NoWrap" FontSize="12" FontWeight="Bold" Width="Auto" MaxWidth="120" Height="20" Margin="5,0,0,0" FontFamily="Tahoma" />
            </stackpanel>
            <button Style="{StaticResource SwitchButton}"  HorizontalAlignment="Left" Grid.Column="2" Margin="0,0,2,0" x:Name="PART_ExpandButton" VerticalAlignment="Top" Width="Auto" Height="Auto"/>
            <stackpanel Margin="2,0,5,0" Grid.ColumnSpan="3" Grid.Row="1" Orientation="Horizontal">
              <image x:Name="PART_SubHeaderIcon" Width="Auto" Height="Auto" MaxHeight="10" MaxWidth="10" Margin="3,0,0,0"/>
              <textblock x:Name="PART_SubHeader"  Width="Auto" Height="Auto" Foreground="#FFFFFFFF"  TextWrapping="Wrap" FontSize="11" Margin="5,0,0,0" FontFamily="Tahoma"/>
            </stackpanel>
            <stackpanel Margin="2,0,5,0" Grid.ColumnSpan="2" Grid.Row="2" Orientation="Horizontal">
              <image x:Name="PART_SubSubHeaderIcon" Width="Auto" Height="Auto" MaxHeight="10" MaxWidth="10" Margin="3,0,0,0"/>
              <textblock x:Name="PART_SubSubHeader" Width="Auto" Height="Auto" Foreground="#FFFFFFFF"  TextWrapping="Wrap"  FontSize="11" Margin="5,0,0,0" FontFamily="Tahoma"/>
            </stackpanel>
 
        </border>
      </controltemplate>
    </setter>
 
</style>

Finally, the serialization part. This is really where G2 shines, I think. I probably invested half a year into the data-exchange pipeline of G2 but looking now how much the development benefits from this I’m really happy I went through this difficult development period.
The data exchange pipeline (called internally G2D) is a rather complex piece of software which to some extend is explained in my series of articles on Unity and Unity extensions. It basically consists of ‘actions’ which sit inside the Unity container and are orchestrated into one ‘transaction’ to achieve various things like binary serialization, XML serialization, copy/paste and the creation of undo/redo units of (diagramming) work. It might come as a suprise but probably half of the code of G2 has to do with serialization and data exchange and only a minor part is related to visualization and layout.
Anyway, the data-exchange code (note that this entails more than just serialization) of the TreeViewShape consists of three parts:

• the data-bucket or the serialization counterpart of the shape. This is a true data-entity much like one has in data access layers of a N-tiered database application. It contains the presentation-independent stuff of the shape and can be serialized to any repository (database, WCF, XML, binary files).
• The converter between the shape and the data-entity. This can be compared to a mapping layer. Actually, the whole G2D pipeline is much like the Entity Framework as far as functionality is concerned. One could really take the G2D code and generalize it with little efforts to a generic data mapping layer.
• a lot of XML fine-tuning in order to make WPF things XML-readable. Some would use here the out-of-the-box XAML-writer but I discovered after many failures that the XAML reader/writer of WPF has some limitations and is not suitable if you wish to have a bit of control on what is being outputted.

I will discuss in a separate article the beautiful XML features of G2 but let me briefly here show how easy one can create or modify diagrams through XML. Below is a snippet of G2 XML which serializes a single G2 page with a single layer and in this layer two treeview shapes. Now, it doesn’t require a PhD to see what it all means and to modify things; connections, layers, pages and other shapes are added in a snap. Don’t get confused by the many GUID’s, they are internally generated and can be replaced by your own ID’s. This means in fact that these ID’s could have some meaning inside your applications (database record ID’s for example) and that the XML could be generated outside G2. In addition, G2 allows you to import parts of diagramming documents like pages or bundles of shapes and connections. This then, in effect, allows you to import parts of diagrams from multiple source which then merge into one document. For example, it’s perfectly possible to use multiple WCF services (the data buckets are WCF-ready and serializable through WCF) to feed one diagram.

To conclude, somewhere soon I’ll also demonstrate how G2 can be used to create workflow diagrams in the same fashion. I also intend to create a XOML importer which would enable one to model WF models outside Visual Studio, but considering the upcoming WF 4.0 and its many new features I think I’d better wait until .Net 4.0 is released.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

< ?xml version="1.0" encoding="utf-8" standalone="yes"?>
<gradium Version="1.0">
  <document>
    <metadata>
      <creationdate>2009-01-05T19:35:12.4154+01:00</creationdate>
    </metadata>
    <pages>
      <page AutoLayout="false" AutoConnect="false" IsActivePage="true" PageType="ConceptMap" UID="e5e78121-55c3-422c-a423-39b681fca3c8" Title="Concept map">
        <connections />
        <layers>
          <layer Visible="false" IsDefaultLayer="true" Title="Default layer" UID="bba7b83a-718c-4305-a6a8-5274d4174351">
            <shapes>
              <treeviewshape UID="365b6faf-44e6-4dce-9b28-975990da3ced" Size="NaN (Niet-een-getal);NaN (Niet-een-getal)" Location="1013;546,04" Header="BezierConnection" SubHeader="Class" SubSubHeader="ConnectionBase">
                <connector UID="b9137087-095e-45f5-b92a-04a640b9bc83" Layer="Left" Orientation="Left" Position="1014;599,5" />
                <connector UID="98075af4-77c0-45fa-a407-cc0d7d272643" Layer="Top" Orientation="Top" Position="1106;547,04" />
                <connector UID="e1b496f0-f393-4556-a0db-4b6935831a4f" Layer="Right" Orientation="Right" Position="1198;599,5" />
                <connector UID="e1c800dc-7014-41d1-9930-280a6c317f3c" Layer="Bottom" Orientation="Bottom" Position="1106;651,96" />
                <treeitems>
                  <treeviewitem Header="Methods">
                    <treeviewitem Header="OnApplyTemplate" />
                  </treeviewitem>
                </treeitems>
              </treeviewshape>
              <treeviewshape UID="bfcbbeef-fa17-4ea5-8f66-32e5aff6572b" Size="NaN (Niet-een-getal);NaN (Niet-een-getal)" Location="223;114,04" Header="ActivityBase" SubHeader="Class" SubSubHeader="Object">
                <connector UID="c7c5d368-1773-4267-8f2d-e2f82b42bc29" Layer="Left" Orientation="Left" Position="224;231,34" />
                <connector UID="45e7cf57-1cc6-4529-a03f-dae3f483b231" Layer="Top" Orientation="Top" Position="316;115,04" />
                <connector UID="96547264-8961-4909-a4a6-6b5b1c307e6d" Layer="Right" Orientation="Right" Position="408;231,34" />
                <connector UID="8162149f-1304-40b9-8b1b-9f94c46f8b42" Layer="Bottom" Orientation="Bottom" Position="316;347,64" />
                <treeitems>
                  <treeviewitem Header="Properties">
                    <treeviewitem Header="Name" />
                    <treeviewitem Header="Enabled" />
                    <treeviewitem Header="StepTime" />
                    <treeviewitem Header="StartTime" />
                    <treeviewitem Header="Duration" />
                  </treeviewitem>
                  <treeviewitem Header="Methods">
                    <treeviewitem Header="Run" />
                    <treeviewitem Header="RunAfter" />
                    <treeviewitem Header="Stop" />
                  </treeviewitem>
                </treeitems>
              </treeviewshape>
            </shapes>
          </layer>
        </layers>
      </page>
    </pages>
  </document>
</gradium>

After many fan requests I finally took a few hours to cook up a proof-of-concept showing how to construct a MVC decoupling between data storage, logic and presentation. The sample does not show:

• how to use the command pattern and how to implement undo-redo
• how to data-bind connections to shapes
• how to enable copy/paste

On the other hand, I did implement the (de)serialization of the diagram and shapes are templated. This simple bunch of code is the core architecture of how GraphSquare is internally (modulo the omissions I metioned above), all the rest is simply a few thousands hours of work more

Download the sample

Note that this sample has been integrated into the DSK which contains a paradise of diagramming code if you wish to get started in WPF diagramming.

How to serialize stuff in .Net

Black-box serialization

The easiest way to serialize a class in .Net is by decorating a class with the System.Serializable attribute. It tells the CLR to pick up the public and private fields and to save them as part of the data necessary to reconstruct an instance. In case you want to drop a few fields in this process you can use the NonSerializedAttribute attribute which will discard the field decorated with this attribute.Note that the NonSerialized attribute cannot be applied on a property but only on a field, the reason escapes me however.

1
2
3
4
5
6
7
8
9
10
11

[Serializable]
public class BlackBox
{
[NonSerialized]
public object ThisWillNotBeSerialized;
 
public string FirstName { get; set; }
public string LastName { get; set; }
public int Weight { get; set; }
 
}

The controlled serialization

If the two attributes above do not give you enough control over the serialization of your class you can go for the handcrafted serialization using the System.Runtime.Serialization.ISerializable interface. This interface has a deceptively simple signature which only requires you to hadn over those objects you want to serialize. The method passes a serialization info object which acts as a string-object dictionary in which you can store whatever you wish, even things non-related to the fields of you class.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

[Serializable]
internal class ControlledBlackBox : ISerializable
{
 
    public object ThisWillNotBeSerialized;
 
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int Weight { get; set; }
 
    public void GetObjectData(SerializationInfo info, StreamingContext context)
    {
        info.AddValue("FirstName", this.FirstName);
        info.AddValue("LastName", this.LastName);
        info.AddValue("InFactAnyNameYouWish", this.Weight);
        //non-field related data
        info.AddValue("SomethingYouWantToSave", 3.141592);
    }
 
    protected ControlledBlackBox(SerializationInfo info, StreamingContext context)
    {
 
        FirstName = info.GetString("FirstName");
        LastName = info.GetString("LastName");
        Weight = info.GetInt32("InFactAnyNameYouWish");
        double pi = info.GetDouble("SomethingYouWantToSave");
    }
}

The interface does not tell you that in order to function well this requires a constructor with the same signature wherein you can pick up the stuff you saved and re-initialize the class with it. Actually, you can store whatever you wish in the serialization info, it does not need to be related to fields of you class. Often you need some ambient information to correctly instantiate an object and this is how you can store additonal data. The AddValue has many overloads and at times it can be difficult to use the correct one (try to (de)serialize an Enum to see what I mean). It’s also through this AddValue method that you actually chain a serialization process. As soon as you use custom objects as data types in your fields you tell the CLR to serialize this data type as well. The CLR will automatically create internally a graph of those objects to be serialized and by wanting to serialize one class in easily slip in having to serialize a whole bunch of classes in your project.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

[Serializable]
internal class ControlledBlackBox : ISerializable
{
 
public CustomData ChainedDataMember { get; set; }
 
public void GetObjectData(SerializationInfo info, StreamingContext context)
{
info.AddValue("ChainedDataMember", this.ChainedDataMember);
 
}
 
protected ControlledBlackBox(SerializationInfo info, StreamingContext context)
{
 
ChainedDataMember = info.GetValue("ChainedDataMember", typeof(CustomData)) as CustomData;
}
}
[Serializable]
internal class CustomData
{
public string SomeMoreHere { get; set; }
}

The controlled deserialization with callback

During serialization the CLR will traverse the serialization graph from top to bottom and you can control everyting using the GetObject method. During deserialization you have an additional interface at your disposal which will be called after all classes in the internal graph have been deserialized. The CLR will call the System.Runtime.Serialization.IDeserializationCallback if implemented in reverse order and it allows you to do some post-deserialization which can be necessary when objects are inter-related.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

[Serializable]
internal class SerializationWithCallback : ISerializable, IDeserializationCallback
{
 
    public void OnDeserialization(object sender)
    {
        //some post-serialization code here
    }
 
    public void GetObjectData(SerializationInfo info, StreamingContext context)
    {
 
    }
 
}

The controlled (de)serialization with pre-post processing

On top of all this you can complement you (de)serialization process with pre & post (de)serialization methods which will be called directly before respectively after the (de)serialization is applied to your class. There is not conflict with the callback described above since the callback is applied after all classes have been deserialized while the OnDeserialized method is called directly after the class was deserialized. Yet, I admit, it can be quite compelx sometimes to trace down some bugs and to understand what the CLR is doing when it starts to switch between classes and calling recursively all kinds of methods.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

[Serializable]
internal class SerializationWithCallbackAndPrePost : ISerializable, IDeserializationCallback
{
 
    public void OnDeserialization(object sender)
    {
        //some post-serialization code here
    }
 
    public void GetObjectData(SerializationInfo info, StreamingContext context)
    {
 
    }
    [OnDeserialized]
    public void OnDeserialized()
    {
       //called just after the class was deserialized
    }
    [OnDeserializing]
    public void OnDeserializing()
    {
      //called just before the CLR enters the deserialization of this class
    }
    [OnSerialized]
    public void OnSerialized()
    {
      //called just after the CLR serialized this class
    }
    [OnSerializing]
    public void OnSerializing()
    {
      //called just before the CLR enters the serialization of this class
    }
}

Be aware that all this goodness gives you a lot of power but as with every big power, you need to understand in details what is going on in order to use it effectively or you easily end up with a spaghetti of ‘goto’ effects in you code.

Xml serialization

Besides the binary serialization we have described above you have also an whole set of possibilities to (de)serialize things to XML (and SOAP in particular). From my point of view this whole machinery has become somewhat obsolete since the introduction of LINQ to XML where I think things are much easier to manipulate, but we’ll quickly review things here.

Here again you can either rely on a black-box XML serialization by simply passing you type to the XmlSerializer method or you can fine-tune the process by means of attributes.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

[XmlRoot("RootName")]
internal class SimpleXmlSerialization
{
    [XmlElement("TheFirstName")]
    public string FirstName { get; set; }
  [XmlIgnore]
  public NameValueCollection Attributes
  {
    get { return _attributes; }
    set { _attributes = value; }
  }
}
 
internal class YourMainCode
{
    public void SerializeToXml()
    {
 
        SimpleXmlSerialization obj = new SimpleXmlSerialization {FirstName = "Just me"};
        XmlSerializer serializer = new XmlSerializer(obj.GetType());
        Stream stream = new FileStream("c:\\MyFile.xml", FileMode.Create,
               FileAccess.Write, FileShare.None);
        serializer.Serialize(stream, obj);
        stream.Close();
 
    }
}

To gain more control on this process you can implement the IXmlSerializable interface which allows you to actually control completely what will be written to disk:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

[Serializable]
internal class XMLControlledBox : IXmlSerializable
{
 
    public System.Xml.Schema.XmlSchema GetSchema()
    {
    }
 
    public void ReadXml(System.Xml.XmlReader reader)
    {
    }
 
    public void WriteXml(System.Xml.XmlWriter writer)
    {
    }
 
}

It’s precisely in this context (in the WriteXml and ReadXml) that I believe you can actually nowadays better rely on the LINQ to XML than to fiddle with the System.Xml.XmlWriter class.

You will also find in the System.Runtime.Serialization.Formatters namespace (you’ll need to reference the associated equally-named assembly in order to access it) the SOAP formatter which allows you to (de)serialize things using a SOAP envelope which can be used in peculiar (webservice related) situations.

In the context of WPF and somewhat related to XML you can also find in the System.Windows.Markup namespace the XAMLWriter class which exports any WPF construct to XAML markup. We will come back to this below.

Diagramming and (de)serialization

Debugging complexity

In general, serializing simple things is simple and serializing complicated things is, well, complicated. In most cases you can get away with the black-box serialization by simply decorating a class with the [Serializable] attribute, which is based on the properties and the default constructor. This works well for standard data types and not too complicated hierarchies of classes. Indeed, as soon as you decorate a class with the serialization attribute the CLR will create internally a graph of objects which has to be serialized. If you have a complex inheritance system and many custom data types you quicly get a huge set of classes you are forced to decorate too and eventually end up with serialization loops: two classes referencing each other by means of properties will create loops in the serialization graph and you will get exceptions at runtime. Not at compile time but at runtime. Even with all the pre/post attributes and callbacks at your disposal things easily get horrendously difficult to trace when your Visual Studio debugger starts to jump between (de)serialization methods, pre-post methods and callbacks.

No control over the (de)serialization sequence

The custom serialization gives you a grip on the serialization process on the class level but not on the hierarchy level. By this I mean that you can control how and what will be (de)serialized on a class level but you have no control over the order the CLR accesses the various classes in your object hierarchy. In order to explain this more in details I’ll have to explain first the way that one usually starts a serialization process.

If you want to serialize some stuff to binary format you’ll scribble something down like the following:

1
2
3
4
5
6
7
8

internal override void Serialize(DocumentWrapper wrapper)
{
    BinaryFormatter binFormat = new BinaryFormatter();
    using (Stream fStream = new FileStream(FileName, FileMode.Create, FileAccess.Write, FileShare.None))
    {
        binFormat.Serialize(fStream, wrapper);
    }
}

where the ‘wrapper’ is the stuff you want to save to disk. The serialize method of the binary formatter will first create and object graph on the basis of the wrapper object by looking at either the properties (in the case of black-box serialization) or by recursively calling the ISerializable method in the order that you added object to the serialization info dictionary. In general this works well but not for the serialization of diagrams. The problem being the fact that you cannot serialize bindings of objects and this is precisely the case with diagram connections between diagram nodes. The issue is rather technical but it all amounts to two different tensions: on the one hand the order of things to serialize and on the other the inter-dependency of objects in a diagram. The situation is really rather unusual in the sense that most line of business applications have a tree-like data dependency while diagram data is inherently graph-like (non-linear, that is). The situation is aggravated by the inverse problem when you deserialize a diagram, even with all these techniques described above you will discover that deserialization of diagrams is a complicated affair.

Strong coupling with WPF, import, export, WCF and more

If you present something like a ‘shape’ in a diagram you inevitably have somewhere a class which inherits from a WPF base class like the ContentControl. This makes your Model WPF dependent but worse, it brings along a whole bunch of stuff you have no control over. Imagine you wish to re-use the Model underneath a WCF service and create diagrams outside the WPF surface, you will be forced to reference WPF assemblies where they don’t make much sense. In addition, you will run into troubles when having to rely on style and template resources (XAML) which will not be actually applied unless you internally create a surface (something like a Canvas).

Consider also the need for importing diagrams from standard XML, say you want to display any type of XML in a tree diagram. Do you actually want to expose the internals of your Model to the outside world? One of the ideas I had while creating the whole architecture was to be able to have a provider pattern underneath the diagram repository. Because one cannot envisage all possible data scenarios it’s a good idea to create an open end where others can plug into. For example, how to enable one to create a data connection to a custom database? That is, storing diagrammatic information in some database and, conversely, importing data from external systems. What about creating mashups with webservices like Facebook or MySpace?

Last but not least, one of the most powerful aspects of WPF is data binding. However, data binding cannot be (de)serialized in a snap, which both handicaps the standard mechanisms and also requires extra efforts from your side.

Code doubling and decentralization of diagram manipulation code

Deserialization on the basis of the standard .Net mechanisms doubles your code which relates to your model. On the one hand you have inside the command units (the classes which are part of the undo-redo system) some code which accesses methods of your controller or model, things like AddShape, AddPage and so on. On the other hand, the deserialization is constructing shapes and pages without making use of these methods. Indeed, it would make little sense to call an AddShape method inside the deserialization constructor since this would create a recusive stack. So, if you change something in your AddShape method you have to make sure that this addition is also reflected in your deserialization and vice versa. Note also that calling the undo-redo commands in your deserialization is not an option. Opening and saving stuff is never an undo-able action.

Wouldn’t it be better to have a centralized diagram methods which are used whether the origin is deserialization, import, originating from a webservice call or a user interactions on the surface?

The conclusion

After many experiments, trials and frustration it became obvious (to me) that instead of relying on the internal process of the CLR it was necessary to create a custom serialization which would

• give complete control over the way that the Model was being serialized
• enable to use the diagrammatic methods (like AddShape, AddPage and son on) rather than the instantiation of classes which required complicated pre- and post-processing
• decouple the WPF dependency and in fact enable a client-independent Model and serialization
• eventually lead to more work but would ease the debugging considerably
• enable unit-tests and have a fine-grained control over all aspects of everything related to data import, export and (de)serialization

Data exchange in GraphSquare

In the next few paragraphs I’ll highlight how the (de)serialization was constructed in GraphSquare but I’d like to emphasize again that you should carefully consider your options in your own project because in general you don’t need the high-tech stuff we have implemented. I think as a data structure a diagram is rather peculiar and, in fact, the most generic type of data hierarchy you can imagine: blobs of data bound in an arbitrary way to each other. Usually you’ll find in your own to-be-serialized data structures some kind of symmetry or pattern which allows you to simplify the serialization considerably.

Before continuing, let me mention or recall the following:

• there is a XAMLWriter class which provides a single static Save method that can be used for limited Extensible Application Markup Language (XAML) serialization of provided runtime objects into XAML. This class provides an additional black-box serialization method in the context of WPF, see however its limitations. The advice here is to experiment and see if this suits your needs. It basically implements the XML serialization of .Net
• you cannot serialize data bindings without extra efforts, don’t expect binding to magically re-appear after deserialization. If you have bindings you’ll need either to serialize in some way or hard-code it in your deserialization system.
• the templating system of WPF can be at times an horrendous obstacle. The reason is that a template and the loading of the elements defined in it are only applied when the control is effectively visible in the interface. Imagine you have (as it is in our GraphSquare case) connectors defined in a template, how to deserialize connections bound to connectors if these will only be available when the connection has been already added to the surface? There is an ApplyTemplate() method defined in the FrameworkElement class but it does not always bypass the problem. This template issue creates an additional ordering problem (besides the two ordering problems I alluded above) when you (de)serailize a diagram.
• the resources (i.e. styles, templates…) of WPF are unavailable if you use unit tests which blocks the debugging of (de)serialization through unit tests. As far as I know there is no solution to this.

The document hierarchy

Before explaining the actual serialization code let me highlight the internal structure of the model. The MVC-model is actually called the ‘Document’ and can be considered as the database of the diagram. The Document contains all the info and its hierarchy reflects the way that the diagram control presents itself to the user. For example, the layers are sub-ordinate to the page and shapes are part of a layer.

The Document is the root of the hierarchy is in fact the same as the Model in the MVC pattern. It’s the data repository of the whole system and contains all members which alters the diagram and the control. The surface members are aliases to the Controller which delegates things down to the Document. The alterations are propagated back to the surface through events which are picked up by the controller and sub-sequentially by the surface.

The metadata is a small class wherein things like author and creation date are recorded.

The page collection contains all the pages of the diagram control and each page contains info like background color, layout type, page title and so on.

The layer collection contains the layers per page. Some page types do not accept multiple layers, like the mindmapping type where a layer is conceptually similar to collapsing branches.

A layer contains shapes and connections as separate collection even though each connector in a shape has the information about the connections. One could put the connection collection hierarchically underneath the connector but in practice it makes life easier to have it like this in function of (de)serialization.

An important note here is that the binding between shape and connector is loose in the sense that the connector collection is not part of the shape definition but defined in the template applied to the shape. This makes things more complicated for the (de)serialization but allows a certain flexibility in defining and customizing shapes.

The data abstraction and data adapters

The data abstraction layer consist of surrogate classes which can be compared with data entities in multi-tiered database application. They encapsulate the essence of a diagram entity (connector, shape, page…) without any reference to WPF or anything. Obviously you need to store in them a reference to the name of a template or style if you wish to show them on a UI/WPF surface but this does not enforce anything. In fact, using our abstraction layer one can create diagrams in totally non-WPF environments like underneath a WCF service, using database inserts or through standard WinForms (propertygrid). Unity is also playing a big role in this mechanism, because at some point you need to convert a surrogate entity to an actual Document entity. The decoupling allows one to perform this conversion inside a Unity container and in this way to achieve a certain independence, that is the container injects some objects which are allowed to be assigned on the basis of a common interface.

For each concrete diagram class one has a surrogate class which we prefixed with ‘Pre’ (what’s in a name obviously?) and they are bound to each other by means of reciprocal methods called GetShape and Wrap. When a data exchange process is started the surrgate DocumentWrapper will be handed over and it allows a data adpater to serialize it in some way. Conversely, when a data adapter loads serialized data it hands over a DocumentWrapper to the core, i.e. the Document. In this sense, the data abstraction layer consists of a single class, the DocumentWrapper, through which all data exchange occurs. From the point of view of the Document the origin of the DocumentWrapper is unknown. From the point of view of the external provider the DocumentWrapper is unrelated to WPF and the Document. As much as data entities in a N-tier database application form the intermediate step to business entities, so are the surrogate entities intermediate to the actual shapes in the Document (Model).

When the controller starts an exchange process it needs to provide a data adapter and all the rest occurs inside the adapter. The adapter accesses the DocumentWrapper and turns whatever it wishes into whatever format. For example, the XML adapter uses LINQ to XML to turn all the surrogate classes into XML elements. Conversely, we have a generic XML adapter which takes any incoming XML and turns it into a default DocumentWrapper. The adapter (or provider model if you prefer) is generic and can be implement externally. In order to add it to the control we make use of the Unity application block.

Coming back to the problems mentioned above, in the process of building the DocumentWrapper we implement our own to-be-serialized graph of surrogate classes. While this might sound complicated it really amounts just to some for-each loops on the pages, layers and other collections. Conversely, in order to convert a DocumentWrapper to an actual Document we control every step whereby we make use of the AddShape, AddPagee…methods of the Document to build up the diagram. This then is probably the crucial point; we don’t use serialization constructor but rather the standard Document methods to deserialize a diagram. In this sense, the whole logic remains centralized in these methods: data binding, event binding and so on. In order not to cause an avalange of events if the diagram control is embedded we have a global event-blocking property, but this can be switched off if necessary.

Obviously, the description here is rather schematic and a whole lot of code (over 2000 lines in fact) is required to make all this really functional. The details will not be published or released but I’d hope that this article clears the sky a bit for those who are looking for a robust serialization architecture.

In the next part we’ll have a look at something more fun and simple; WPF styling, triggers, animation and such.

• selecting some shapes with the typical rubberband is a tool, the series of actions being related to the mouse down, mouse move and mouse up events.
• scaling or rotating a shape, which involves the adorners and the mouse events
• creating a connection

and so on. The abstract tool concept originates from the fact that if you don’t package a series of actions in a separate class you inevitably have a complex logical flow in the overriden mouse-methods of the surface. So, instead of having various if-then-else statements in the MouseDown, MouseMove and MouseUp handlers you simply loop over all registered tools and whichever tool is ‘on’ can react accordingly. This approach has the additional advantage that you can

• add tools with ease
• disable or overrule other tools in the loop
• chain tools, if necessary

Below is a snippet of the mouse handlers which are called by the surface corresponding to the mouse events on this surface. Note that the loop in these handlers are broken as soon as one of the tools have opted to handle the event.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

public void MouseDown(MouseEventArgs e)
{
 
 
    foreach (ITool tool in toolList)
    {
        if (tool is Core.IMouseListener)
            if ((tool as Core.IMouseListener).MouseDown(e))
                return;
    }
 
}
public void MouseMove(MouseEventArgs e)
{
    foreach (ITool tool in toolList)
    {
        if (tool is Core.IMouseListener)
            if ((tool as Core.IMouseListener).MouseMove(e))
                return;
    }
 
}
public void MouseUp(MouseEventArgs e)
{
    foreach (ITool tool in toolList)
    {
        if (tool is Core.IMouseListener)
            if ((tool as Core.IMouseListener).MouseUp(e))
                return;
    }
 
}

Most of the tools have some kind of visual feedback, on creating a rectangle you would see for example a rubberband which previews the end-result. For this purpose a few classes are necessray which specializes the ITool interface (depicted above) and all tools which need a rubberband are inheriting from it. The whole rubberband (sometimes called ‘marching ants’) affair is also taken separately in other constructs (a static helper class) and the process of creating tools becomes in the end a game of putting some blocks together. In fact, a dummy tool with visual feedback would look something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

public class DummyTool : RubberCreationToolBase
{
 
 
    #region Constructor
    ///<summary>
    ///Default constructor
    ///</summary>
    public DummyTool():base("Dummy Tool")
    {
 
    }
    #endregion
    public override void OnExecute(object sender, System.Windows.Input.ExecutedRoutedEventArgs e)
    {
        GhostManager.Surface = sender as DiagramSurface;
        base.OnExecute(sender, e);
    }
 
    public override void DrawGhost(System.Windows.Rect rec)
    {
        GhostManager.DrawRectangularGhost(rec);
    }
 
    public override void OnRubberCreated(System.Windows.Rect rec)
    {
        Surface.Controller.Output("The '" +this.Name + "' tool finished but no realshape was added.");
    }
}

The overridable DrawGhost method allows you to give whatever feedback you wish while the overridable OnRubberCreated allows you to do whatever you wish after the rubber was creates, i.e. after the user released the mouse. It’s precisely in this method that one should package the action (say, the creation of a shape) in a command and push it onto the undo-stack. In the dummy tool above only an informative message is displayed.

Of course, in order to manage the available tools and to connect them to the UI you need some more code in the form of some tool manager. The tool manager is just a wrapped generic list created through Unity inside the surface class. Note, in this context, that the concept of a tool only makes sense on the UI level and is, hence, not re-usable in other surfaces (e.g. a web-interface).

In the next part we’ll discuss the other end of the architecture; data abstraction and the serialization of diagrams.

The surface (or View)

The surface holds and presents the UIElement by means of an inherited Canvas. All diagram elements inherit (sometimes through a long chain) from the Control class, but we will describe later on the hierarchy behind shapes and diagram elements.

The surface is a rather ‘dumb’ piece in the sense that it’s mostly a sink for all actions from the user and a drain for all things coming from the controller:

• it presents a variety of routed commands which allows one to attach buttons and other UI element to act upon the diagram
• it offers a lot of events one can hook on to (OnShapeAdded, OnPageAdded, OnLayerRemoved…)
• it listens to mouse events and pass them on to the Controller
• it hosts the various tools (selection tool, rotate tool…) which only have a meaning on the surface level: the controller doesn’t know about ‘tools’, much less the Model
• it enables zooming, panning and scrolling of the diagram (which is really easy in WPF)
• it presents all the methods you need to manipulate, edit and create diagrams (and all its organizing elements like layers, pages, groups) by means of code

The surface is, hence, just a facade to the outside world and this is precisely why one can replace it with Silverlight or a web-based interface. You can replace here the word ‘facade’ with API if you prefer since the collection of event, proprerties and methods available on the diagram control really represent the programming interface to the diagram the control).

One important piece on top of the list is, however, the presentation factory. The controller and the model are unaware of the layout algorithm and simply hold the raw data of the shape. When a shape (or diagram element in general) is added to the diagram it really starts in the Document and bubbles up to the surface. This occurs by means of standard chained events and this chain end at the surface where either the diagram element is added ‘as is’ or handed over to the presentation factory:

1
2
3
4
5
6
7
8
9

void Controller_OnDiagramElementAdded(object sender, DiagramEntityArgs e)
{
    if (e.Entity is ILayoutShape)
    {
        presentationFactory.Present(e.Entity as ITreeShape);
    }
    else if (e.Entity is UIElement)
        this.Children.Add(e.Entity as UIElement);
}

For example, the standard diagram (we call it a ‘Concept map’) doesn’t need extra presentation processing while a mindmap uses the presentation factory to lay shapes in the well-known fashion. The presentation factory is responsible for the layout and this is the place where one can either use the wonderful possibilities of WPF or rely on precise positioning of elements on the Canvas. We have even gone a step beyond this and use the presentation factory to convert shapes on the fly and sometimes ‘wrap’ shapes in containers, which e.g. makes it possible to have grouping or sub-structures which not necessarily have a meaning on the controller or model level.

The Controller

The controller, well, controls the interactions and acts as a switchboard between the model and the surface. One might wonder why it is useful to separate the code into a controller and not keep it in the view. The reason is that this

• enables the re-use of the controller with a different view, i.e. makes a lot of the code view-independent
• does not force one to override or carry the inherited methods which the Canvas (or whatever base surface class) brings along

This decoupling comes with a penalty; you need to write extra code to marshall objects from the controller to the surface and vice versa. We have used standard events to couple the different layer together (as can be see in the screenshot above of the bubbled events from the controller to the surface).

The controller receives changes from the surface mainly through three channels:

• by means of mouse actions (OnMouseUp)
• by means of tools (a selection process)
• by means of API calls (AddShape())

Whatever the channels, the end result is always the encapsulation of some change(s) in either an undo-redo unit or the preparation before being delegated to a lower service, like e.g. the serialization of the diagram. So, the controller can be seen as a packaging engine for the command patternor a preparative switchboard for other services.

Either there a change in the diagram or some other action is performed. If the change affects the diagram (or the organization of it) this has an effect on the Document, otherwise the action is delegated. Serialization or data export are not considered as undoable action and, hence, only those action affecting the Document are recorded in the undo stack.

As is highlighted in the diagram above, the controller makes use of the Unity (injection) container(s) to access diverse services, which can be replaced by custom services if necessary.

From the point of view of the controller:

• the surface is an ‘unknow’ layer where events are passed to and where eventually Document objects (layers, shapes…) are being presented
• the Document is a repository where things bubble up from or are delivered to

From the point of view of the surface the controller is where all actions are being delegated to. In fact, most methods on the surface resemble the follow snippet:

1
2
3
4

public IShape AddShape(Point location, object content, LayerBase layer, PageBase page)
{
    return Controller.AddShape(location, content, layer, page);
}

while things bubbling from the Document are usually simply passed on to the surface as in the prototype below:

1
2
3
4

void document_OnPageAdded(object sender, PageArgs e)
{
    RaiseOnPageAdded(e);
}

Note that through this decoupling we were able to unit-test all interactions without having to rely on UI-automation.

The Document (or Model)

The Document is where the diagram and its hierarchy is stored and where all changes propagate from. For example, if on the surface a new shape is added:

• this action will be first packaged by means of the controller to an undoable unit
• the unit will be executed and an AddShape method will be called on the Document
• the document will create the new shape and will allocate it
• by allocating it a post-creation process will be started which binds events, dresses the shape (templating), binds it to the layer and so on
• the OnShapeAdded event will be raised and it will propagate up to the surface where either it’s presented by adding it via the Canvas.Children.Add() method or there is a presentation process which will lay it out before adding it to the canvas as a child

So, the Document contains the actual information while the controller contains the actual ‘logic’. From the point of view of the Document the controller is simply an instance which passes the info on upwards.

Before WPF it would have been possible to abstract away all UI dependence. Because of the templating mechanism and for other reasons the elements of the Document are not completely WPF independent and, hence, not UI independent. This has been handled by adding an additional layer of abstraction which was also necessary for the serialization of the diagram (the Document, that is). We will delve deeper into this when we present the serialization and import/export of the diagram.

Before guiding you in all the abstract concepts let me summarize the features of GraphSquare (abbreviated: G2):

• a WPF diagramming control which can be hosted in any WPF or WinForm application
• a model-view-controller (MVC) architecture which can be used seperately: we have used the model, for example, independently in Silverlight and WCF without having to include the view and the controller
• a plugable system based on Unity which allows you to replace whole parts of the system: you can register custom implementations of, say, the undo or selection service without recompiling the control
• traditional layout algorithms (tree, circular, mindmap…) which are decoupled from the view through a presentation factory and which, here again, allows you to manipulate the layout outside the compiled code. In particular, the mindmap and tree layouts are completely built based on WPF’s templating system and, hence, amounts to restyling some XAML
• undo-redo through a classic command pattern on the controller level
• a provider (adapter) based serialization system which can also be extended through Unity. Out of the box we have built binary, XML and a WCF adapter to import/export data.
• an event-based decoupling of the MVC which enables you to connect to, for example, over twenty events on the model to react according to you needs on an application level
• a data-flow mechanism  (engine) built into the architecture which allows HMI and other data simulation diagramming interfaces
• design-time support for Visual Studio and Expression Blend
• fully coded on .Net 3.5 (no interop or Win32 code)
• multi-page support: you can have multiple pages per control much like one has multiple sheets in Excel. Each page can have a separate layout algorithm, a separate set of layers and a custom theme.
• multi-layer support: inside a page you can organize shapes in layers which can be manipulated independently (transparency, visibility and so on)
• custom themes, styles, templates and the wealth of WPF features are at your disposal to customize shapes and connections
• custom shapes for specific purposes: the class shape (UML-like shapes), collapsible shapes (with WPF animations)…
• autoconnect shapes, drag-dop support for various data types, zooming, panning, thumbnail view of the diagram…and many more features you can expect of a high-end diagramming library

We will move through the architecture in a top-down approach and start with the main lines and refine as we move down. The intention is to cover more-or-less the following topics:

• The MVC architecture: how the model, the view, the presenter and the controller work together to organize the diagram together with many classes and interfaces.
• Presentation decoupling and layout: how the layout is achieved without affecting the underlying Model
• Serialization, XML and the data abstraction layer: how we abstracted away the WPF stuff to remain with just the raw data for serialization purposes and data exchange in general.
• Styles, themes, templates: how the WPF presentation is used in G2.
• Testing and unit testing: how we thoroughly tested the architecture.
• Tree diagrams,Concept maps, mindmapping: how the particular layout schemes can be used. We’ll give an overview of the samples we created.
• Server side diagramming and WCF: how the G2-server was built.
• A proof of concept: Silverlight. This is to highlight the fact that G2 can be used with Silverlight and, in fact, any type of presentation layer.
• Independence through Unity: how Unity articulates extensibility and unifies the decoupling of classes.
• Tools for the surface: the tool-mechanism or how you can allow the end-user to create things, pass it to undoredo and manipulate the Model.
• Shapes, connections, connectors and the object model: everything about diagram entities and how the visuals are connected in an object model.
• The data-flow engine: how we implemented the data-flow mechanism inside the control.
• Design-time support: not specific for a diagramming control but merely an overview of the new design-time paradigm Microsoft introduced.
• Animations and other WPF specifics: about tangentially related topics.

The diagram below should be kept in mind as we move along, it schematically depicts the essential blocks of what we will cover.

In Part II we will discuss the MVC system.

1
2
3
4
5
6
7
8

//turn the diagramming surface into a mindmapping surface surface.CurrentPage.PageType = PageType.MindMap;
 
//You can add a child in one go.
surface.AppendChild(new ThoughtShape("A sub-node"), surface.CurrentPage.Root as ThoughtShape);
//Or you can customize the node
ThoughtShape t = new ThoughtShape("Child of the root");
t.Background = Brushes.LightSlateGray;
surface.AppendChild(t, surface.CurrentPage.Root as ThoughtShape);

With the same ease one can turn the surface in a canvas with tree-layout. The resulting application (together with some info I added to highlight our API) looks like in the screenshot below.

Out of the box you get the gray/silver thought-shapes but one can turn on some themes and use the styling features of WPF. By simply adding a custom style in the Window resource or at the application level (the preferred way to save system resources) you get something like this:

The icons are easily added by means of code like

1
2
3
4
5
6
7
8
9

 
ThoughtShape t;
t.Icon = GetImage("category.gif");
...
private ImageSource GetImage(string name)
{
  ImageSourceConverter imageSourceConverter = new ImageSourceConverter();
  return imageSourceConverter.ConvertFromString(@"pack://application:,,/Resources/images/" + name) as ImageSource;
}

Of course, just with these feature you can go on and on, experiment and test various things. Obviously, sometimes you need to flip the diagram or rotate it, which can also be done with only one line of code

1

Surface.HandleCommand(DiagramSurface.ChangeLayoutDirectionCommand, null);

To complete this little intro to GraphSquare’s I should mention the following features:

• full undo-redo
• totally, completely fully MVC (or MVP or MVCP or MMVC)
• multi-page and multi-layer support built into the control
• styling, themes, templates and the whole WPF customization
• extensibility through our own plugable system and Unity
• data abstraction and adapters for XML, binary and relational data
• runtime scripting

In addition, you can expect more from Denis on our server-side diagramming solution (baptized G2 Server) and many more high-end features.