Soon I started using the power of code generation libraries like freezed, json_serializable, slang_build_runner and others. These libraries usually work with attributes in your class or methods, or by transforming existing metadata files into more useful stuff.

The build_runner package will be in charge of generating all the code for you. I learned this is a very common pattern and practice in the Dart world and hard to avoid if you value your time.

Have you wondered if those files should go into the git repository or not?

I asked myself that question. Searching some people's opinions online I saw there are different points of view on the subject so I needed to figure it out internally on my team.

Next, let's explore reasons to include or exclude those files 👇.

The main reasons to include code generation files

If the files are not included, your app will not build correctly whenever you:

• clone the project

• switch branches

• git clean -xdf

• other cleaning scenarios

It's inconvenient to manually run commands or tasks to generate all files every time.

I heard some people saying that code generation can differ from one machine to another. For instance: your local machine vs a CI server machine. However, I guess this can be done right by taking good care of dependency versions.

Reasons to exclude code generation files

Let's assume you work in a team environment where Pull Requests and code reviews are common practice. The list of files to review will increase significantly when all the generated files are there, making it harder for your teammates (we can learn to ignore them but it requires an extra effort that might not be worth it).

Besides that, you will be polluting your git repository with unnecessary trash that eventually will increase the size big time. It might not look like a problem now, but your build pipeline will suffer in the long term.

If you work alone in small projects though, those files should not be a problem.

Guess what? we chose to exclude the files

But then we needed to fix the problems mentioned above.
It became easy with a couple of workarounds.

The first thing to notice is that watching files to re-generate the code is as simple as running this command line:

flutter pub run build_runner watch --delete-conflicting-outputs

If you feel too lazy to mess with your terminal you might like this VSCode extension which does the same with a click of a button.

But that didn't always work for me.
If someone added a new dart package to Pubspec we had to run dart pub get.

The library we use for translations (slang) requires an additional command to convert JSON files into dart code: dart run slang.

And who knows what we'll need in the future?

Simple solution: automate the boring stuff

Simple as a git post-checkout script.
You can tell Git to run any command(s) you like when switching branches.
Here's how to:

Create a file post-checkout (without extension) at: [Project root]/.git/hooks/ directory.

Your system may be hiding the .git directory, but this can be done easily with your command line:

cd your project
touch .git/hooks/post-checkout # creates the file
chmod -x .git/hooks/post-checkout # give it execute permissions
code .git/hooks/post-checkout # open the file with vscode for edit

At this point, you can add any commands to the file. This is my current setup:

#!/bin/bash
# 👆this line here is important!

# restore packages
dart pub get 
# generate translations
dart run slang 
# library code generation
dart run build_runner build --delete-conflicting-outputs

And now I can happily switch to any branch of the project and everything will just work.

The only downside now is that switching branches will take longer than expected.

If you like this solution and want to share it with the team, beware that
git hooks cannot be shared through git (as with any other file inside .git/) so your teammates won't see it. Instead, you can instruct them how to set it up or just add this information to the project's README as I did.

There is a workaround though, but that goes beyond the scope of this post. Here's a blog explaining it.

I´ve been doing this forever on web development so I tried on mobile by configuring a proxy on Android emulators according to some detailed tutorials out there.

Result: None of the tutorials worked with my Xamarin app

Well, those tutorials work 😜 but Xamarin needs an additional piece of code. As I don´t want to replicate wonderful posts from other developers, I recommend you follow this specific tutorial step by step: The Android Emulator and Charles Proxy: A Love Story. It´s a bit long but hey, you only need to do it once!

Xamarin-specific bits: writing a custom HttpClientHandler

I´ve been pulling my hair big time because the tutorial didn´t work until I tried manually pointing to Charles Proxy from the app code.

First of all, check your local IP and Charles port.
On Charles, click menu > Local IP addresses:

Then go to menu > Proxy > Proxy settings… to check the default port:

Setup the proxy with a custom HttpClientHandler:

var handler = new HttpClientHandler
{
    // local ip, charles port
    Proxy = new WebProxy("192.168.0.52", 8888) 
};

Then use it whenever you create an HttpClient in your app

var client = new HttpClient(handler);
// TODO: make some requests to test charles!

At this point, everything should work and you should be able to observe all network traffic. For the sake of your mental health, make sure you only do this in debug mode and it never gets to production.

Bonus

Beware that your app stops working if your HttpClientHandler is pointing to Charles but Charles is not running. To tackle this issue I use an environment variable that I can set to false when I´m not debugging network traffic:

// http proxy
if (Environment.GetEnvironmentVariable("UseHttpProxy") == "true")
{
    var handler = new HttpClientHandler
    {
        Proxy = new WebProxy(
            Environment.GetEnvironmentVariable("ProxyHost"), 
            int.Parse(Environment.GetEnvironmentVariable("ProxyPort") 
                ?? throw new InvalidOperationException()))
    };

    _client.SetHandler(handler);
}

To set env variables on Android, you have to create a text file in your Android project root, call it env.txt (it can be any name) and set its Build Action to AndroidEnvironment:

We will create a default channel to be used when any push notification arrives. You can create multiple channels but I bet most applications will be just fine with one.

public static class NotificationHelper 
{ 
    public const string ChannelId = "com.unique.string.onyourapp.default";

    // make sure you call this method only once 
    public static void CreateDefaultChannel(Context context) 
    { 
        if (Build.VERSION.SdkInt < BuildVersionCodes.O) 
            return;
        var channel = new NotificationChannel(ChannelId, 
            "AppName default", NotificationImportance.High);

        channel.EnableVibration(true); 
        channel.LockscreenVisibility = NotificationVisibility.Public;

        var notificationManager = (NotificationManager) context
            .GetSystemService(Context.NotificationService);

        notificationManager.CreateNotificationChannel(channel); 
    }

    // method extension to ease the creation of the nofication 
    public static NotificationCompat.Builder SetChannelIdIfNeeded( 
        this NotificationCompat.Builder builder, string channelId) 
    { 
        if(Build.VERSION.SdkInt >= BuildVersionCodes.O) 
            builder.SetChannelId(channelId);

        return builder; 
    } 
}

It's a good idea to create the default channel at the app start, either on your main activity or your custom Application OnCreate() override:

public override void OnCreate() 
{ 
    base.OnCreate(); 
    NotificationHelper.CreateDefaultChannel(this); 
}

Last, but not least, you need to make and slight modification to the code that creates the notification.

Before:

var notificationBuilder = new NotificationCompat.Builder(this)
    .SetSmallIcon(Resource.Drawable.ic_notification)
    .SetContentTitle(title)
    .SetContentText(message)
    .SetAutoCancel(true)
    .SetContentIntent(pendingIntent);

After:

var notificationBuilder = new NotificationCompat.Builder(this)
    .SetChannelIdIfNeeded(NotificationHelper.ChannelId) // method extension
    .SetSmallIcon (Resource.Drawable.ic_notification)
    .SetContentTitle(title)
    .SetContentText(message)
    .SetAutoCancel(true)
    .SetContentIntent(pendingIntent);

From now on your push notifications will start working again on Android 8.

How do I create it?

I´m assuming your launcher icon (app icon) is called ic_launcher, but it can be any name. Just make sure it´s the same name you set on your main launcher activity:

[Activity(
        Label = "YourApp"
        , MainLauncher = true
        , Icon = "@mipmap/ic_launcher"]
public class YourInitialActivity : AppCompatActivity {}

Create the folder YourAndroidProject/Resources/mipmap-anydpi-26.

Inside that folder create an xml file with the exact name of your launcher icon. For instance: ic_launcher.xml:

<?xml version="1.0" encoding="utf-8"?>
<!-- ic_launcher.xml content -->
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
    <background android:drawable="@color/ic_launcher_background_color" />
    <foreground android:drawable="@mipmap/foreground" />
</adaptive-icon>

Replace ic_launcher_background_color with any color you like.

Now create an SVG file with the vector tool of your choice, like Sketch, Illustrator, Inkscape, etc. The canvas should be a square of 108 x 108. However the size doesn´t matter as we can change it later on the XML, but it´s handy to set it right for design purposes. For that, I would suggest you download a template from the link (Resources and tools). I used the Illustrator template and placed my icon inside the grey circle in the middle.

Here you can see the same with the template grid:

Exporting the SVG:

This will be the foreground graphic of your adaptative icon, so apart from the icon, everything else should be hidden, BUT YOU NEED an square shape for the icon to size correctly. The trick is to make that shape invisible, setting the alpha to 0, as per the screenshot above.

Export it to SVG, and then convert it to an Android vector XML file. Call that file foreground.xml and put it in the mipmap-anydpi-26 folder.

Now open foreground.xml and make sure the width and height are 108:

<?xml version="1.0" encoding="utf-8"?>
<vector xmlns:android="http://schemas.android.com/apk/res/android"
    android:width="108dp"
    android:height="108dp"
    android:viewportWidth="108"
    android:viewportHeight="108">

    ...

</vector>

That´s it.

TL;DR

Take a look at the Official UI guideline, a blog post about Understanding Android Adaptive Icons and another about Implementing Adaptive Icons

IMO, the most remarkable improvement is that the launcher icon can now be an Android vector XML. That means you can take any SVG file, convert it to the Android XML format with a tool, and then use that single file in all 26+ devices.

Can I get rid of the former drawable/mipmap_[density] versions?

NO. Any device using an SDK less than 26 will ignore your new adaptative icon, so you still have to provide images for the different pixel densities for those devices.

So what´s the point then?

1. As I said earlier, your icon will look bad on API 26+ without an adaptative icon.

2. Device OEMs can now consolidate the appearance of all icons on the launcher. This means that your icon can now adapt to different kinds of shape masks, and even be animated, looking good everywhere. One device OEM can set a circle mask on them, while another OEM can use a rectangle with rounded corners.

What´s wrong with the good old, super awesome AutoLayout?

Consider the following layout (“–” represents padding):

|--view1--view2--view3--|

Doing this silly layout the “old” way involves lots of constraints, for instance:

• align the views vertically (2 or 3 constraints)

• set leading and trailing of each view (3 to 4 constraints)

• set with and height of each view (6 constraints or maybe 3 if they provide intrinsic height)

Next week your boss comes to tell you that view2 is no longer needed, so you have to:

• delete view2

• manually rearrange view3 to get the place where view2 was placed, fixing all the wrong constraints

Then, a great designer in your team tells you by Slack that paddings are too small. There´s no single “padding” or “margin” property. Again, you need to change all leading/trailing constraints of each view, one by one.

And well… we are talking about “design time” here (aka Interface Builder). If you need to do this on runtime (state changes) it may become a nightmare because you first need to locate the attached constraints to remove them and then create new ones, if you know what I mean.

Now imagine you´ve got like 5 more places in the screen where this can happen. The next move is probably pulling your hair and complaining about how miserable your life is.

What can UIStackView do for me?

This guy is using AutoLayout internally and it does nothing you can´t do with AutoLayout and some code but it will make your life easier in many ways. Think of it as some kind of Android LinearLayout. It can also be nested easily to achieve more complex layouts.

Going back to the previous example, if view1, view2 and view3 were within a UIViewStack wouldn´t need any constraint created manually (unless you want to) and removing one of them (design time or runtime) will readjust all the constraints for you. Done. The same happens if you want to add a new view to the stack. You can even animate that change with a one-liner, as we will see later.

To recap:

1. Design time layouts become easier

2. Coded layouts become easier

3. Runtime state changes (adding or removing elements) take a single line of code.

4. Animating layout changes is now very simple

Shut up and show me the code

No need to give you all the small details of this component, as you can easily google it. Instead, I´m going to jump right to the code with some real cases I came up with.

All the samples will be coded (sorry IB fans) and layout with the anchor constraint API (did I say it correctly?) and a few method extensions to speed up trivial tasks. If you don´t know what it is, go ahead and read my previous post.

Adding and removing elements

For UIStackView to manage children's constraints properly, use any of the following methods:

stackView.AddArrangedSubview(view);
stackView.InsertArrangedSubview(view, index);
stackView.RemoveArrangedSubview(view);

You can also remove a child view like you normally would:

view.RemoveFromSuperview();

A vertical scroll of stacked elements

Let´s say you need a simple scroll for a small number of stacked elements (better use a Table if you need many) but you don´t need/want to mess with cells.

A simple UIStackView within a UIScrollView will make the trick:

public override void ViewDidLoad()
{
    base.ViewDidLoad();

    // Create and add Views

    var stackView = new UIStackView
    {
        Axis = UILayoutConstraintAxis.Vertical,
        // make the inner views to fill the whole available width
        Alignment = UIStackViewAlignment.Fill, 
        Distribution = UIStackViewDistribution.EqualSpacing,
        // margin between views
        Spacing = 4, 
        // apply padding between the parent view (the scroll) 
        // and the stack
        LayoutMargins = new UIEdgeInsets(4, 4, 4, 4),
        // this will make padding actually work
        LayoutMarginsRelativeArrangement = true 
    };

    var scroll = new UIScrollView();
    Add(scroll);

    scroll.AddSubview(stackView);

    // Add some views to the stack with random height and color
    // Notice that we use AddArrangedSubview rather than the 
    // former AddSubview for UIStackView to manage it. 
    // Otherwise it won´t work
    for (var i = 0; i < 20; i++)
        stackView.AddArrangedSubview(GetRandomView());

    // Layout Views

    // For AutoLayout to work, all views and nested views need to set 
    // "TranslatesAutoresizingMaskIntoConstraints" property to `false`. 
    // It´s easy to forget it so I created an extension method that 
    // will do this to the view and its subviews
    scroll.EnableAutoLayout();

    // "FullSizeOf" is a method extension to set leading, trailing, 
    // bottom and top constraints
    scroll.FullSizeOf(View); 
    stackView.FullSizeOf(scroll);

    // constraint needed when the UIStackView is inside the UIScrollView
    stackView.WidthAnchor
        .ConstraintEqualTo(scroll.WidthAnchor)
        .Active = true;
}

private static readonly Random Random 
    = new Random(DateTime.Now.Millisecond);

private static UIView GetRandomView()
{
    var view = new UIView();
    view.BackgroundColor = ColorUtil.GetRandomColor();
    view.Layer.CornerRadius = 8;

    var randomHeight = Random.Next(25, 200);
    view.HeightAnchor.ConstraintEqualTo(randomHeight).Active = true;
    return view;
}

I´m using here two custom method extensions: FullSizeOf() and EnableAutoLayout to make the code cleaner.

Nested stacks

Nesting stacks is no mystery as it works like nesting any other view.

The layout hierarchy looks like the following:

UIScrollView
    UIStackView
        UIView (with gray background)
            UILabel
            UIStackView
                Children
        UIView (with gray background)
            UILabel
            UIStackView
                Children
        ...

Grab the source code for this screen here

Add/remove elements with animation

Animating constraints in iOS has been always simple:

// add/remove/change constraints and then...
UIView.Animate(0.3, () => view.LayoutIfNeeded());

Working with UIViewStack is not different. When adding or removing a view from the stack it will internally change the constraints with AutoLayout so the animation works in the same way. Let´s create a button that will add an arranged subview with a random color to the stack. Then destroy that view when the user taps on it:

public override void ViewDidLoad()
{
    base.ViewDidLoad();

    var stack = new UIStackView
    {
        TranslatesAutoresizingMaskIntoConstraints = false,
        Axis = UILayoutConstraintAxis.Vertical,
        Alignment = UIStackViewAlignment.Fill,
        Distribution = UIStackViewDistribution.FillEqually,
        Spacing = 4
    };

    Add(stack);

    stack.FullSizeOf(View);

    var addButton = new UIButton(UIButtonType.System);
    addButton.SetTitle("Add view", UIControlState.Normal);
    addButton.TouchUpInside += (s, e) =>
    {
        stack.InsertArrangedSubview(GetAutoDestroyButton(), 1);
        UIView.Animate(0.3, () => stack.LayoutIfNeeded());
    };

    stack.AddArrangedSubview(addButton);
}

private static UIButton GetAutoDestroyButton()
{
    var button = new UIButton
    {
        BackgroundColor = ColorUtil.GetRandomColor(true),
        ClipsToBounds = true
    };

    button.SetTitle("Destroy", UIControlState.Normal);
    button.TouchUpInside += (sender, args) => 
        UIView.Animate(0.3, () => 
            button.Hidden = true, button.RemoveFromSuperview);

    return button;
}

Accordion component POC

In a real application, I would probably use a UITableView to create an accordion component because it will handle items and scroll more efficiently using cell virtualization. However, this can be done faster with a UIStackView and it works pretty decently for a few views:

In this sample, only a single item can be opened at a time. The content view is a resized UILabel with a random height, but it could be anything else.

It´s worth saying that content views in this sample are all added on initialization and later hidden and shown. This means that UIStackView is smart enough to handle constraint changes not only when views are added or removed, but also when their visibility changes (view.Hidden = true|false), simplifying your code even more.

private static readonly Random Random 
    = new Random(DateTime.Now.Millisecond);

private UIStackView _stackView;
private UIView _visibleContent;

public override void ViewDidLoad()
{
    base.ViewDidLoad();

    _stackView = new UIStackView
    {
        TranslatesAutoresizingMaskIntoConstraints = false,
        Axis = UILayoutConstraintAxis.Vertical,
        Alignment = UIStackViewAlignment.Fill,
        Distribution = UIStackViewDistribution.EqualSpacing,
        Spacing = 1
    };

    var scroll = new UIScrollView();
    Add(scroll);

    scroll.AddSubview(_stackView);
    scroll.FullSizeOf(View);
    scroll.EnableAutoLayout();

    _stackView.FullSizeOf(scroll);
    _stackView.WidthAnchor
        .ConstraintEqualTo(scroll.WidthAnchor)
        .Active = true;

    for (var i = 0; i < 25; i++)
    {
        _stackView.AddArrangedSubview(
            GetButton($"Category {i + 1}", i));

        _stackView.AddArrangedSubview(
            GetContent($"Child of category {i + 1}", i + 100));
    }
}

private UIButton GetButton(string title, int tag)
{
    var button = new UIButton
    {
        BackgroundColor = UIColor.Blue,
        HorizontalAlignment = UIControlContentHorizontalAlignment.Left,
        ContentEdgeInsets = new UIEdgeInsets(4, 10, 4, 10),
        ClipsToBounds = true,
        Tag = tag
    };

    button.SetTitle(title, UIControlState.Normal);

    button.TouchUpInside += (sender, args) =>
    {
        var content = View.ViewWithTag(((UIButton) sender).Tag + 100);
        UIView.Animate(0.3, () =>
        {
            if (_visibleContent != null)
                _visibleContent.Hidden = true;

            if(!Equals(_visibleContent, content))
                content.Hidden = !content.Hidden;

        }, () => _visibleContent = content.Hidden ? null : content);
    };

    return button;
}

private static UILabel GetContent(string title, int tag)
{
    var content = new UILabel
    {
        Text = title,
        Lines = 0,
        TextAlignment = UITextAlignment.Center,
        TextColor = UIColor.Black,
        BackgroundColor = UIColor.LightGray,
        Tag = tag,
        Hidden = true
    };

    content.HeightAnchor
        .ConstraintEqualTo(Random.Next(40, 250))
        .Active = true;

    return content;
}

Change axis with animation

I don´t see any useful case to change the axis in a real app, but here it is. Changing from horizontal to vertical and viceversa takes one line:

stackView.Axis = UILayoutConstraintAxis.Horizontal;
stackView.Axis = UILayoutConstraintAxis.Vertical;

And if you want to animate it:

UIView.Animate(0.3, () =>
{
    stackView.Axis = stackView.Axis == UILayoutConstraintAxis.Vertical
        ? UILayoutConstraintAxis.Horizontal
        : UILayoutConstraintAxis.Vertical;

    stackView.LayoutIfNeeded();
});

Enough for now, you can find these and other samples in the GitHub repo.
Here it´s a screen recording with the rest of them:

Remember that UIStackView is available from iOS 9. If you need to support previous versions, go ahead and try Cheesebaron TZStackView.

Every UIView has now several NSLayoutAnchor properties

that can be used to create constraints (NSLayoutCostraint):

Creating a constraint does not mean it will be active by default and you´ve got do it explicitly:

var c = origin.CenterXAnchor.ConstraintEqualTo(target.CenterXAnchor);
c.Active = true;

// or just
origin.CenterXAnchor
    .ConstraintEqualTo(target.CenterXAnchor)
    .Active = true;

// activate multiple constraints at once:
NSLayoutConstraint.ActivateConstraints(new[]{
    origin.CenterXAnchor.ConstraintEqualTo(target.CenterXAnchor),
    origin.CenterYAnchor.ConstraintEqualTo(target.CenterYAnchor)
});

It´s really easy to create UIView method extensions. For instance, to center a view in its parent (following the above sample):

public static NSLayoutConstraint[] CenterIn(this UIView origin, 
    UIView target, bool activate = true)
{
    origin.TranslatesAutoresizingMaskIntoConstraints = false;
    var contraints = new[]
    {
        origin.CenterXAnchor.ConstraintEqualTo(target.CenterXAnchor),
        origin.CenterYAnchor.ConstraintEqualTo(target.CenterYAnchor)
    };

    if (activate)
        NSLayoutConstraint.ActivateConstraints(contraints);

    return contraints;
}

// use case
view.CenterIn(parentView);

Now let´s adjust a view to its parent bounds:

public static NSLayoutConstraint[] FullSizeOf(this UIView origin, 
    UIView target, UIEdgeInsets edges, bool activate = true)
{
    origin.TranslatesAutoresizingMaskIntoConstraints = false;
    var contraints = new[]
    {
        origin.LeadingAnchor.ConstraintEqualTo(target.LeadingAnchor, edges.Left),
        origin.TrailingAnchor.ConstraintEqualTo(target.TrailingAnchor, -edges.Right),
        origin.TopAnchor.ConstraintEqualTo(target.TopAnchor, edges.Top),
        origin.BottomAnchor.ConstraintEqualTo(target.BottomAnchor, -edges.Bottom)
    };

    if(activate)
        NSLayoutConstraint.ActivateConstraints(contraints);

    return contraints;
}

public static NSLayoutConstraint[] FullSizeOf(this UIView origin, 
    UIView target, float margin = 0, bool activate = true) 
    => origin.FullSizeOf(target, new UIEdgeInsets(margin, margin, margin, margin), activate);

// use cases
view.FullSizeOf(parentView);
view.FullSizeOf(parentView, 10); // 10 points of margin
view.FullSizeOf(parentView, new UIEdgeInsets(5, 10, 5, 10));

And now let´s make a shortcut to set the width and height:

public static NSLayoutConstraint[] ConstraintSize(this UIView origin, 
    float width, float height, bool activate = true)
{
    origin.TranslatesAutoresizingMaskIntoConstraints = false;
    var contraints = new[]
    {
        origin.WidthAnchor.ConstraintEqualTo(width),
        origin.HeightAnchor.ConstraintEqualTo(height)
    };

    if (activate)
        NSLayoutConstraint.ActivateConstraints(contraints);

    return contraints;
}

// use case
view.ConstraintSize(100, 100);

Consider playing around with all anchors and Constraint...To() methods. You can make anything.

Those method extensions above return an array of constraints so we can deactivate/activate them later. Consider a set of constraints like a visual state we can store in a variable:

var small = view.ConstraintSize(100, 80);
var big = view.ConstraintSize(200, 200, false);

States can get even more complex by chaining the constraints from multiple objects:

var small = view1.ConstraintSize(100, 100)
    .Concat(view2.ConstraintSize(50, 50))
    .Concat(view3.ConstraintSize(30, 30))
    .ToArray();

var big = view1.ConstraintSize(200, 200, false)
    .Concat(view2.ConstraintSize(100, 100, false))
    .Concat(view3.ConstraintSize(60, 60, false))
    .ToArray();

State changes

Simply deactivate the old constraints and activate the new ones:

NSLayoutConstraint.DeactivateConstraints(small);
NSLayoutConstraint.ActivateConstraints(big);

With the basic blocks in place, let´s create a new extension to get fancy with state changes:

public static void ChangeState(this UIView parentView, 
    NSLayoutConstraint[] before, 
    NSLayoutConstraint[] after, 
    double duration = 0)
{
    parentView.LayoutIfNeeded();

    NSLayoutConstraint.DeactivateConstraints(before);
    NSLayoutConstraint.ActivateConstraints(after);

    if (duration > 0)
    {
        UIView.Animate(duration, parentView.LayoutIfNeeded);
    }
}

// use cases
View.ChangeState(small, big);
View.ChangeState(big, small, duration:0.3);

Here´s a working example:

In the past, I´ve done some view pagers with those circle page indicators in Android that involved using either 3rd party libraries or a ton of code. That was before Lollipop came out. This is now very obvious and ridiculously simple but I´m sharing it here in case you don´t know about it.

With a little xml we are going to convert this:

into something like this:

Making the connection between the view-pager and our page indicator (TabLayout) takes a single line:

var viewPager = FindViewById<ViewPager>(Resource.Id.viewpager);
viewPager.Adapter = new MyPagerAdapter(SupportFragmentManager, funkyList);

var dots = FindViewById<TabLayout>(Resource.Id.dots);
dots.SetupWithViewPager(viewPager, true); // <- magic here

So we now need to make a TabLayout look like a page indicator.
The good news are that it´s pretty easy:

<LinearLayout
    android:orientation="vertical"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:paddingLeft="@dimen/activity_horizontal_margin"
    android:paddingRight="@dimen/activity_horizontal_margin"
    android:paddingBottom="@dimen/activity_horizontal_margin">
    <android.support.v4.view.ViewPager
        android:id="@+id/viewpager"
        android:layout_width="match_parent"
        android:layout_height="250dp"
        android:layout_marginBottom="5dp"/>
    <android.support.design.widget.TabLayout
        android:id="@+id/dots"
        android:layout_width="match_parent"
        android:layout_height="26dp"
        local:tabBackground="@drawable/dot_selector"
        local:tabGravity="center"
        local:tabIndicatorHeight="0dp"
        local:tabPaddingStart="7dp"
        local:tabPaddingEnd="7dp"/>
</LinearLayout>

tabPaddingStart and tabPaddingEnd will define the separation between the dots.

I´ve used a LinearLayout here for brevity but you could use whatever layout you need. It doesn´t matter.

To have TabLayout available in your project you must install the Nuget Xamarin.Android.Support.Design.

Now take a look at the dot_selector.xml. It defines the selected/unselected states:

<?xml version="1.0" encoding="utf-8" ?>
<selector xmlns:android="http://schemas.android.com/apk/res/android">
  <item android:drawable="@drawable/selected_dot" android:state_selected="true"/>
  <item android:drawable="@drawable/default_dot"/>
</selector>

The selected state (selected_dot.xml):

<?xml version="1.0" encoding="utf-8" ?>
<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
  <item>
    <shape
      android:innerRadius="0dp"
      android:shape="ring"
      android:thickness="4dp"
      android:useLevel="false">
      <solid android:color="@color/page_indicator_selected_color"/>
    </shape>
  </item>
</layer-list>

And the default state (default_dot.xml), that is pretty much the same with a different color:

<?xml version="1.0" encoding="utf-8" ?>
<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
  <item>
    <shape
      android:innerRadius="0dp"
      android:shape="ring"
      android:thickness="4dp"
      android:useLevel="false">
      <solid android:color="@color/page_indicator_default_color"/>
    </shape>
  </item>
</layer-list>

As you may guess, android:thickness is the size of the dot.

That´s it!

• Separate the download process from the current view in a background task: we don´t want the download to stop if we navigate to another view or the device goes idle

• The download stream should not write directly to memory: the device may run out of memory very soon, crashing your app. Instead, we should write to the file system directly as soon as the bytes are downloaded.

• Report progress: users should know how long it will take to finish. Otherwise, it may look like it´s stuck

The same rules apply to any operating system, like iOS and Android (that will come in a future post).

It turns out that doing all this on Windows RT is fairly easy thanks to the class Windows.Networking.BackgroundTransfer.BackgroundDownloader, because it will follow all the rules:

var downloader = new BackgroundDownloader();
var download = downloader.CreateDownload(uri, destinationFile);
download.Priority = BackgroundTransferPriority.High;

var progressCallback = new Progress<DownloadOperation>(operation =>
{
    if (download.Progress.TotalBytesToReceive > 0)
    {
        var percent = download.Progress.BytesReceived * 100 / download.Progress.TotalBytesToReceive;
        // TODO report percent
    }
});

await download.StartAsync().AsTask(progressCallback);
// at this point the download has been completed

That´s it actually, but to implement this in a cross-platform way (thinking about iOS and Android and Xamarin.Forms) I created an event OnDownloadPercentProgress and wrapped it all with a platform-agnostic interface:

using System;
using System.Threading.Tasks;
using PCLStorage;

namespace Core.Helpers
{
    public interface IFileManager
    {
        /// <summary>
        /// Parameter double is the download percent
        /// Parameter string is the uri string currently being downloaded
        /// </summary>
        event Action<double, string> OnDownloadPercentProgress;


        Task<IFile> Download(Uri uri, IFolder downloadFolder, string desiredFileName = null);
    }
}

IFolder comes from the cross-platform storage library called PCLStorage

And here is the implementation on Windows:

using System;
using System.IO;
using System.IO.Compression;
using System.Threading.Tasks;
using Windows.Networking.BackgroundTransfer;
using Windows.Storage;
using Core.Helpers;
using PCLStorage;

namespace UWP.Helpers
{
    public class FileManager : IFileManager
    {
        public event Action<double, string> OnDownloadPercentProgress;

        public async Task<IFile> Download(Uri uri, IFolder downloadFolder, string desiredFileName = null)
        {
            desiredFileName = desiredFileName ?? Path.GetFileName(uri.LocalPath);

            var localFolder = await StorageFolder.GetFolderFromPathAsync(downloadFolder.Path);
            var destinationFile = await localFolder.CreateFileAsync(desiredFileName, Windows.Storage.CreationCollisionOption.GenerateUniqueName);

            var downloader = new BackgroundDownloader();
            var download = downloader.CreateDownload(uri, destinationFile);
            download.Priority = BackgroundTransferPriority.High;

            var progressCallback = new Progress<DownloadOperation>(operation =>
            {
                if (download.Progress.TotalBytesToReceive > 0)
                {
                    var percent = download.Progress.BytesReceived * 100 / download.Progress.TotalBytesToReceive;
                    OnDownloadPercentProgress?.Invoke(percent, uri.ToString());
                }
            });

            await download.StartAsync().AsTask(progressCallback);

            return await downloadFolder.GetFileAsync(desiredFileName);
        }
    }
}

We are done.

Actually, you don´t need HockeyApp to side-load Windows 10 apps as you can upload your build wherever you want, but obviously, with HockeyApp you get many more features for free, like crash reporting, distribution management, event logging, integration with Visual Studio, etc. Visual Studio Mobile Center is the next generation of HockeyApp but as of today it doesn´t support Windows Universal apps.

Compile a release build for mobile

Not much to add to the HockeyApp doc in this step. Check it out here, but bear in mind that in the last step (architecture check-boxes), you should only check ARM if your app is not targeting desktop devices. The bundle size will decrease a lot.

Upload the build to HockeyApp

The result of the previous step is a new folder (i.e: YourApp_1.0.0.0_Test) in the AppPackages directory of your UWP project with the following contents:

You´ve got two options here:

1. Upload the single .appxbundle file

2. Zip the whole directory and upload it to HockeyApp (this is the same thing Visual Studio does for you when right-clicking on the project > HockeyApp > Distribute app…)

Whether you choose 1 or 2 will affect how users install the app:

If you choose 1), installing the app is easier, as the user will just click the “Download” button on the HockeyApp web page, and then click the downloaded file to install it.

Going for option 2 means that a user will download a zip to the mobile device, open that zip and then tap on the .appxbundle file to finally install the app. Windows 10 Mobile cannot open zips out of the box, so a third-party app like Zip Archiver should be installed first.

Why on earth would you want to make things harder with a zip file and why is it the default option in Visual Studio? See below on “Installing dependencies”

Upload symbols to HockeyApp

To see better crash information and stack traces, right after the previous step, drag the .appxsym file to the HockeyApp page. Then, go to ProjectFolder/bin/ARM, zip the file YourAppName.pdb and drag YourAppName.zip to the same page. There is also a button to “Upload build or sym” and another to “Upload zipped .pdb”:

Device setup

To install any app compiled with a test certificate or coming from an untrusted source (like HockeyApp), the user needs to enable Windows developer mode on the device. Go to settings > Update & Security > For developers and select “Developer mode”:

Installing dependencies

When you debug your app through a USB connected device, Visual Studio will install all dependencies for you in the background and everything will just work. However, other users trying to install your app will open the .appxbundle, install the app and it won´t appear anywhere on the device. Windows won´t let them know something wrong happened (the installation failed silently without errors).

This happens when dependencies are not installed on the user´s device because they don´t get installed automatically (BTW, a simple “please, install dependencies” alert would have saved me many wasted hours thinking that I did something wrong with the app bundle package).

Dependencies need to be installed usually once per device unless you release a new version of your app that targets a newer version of Windows. In that case, users will need to install them again. It´s a good idea to inform the users and testers about these details before they try to install them for the first time.

Installing dependencies involves having them on the device and then clicking/tapping on each one to confirm the installation. They are located in the “Dependencies” folder inside the zip you created previously:

Keep in mind that if your release build is composed of the single .appxbundle file, you are assuming the user already installed these dependencies.

Installing the application

Last, but not least, tap on the .appxbundle to install the app. Everything should work now. For the next version release, this is the only step needed.

The reason to use SQLiteAsyncConnection is pretty simple: I want my app to stay responsive when querying the database. Big queries take time. If the connection is synchronous my app may become unresponsive for a while until the data is retrieved. We care about users and C# async/await is relatively easy, so let´s use it everywhere!, right?

Well… sqlite is NOT async.

That´s right. Sqlite accesses data synchronously, no matter what. Async connections are fake 💩. Simple as that. Taking a look at the source code, you´ll find out that every method call is wrapped within a Task:

public Task<T> GetAsync<T>(object pk) where T : new()
{
    return Task.Factory.StartNew(() =>
    {
        var conn = GetConnection();
        using (conn.Lock())
        {
            return conn.Get<T>(pk);
        }
    });
}

Okay… so what´s wrong with it?

You are forced to use async wrappers everywhere

You can´t choose to make something async only when it´s needed. Once you set up an async connection, you will be forced to use these wrappers everywhere unless you create a new sync connection. What if you find out that a query is fast enough to be sync?

1. Would you stick to async/await anyway?

2. Would you create a new sync connection for those cases?

If you choose 1, you are complicating things. I mean: you are awaiting a Task rather than a direct and simple method call, forcing your method to be async. I found out that in mobile development (mostly in UI initialization logic), async is harder to manage. Database queries are usually made on-screen initialization, so there you have it. You still can make it worst, by getting the result of a task in a sync fashion: var user = connection.GetAsync<User>(1).Result so you end up using a sync method, wrapped in a Task to be async, and then converted back to sync. Well played! :punch:

If you choose 2, you are complicating things. The best way to work with SQLite in most cases is by reusing a single connection during the whole life cycle.

You need to be careful with concurrency and locking errors

Just take a look here or here or here. The same can happen with sync connections, but it´s easier to fix:

Connection = new SQLiteConnection(path, SQLiteOpenFlags.ReadWrite 
    | SQLiteOpenFlags.Create | SQLiteOpenFlags.FullMutex);

I´ve never had a single issue when creating the connection that way.

How many of your queries really take so long to be async?

I´m pretty sure that if you measure the time it takes for most of your queries to run, you´ll realize they are surprisingly fast. Fast enough so that the user won´t notice a delay, therefore async here is useless. Go ahead and try it.

What happens with blocking, time-consuming queries?

In those cases, you can/should just make the async wrapper yourself. Besides, your code will provide more information: other developers working with your code will easily figure out which queries are fast enough (sync) and which are not (async).

Conclusion

KISS is an acronym for "Keep it simple, stupid". The KISS principle states that most systems work best if they are kept simple rather than made complicated; therefore simplicity should be a key goal in design and unnecessary complexity should be avoided.

Wikipedia

Have you been through that moment when you click a form text field and the soft keyboard shows up overlaying the text field and you can´t see what you are writing?

Let´s make it worse:

• No way to hide the keyboard (How can I tap the damn button below?).

• The “next” or “intro” keys of the keyboard do exactly nothing.

These problems and others may end up with your users leaving the app and never coming back.

Did you let that happen?

I´m pretty sure you won´t let that happen if you are a decent developer :flushed:, but I´ve seen this in more than a few apps (an Apple reviewer may have been drunk at the time) and I want to stop it now 🎷.

Let´s get to work

Before we start writing code to control keyboard behavior we need to create a container view for our form that can scroll.

Creating scrollable containers with Interface Builder and AutoLayout

You can´t just drop your form elements into a scroll view. That won´t work if you want to center the form vertically (i.e: a login screen). The form must be wrapped within its container.

1. Place a UIScrollView fitting the full size of the view controller

2. Create a content UIView inside the scroll view, fitting the full size as well

3. Add your form elements to the content view

4. Add necessary constraints to make everything work with Autolayout

This can be challenging if you´ve never done it before, so here is an awesome step-by-step video showing you exactly how to proceed with Xcode:

My favourite visual designer is Xcode Interface Builder which is set as my default visual designer on Xamarin Studio. Visual Studio / Xamarin designers are the alternative but I could not get them to work properly yet.

Creating scrollable containers with code

If you don´t like designers, the same can be done with code.
I´m going to replicate the same layout of the video above with FluentLayout as it simplifies constraints creation substantially.

FormViewController.cs:

// Create containers
var contentView = new UIView();
var scrollView = new UIScrollView {contentView};
Add(scrollView);

// Create form elements
for (var i = 0; i < 20; i++)
{
    contentView.Add(new UITextField
    {
        Placeholder = $"Test {i + 1}",
        BorderStyle = UITextBorderStyle.RoundedRect
    });
}

var loginButton = new UIButton(UIButtonType.System);
loginButton.SetTitle("Login", UIControlState.Normal);

contentView.Add(loginButton);

// Auto layout
View.SubviewsDoNotTranslateAutoresizingMaskIntoConstraints();
View.AddConstraints(scrollView.FullWidthOf(View));
View.AddConstraints(scrollView.FullHeightOf(View));
View.AddConstraints(
    contentView.WithSameWidth(View),
    contentView.WithSameHeight(View).SetPriority(UILayoutPriority.DefaultLow)
);

scrollView.SubviewsDoNotTranslateAutoresizingMaskIntoConstraints();
scrollView.AddConstraints(contentView.FullWidthOf(scrollView));
scrollView.AddConstraints(contentView.FullHeightOf(scrollView));

var formConstraints = contentView
    .VerticalStackPanelConstraints(new Margins(20), contentView.Subviews);

// very important to make scrolling work
var bottomViewConstraint = contentView.Subviews.Last()
    .AtBottomOf(contentView).Minus(20);

contentView.SubviewsDoNotTranslateAutoresizingMaskIntoConstraints();
contentView.AddConstraints(formConstraints);
contentView.AddConstraints(bottomViewConstraint);

This is what we’ve got so far:

Notice that once we tap on the bottom text view, the keyboard appears leaving the content behind. We can´t even scroll down to the bottom and there´s no way to hide the keyboard.

Hiding the keyboard when tapping on the view background

This doesn´t solve the problem, but at least the user will have a chance to visualize the whole content again. We will detect tap gestures on the controller´s View and just react when the trigger is not a UIControl (i.e.: text field or button). A method extension will allow us to reuse the behaviour on any screen:

public static UITapGestureRecognizer DismissKeyboardOnTap(this UIView view)
{
    // Add gesture recognizer to hide keyboard
    var tap = new UITapGestureRecognizer { CancelsTouchesInView = false };
    tap.AddTarget(() => view.EndEditing(true));
    tap.ShouldReceiveTouch = (recognizer, touch) => !(touch.View is UIControl);

    view.AddGestureRecognizer(tap);

    return tap;
}

Back in our FormViewController:

View.DismissKeyboardOnTap();

Reacting to keyboard events

_willHideObserver = NSNotificationCenter.DefaultCenter
    .AddObserver(UIKeyboard.WillHideNotification, OnKeyboardNotification);

_willShowObserver = NSNotificationCenter.DefaultCenter
    .AddObserver(UIKeyboard.WillShowNotification, OnKeyboardNotification);

That´s all you need to react to the keyboard showing up or hiding in iOS. Next, we´ll move/animate the content accordingly:

private void OnKeyboardNotification(NSNotification notification)
{
    if (!_controller.IsViewLoaded) return;

    //Check if the keyboard is becoming visible
    var visible = notification.Name == UIKeyboard.WillShowNotification;

    //Start an animation, using values from the keyboard
    UIView.BeginAnimations("FollowKeyboard");
    UIView.SetAnimationBeginsFromCurrentState(true);
    UIView.SetAnimationDuration(UIKeyboard.AnimationDurationFromNotification(notification));
    UIView.SetAnimationCurve((UIViewAnimationCurve)UIKeyboard.AnimationCurveFromNotification(notification));

    //Pass the notification, calculating keyboard height, etc.
    var landscape = _controller.InterfaceOrientation == UIInterfaceOrientation.LandscapeLeft
                    || _controller.InterfaceOrientation == UIInterfaceOrientation.LandscapeRight;

    var keyboardFrame = visible
        ? UIKeyboard.FrameEndFromNotification(notification)
        : UIKeyboard.FrameBeginFromNotification(notification);

    OnKeyboardChanged(visible, landscape ? keyboardFrame.Width : keyboardFrame.Height);

    //Commit the animation
    UIView.CommitAnimations();
}

protected virtual void OnKeyboardChanged(bool visible, nfloat keyboardHeight)
{
    var activeView = _controller.View.FindFirstResponder();
    var scrollView = activeView?.FindSuperviewOfType(_controller.View, typeof(UIScrollView)) as UIScrollView;

    if (scrollView == null)
        return;

    if (!visible)
    {
        scrollView.ContentInset = UIEdgeInsets.Zero;
        scrollView.ScrollIndicatorInsets = UIEdgeInsets.Zero;
    }
    else
    {
        var contentInsets = new UIEdgeInsets(0.0f, 0.0f, keyboardHeight, 0.0f);
        scrollView.ContentInset = contentInsets;
        scrollView.ScrollIndicatorInsets = contentInsets;

        // Position of the active field relative isnside the scroll view
        var relativeFrame = activeView.Superview.ConvertRectToView(activeView.Frame, scrollView);

        var landscape = _controller.InterfaceOrientation == UIInterfaceOrientation.LandscapeLeft
                        || _controller.InterfaceOrientation == UIInterfaceOrientation.LandscapeRight;

        var spaceAboveKeyboard = (landscape ? scrollView.Frame.Width : scrollView.Frame.Height) - keyboardHeight;

        // Move the active field to the center of the available space
        var offset = relativeFrame.Y - (spaceAboveKeyboard - activeView.Frame.Height) / 2;
        scrollView.ContentOffset = new CGPoint(0, offset);
    }
}

The previous code is adapted from a great snippet found here. I put it all together in a single reusable class called AutoScrollHelper to use in any UIViewController by composition:

private UITapGestureRecognizer _gesture;
private AutoScrollHelper _autoScrollHelper;

public override void ViewWillAppear(bool animated)
{
    base.ViewWillAppear(animated);

    _gesture = View.DismissKeyboardOnTap();
    _autoScrollHelper = new AutoScrollHelper(this);
}

public override void ViewWillDisappear(bool animated)
{
    base.ViewWillDisappear(animated);

    _gesture.Dispose();
    _gesture = null;

    _autoScrollHelper.Dispose();
    _autoScrollHelper = null;
}

Now any focused control will be always visible:

Using tags and the Next/Done button

A user can simply tap the next control when she is done editing the current one, but a good practice is enabling the “Next” key of the keyboard to do it automatically. This will be faster and improve usability.

Setting the property ReturnKeyType of a UITextField we can change the keyboard “intro” key to:

• UIReturnKeyType.Next

• UIReturnKeyType.Done

• UIReturnKeyType.Send

• UIReturnKeyType.Search

• etc

We are interested in Next and Done actions, so we will set “Next” for all text fields except the last one, which will be set to “Done”:

const int count = 7;
for (var i = 1; i <= count; i++)
{
    _contentView.Add(new UITextField
    {
        Placeholder = $"Test {i}",
        BorderStyle = UITextBorderStyle.RoundedRect,
        Tag = i, // useful for ShouldReturn delegate
        ReturnKeyType = i < count 
            ? UIReturnKeyType.Send 
            : UIReturnKeyType.Done
    });
}

Subscribe to the ShouldReturn delegate on every UITextField:

textField.ShouldReturn = ShouldReturn;

Now we need to change the focus to the next control when the “Next” key is pressed and hide the keyboard when the “Done” key is pressed on the last UITextField. Additionally, the “Done” key may invoke the Save() method if you like:

private bool ShouldReturn(UITextField textField)
{
    if (textField.ReturnKeyType == UIReturnKeyType.Done)
    {
        // we are done, hide the keyboard
        View.EndEditing(true);

        // nothing else to edit, why not just saving the form?
        Save();

        return false;
    }

    var nextTag = textField.Tag + 1;
    UIResponder nextControl = _contentView.ViewWithTag(nextTag);

    if (nextControl != null)
    {
        // set focus on the next control
        nextControl.BecomeFirstResponder();
    }
    else
    {
        // Not found, hide keyboard.
        View.EndEditing(true);
    }

    return false;
}

Conclusion

I think usability is sometimes underappreciated and it can make a big difference for the end user if we care about these kinds of details.

I focused on the obvious in this post, but a lot more can be done. It depends on the type of form and the type of controls we are dealing with.

Grab the complete source code at GitHub

If you are a .NET dev, Resx is probably the first thing crossing your mind, and that´s fine for Visual Studio. It can be implemented on Xamarin as well but you´ll find yourself (and potentially your client) editing XML files with the following format:

<data name="Key" xml:space="preserve">
    <value>KeyValue</value>
    <comment>Some comments</comment>
</data>

At least at the time of this writing Xamarin does not provide a Resx editor. Besides, you need to write code for manually loading the correct language, based normally on the current system culture. Xamarin has a nice tutorial on how to do it. You´ll find even iOS, Android and Win phone concrete implementations and a bunch of useful details. They also explain how to automatically bind translations in XAML creating a IMarkupExtension class.

The problem is:

• I don´t want to repeat all that process in every project, or even copy-paste across projects and platforms.

• I just want a library to do it for me

• I don´t like/want Resx files and I don´t want to have a client editing them

Hello I18N-Portable

I love simplicity and that´s why I created a lightweight utility for this matter. My idea was based on two concepts:

• Simpler locale files (similar to java .properties format)

• Straightforward setup and initialization

Install

I18N-Portable is a Nuget package

Locales

A locale is just a [locale].txt file with key=value pairs. You place these files on a PCL project once, under a directory called “Locales”. They will be shared across platforms:

# this is a comment
key1 = one
key2 = two
key3 = translation with \nmultiple \nlines

Setup

I18N.Current
    .SetFallbackLocale("en")
    .Init(GetType().GetTypeInfo().Assembly);

That´s all you need. Simple enough?

You put this line at your PCL code, normally in any method executed during app initialization.

What just happen?

The Init() method tells I18N-Portable which assembly is hosting the locales. Now the library figures out the current system culture and tries to load a matching locale. If you didn´t provide a locale for the current culture, it will fall back to English (“en.txt”).

From now on you can get any translation with a string method extension from anywhere in your app PCL and/or platform projects:

var translation = "key1".Translate(); // one

Can I use this with my awesome Mvvm framework?

Sure. You can bind any text view to a particular key, from XAML (Xamarin.Forms, UWP, etc) and classic Android/iOS if your Mvvm framework implements bindings:

XAML:

<Button Content="{Binding [key]}" />

Xamarin.Forms XAML:

<Button Text="{Binding [key]}" />

Android with MvvmCross:

<TextView local:MvxBind="Text [key]" />

iOS with MvvmCross:

bindingSet.Bind(view).To("[key]");

To make this work, a simple indexer is needed in your ViewModel (I usually do this in a BaseViewModel once):

public string this[string key] => key.Translate();

More handy stuff and details are available at the GitHub repo

Cheers!