Connecting the application logic with the user interface in Uiml.net

Let me warn you first, this will be a long blog post.

Creating a cross-platform user interface with Uiml.net is one thing, actually getting it to do something useful by interacting with the application logic is another issue.

Currently, the logic element in UIML only specifies the class of object associated with a call element. This implies that the objects are stateless or static and that the UIML rendering engine will instantiate the object each time a call is made.

Here’s a simple example:

<call name="Console.println">
  <param>Uiml says hello!</param>
</call>
...
<logic>
  <d-component id="Console" maps-to="System.Console">
    <d-method id="println" returns-value="void" maps-to="WriteLine">
      <d-param id="message" type="System.String"/>
    </d-method>
  </d-component>
</logic>

Of course, in this example that’s fine, because the Console class only has static methods. It doesn’t have a state we wish to monitor in the user interface. When we want to interact with a database connection for example, things become more difficult.

One way to solve the problem would be to develop a mechanism to specify which instance of an object will be referenced by a specific call. This would allow multiple instances of the same external object to exist within the system and be referenced separately.

However, in our opinion this would only complicate the application logic binding mechanism and the UIML language itself.

Uiml.net provides an API that allows multiple object instances to be connected to the same user interface. When a call to the application logic is made, we first check if a call can be invoked on one of the connected object instances. When that fails, we’ll try to invoke it statically liked we did before.

If we call a certain method, all connected objects will invoke this method. There’s a catch though. When the call has to return a value, which return-value do we use? We suggest to use the return-value of the object that was connected last. Considering the fact that each invocation may have an effect on the other connected objects, this is the most sensible thing to do.

This API has been supported in Uiml.net for a while now (in fact, I completed the implementation during my internship in July 2004, building upon Kris ideas). Unfortunately we hadn’t communicated it very well. Hopefully this blog post is a start. I will probably also provide some example in the future.

Following is a simple example with a modification of the UIML calculator. When you hit the = button, the contents of the output entry will be sent to the Print method of an instance of the CalcInspector class. Depending on a member _times, this value is written out _times times:

<behavior>
  ...
  <rule>
    <condition>
      <event part-name="bsol" class="ButtonPressed"/>
    </condition>
    <action>
      <call name="CalcInspector.Print">
        <param>
          <property part-name="output" name="text"/>
        </param>
      </call>
    </action>
  </rule>
  ...
</behavior>
...
<logic>
  <d-component id="CalcInspector" maps-to="CalcInspector">
     <d-method id="Print" maps-to="Print">
      <d-param id="output" type="System.String"/>
    </d-method>
  </d-component>
</logic>
...

public class CalcInspector 
{
  int _times;
  public CalcInspector(int times)
  {
    _times = times;
  }
 
  /// <summary>
  /// Prints the output _times times.
  /// </summary>
  public void Print(string output)
  {
    for(int i = 0; i < _times; i++)
    {
      Console.WriteLine(output);
    }
    Console.WriteLine("...Done!");
  }
}

The relevant code when the interface is rendered:

CalcInspector small = new CalcInspector(2);
CalcInspector large = new CalcInspector(5);
 
uimlDoc.Connect(small);
uimlDoc.Connect(large);

As you can see, we created two CalcInspector instances: small and large. One will write the output two times while the other will print it five times. Following are two screenshots on a PDA, one just before pressing the = and one right after:

[img:113715576,medium]

[img:113715577,medium]

Since we connected small first, small‘s Write method will be executed first.

We also implemented a connection to other way around. It allows the application logic to subscribe to certain events from the UIML user interface. This was originally inspired by the connection mechanism of Glade. We wanted an easy and convenient way to connect with the rendered user interface. Uiml.net takes advantage of the .NET framework‘s basic support for aspect-oriented programming to realize this. Methods, classes, variables and the like can be augmented with so-called attributes. These attributes can then be queried using reflection. The instances are again connected in the same way as in the previous example.

The attribute UimlEventHandler specifies that a method can deal with user interface events. Parameters can be passed with the attribute that specify the information the method wants to receive together with the event.

[UimlEventHandler("ButtonPressed")]
public void OnButtonPressed(Part sender, UimlEventArgs a)
{
  Console.WriteLine("Received event from a part:");
  Console.WriteLine("\tApparantly it's the \"{0}\" part",
                    sender.Identifier);
  Console.WriteLine("\tIt's class is <{0}>", sender.Class);
  Console.WriteLine("\tThe UI object is of the type [{0}]",
                    sender.UiObject.GetType());
  }
}

In this example, the method would receive every ButtonPressed event. It then writes out from which part it got the event. It writes out its class, and the class of the actual underlying user interface object. So in fact the application logic queries a piece of the part tree, in which a lot of information is present.

But we could go further:

[UimlEventHandler("ButtonPressed", "fr", "l_recent")]
public void OnButtonPressed(Part sender, UimlEventArgs a)
{
  Part fr = a.GetPart("fr");
 
  Console.WriteLine("\nPart \"{0}\" of type <{1}> has" + 
                    "the following subparts:", fr.Identifier, fr.Class);
 
  System.Collections.IEnumerator e = fr.GetSubParts();
  while(e.MoveNext())
  {
    Part sub = (Part)e.Current;
    Console.WriteLine("\t\"{0}\" of type <{1}>;",
                      sub.Identifier, sub.Class);
  }
 
  Part l_recent = a.GetPart("l_recent");
  string propertyName = "text";
  Console.WriteLine("The [{0}] property of part \"{1}\"" +
                    " is: {2}", propertyName, l_recent.Identifier, 
                    l_recent.GetProperty(propertyName));
}

Since this is a lot of code, we’ll go over it gradually.

1	[UimlEventHandler("ButtonPressed", "fr", "l_recent")]

The first line specifies that we are interested in ButtonPressed events. We also request the parts fr and l_recent from the user interface, so we can examine them. These parts will be collected in the UimlEventArgs parameter.

4	Part fr = a.GetPart("fr");

This line gets the fr part from the event arguments.

The next few lines go through all of fr‘s children, and writes them to the console:

System.Collections.IEnumerator e = fr.GetSubParts();
while(e.MoveNext())
{
  Part sub = (Part)e.Current;
  Console.WriteLine("\t\"{0}\" of type <{1}>;",
                    sub.Identifier, sub.Class);
}

In a similar fashion, we request the l_recent part:

Part l_recent = a.GetPart("l_recent");
string propertyName = "text";
Console.WriteLine("The [{0}] property of part \"{1}\"" +
                  " is: {2}", propertyName, l_recent.Identifier, 
                  l_recent.GetProperty(propertyName));

Here we write out l_recent‘s text property. So it is also possible to request properties from a part, and query their value. In fact, the whole Uiml.net API is available through this mechanism.

One might wonder, what if the application logic is only interested in certain events from a specific branch of the part tree? This is possible by adding an additional parameter to the Connect method, specifying which part and its subchildren it should connect to:

uimlDoc.Connect(this, "l_recent");