Help-SimpleDialogsTutorial

Simple Dialogs Tutorial

The Simple Dialogs framework, introduced in version 1.1.0, is a part of the Two-Layered GUI Toolkit that allows for the UI-toolkit-agnostic definition of entire dialog boxes. This tutorial provides some guidance on the first steps with using the framework.

Basics

The Simple Dialogs framework serves for two main purposes:

• Plugins can flexibly provide user interfaces or dialog boxes without introducing any UI-toolkit-specific dependencies.
• Certain parts of a user interface can be defined based upon a simplistic model rather than dealing with the full complexity of a UI toolkit.

The Simple Dialogs framework works similarly as other parts of the Two-Layered GUI Toolkit: The user interface is defined in a UI-toolkit-independent way by means of settings objects, which are then interpreted by UI-toolkit-specific classes that display an actual user interface. In the case of the Simple Dialogs framework, the settings objects are a tree of so-called dialog elements.

The tree of dialog elements is passed to a dialog generator that creates a UI-toolkit-specific representation of the tree. Internally, this works by invocation of dialog element generators and label generators.

While the Two-Layered GUI Toolkit provides a number of basic standard dialog elements, such as text boxes, or check boxes, applications can add their own domain-specific dialog elements.

Defining a User Interface

A simple dialog element tree can consist of as little as one dialog element. As that would be somewhat uninteresting, though, some of the pre-defined dialog elements can contain child elements (or are explicitly meant for that purpose). Therefore, our first Simple Dialogs user interface is going to consist of a FormContainerElement, a TextInputElement, and an Int32InputElement. It will serve to input the name and the age of a contact:

var parent = new FormContainerElement();
var tName = new TextInputElement();
var iAge = new Int32InputElement() {
  Minimum = 0,
  Maximum = 200
};
parent.ChildElements.Add(tName);
parent.ChildElements.Add(iAge);

The parent variable now contains a reference to the root element of our user interface. We can pass this root element to a DialogGenerator appropriate for the UI toolkit we would like to use to retrieve a widget tree that we can use in one of our windows. Alternatively, we can pass the root element to an overload of DialogBox.Create that conveniently accepts such a root element:

var dlg = DialogBox.Create("Simple Dialogs Test", parent, ButtonDef.CloseButton);

If this dialog is displayed, it should look similar to this:

Labels

This looks nice for a start, but something is missing. As it is, we know the purpose of our two input elements, but a user cannot - the dialog elements have no descriptive labels!

Luckily, Simple Dialogs lets us assign a label to our input elements. In fact, any dialog element can receive a label. The DialogElement.Label property is typed to object, meaning that we can assign any value there.

In this case, we are going to assign a simple string value, as well as an AccessString value (a string with a mnemonic character). We can extend the above example by inserting the following code somewhere after tName and iAge have been created, and somewhere before the user interface is generated:

tName.Label = "Name:";
iAge.Label = new AccessString("Age:", 'a');

If we display the dialog box again, it should now look roughly like this:

At this point, it should be noted that dialog element labels in Simple Dialogs are not necessarily textual: As mentioned above, we can assign arbitrary objects to the DialogElement.Label property, and they will be displayed, provided that an appropriate label generator is available.

Handling of Events

Simple Dialogs elements issue a number of notifications while being edited, so it is possible for us to create interactive user interfaces. For most of these, no new dedicated events have been declared. Instead, they use the PropertyChanged event from the INotifyPropertyChanged interface.

For a simple showcase, we will extend our dialog box to contain a display element that indicates the initials extracted from the name. Therefore, add a text element (a dialog element used to display short texts) first, and do not forget to add it to the parent container:

var tInitials = new TextElement() {
  Label = "Initials:"
};
parent.ChildElements.Add(tInitials);

Then, register an event handler with the PropertyChanged event of tName. We will use the IncludesProperty extension method to check whether the text of tName has been modified. A very crude algorithm to extract the initials is suggested here - refine at your discretion:

tName.PropertyChanged += delegate(object source, PropertyChangedEventArgs args) {
  if (args.IncludesProperty("Text")) {
    string[] names = tName.Text.Split(' ', '-');
    tInitials.Text = string.Join("", names.Where(n => n.Length >= 1).Select(n => n[0].ToString()));
  }
};

Before compiling this code, do not forget to add using directives for the namespaces System.ComponentModel and System.Linq to your source file.

After these modifications, the dialog box looks like this: