Coding4Fun WP7 Message Prompt in depth

by WindowsPhoneGeek

In this article I am going to talk about the MessagePrompt control from the Coding4fun Toolkit in details. I will explain everything about the main features, available public API, and will  give lots of examples in different scenarios.

Basically MessagePrompt is an UI component that derives from the toolkit`s UserPrompt class . As its name says it is a kind of extended popup  that displays a message. MessagePrompt can display different  content like Title, composite Body content, custom buttons, etc .

NOTE: In this article I will use the latest version 1.3.2 of the toolkit assemblies(the dll is attached to the sample project at the end of the article).

Getting Started

To begin using MessagePrompt first  add a reference to  the Coding4Fun.Phone.Controls.dll assembly.

NOTE: You can download this assembly from here: Coding4Fun Toolkit .

NOTE: You will also have to add a reference to Microsoft.Phone.Controls.Toolkit from the Silverlight Toolkit because of some dependencies. (This assembly is included in the download package of the Coding4Fun Toolkit. It is also attached to the sample project at the end of the article).

Generally the MessagePrompt is designed to be used in code. The sample code should looks like:

private void btnSimpleMessage_Click(object sender, RoutedEventArgs e)
{
    var messagePrompt = new MessagePrompt
    {
        Title = "Simple Message",
        Message = "This is a demo of the Coding4Fun MessagePrompt.",
    };

    messagePrompt.Show();
}

Here is how a basic structure of a MessagePrompt looks like:

Key Properties

• ActionPopUpButtons

       This is a dependency property of type List<Button>. It represents a list of action buttons. You can add whatever button you prefer here and as a result it will appear immediately next to the default OK button. (see Example 4 below!)

• Body

      This is a dependency property of type object. It gets or sets the Body of the MessagePrompt control.

• IsAppBarVisible

       This is a dependency property of type bool. It determine whether the app bar is visible or not.

• IsCancelVisible

       This is a dependency property of type bool. It determine whether the cancel button is visible or not.

• IsOpen

       This is a read only dependency property of type bool. Determine whether the popup is opened or not.

• HasGesturesDisabled

       This is a dependency property of type bool. It determines whether Gestures are disabled or not disabled.The default value is true.

NOTE: With the current Gesture Service in the Silverlight Toolkit (Feb 2011 release), if two controls are overlapped and the bottom control has a listener attached, events will still bubble through with no way to cancel it without putting on a listener.  In a control that is called PopUp, it is self defeating to have this bubble through effect happening.  If the SL toolkit corrects the behavior then the Coding4fun team will remove this as it would no longer be needed.  This would also remove the dependency on the Silverlight Toolkit.

• Message

       This is a dependency property of type string. It gets or sets the Message of the MessagePrompt control.

• Overlay

       This is a dependency property of type Brush. It gets or sets the overlay of the MessagePrompt control.

• Title

       This is a dependency property of type string. It gets or sets the Title of the MessagePrompt control.

Key Methods and Events

• Show()

       This method shows the MessagePrompt control.

• Completed event

       This event Occurs when the popup is closed.

Examples

1. Sample Usage:

Here is an example shows how to use this control. You can use IsCancelVisible  property to Show/Hide the MessagePrompt `s  cancel button. As to the IsAppBarVisible property of MessagePrompt:  if you set this property to True as a result the Application Bar will be visible when the popup is opened, otherwise if you set it to False the App Bar will not be visible.

private void bntAdvancedMessage_Click(object sender, RoutedEventArgs e)
{
    var messagePrompt = new MessagePrompt
    {
        Title = "Advanced Message",
        Body = new TextBlock { Text = "Bory of the Coding4Fun MessagePrompt.", Foreground = new SolidColorBrush(Colors.Green),FontSize = 30.0, TextWrapping=TextWrapping.Wrap},
        IsAppBarVisible = true,
        IsCancelVisible = true
    };

    messagePrompt.Show();
}

2.Advanced Body in XAML using UserControl

Generally the MessagePrompt is designed to be used in code but sometimes users want to put some composite elements into the popup body so in this case it is easy to define these element is XAML. Here is one possible solution with UserControl. Just create a new UserControl named BodyUserControl.xaml and add the following code into it:

<Border BorderBrush="YellowGreen" BorderThickness="2">
    <StackPanel x:Name="LayoutRoot" Background="{StaticResource PhoneChromeBrush}"  Margin="0,0,0,10">
        <TextBlock Text="Body declared in UserControl XAML" HorizontalAlignment="Center"/>
        <Image Source="AppIcon.png" Height="80" Width="80" HorizontalAlignment="Center"/>
        
        <Border Background="YellowGreen" Height="100" Width="400">
            <TextBlock Text="This is the first text in the Body section. Another Body content here" TextWrapping="Wrap" VerticalAlignment="Center"/>
        </Border>
    </StackPanel>
</Border>

After that go back to MainPage.xaml.cs and add the following code:

private void btnAdvancedMessageXAML_Click(object sender, RoutedEventArgs e)
{
    MessagePrompt messagePrompt = new MessagePrompt();
    messagePrompt.Title = "UserControl test";
    messagePrompt.Body = new BodyUserControl();
    messagePrompt.Show();
}

3. Adding Custom Buttons and colors

This example demonstrates how to add a sample Custom Button to the ActionPopUpButtons  collection of the MessagePrompt . When the button is pressed the background of the MessagePrompt will be changed:

MessagePrompt messagePrompt;
private void btncustomizedMessage_Click(object sender, RoutedEventArgs e)
{
    messagePrompt = new MessagePrompt();
    messagePrompt.Message = "Some Message.";
    Button customButton = new Button() { Content = "Custom Button" };
    customButton.Click += new RoutedEventHandler(customButton_Click);
    messagePrompt.ActionPopUpButtons.Add(customButton);
    messagePrompt.Show();
}

void customButton_Click(object sender, RoutedEventArgs e)
{
    messagePrompt.Background = new SolidColorBrush(Colors.Gray);
}

That was all about the MessagePrompt control from the Coding4fun Toolkit in depth.  You can find the full source code here:

I hope that the article was helpful.

You can also follow us on Twitter @winphonegeek

Comments

        MessagePrompt messagePrompt;
        private void btncustomizedMessage_Click(object sender, RoutedEventArgs e)
        {
            messagePrompt = new MessagePrompt();
            messagePrompt.Message = "Some Message.";
            messagePrompt.ActionPopUpButtons.Clear();
            Button customButton = new Button() { Content = "Custom Button" };
            customButton.Click += new RoutedEventHandler(customButton_Click);
            messagePrompt.ActionPopUpButtons.Add(customButton);
            messagePrompt.Show();


         }
        void customButton_Click(object sender, RoutedEventArgs e)
        {
         //do something
        }

cancelButton.Click += (sender, e) =>
{
    messagePrompt.Hide();
};

public static void Show(string message, params MessageBoxExCommand[] commands)
    {
        MessagePrompt prompt = new MessagePrompt();
        prompt.Body = new MessageBoxExControl
        {
            Message = message
        };
        prompt.Title = new AppInfo().Title;
        prompt.IsCancelVisible = false;
        prompt.IsAppBarVisible = false;
        prompt.ActionPopUpButtons = new System.Collections.Generic.List<Button>();

        for (int i = 0; i < commands.Length; i++)
        {
            Button button = new Button();
            button.Margin = new Thickness(0, -10, 0, 0);
            button.Content = commands[i].Content;
            button.Tag = commands[i];
            button.Click += new RoutedEventHandler(delegate(object sender, RoutedEventArgs args)
                {
                    MessageBoxExCommand currentCommand = (MessageBoxExCommand)((Button)sender).Tag;

                    if (currentCommand.OnClick != null)
                        currentCommand.OnClick();

                    prompt.OnCompleted(new PopUpEventArgs<string, PopUpResult>
                    {
                        Result = prompt.Value,
                        PopUpResult = PopUpResult.Ok
                    });
                });

            prompt.ActionPopUpButtons.Add(button);
        }
        prompt.Show();
    }