Introduction to MonoTouch.Dialog

Adding a UINavigationController

Notice however that the title “Create a task” that we passed to the BindingContext is not displayed. This is because the DialogViewController is not part of a UINavigatonController. Let’s change the code to add a UINavigationController as the window’s RootViewController, and add the DialogViewController as the root of the UINavigationController as shown below:

nav = new UINavigationController(dvc);
window.RootViewController = nav;

Now when we run the application, the title appears in the UINavigationController’snavigation bar as the screenshot below shows:

By including a UINavigationController, we can now take advantage of other features of MT.D for which navigation is necessary. For example, we can add an enumeration to the Expense class to define the category for the expense, and MT.D will create a selection screen automatically. To demonstrate, modify the Expense class to include an ExpenseCategory field as follows:

public enum Category
{
       Travel,
       Lodging,
       Books
}
      
public class Expense
{
       …

       [Caption("Category")]
       public Category ExpenseCategory;
}

Running the application now results in a new row in the table for the category as shown:

Selecting the row results in the application navigating to a new screen with rows corresponding to the enumeration, as shown below:

Working with Element Values

Elements that are used to capture user input expose a public "Value" property that holds the current value of the element at any time. It is automatically updated as the user uses the application and does not require any programmer intervention to fetch the state of the control.

This is the behavior for all of the Elements that are part of MonoTouch.Dialog but it is not required for user-created elements.

new StringElement (
       "Click me",
       () => { new UIAlertView("Tapped", "String Element Tapped"
, null, "ok", null).Show(); })

mtRoot = new RootElement ("Demos", new RadioGroup("MyGroup", 0))

var root = new RootElement ("Meals", new RadioGroup ("myGroup", 0))

public class SampleOwnerDrawnElement : OwnerDrawnElement
{
    public SampleOwnerDrawnElement (string text) : base(UITableViewCellStyle.Default, "sampleOwnerDrawnElement")
    {
        this.Text = text;
    }
    public string Text
    {
        get;set;   
    }
    public override void Draw (RectangleF bounds, CGContext context, UIView view)
    {
        UIColor.White.SetFill();
        context.FillRect(bounds);
        UIColor.Black.SetColor();  
        view.DrawString(this.Text, new RectangleF(10, 15, bounds.Width - 20, bounds.Height - 30), UIFont.BoldSystemFontOfSize(14.0f), UILineBreakMode.TailTruncation);
    }
    public override float Height (RectangleF bounds)
    {
        return 44.0f;
    }
 }

var je = new JsonElement ("Dynamic Data", "http://tirania.org/tmp/demo.json");

var je = JsonElement.FromFile ("json.sample");
using (var reader = File.OpenRead ("json.sample"))
    return JsonElement.FromJson (JsonObject.Load (reader) as JsonObject, arg);

Pull-to-Refresh Support

Pull to Refresh is a visual effect originally found in Tweetie2 which became a popular effect among many applications.

To add automatic pull-to-refersh support to your dialogs, you only need to do two things: hook up an event handler to be notified when the user pulls the data and notify the DialogViewController when the data has been loaded to go back to its default state.

Hooking up a notification is simple, just connect to the RefreshRequested event on the DialogViewController, like this:

dvc.RefreshRequested += OnUserRequestedRefresh;

Then on your method OnUserRequestedRefresh, you would queue some data loading, request some data from the net, or spin a thread to compute the data. Once the data has been loaded, you must notify the DialogViewController that the new data is in, and to restore the view to its default state, you do this by calling ReloadComplete:

dvc.ReloadComplete ();

Search Support

To support searching, set the EnableSearch property on your DialogViewController. You can also set the SearchPlaceholder property to use as the watermark text in the search bar.

Searching will change the contents of the view as the user types, it searches the visible fields and shows those to the user. The DialogViewController exposes three methods to programatically initiate, terminate or trigger a new filter operation on the results:

StartSearch, FinishSearch, PerformFilter

The system is extensible, so you can alter this behavior if you want

Background Image Loading

MonoTouch.Dialog incorporates TweetStation's image loader. This image loader can be used to load images in the background, supports caching and can notify your code when the image has been loaded.

It will also limit the number of outgoing network connections.

The image loader is implemented in the ImageLoader class, all you need to do is call the DefaultRequestImage method, you will need to provide the Uri for the image you want to load, as well as an instance of the IImageUpdated interface which will be invoked when the image has been loaded.

The ImageLoader exposes a "Purge()" method that you can call when you want to release all of the images that are currently cached in memory. The current code has a cache for 50 images. If you want to use a different cache size (for instance, if you are expecting the images to be too large that 50 images would be too much), you can just create instances of ImageLoader and pass the number of images you want to keep in the cache.

Via the clever usage of LINQ and C#’s initialization syntax, LINQ can be used to create an element hierarchy, for example, the following code creates a screen from some string arrays:

var rootElement = new RootElement ("LINQ root element") {
    from x in new string [] { "one", "two", "three" }
    select new Section (x) {
       from y in "Hello:World".Split (':')
       select (Element) new StringElement (y)
    }
};

This could easily be combined with an XML data store or data from a database to create complex applications nearly entirely from data.

Creating Custom Elements

You can create your own element by deriving from either an existing Element or by deriving from the root class Element.

To create your own Element, you will want to override the following methods:

// To release any heavy resources that you might have
    void Dispose (bool disposing);

    // To retrieve the UITableViewCell for your element
    // you would need to prepare the cell to be reused, in the
    // same way that UITableView expects reusable cells to work
    UITableViewCell GetCell (UITableView tv)

    // To retrieve a "summary" that can be used with
    // a root element to render a summary one level up. 
    string Summary ()
    // To detect when the user has tapped on the cell
    void Selected (DialogViewController dvc, UITableView tableView, NSIndexPath path)
    // If you support search, to probe if the cell matches the user input
    bool Matches (string text)

If your element can have a variable size, you need to implement the IElementSizing interface, which contains one method:

// Returns the height for the cell at indexPath.Section, indexPath.Row
    float GetHeight (UITableView tableView, NSIndexPath indexPath);

If you are planning on implemeneting your GetCell method by calling "base.GetCell(tv)" and customizing the returned cell, you need to also override the CellKey property to return a key that will be unique to your Element, like this:

static NSString MyKey = new NSString ("MyKey");
    protected override NSString CellKey {
        get {
            return MyKey;
        }
    }

This works for most elements, but not for the StringElement and StyledStringElement as those use their own set of keys for various rendering scenarios. You would have to replicate the code in those classes.

DVCs

Both the Reflection and the Elements API use the same DialogViewController. Sometimes you will want to customize the look of the view or you might want to use some features of the UITableViewController that go beyond the basic creation of UIs.

The DialogViewController is merely a subclass of the UITableViewController and you can customize it in the same way that you would customize a UITableViewController.

For example, if you wanted to change the list style to be either Grouped or Plain, you could set this value by changing the property when you create the controller, like this:

var myController = new DialogViewController (root, true){
        Style = UITableViewStyle.Grouped;
    }

For more advanced customizations, like setting the default background for the DialogViewController, you would need to create a subclass of it and override the proper methods.

This example shows how to use an image as the background for the DialogViewController:

class SpiffyDialogViewController : DialogViewController {
    UIImage image;

    public SpiffyDialogViewController (RootElement root, bool pushing, UIImage image)
        : base (root, pushing)
    {
        this.image = image;
    }
    public override LoadView ()
    {
        base.LoadView ();
        var color = UIColor.FromPatternImage(image);
        TableView.BackgroundColor = UIColor.Clear;
        ParentViewController.View.BackgroundColor = color;
    }
}

Another customization point is the following virtual methods in the DialogViewController:

public override Source CreateSizingSource (bool unevenRows)

This method should return a subclass of DialogViewController.Source for cases where your cells are evenly sized, or a subclass of DialogViewController.SizingSource if your cells are uneven.

You can use this override to capture any of the UITableViewSource methods. For example, TweetStation uses this to track when the user has scrolled to the top and update accordingly the number of unread tweets.

Elements do not provide validation themselves as the models that are well suited for web pages and desktop applications do not map directly to the iPhone interaction model.

If you want to do data validation, you should do this when the user triggers an action with the data entered. For example a "Done" or "Next" buttons on the top toolbar, or some StringElement used as a button to go to the next stage.

This is where you would perform basic input validation, and perhaps more complicated validation like checking for the validity of a user/password combination with a server.

How you notify the user of an error is application specific: you could pop up a UIAlertView or show a hint.