Windows 8 comes with a somewhat extended Message box functionality – you can control the text on the message box and the content of the buttons.
However, for Flyouts and arbitrary content, there’s no easy mechanism to use. WinRT does, however, provide a Popup class that can be used to easily overlay information on your page.
This is where the PopupHelper library comes to the rescue. It can take any UserControl and turn it into a dialog-like element on your app complete with animation and other relevant UI changes. One place where dialogs and popups differ is with regard to how they treat the UI thread. Whereas in the “old-world”, a popup would be essentially a blocking call, in Windows 8, you can’t really block the UI thread. Instead, the classes use the new awaitable mechanisms in .NET 4.5 to make this a little easier to handle.
Show me how I use it!
So say you have a message box in which you want to show a link to the user – say an error message with “more information” type link on it.
When showing the message box, the library animates the UI to flip into view and the background to “dim” and the UI under it to unusable (since it’s covering it).
The code is fairly simple.
Step 1: Design your XAML
Create a UserControl and add to it the following XAML:
The important bits here are that HorizontalAlignment is stretch and VerticalAlignment is Center to get that “band” look of Windows 8.
Step 2: Implement an inner class that inherits from PopupHelper.
Now, for the code. First off, you define the class that will let you show the popup. Note that this is not mandatory – it’s here for convenience. You can always just call the vanilla (non-templated) PopupHelper class to create it:
This creates a PopupHelper class that knows how to show the SimplePopup UserControl (see below on how to call it)
Step 3: Implement the IPopupControl interface
The interface has just 3 methods:
- SetParent(): This will be called when the popup is just about to show and tells the control who the PopupHelper showing it is.
- Opened(): Called after the popup is done animating in.
- Closed(): Called after the popup is done doing the close animation.
Note that SetParent() is the only method implemented – it stores the popup as a member variable.
Finally – the button on the popup needs to close it. That’s done by calling into the PopupHelper derivative and calling CloseAsync() on it.
Step 4: Using the popup
In your code, when you want to raise the event, all you need to do is this:
var popup = new SimplePopup.Popup();
That’s about it! Note that I could have just easily written this code (and avoided the inner-class):
var popup = new PopupHelper(new SimplePopup());
It’s a matter of choice how you want to work it.
How about returning values from dialogs?
The infrastructure also supports dialog that return data. This can be easily done with what you’ve seen so far, but there are a few small things added to make it even easier.
In this case, we’ll use a different example that shows a more traditional popup right smack in the middle of the page:
When defining your Popup class as an inner class, use PopupHelperWithResult<>:
public class Popup :
In this case, the result returned is a NetworkCredential and the UserControl name is SimpleResultPopup.
Everything else about this is the same, except for what happens when a user taps one of the buttons (cancel or login):
As you can see, when cancelling, we simply set the .Result poperty to null, whereas when the user actually taps “Login”, we set it to a NetworCredential instance.
Using the popup is also fairly simple – you call into it, awaiting the result, and use it to do what’s needed:
How about flyouts?
You can use the same infrastructure described to create Windows 8 Flyouts that look great.
The only difference is in how you define your PopupHelper class and the XAML design:
This is a standard definition of an inherited UserControl. The interesting bits are in VerticalAlignment and HorizontalAlignment. The first is set to Stretch since the Flyout needs to take the entire available vertical screen size. The latter is set to Right so that it’s “docked” to the charms bar.
The code for defining the Flyout:
public class Flyout : PopupHelper<SimpleFlyout>
public override PopupSettings Settings
The Flyout class overrides the Settings property and returns settings that tell the Popup to behave like a flyout.
The result looks just like any Flyout:
Note that there’s another difference between how Flyouts and Popups handle themselves. Flyouts are dismissed by simply tapping anywhere on the screen real-estate that does not belong to the Flyout while Popups need to be explicitly dismissed.
Odds and ends
You can create your own Popup behaviors by creating your own PopupSettings instances.
These are the settings you can currently control:
- AnimationDuration : This is the oveall duration of the animation. Both for Flyouts and regular popups, it’s set to 350ms.
- OverlayToControlAnimationRatio: This is the difference between how long it takes the overlay to animate and how long it takes the popup to animate. In the case of a regular popup, this is 0.7 (the control starts animating in a delay of 30% of the total animation time). For Flyouts, this is 1 (since there’s no noticeable animation happening on the overaly)
- OverlayOpacity: This governs how opaque the overlay is. For Popups this is set at 0.5 and for Flyouts at 0.
- Animation: The type of animation to apply when showing and closing the popup (enum flags)
- OverlayDismissal: Whether clicking or tapping on the overlay will dismiss the dialog. True for Flyouts, false for regular popups.
The Soft Keyboard (SIP), when showing, will cause the popup to reposition itself on the page.
You can download full source code and a demo project here.