MediaCenterEnvironment.Dialog Method

  • Article

Displays a Windows Media Center-style dialog box.

Overload List

public DialogResult Dialog(string, string, DialogButtons, int, bool)
public DialogResult Dialog(string, string, IEnumerable, int, bool, string, DialogClosedCallback)
public DialogResult Dialog(string, string, IEnumerable, int, bool, string)

The MediaCenterEnvironment.Dialog method displays a modal or modeless Windows Media Center-style dialog box. The dialog box has a caption, body text, buttons, and a timeout duration.

Syntax

public DialogResult Dialog(
   string text,
   string caption,
   DialogButtons buttons,
   int timeout,
   bool isModal
);

Parameters

text

System.String.  The text for the body of the dialog box.

caption

System.String.  The text for the caption.

buttons

DialogButtons.  The types of buttons to add to the dialog box.

To specify multiple buttons on a dialog box, add the numbers for the individual buttons. The complete list is in the following table. Descriptions show resulting buttons in the left-to-right order, as they will appear in the dialog box.

Value Description
1 OK
2 Cancel
3 OK, Cancel
4 Yes
5 OK, Yes
6 Yes, Cancel
7 OK, Cancel, Yes
8 No
9 OK, No
10 No, Cancel
11 OK, No, Cancel
12 Yes, No
13 OK, Yes, No
14 Yes, No, Cancel
15 OK, Yes, No, Cancel

Although you can specify any combination, it is best to avoid the following combinations because they may be unclear to the user:

  • OK, Yes
  • OK, Cancel, Yes
  • No, Cancel
  • OK, Yes, No
  • OK, Yes, No, Cancel
  • Yes
  • No

timeout

System.Int32.  The time-out duration, in seconds, for the dialog box, at the end of which the dialog box will automatically close. A value of -1 or 0 for a modal dialog box indicates an infinite time-out duration. For modeless dialog boxes, Windows Media Center does not allow infinite time-out. Modeless dialog boxes have a time-out duration range between 5-120 seconds.

isModal

System.Boolean.  Indicates whether the dialog box is modal (true) or modeless (false). A modal dialog box must be closed by the user or time out before you can continue working with the rest of the application. A modeless dialog box lets you change focus away from it without having to close the dialog box.

This overloaded version of the Dialog method can create a modeless dialog box to present information to the user, but it does not return a value to indicate what button was selected to close the dialog box.

To ensure that a dialog box is displayed, an on-demand application should use a modal dialog box. Note that when an on-demand application creates a modal dialog box, Windows Media Center stops executing until the user dismisses the dialog box.

Return Value

DialogResult. A member of the DialogResult enumeration that indicates how the dialog box was dismissed.

Remarks

These dialog boxes are specially designed to integrate with the Windows Media Center user experience; they should be used instead of standard Windows dialog boxes.

You can specify Unicode characters using \uNNNN notation, where NNNN indicates the Unicode character.

Modeless dialog boxes do not return a value indicating what button is selected to close the dialog box. If your application needs to get information from the user (Yes, No, OK, or Cancel), you should set the isModal parameter to true to make your dialog box modal. Or, use the overload of Dialog that takes a DialogClosedCallback delegate.

MediaCenterEnvironment.Dialog Method

Shows a Windows Media Center-style dialog box that can contain custom buttons and images, and can pass a result code to an application-defined event handler.

Syntax

public DialogResult Dialog(
   string text,
   string caption,
   IEnumerable buttons,
   int timeout,
   bool isModal,
   string imagePath
   DialogClosedCallback callback,
);

Parameters

text

System.String.  The text for the body of the dialog box.

caption

System.String.  The text for the caption.

buttons

System.Collections.IEnumerable. A collection of strings and integers that defines the buttons to include in the dialog box. For each string in the collection, the method adds a custom button that contains the string. For each number, the method creates a standard button. The standard buttons have the following values:

Value Description
1 OK button
2 Cancel button
4 Yes button
8 No button

timeout

System.Int32.  The time-out duration, in seconds, for the dialog box, at the end of which the dialog box will automatically close. A value of -1 or 0 for a modal dialog box indicates an infinite time-out duration. For modeless dialog boxes, Windows Media Center does not allow infinite time-out. Modeless dialog boxes have a time-out duration range between 5-120 seconds.

isModal

System.Boolean.  Indicates whether the dialog box is modal (true) or modeless (false). A modal dialog box must be closed by the user or time out before you can continue working with the rest of the application. A modeless dialog box lets you change focus away from it without having to close the dialog box.

To ensure that a dialog box is displayed, an on-demand application should use a modal dialog box. Note that when an on-demand application creates a modal dialog box, Windows Media Center stops executing until the user dismisses the dialog box.

imagePath

System.String.  The path to the image to display in the dialog box. The resx:// protocol is supported when specifying a path to a managed assembly.

callback

Microsoft.MediaCenter.DialogClosedCallback.  For modeless dialog boxes, this parameter specifies the DialogClosedCallback delegate that Windows Media Center invokes when the dialog box is dismissed. Windows Media Center passes a value to the delegate that indicates how the dialog box was dismissed. For modal dialog boxes, use the return value to determine how the dialog box was dismissed.

Return Value

DialogResult. A member of the DialogResult enumeration that indicates how the dialog box was dismissed. For a modal dialog box, the return value is one of the values listed in the description of the onClose parameter. For a modeless dialog box, the return value is always DialogResult.Active, indicating that the dialog box is active. Regardless of the dialog box type, if no valid buttons are specified, the dialog box does not appear and an exception is thrown.

Remarks

These dialog boxes are specially designed to integrate with the Windows Media Center user experience; they should be used instead of standard Windows dialog boxes.

You can specify Unicode characters using \uNNNN notation, where NNNN indicates the Unicode character.

If an on-demand application uses this method to display a modal dialog box, Windows Media Center ignores the onClose parameter. This is because the application would need to block execution while waiting for the result to be passed to its DialogClosedCallback delegate. However, the application cannot block its execution without also blocking the execution of Windows Media Center, meaning that the result would never reach the delegate.

Requirements

Reference: Microsoft.MediaCenter

Namespace: Microsoft.MediaCenter

Assembly: Microsoft.MediaCenter.dll

Platform: Windows Vista Ultimate, Windows Vista Home Premium, and later

See Also

MediaCenterEnvironment.Dialog Method

Shows a Windows Media Center-style dialog box that can contain custom buttons and images, and can pass a result code to an application-defined event handler.

Syntax

public DialogResult Dialog(
   string text,
   string caption,
   IEnumerable buttons,
   int timeout,
   bool isModal,
   string imagePath
);

Parameters

text

System.String.  The text for the body of the dialog box.

caption

System.String.  The text for the caption.

buttons

System.Collections.IEnumerable. A collection of strings and integers that defines the buttons to include in the dialog box. For each string in the collection, the method adds a custom button that contains the string. For each number, the method creates a standard button. The standard buttons have the following values:

Value Description
1 OK button
2 Cancel button
4 Yes button
8 No button

timeout

System.Int32.  The time-out duration, in seconds, for the dialog box, at the end of which the dialog box will automatically close. A value of -1 or 0 for a modal dialog box indicates an infinite time-out duration. For modeless dialog boxes, Windows Media Center does not allow infinite time-out. Modeless dialog boxes have a time-out duration range between 5-120 seconds.

isModal

System.Boolean.  Indicates whether the dialog box is modal (true) or modeless (false). A modal dialog box must be closed by the user or time out before you can continue working with the rest of the application. A modeless dialog box lets you change focus away from it without having to close the dialog box.

To ensure that a dialog box is displayed, an on-demand application should use a modal dialog box. Note that when an on-demand application creates a modal dialog box, Windows Media Center stops executing until the user dismisses the dialog box.

imagePath

System.String.  The path to the image to display in the dialog box. The resx:// protocol is supported when specifying a path to a managed assembly.

Return Value

DialogResult. A member of the DialogResult enumeration that indicates how the dialog box was dismissed. For a modal dialog box, the return value is one of the values listed in the description of the onClose parameter. For a modeless dialog box, the return value is always DialogResult.Active, indicating that the dialog box is active. Regardless of the dialog box type, if no valid buttons are specified, the dialog box does not appear and an exception is thrown.

Remarks

These dialog boxes are specially designed to integrate with the Windows Media Center user experience; they should be used instead of standard Windows dialog boxes.

You can specify Unicode characters using \uNNNN notation, where NNNN indicates the Unicode character.

If an on-demand application uses this method to display a modal dialog box, Windows Media Center ignores the onClose parameter. This is because the application would need to block execution while waiting for the result to be passed to its DialogClosedCallback delegate. However, the application cannot block its execution without also blocking the execution of Windows Media Center, meaning that the result would never reach the delegate.

Requirements

Reference: Microsoft.MediaCenter

Namespace: Microsoft.MediaCenter

Assembly: Microsoft.MediaCenter.dll

Platform: Windows Vista Ultimate, Windows Vista Home Premium, and later

See Also