DXPopup Class
A popup view that you can attach to any view on the screen or show as a separate dialog.
Namespace: DevExpress.XamarinForms.Popup
Assembly: DevExpress.XamarinForms.Editors.dll
NuGet Package: DevExpress.XamarinForms.Editors
Declaration
public class DXPopup :
ViewRemarks
The DevExpress Popup for Xamarin.Forms allows you to show a popup view that overlays the rest of the application content. For example, you can use it to display important information to a user or to ask the user to make a decision.
How to: Add DevExpress Popup to your Xamarin.Forms solution
You can configure a Popup as follows:
- Attach the Popup to a view (UI element) on the screen and position it relative to this view.
- Display the Popup as a dialog and position it relative to the screen.
Define Popup Content and Appearance
You can specify any complex view or layout to display it within a Popup. To do this, assign a View class descendant to the DXPopup.Content property.
This example shows how to specify a Popup that displays detailed information on a customer that a user selects in a DataGridView bound to a collection of CompanyCustomer objects.
Set the DXPopup.Content property to a StackLayout with a Grid that contains images and labels, and a Button that closes the Popup. Bind customer-related elements to a CompanyCustomer object’s properties (Photo, Name, CompanyName, Position, Phone, and Address).
Note
You can skip the Content property tags in the XAML markup as this property has a ContentProperty attribute.
<ContentPage.Resources>
<Style TargetType="Label">
<Setter Property="TextColor"
Value="#54565a" />
</Style>
</ContentPage.Resources>
<ContentPage.Content>
<StackLayout>
<dxg:DataGridView>
<!--Specify the DevExpress DataGrid
bound to the collection of CompanyCustomer objects here. -->
</dxg:DataGridView>
<dxp:DXPopup x:Name="popup" AllowScrim="True">
<!--Specify the popup content.
Bind its customer-related elements to properties of a CompanyCustomer object. -->
<StackLayout>
<Grid RowSpacing="15" ColumnSpacing="13"
HeightRequest="220" WidthRequest="320"
Margin="10, 10">
<Grid.RowDefinitions>
<RowDefinition Height="Auto" />
<RowDefinition Height="Auto" />
<RowDefinition Height="Auto" />
<RowDefinition Height="Auto" />
<RowDefinition Height="Auto" />
</Grid.RowDefinitions>
<Grid.ColumnDefinitions>
<ColumnDefinition Width="Auto" />
<ColumnDefinition Width="Auto" />
<ColumnDefinition Width="*" />
</Grid.ColumnDefinitions>
<ContentView Grid.Row="0" Grid.Column="0" Grid.RowSpan="5">
<ContentView VerticalOptions="Start"
HeightRequest="122"
WidthRequest="102"
BackgroundColor="{DynamicResource GridCellBorderColor}">
<Image Margin="1"
VerticalOptions="CenterAndExpand"
Aspect="AspectFill"
HeightRequest="120"
WidthRequest="100"
Source="{Binding Photo}"/>
</ContentView>
</ContentView>
<Image Grid.Row="0" Grid.Column="1" Source="person_icon.png"/>
<Label Grid.Row="0" Grid.Column="2" Text="{Binding Name}"/>
<Image Grid.Row="1" Grid.Column="1" Source="card_icon.png"/>
<Label Grid.Row="1" Grid.Column="2" Text="{Binding CompanyName}"/>
<Image Grid.Row="2" Grid.Column="1" Source="portfolio_icon.png"/>
<Label Grid.Row="2" Grid.Column="2" Text="{Binding Position}"/>
<Image Grid.Row="3" Grid.Column="1" Source="phone_icon.png"/>
<Label Grid.Row="3" Grid.Column="2" Text="{Binding Phone}"/>
<Image Grid.Column="1" Grid.Row="4" Source="location_icon.png"/>
<Label Grid.Row="4" Grid.Column="2" Text="{Binding Address}"/>
</Grid>
<Button Text="Close" Clicked="ClosePopup_Clicked"/>
</StackLayout>
</dxp:DXPopup>
</StackLayout>
</ContentPage.Content>
Specify a binding context for the Popup’s content and open the Popup in the DataGridView.Tap event handler.
CompanyCustomer customer;
// ...
void OnTap(object sender, DevExpress.XamarinForms.DataGrid.DataGridGestureEventArgs args) {
if (args.Item != null)
customer = (CompanyCustomer)args.Item;
popup.Content.BindingContext = customer;
popup.IsOpen = true;
}
void ClosePopup_Clicked(System.Object sender, System.EventArgs e) {
popup.IsOpen = false;
}
A view assigned to the Content property defines the size and appearance of the Popup. The CornerRadius property allows you to change the radius of popup corners. You can also customize the Popup’s shadow.
Open and Close a Popup
Use the IsOpen property to show or hide a Popup.
The following example opens a Popup when a user taps a button:
<Button Text="Tap to show a Popup view" Clicked="OpenPopup_Clicked" />
<dxp:DXPopup x:Name="popup">
<StackLayout WidthRequest="200">
<Label Text="This is the DevExpress Xamarin.Forms Popup component."
Margin="10, 10"/>
</StackLayout>
</dxp:DXPopup>
void OpenPopup_Clicked(System.Object sender, System.EventArgs e) {
popup.IsOpen = true;
}
A Popup raises the following events when a user opens and closes it:
Event | Description |
|---|---|
Occurs before the Popup appears and allows you to cancel this action. | |
Occurs after the Popup appears. | |
Occurs before the Popup closes and allows you to cancel this action. | |
Occurs after the Popup closes. |
Display a Popup Relative to a View
Set the PlacementTarget property to the view (a View class descendant) to which you want to attach a Popup and position the Popup relative to this view.
The following example positions a Popup relative to a button:
<Button x:Name="button" Text="Tap to show a Popup view"/>
<dxp:DXPopup PlacementTarget="{x:Reference button}">
<StackLayout WidthRequest="200">
<Label Text="This is the DevExpress Xamarin.Forms Popup component."
Margin="10, 10"/>
</StackLayout>
</dxp:DXPopup>
If you don’t specify the Popup placement explicitly, it is attached to the bottom edge of the target view and opens from top to bottom (as the example above shows). You can use the Placement property to specify the direction in which the Popup should open.
The HorizontalAlignment and VerticalAlignment properties specify how to align the Popup relative to the target view.
Vertical Alignment
Horizontal Alignment
If you set the HorizontalAlignment property to Stretch, a popup view’s width aligns with the width of the target view.
If a Popup Encounters the Screen Edge
In most cases, the Popup size is the same as the size of the view assigned to the Content property, and the Popup placement relative to the PlacementTarget view depends on the Placement property.
Example:
Popup Content: WidthRequest = 200
Popup Placement = Left
If there is not enough screen space for a Popup to be displayed according to its Placement property, you can use the PlacementHorizontalThreshold and PlacementVerticalThreshold properties to specify the Popup placement behavior.
If a Popup doesn’t fit in the screen, it can behave as follows:
- Available space > *Threshold
If the size (width or height) of available screen space is greater than a Popup’s PlacementHorizontalThreshold or PlacementVerticalThreshold property value (default is 200), the Popup size is reduced to the size of available space.
Example:
Popup Content: WidthRequest = 200
Popup Placement = Left
Available screen space: Width = 150
PlacementHorizontalThreshold = 100
The Popup width is reduced to 150.
- Available space <= *Threshold
If available screen space is less than a Popup’s PlacementHorizontalThreshold or PlacementVerticalThreshold property value, the Placement property value is changed to the opposite value so that the Popup is displayed on the other side of the target element.
Example:
Popup Content: WidthRequest = 200
Popup Placement = Left
Available screen space: Width = 150
PlacementHorizontalThreshold = 200 The Popup’s Placement is changed from Left to Right.
- *Threshold = 0
If a Popup encounters the screen edge and its PlacementHorizontalThreshold or PlacementVerticalThreshold property is set to 0, the Placement property value is changed to the opposite value. If neither side has enough space to fit the Popup, it is displayed on the side with more available space.
Example:
Popup Content: WidthRequest = 200
Popup Placement = Left
Available screen space on the left: Width = 150
Available screen space on the right: Width = 100
PlacementHorizontalThreshold = 0The Popup opens on the left of the PlacementTarget view and the Popup’s width is reduced to 150.
Display a Popup Relative to the Screen
If you do not specify the PlacementTarget property explicitly, the Popup view is displayed as a dialog. When a user taps outside the Popup’s boundaries, the Popup closes.
<dxp:DXPopup>
<StackLayout WidthRequest="200">
<Label Text="This is the DevExpress Xamarin.Forms Popup component displayed as a dialog.
Tap outside the popup to hide it."
Margin="10, 10"/>
</StackLayout>
</dxp:DXPopup>
Alignment
The HorizontalAlignment and VerticalAlignment properties allow you to horizontally and vertically align a Popup relative to screen edges.
Vertical Alignment
Horizontal Alignment
Scrim
Enable a scrim (AllowScrim) to use a Popup as a modal window (which disables the rest of the UI until the Popup is addressed). You can apply an overlay color (transparent, if required) outside the Popup to indicate that a user must interact with the dialog in order to return to the underlying UI. Use the ScrimColor property to customize the scrim color and transparency.
This example shows how to specify the scrim to block interaction with the rest of the UI until a user taps the button within the Popup to close it.
<dxp:DXPopup x:Name="popup"
AllowScrim="True"
ScrimColor="#b3adb9ce">
<StackLayout WidthRequest="200">
<Label Text="This is the DevExpress Xamarin.Forms Popup component used as a modal window."
Margin="10, 10"/>
<Button Text="Close the popup" Clicked="ClosePopup_Clicked"/>
</StackLayout>
</dxp:DXPopup>
void ClosePopup_Clicked(System.Object sender, System.EventArgs e) {
popup.IsOpen = false;
}
Animation
When a Popup opens or closes in the screen, it applies the fade-in or fade-out animation effect.
Use the AnimationDuration property to manage the animation duration.
<dxp:DXPopup AnimationDuration="0:0:2">
<StackLayout WidthRequest="150" BackgroundColor="AliceBlue">
<Label Text="DevExpress Popup for Xamarin.Forms"
FontSize="Small"
Margin="5, 5"/>
</StackLayout>
</dxp:DXPopup>
A DXPopup control raises the following events when it plays the fade animation to display or hide the popup view:
Event | Description |
|---|---|
Occurs before the Popup’s opening animation starts. | |
Occurs after the Popup’s opening animation completes. | |
Occurs before the Popup’s closing animation starts. | |
Occurs after the Popup’s closing animation completes. |
To disable the animation, set the AllowAnimation property to false.
Size
A Popup size is calculated according to size-related settings (WidthRequest, HeightRequest, MinimumWidthRequest, MinimumHeightRequest) of a view assigned to the Content property.
If a Popup is positioned relative to a specified view (PlacementTarget) and the DXPopup.HorizontalAlignment property is set to Stretch, the Popup width aligns with the width of the target view.
If a Popup positioned relative to a specified view doesn’t fit in the screen, you can adjust the Popup size so that it displays all content.
Shadow
A Popup is displayed with a shadow.
You can use the following properties to manage the shadow visibility and customize its appearance:
Property | Description |
|---|---|
Gets or sets whether the Popup’s shadow is visible. | |
Gets or sets the color of the Popup’s shadow. | |
Gets or sets the blur radius of the Popup’s shadow. | |
<dxp:DXPopup ShadowColor="SteelBlue"
ShadowRadius="5"
ShadowHorizontalOffset="5">
<StackLayout WidthRequest="150">
<Label Text="DevExpress Popup for Xamarin.Forms"
FontSize="Small"
Margin="5, 5"/>
</StackLayout>
</dxp:DXPopup>