Create a time zone selection control for .NET MAUI (2023)

This article is part of thatMaui UI JulyA community series of blog posts and videos hosted by Matt Goldman. Be sure to check out the other posts in this series!

Hello, my name is Matt Johnson Pints. I recently joined Sentry as a working engineerSentry .NET-SDK.One of my first big projects was raising theFixed .NET, now westart preview.Come on, tried!

I'm also a time zone nerd. Yes, I jumped in while others shouted to avoid the problem. If you've ever asked a technical question about time zones on the internet, chances are we've met. Ah yes - time zones. They are absolutely essential to our modern world, but they can be a pain to deal with - especially for software developers! Most of our platforms and languages ​​include features to handle time zones, but sometimes a better understanding is required to use these features properly. When it comes to cross-platform mobile development, such as offering .NET MAUI, it can be very difficult to provide a consistent experience.

So what does Sentinel have to do with time zones? Well, not much, but now that I'm a .NET MAUI developer, I thought it would be fun to contribute some open source stuff! For your enjoyment I have created a free oneMAUI time zone dialer control, which provides a consistent cross-platform user experience for selecting a time zone from a list. You can use it anywhere (and in any time zone)! Maybe you're building an event planning app? I bet you have to choose a time zone for your event.

For the record, the sample app included in the project also uses theSentinel .NET MAUI-SDK.If the sample app crashes on your device, I'll know automatically! Hopefully this means I'll be improving this control over time to make it even better.

In this blog post I will show you how I put together the MAUI time zone dialer controls. My goal is to teach you about time zones and hopefully give you some insight into writing custom UI controls for .NET MAUI.

What's so hard about time zones?

One of the biggest challenges with time zones isidentify them. Ask someone what their time zone is and you'll probably get several answers, such as "Central Time," "Central Standard Time," "Central Daylight Saving Time," or "Chicago Time." You may receive an abbreviation such as "CST", "CDT", or "CT". Sometimes you get a value like "UTC-6", "GMT-6", "UTC-06:00", "UTC-5", "GMT-5" or "UTC-05:00". All of these are used for the third official time zone of the United States (yes,thirdSome of these names are valid all the time, while others are only valid during certain times of the year. This is only one time zone on Earth, and it's insideEngels.Usually time zone names and abbreviations are localized. If you speak French, you're probably calling in the same time zone"Central Standard Time"and abbreviate it as "HNC".

Time zone abbreviations are also very confusing because the world is big and there are many countries that start with the same letter. Therefore, if you simply state a time zone as "CST", without any additional context, there is no way to know if it refers to "Central Standard Time", "Cuba Standard Time", or "China Standard Time".

To solve this problem in the calculations, we use the time zoneID card.in the past there were different sets of timezone identifiers, but they have mostly been merged and we use them nowIANA time zone databaseIn almost every programming language, platform and operating system. Even Microsoft Windows (which used to just use their own set of identifiers) has started using IANA so you can use them in .NET. The IANA time zone IDs for the above regions are "America/ChicagoIt is an exact string that can be used as an identifier on all platforms and is never translated.

This is where we get to the fun part. Do we really want to show our users the IANA time zone ID? What if they only know Japanese? How would English strings help them? While you may have seen some applications provide a list of these strings for the user to choose from, this is not the recommended approach. In fact, the recommendation of the IANA time zone administrators is that you shouldNeeshown to the user. Instead, the string displayed to the user must come from another source, such asUnicode Common Locale data repository(CLDR).

So let's create a time zone selector that will be displayedUnicodestring, each supported by the corresponding IANA time zone ID. We also provide each with a location and current UTC offset to help users make their choice. We want it to be a scrollable list like this:

Note that this is a very rough first try - I have lots of ideas to make it better over time!

Create a .NET MAUI control project

I assume you already have a development environment set up to use MAUI. If not, check MicrosoftStart itContinue with the previous document.

The first step in our journey is to create a new .NET project. Since this is a reusable component, I will create a MAUI class library. I also want to sample a MAUI app and test project and link them together.

mkdir MauiTimeZonePickercd MauiTimeZonePicker dotnet néo mauilib -n MauiTimeZonePicker -o srcdotnet néo maui -n MauiTimeZonePickerSampleApp -o sampledotnet néo xunit -n MauiTimeZonePicker voeg testreftT toe.

Note that you may want to delete the sln file created in the examples folder and create a new file in the root folder.

Now I can fire up VS Code and start editing. You can also use Visual Studio, VS for Mac, or JetBrains Rider, but you'll need the latest sample version of each tool to use MAUI. For this blog post, I'll stick with the command line and VS Code.

Create controls and their elements

We're going to create a new control, but we don't want to start from scratch. Instead, we start with a layout so we can add other elements to it. There are manylay-out typeusable. To match our design, we will useverticale stapellay-out, it just puts each element on top of each other.

Namespaces Maui time zone selector;People class time zone selector : verticale stapellay-out{}

Next, we'll add some content to the layout. FirstInscriptionbefore the title, after theLimitationfor the box below. Within the boundaries we place oneview collectioncontrol, which will do most of the heavy lifting of displaying the list of time zones.

use Microsoft.Maui.control.form;Namespaces Maui time zone selector;People class time zone selector : verticale stapellay-out{ People time zone selector() { add content(); } private vacuum add content() { Add to(jong Inscription {text= "Select time zone...",lettertypegrootte= 14 }); Add to(jong Limitation {blow shape= jong rectangle(),stuffing= 2,contents= Download the collection view() }); } private view collection Download the collection view() { it wasdisplay= jong view collection { // Itembron = ALLES, //project template = ALL,Maximum required height= 200,fashion selection=fashion selection.single}; ((LinearItemsLayout)display.layout of the project).distance from objects= 10; YIELDdisplay; }}

One important "pitfall" to point out: if you're using a boundary checker, make sure you set up the StrokeShape. Otherwise, you will not only have the border, but also the internal contentinvisibleWhen viewed on iOS and macCatalyst. This may be a bug in MAUI, but it's easy to find.

Next we want to create an element template for our control and give it some elements to render! You can see the full template I'm using in the source code repositoryhere.

Retrieve time zone resource information

Creating the controls seems simple enough so far - but where does the data come from? We can try to usetime zone informationobject, but we'll find that it doesn't necessarily have all the local strings we need. As mentioned earlier, we expect most of our data to come from the CLDR project on Unicode. Well, it turns out that this data is already available on all the platforms we use - mostly through platform-specific Unicode appsICLibraries (international components of Unicode), distributed by the operating system.

Because .NET MAUI has great call supportplatformspecifieke code, let's use it.

• On Android we have accessICU application from Android.Android exposes Java classes, while .NET uses MAUI C# inAndroid.IcuNamespaces.

• In iOS and macCatalyst, we have access to Apple Foundation classes that have behind-the-scenes access to IANA and ICU data, includingNS time zone,NSlocale, InNSDateFormatter.These are also available through C# inbaseNamespaces.

• In Windows, we have accessICUs supported by WindowsVia C api only. However, we can still access it through our .NET MAUI codep/bel.These can get a little complicated, butICU4C API referenceCome to handy. Note that we can only call the C API - not C++.

If you want to delve into this, check out theTime zone resource providerView the lessonsource code repositoryIt is important to note that there are many different implementations of the same method for specific platforms. Thank you Maui!

Once we have the data, we can create methods to access it and call those methods from our control. The details don't really matter here, it's enough to show the end resultelement broncollection overview of . i designed mineTime zone resource providergive listtime zone sourceobjects, each of which has different information needed to represent and use a particular time zone.

response event

we are not enoughprojectionA list from which we also need to allow the user to select an item. After making that choice, we may need to take action. Most of these are achieved through our useview collectioncontrol, but we need to expose it to the user. I also expose the collection view itself so we can set other properties if needed.

People view collectionview collection{ I get; }People time zone source;selected item=>view collection.selected itemif time zone source;People Event event handler<SelectedItemChangedEventArgs>;The selected item has been changed;People class SelectedItemChangedEventArgs : event parameters{ People SelectedItemChangedEventArgs(time zone source;previous choice, time zone source;current selection) {previous choice=previous choice;current selection=current selection; } People time zone source;previous choice{ I get; } People time zone source;current selection{ I get; }}

We can outsource collection viewingsthe selection has been changedWhen we create control, our own events.

display.the selection has been changed+= (_,parameter) =>{ it wasprevious choice=parameter.previous choice.priority or default() if time zone source; it wascurrent selection=parameter.current selection.priority or default() if time zone source; it wasevent parameters= jong SelectedItemChangedEventArgs(previous choice,current selection);The selected item has been changed;.TRANSPORT(It,event parameters);};

Now users will have an intense typing experiencethe selection has been changedevents andselected itemproperty in our TimeZonePicker.

Use our controls in your app

Now that we've created our control, we can use it in our application. Well - you've probably gotten to this point before, because it's hard to get there without trying to check it out a few times along the way. Anyway, here's how you add it:

In your application, refer to the class library project that contains the custom control and support code. we have usedadd point netcommand before, but you can also add project references via Visual Studio or edit the csproj file directly to addprojectrapportInscription.

<Work team> <projectrapport Involving="..\src\MauiTimeZonePicker.csproj" />Work team>

Your end users dopackage reportlabel instead. For example, if you want to test my current app:

<Work team> <package report Involving="mjp.MauiTimeZonePicker" Version="0.1.0 preview" />Work team>

Now add a package reference toMaui sentinel.wait, kidding! You don't have to use guards if you don't want to. But it's easy if you do the following:

<package report Involving="Maui sentinel" Version="3.19.0-preview.2" />

Finally add. Let's add the controls to your app! Assuming you're in XAML, you'll need to enter a namespace and give it an alias.

xmlns:mjp="clr-namespace:MauiTimeZonePicker;assembly=MauiTimeZonePicker"

You can then add the control anywhere in your application. I also named and leveraged the event we created.

<mjp:time zone selector X:Name="time zone selector" The selected item has been changed="the time zone has been changed" />

Sure, you might want your app to do a lot of other things, but when it comes to using controls, it's pretty straightforward.

Yes, it works

This is what the final sample app looks like on my Android emulator.

check out other platformsScreenshot from the README repository.

test

It would be great if we could add some unit tests to this project. Unfortunately, most of the code that actually needs to be tested is platform specific. To verify this, unit tests must be performed on the device. Currently this is a challenge for MAUI developers.

We have that too at SentrySentry.Maui same problem, so we started working on it. We also recently learned that there is oneXunit.Runners.MauiThe project is under development. Hopefully we can join forces and find a solution that everyone can use (including the time zone selector)!

final thoughts

.NET MAUI is beautiful. I absolutely love using it. Xamarin laid the groundwork and still provides much of the basic foundation of how MAUI works, but MAUI is simpler. I especially like that it uses the same modern .NET toolchain that I use today when I write everything else.

I will keep repeating this MAUI time zone selection project. Who knows, someone might find it useful and it will become super popular. comeJoin me on GitHubIf you want to join. I like to give feedback and input. I'm glad to have custom controls to play with and would love to work on this with you.

don't forget to tryAll guards for .NETNeeds for bug tracking and performance monitoring. Our .NET MAUI SDK is brand new, but we have many other satisfied .NET customers using our product.

If you liked this article, feel free to contact me on Twitter:@mattjohnsonpint.Thank you!