Información general sobre cuadros de diálogoDialog boxes overview

Las aplicaciones independientes tienen normalmente una ventana principal que muestra los datos principales en el que la aplicación funciona y expone la funcionalidad para procesar los datos a través de interfaz de usuario (UI)user interface (UI) mecanismos, como las barras de menús, barras de herramientas y barras de estado.Standalone applications typically have a main window that both displays the main data over which the application operates and exposes the functionality to process that data through interfaz de usuario (UI)user interface (UI) mechanisms like menu bars, tool bars, and status bars. Una aplicación no trivial también puede mostrar ventanas adicionales para realizar lo siguiente:A non-trivial application may also display additional windows to do the following:

  • Mostrar información específica a los usuarios.Display specific information to users.

  • Recopilar información de los usuarios.Gather information from users.

  • Mostrar y recopilar información.Both display and gather information.

Estos tipos de ventanas se conocen como cuadros de diálogo, y hay dos tipos: modales y no modales.These types of windows are known as dialog boxes, and there are two types: modal and modeless.

Un modal cuadro de diálogo se muestra una función cuando la función necesita datos adicionales de un usuario para continuar.A modal dialog box is displayed by a function when the function needs additional data from a user to continue. Como la función depende del cuadro de diálogo modal para recopilar datos, el cuadro de diálogo modal también impide que un usuario active otras ventanas de la aplicación mientras permanece abierto.Because the function depends on the modal dialog box to gather data, the modal dialog box also prevents a user from activating other windows in the application while it remains open. En la mayoría de los casos, un cuadro de diálogo modal permite que un usuario indique cuando ha terminado con el cuadro de diálogo modal presionando un Aceptar o cancelar botón.In most cases, a modal dialog box allows a user to signal when they have finished with the modal dialog box by pressing either an OK or Cancel button. Al presionar el Aceptar botón indica que el usuario ha especificado los datos y quiere que la función continúe procesando esos datos.Pressing the OK button indicates that a user has entered data and wants the function to continue processing with that data. Al presionar el cancelar botón indica que un usuario desea detener la ejecución de la función.Pressing the Cancel button indicates that a user wants to stop the function from executing altogether. Los ejemplos más comunes de cuadros de diálogo modales se muestran para abrir, guardar e imprimir datos.The most common examples of modal dialog boxes are shown to open, save, and print data.

Un no modal cuadro de diálogo, por otro lado, no impide que un usuario active otras ventanas mientras está abierto.A modeless dialog box, on the other hand, does not prevent a user from activating other windows while it is open. Por ejemplo, si un usuario quiere buscar las repeticiones de una palabra determinada en un documento, a menudo una ventana principal abrirá un cuadro de diálogo para solicitar al usuario la palabra que está buscando.For example, if a user wants to find occurrences of a particular word in a document, a main window will often open a dialog box to ask a user what word they are looking for. En cambio, como buscar una palabra no impide que un usuario edite el documento, el cuadro de diálogo no necesita ser modal.Since finding a word doesn't prevent a user from editing the document, however, the dialog box doesn't need to be modal. Un cuadro de diálogo no modal proporciona al menos un cerrar botón para cerrar el cuadro de diálogo y puede proporcionar botones adicionales para ejecutar funciones específicas, como un Buscar siguiente botón para buscar la siguiente palabra que coincide con los criterios de búsqueda de una búsqueda de palabras.A modeless dialog box at least provides a Close button to close the dialog box, and may provide additional buttons to execute specific functions, such as a Find Next button to find the next word that matches the find criteria of a word search.

Windows Presentation Foundation (WPF) le permite crear varios tipos de cuadros de diálogo, incluidos los cuadros de mensaje, cuadros de diálogo comunes y cuadros de diálogo personalizados.Windows Presentation Foundation (WPF) allows you to create several types of dialog boxes, including message boxes, common dialog boxes, and custom dialog boxes. Este tema describe cada uno y el ejemplo de cuadro de diálogo proporciona ejemplos relacionados.This topic discusses each, and the Dialog Box Sample provides matching examples.

Cuadros de mensajeMessage boxes

Un cuadro de mensaje es un cuadro de diálogo que puede usarse para mostrar información textual y permitir a los usuarios tomar decisiones con los botones.A message box is a dialog box that can be used to display textual information and to allow users to make decisions with buttons. En la siguiente figura se muestra un cuadro de mensaje que muestra información de texto, realiza una pregunta y proporciona tres botones al usuario para responderla.The following figure shows a message box that displays textual information, asks a question, and provides the user with three buttons to answer the question.

Cierra un cuadro de diálogo procesador de textos que le pregunta si desea guardar los cambios en el documento antes de que la aplicación.

Para crear un cuadro de mensaje, utilice el MessageBox clase.To create a message box, you use the MessageBox class. MessageBox le permite configurar el texto del cuadro de mensaje, título, icono y botones, mediante código similar al siguiente.MessageBox lets you configure the message box text, title, icon, and buttons, using code like the following.

// Configure the message box to be displayed
string messageBoxText = "Do you want to save changes?";
string caption = "Word Processor";
MessageBoxButton button = MessageBoxButton.YesNoCancel;
MessageBoxImage icon = MessageBoxImage.Warning;
' Configure the message box to be displayed
Dim messageBoxText As String = "Do you want to save changes?"
Dim caption As String = "Word Processor"
Dim button As MessageBoxButton = MessageBoxButton.YesNoCancel
Dim icon As MessageBoxImage = MessageBoxImage.Warning

Para mostrar un cuadro de mensaje, llame a la static Show método, como se muestra en el código siguiente.To show a message box, you call the staticShow method, as demonstrated in the following code.

// Display message box
MessageBox.Show(messageBoxText, caption, button, icon);
' Display message box
MessageBox.Show(messageBoxText, caption, button, icon)

Cuando el código que muestra un cuadro de mensaje necesita detectar y procesar la decisión del usuario (qué botón se ha presionado), el código puede inspeccionar el resultado del cuadro de mensaje, como se muestra en el código siguiente.When code that shows a message box needs to detect and process the user's decision (which button was pressed), the code can inspect the message box result, as shown in the following code.

// Display message box
MessageBoxResult result = MessageBox.Show(messageBoxText, caption, button, icon);

// Process message box results
switch (result)
{
    case MessageBoxResult.Yes:
        // User pressed Yes button
        // ...
        break;
    case MessageBoxResult.No:
        // User pressed No button
        // ...
        break;
    case MessageBoxResult.Cancel:
        // User pressed Cancel button
        // ...
        break;
}
' Display message box
Dim result As MessageBoxResult = MessageBox.Show(messageBoxText, caption, button, icon)

' Process message box results
Select Case result
    Case MessageBoxResult.Yes
        ' User pressed Yes button
        ' ...
    Case MessageBoxResult.No
        ' User pressed No button
        ' ...
    Case MessageBoxResult.Cancel
        ' User pressed Cancel button
        ' ...
End Select

Para obtener más información sobre el uso de los cuadros de mensaje, consulte MessageBox, MessageBox Sample, y ejemplo de cuadro de diálogo.For more information on using message boxes, see MessageBox, MessageBox Sample, and Dialog Box Sample.

Aunque MessageBox pueden ofrecer una experiencia de usuario del cuadro de diálogo sencillo, la ventaja de usar MessageBox es que es el único tipo de ventana que se puede mostrar las aplicaciones que se ejecutan en un recinto de seguridad de confianza parcial (vea seguridad), como Aplicaciones del explorador XAML (XBAPs)XAML browser applications (XBAPs).Although MessageBox may offer a simple dialog box user experience, the advantage of using MessageBox is that is the only type of window that can be shown by applications that run within a partial trust security sandbox (see Security), such as Aplicaciones del explorador XAML (XBAPs)XAML browser applications (XBAPs).

La mayoría de los cuadros de diálogo muestran y recopilan datos más complejos que el resultado de un cuadro de mensaje, incluidos texto, selección (casillas), selección mutuamente exclusiva (botón de selección) y selección de listas (cuadros de lista, cuadros combinados, cuadros de lista desplegable).Most dialog boxes display and gather more complex data than the result of a message box, including text, selection (check boxes), mutually exclusive selection (radio buttons), and list selection (list boxes, combo boxes, drop-down list boxes). En estos casos, Windows Presentation Foundation (WPF) proporciona varios cuadros de diálogo comunes y le permite crear sus propios cuadros de diálogo, aunque el uso de uno de ellos está limitado a aplicaciones que se ejecutan con plena confianza.For these, Windows Presentation Foundation (WPF) provides several common dialog boxes and allows you to create your own dialog boxes, although the use of either is limited to applications running with full trust.

Cuadros de diálogo comunesCommon dialog boxes

WindowsWindows implementa una variedad de cuadros de diálogo reutilizables que son comunes a todas las aplicaciones, incluidos los cuadros de diálogo para abrir y guardar archivos, e imprimir.implements a variety of reusable dialog boxes that are common to all applications, including dialog boxes for opening files, saving files, and printing. Como estos cuadros de diálogo se implementan mediante el sistema operativo, pueden compartirse entre todas las aplicaciones que se ejecutan en el sistema operativo, que ayuda a la coherencia de la experiencia de usuario; cuando los usuarios están familiarizados con el uso de un cuadro de diálogo proporcionado por el sistema operativo en una aplicación, no necesitan obtener información sobre cómo usar ese cuadro de diálogo en otras aplicaciones.Since these dialog boxes are implemented by the operating system, they can be shared among all the applications that run on the operating system, which helps user experience consistency; when users are familiar with the use of an operating system-provided dialog box in one application, they don't need to learn how to use that dialog box in other applications. Dado que estos cuadros de diálogo están disponibles para todas las aplicaciones y ya que ayudan a proporcionar una experiencia de usuario coherente, se conocen como cuadros de diálogo comunes.Because these dialog boxes are available to all applications and because they help provide a consistent user experience, they are known as common dialog boxes.

Windows Presentation Foundation (WPF) encapsula el archivo abierto, guardar archivo y cuadros de diálogo comunes de impresión y los expone como clases administradas para su uso en las aplicaciones independientes.Windows Presentation Foundation (WPF) encapsulates the open file, save file, and print common dialog boxes and exposes them as managed classes for you to use in standalone applications. En este tema se proporciona una breve introducción de cada uno.This topic provides a brief overview of each.

Abrir el cuadro de diálogo de archivoOpen File dialog

El cuadro de diálogo Abrir archivo, que se muestra en la siguiente figura, se usa por la función de apertura de archivos para recuperar el nombre de un archivo que se va a abrir.The open file dialog box, shown in the following figure, is used by file opening functionality to retrieve the name of a file to open.

Un cuadro de diálogo Abrir que muestra la ubicación para recuperar el archivo.

El cuadro de diálogo Abrir archivo común se implementa como la OpenFileDialog clase y se encuentra en la Microsoft.Win32 espacio de nombres.The common open file dialog box is implemented as the OpenFileDialog class and is located in the Microsoft.Win32 namespace. En el siguiente código se muestra cómo crear, configurar y mostrar uno, y cómo procesar el resultado.The following code shows how to create, configure, and show one, and how to process the result.

// Configure open file dialog box
Microsoft.Win32.OpenFileDialog dlg = new Microsoft.Win32.OpenFileDialog();
dlg.FileName = "Document"; // Default file name
dlg.DefaultExt = ".txt"; // Default file extension
dlg.Filter = "Text documents (.txt)|*.txt"; // Filter files by extension

// Show open file dialog box
Nullable<bool> result = dlg.ShowDialog();

// Process open file dialog box results
if (result == true)
{
    // Open document
    string filename = dlg.FileName;
}
' Configure open file dialog box
Dim dlg As New Microsoft.Win32.OpenFileDialog()
dlg.FileName = "Document" ' Default file name
dlg.DefaultExt = ".txt" ' Default file extension
dlg.Filter = "Text documents (.txt)|*.txt" ' Filter files by extension

' Show open file dialog box
Dim result? As Boolean = dlg.ShowDialog()

' Process open file dialog box results
If result = True Then
    ' Open document
    Dim filename As String = dlg.FileName
End If

Para obtener más información sobre el cuadro de diálogo Abrir archivo, consulte Microsoft.Win32.OpenFileDialog.For more information on the open file dialog box, see Microsoft.Win32.OpenFileDialog.

Nota

OpenFileDialog puede utilizarse para recuperar los nombres de archivo de manera segura por aplicaciones que se ejecutan con confianza parcial (vea seguridad).OpenFileDialog can be used to safely retrieve file names by applications running with partial trust (see Security).

Guardar archivo (cuadro de diálogo)Save File dialog box

El cuadro de diálogo Guardar archivo, que se muestra en la siguiente figura, se usa por la función de guardado de archivos para recuperar el nombre de un archivo que se va a guardar.The save file dialog box, shown in the following figure, is used by file saving functionality to retrieve the name of a file to save.

Guardar como cuadro de diálogo que muestra la ubicación para guardar el archivo.

Guardar el cuadro de diálogo de archivo común se implementa como la SaveFileDialog clase y se encuentra en la Microsoft.Win32 espacio de nombres.The common save file dialog box is implemented as the SaveFileDialog class, and is located in the Microsoft.Win32 namespace. En el siguiente código se muestra cómo crear, configurar y mostrar uno, y cómo procesar el resultado.The following code shows how to create, configure, and show one, and how to process the result.

// Configure save file dialog box
Microsoft.Win32.SaveFileDialog dlg = new Microsoft.Win32.SaveFileDialog();
dlg.FileName = "Document"; // Default file name
dlg.DefaultExt = ".txt"; // Default file extension
dlg.Filter = "Text documents (.txt)|*.txt"; // Filter files by extension

// Show save file dialog box
Nullable<bool> result = dlg.ShowDialog();

// Process save file dialog box results
if (result == true)
{
    // Save document
    string filename = dlg.FileName;
}
' Configure save file dialog box
Dim dlg As New Microsoft.Win32.SaveFileDialog()
dlg.FileName = "Document" ' Default file name
dlg.DefaultExt = ".txt" ' Default file extension
dlg.Filter = "Text documents (.txt)|*.txt" ' Filter files by extension

' Show save file dialog box
Dim result? As Boolean = dlg.ShowDialog()

' Process save file dialog box results
If result = True Then
    ' Save document
    Dim filename As String = dlg.FileName
End If

Para obtener más información sobre la operación de guardar archivo de cuadro de diálogo, consulte Microsoft.Win32.SaveFileDialog.For more information on the save file dialog box, see Microsoft.Win32.SaveFileDialog.

El cuadro de diálogo Imprimir, que se muestra en la siguiente figura, se usa por la función de impresión para elegir y configurar la impresora con la que el usuario quiere imprimir los datos.The print dialog box, shown in the following figure, is used by printing functionality to choose and configure the printer that a user would like to print data to.

Captura de pantalla que muestra un cuadro de diálogo Imprimir.

El cuadro de diálogo Imprimir común se implementa como la PrintDialog clase y se encuentra en la System.Windows.Controls espacio de nombres.The common print dialog box is implemented as the PrintDialog class, and is located in the System.Windows.Controls namespace. En el siguiente código se muestra cómo crear, configurar y mostrar uno.The following code shows how to create, configure, and show one.

// Configure printer dialog box
System.Windows.Controls.PrintDialog dlg = new System.Windows.Controls.PrintDialog();
dlg.PageRangeSelection = PageRangeSelection.AllPages;
dlg.UserPageRangeEnabled = true;

// Show save file dialog box
Nullable<bool> result = dlg.ShowDialog();

// Process save file dialog box results
if (result == true)
{
    // Print document
}
' Configure printer dialog box
Dim dlg As New PrintDialog()
dlg.PageRangeSelection = PageRangeSelection.AllPages
dlg.UserPageRangeEnabled = True

' Show save file dialog box
Dim result? As Boolean = dlg.ShowDialog()

' Process save file dialog box results
If result = True Then
    ' Print document
End If

Para obtener más información sobre el cuadro de diálogo de impresión, consulte System.Windows.Controls.PrintDialog.For more information on the print dialog box, see System.Windows.Controls.PrintDialog. Para obtener información detallada de la impresión en WPF, vea información general sobre impresión.For detailed discussion of printing in WPF, see Printing Overview.

Cuadros de diálogo personalizadosCustom dialog boxes

Aunque los cuadros de diálogo comunes son útiles, y deben usarse cuando sea posible, no admiten los requisitos de los cuadros de diálogo específicos de dominio.While common dialog boxes are useful, and should be used when possible, they do not support the requirements of domain-specific dialog boxes. En estos casos, necesita crear sus propios cuadros de diálogo.In these cases, you need to create your own dialog boxes. Como veremos, un cuadro de diálogo es una ventana con comportamientos especiales.As we'll see, a dialog box is a window with special behaviors. Window implementa esos comportamientos y, por lo tanto, utilice Window para crear cuadros de diálogo modales y no modales personalizados.Window implements those behaviors and, consequently, you use Window to create custom modal and modeless dialog boxes.

Crear un cuadro de diálogo modal personalizadoCreating a modal custom dialog box

En este tema se muestra cómo usar Window para crear una implementación de cuadro de diálogo modal típica, con el Margins cuadro de diálogo como ejemplo (consulte ejemplo de cuadro de diálogo).This topic shows how to use Window to create a typical modal dialog box implementation, using the Margins dialog box as an example (see Dialog Box Sample). El Margins cuadro de diálogo se muestra en la ilustración siguiente.The Margins dialog box is shown in the following figure.

Un cuadro de diálogo márgenes con campos para definir el margen izquierdo, el margen superior, el margen derecho y el margen inferior.

Configuración de un cuadro de diálogo modalConfiguring a modal dialog box

La interfaz de usuario de un cuadro de diálogo típico incluye lo siguiente:The user interface for a typical dialog box includes the following:

  • Los distintos controles que se necesitan para recopilar los datos deseados.The various controls that are required to gather the desired data.

  • Un Aceptar botón que los usuarios, haga clic en para cerrar el cuadro de diálogo, vuelva a la función y con el procesamiento.An OK button that users click to close the dialog box, return to the function, and continue processing.

  • Un cancelar botón que los usuarios hacen clic para cerrar el cuadro de diálogo y detener la función del procesamiento.A Cancel button that users click to close the dialog box and stop the function from further processing.

  • Un cerrar botón en la barra de título.A Close button in the title bar.

  • Un icono.An icon.

  • Minimizar, maximizar, y restaurar botones.Minimize, Maximize, and Restore buttons.

  • Un sistema menú para minimizar, maximizar, restaurar y cerrar el cuadro de diálogo.A System menu to minimize, maximize, restore, and close the dialog box.

  • Una posición anterior y en el centro de la ventana que abre el cuadro de diálogo.A position above and in the center of the window that opened the dialog box.

  • La capacidad para cambiar de tamaño que sea posible para evitar que el cuadro de diálogo es demasiado pequeño y para proporcionar al usuario con un tamaño predeterminado útil.The ability to be resized where possible to prevent the dialog box from being too small, and to provide the user with a useful default size. Esto requiere que establezca el valor predeterminado y un dimensiones mínimas.This requires that you set both the default and a minimum dimensions.

  • La tecla ESC como un método abreviado de teclado que provoca la cancelar botón presionar.The ESC key as a keyboard shortcut that causes the Cancel button to be pressed. Hacerlo estableciendo la IsCancel propiedad de la cancelar botón true.You do this by setting the IsCancel property of the Cancel button to true.

  • La tecla ENTRAR (o retorno) como un método abreviado de teclado que provoca la Aceptar botón presionar.The ENTER (or RETURN) key as a keyboard shortcut that causes the OK button to be pressed. Para ello, establezca el IsDefault propiedad de la Aceptar botón true.You do this by setting the IsDefault property of the OK button true.

El siguiente código muestra esta configuración.The following code demonstrates this configuration.

<Window 
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    x:Class="SDKSample.MarginsDialogBox"
    xmlns:local="clr-namespace:SDKSample"
    Title="Margins"
    Height="190"
    Width="300"
    MinHeight="10"
    MinWidth="300"
    ResizeMode="CanResizeWithGrip"
    ShowInTaskbar="False"
    WindowStartupLocation="CenterOwner" 
    FocusManager.FocusedElement="{Binding ElementName=leftMarginTextBox}">

  <Grid>
    <!-- Accept or Cancel -->
    <StackPanel Grid.Column="0" Grid.ColumnSpan="2" Grid.Row="4">
      <Button Name="okButton" Click="okButton_Click" IsDefault="True">OK</Button>
      <Button Name="cancelButton" IsCancel="True">Cancel</Button>
    </StackPanel>
  </Grid >
</Window>
using System.Windows;
using System.Windows.Controls;
using System.Windows.Input;

namespace SDKSample
{
    public partial class MarginsDialogBox : Window
    {
        public MarginsDialogBox()
        {
            InitializeComponent();
        }
    }
}
Imports System.Windows
Imports System.Windows.Controls
Imports System.Windows.Input

Namespace SDKSample
    Public Class MarginsDialogBox
        Inherits Window

        Public Sub New()
            Me.InitializeComponent()
        End Sub
    End Class
End Namespace

La experiencia de usuario de un cuadro de diálogo también se extiende a la barra de menús de la ventana que abre el cuadro de diálogo.The user experience for a dialog box also extends into the menu bar of the window that opens the dialog box. Cuando un elemento de menú ejecuta una función que requiere interacción del usuario mediante un cuadro de diálogo antes de que la función pueda continuar, el elemento de menú de la función tendrá puntos suspensivos en su encabezado, como se muestra aquí.When a menu item runs a function that requires user interaction through a dialog box before the function can continue, the menu item for the function will have an ellipsis in its header, as shown here.

<!--Main Window-->
<MenuItem Name="formatMarginsMenuItem" Header="_Margins..." Click="formatMarginsMenuItem_Click" />

Cuando un elemento de menú ejecuta una función que muestra un cuadro de diálogo que no necesita interacción del usuario, como un cuadro de diálogo Acerca de, no se necesitan los puntos suspensivos.When a menu item runs a function that displays a dialog box which does not require user interaction, such as an About dialog box, an ellipsis is not required.

Abrir un cuadro de diálogo modalOpening a modal dialog box

Un cuadro de diálogo se muestra normalmente como el resultado de un usuario que selecciona un elemento de menú para realizar una función específica de dominio, como establecer los márgenes de un documento en un procesador de textos.A dialog box is typically shown as a result of a user selecting a menu item to perform a domain-specific function, such as setting the margins of a document in a word processor. Mostrar una ventana como un cuadro de diálogo es similar a mostrar una ventana normal, aunque necesita una configuración específica de cuadro de diálogo adicional.Showing a window as a dialog box is similar to showing a normal window, although it requires additional dialog box-specific configuration. El proceso completo de crear instancias, configurar y abrir un cuadro de diálogo se muestra en el código siguiente.The entire process of instantiating, configuring, and opening a dialog box is shown in the following code.

using System;
using System.ComponentModel;
using System.Windows;
using System.Windows.Controls;
using Microsoft.Win32;

namespace SDKSample
{
    public partial class MainWindow : Window
    {
        bool needsToBeSaved;
        void formatMarginsMenuItem_Click(object sender, RoutedEventArgs e)
        {
            // Instantiate the dialog box
            MarginsDialogBox dlg = new MarginsDialogBox();

            // Configure the dialog box
            dlg.Owner = this;
            dlg.DocumentMargin = this.documentTextBox.Margin;

            // Open the dialog box modally 
            dlg.ShowDialog();
        }
    }
}
Imports System.ComponentModel
Imports System.Windows
Imports System.Windows.Controls
Imports Microsoft.Win32

Namespace SDKSample
    Public Class MainWindow
        Inherits Window
        
        Private Sub formatMarginsMenuItem_Click(ByVal sender As Object, ByVal e As RoutedEventArgs)
            ' Instantiate the dialog box
            Dim dlg As New MarginsDialogBox

            ' Configure the dialog box
            dlg.Owner = Me
            dlg.DocumentMargin = Me.documentTextBox.Margin

            ' Open the dialog box modally 
            dlg.ShowDialog()
        End Sub
    End Class
End Namespace

En este caso, el código pasa información predeterminada (los márgenes actuales) al cuadro de diálogo.Here, the code passes default information (the current margins) to the dialog box. También establece la Window.Owner propiedad con una referencia a la ventana que muestra el cuadro de diálogo.It also sets the Window.Owner property with a reference to the window that is showing the dialog box. En general, siempre se debe establecer el propietario de un cuadro de diálogo para proporcionar comportamientos relacionados con el estado de ventana que son comunes a todos los cuadros de diálogo (vea WPF Windows Overview para obtener más información).In general, you should always set the owner for a dialog box to provide window state-related behaviors that are common to all dialog boxes (see WPF Windows Overview for more information).

Nota

Debe proporcionar un propietario para admitir la automatización de interfaz de usuario para los cuadros de diálogo (vea UI Automation Overview).You must provide an owner to support user interface (UI) automation for dialog boxes (see UI Automation Overview).

Después de configura el cuadro de diálogo, se muestra modalmente llamando el ShowDialog método.After the dialog box is configured, it is shown modally by calling the ShowDialog method.

Validar los datos proporcionados por el usuarioValidating user-provided data

Cuando un cuadro de diálogo se abre y el usuario proporciona los datos necesarios, un cuadro de diálogo es responsable de garantizar que los datos proporcionados sean válidos por los motivos siguientes:When a dialog box is opened and the user provides the required data, a dialog box is responsible for ensuring that the provided data is valid for the following reasons:

  • Desde una perspectiva de seguridad, se deben validar todas las entradas.From a security perspective, all input should be validated.

  • Desde una perspectiva específica de dominio, la validación de datos impide que los datos incorrectos se procesen por el código, que puede provocar excepciones potencialmente.From a domain-specific perspective, data validation prevents erroneous data from being processed by the code, which could potentially throw exceptions.

  • Desde una perspectiva de experiencia de usuario, un cuadro de diálogo puede ayudar a los usuarios a mostrarles qué datos de los que han especificado no son válidos.From a user-experience perspective, a dialog box can help users by showing them which data they have entered is invalid.

  • Desde una perspectiva de rendimiento, la validación de datos en una aplicación de varios niveles puede reducir el número de recorridos de ida y vuelta entre los niveles de aplicación y cliente, especialmente cuando la aplicación está formada por servicios Web o bases de datos basadas en servidor.From a performance perspective, data validation in a multi-tier application can reduce the number of round trips between the client and the application tiers, particularly when the application is composed of Web services or server-based databases.

Para validar un control enlazado en WPF, debe definir una regla de validación y asociarla con el enlace.To validate a bound control in WPF, you need to define a validation rule and associate it with the binding. Una regla de validación es una clase personalizada que deriva de ValidationRule.A validation rule is a custom class that derives from ValidationRule. El ejemplo siguiente muestra una regla de validación, MarginValidationRule, que comprueba que un valor enlazado es un Double y está dentro del intervalo especificado.The following example shows a validation rule, MarginValidationRule, which checks that a bound value is a Double and is within a specified range.

using System.Globalization;
using System.Windows.Controls;

namespace SDKSample
{
    public class MarginValidationRule : ValidationRule
    {
        double minMargin;
        double maxMargin;

        public double MinMargin
        {
            get { return this.minMargin; }
            set { this.minMargin = value; }
        }

        public double MaxMargin
        {
            get { return this.maxMargin; }
            set { this.maxMargin = value; }
        }

        public override ValidationResult Validate(object value, CultureInfo cultureInfo)
        {
            double margin;

            // Is a number?
            if (!double.TryParse((string)value, out margin))
            {
                return new ValidationResult(false, "Not a number.");
            }

            // Is in range?
            if ((margin < this.minMargin) || (margin > this.maxMargin))
            {
                string msg = string.Format("Margin must be between {0} and {1}.", this.minMargin, this.maxMargin);
                return new ValidationResult(false, msg);
            }

            // Number is valid
            return new ValidationResult(true, null);
        }
    }
}
Imports System.Globalization
Imports System.Windows.Controls

Namespace SDKSample
    Public Class MarginValidationRule
        Inherits ValidationRule

        Private _maxMargin As Double
        Private _minMargin As Double

        Public Property MaxMargin() As Double
            Get
                Return Me._maxMargin
            End Get
            Set(ByVal value As Double)
                Me._maxMargin = value
            End Set
        End Property

        Public Property MinMargin() As Double
            Get
                Return Me._minMargin
            End Get
            Set(ByVal value As Double)
                Me._minMargin = value
            End Set
        End Property

        Public Overrides Function Validate(ByVal value As Object, ByVal cultureInfo As CultureInfo) As ValidationResult
            Dim margin As Double

            ' Is a number?
            If Not Double.TryParse(CStr(value), margin) Then
                Return New ValidationResult(False, "Not a number.")
            End If

            ' Is in range?
            If ((margin < Me.MinMargin) OrElse (margin > Me.MaxMargin)) Then
                Dim msg As String = String.Format("Margin must be between {0} and {1}.", Me.MinMargin, Me.MaxMargin)
                Return New ValidationResult(False, msg)
            End If

            ' Number is valid
            Return New ValidationResult(True, Nothing)
        End Function
    End Class
End Namespace

En este código, se implementa la lógica de validación de una regla de validación invalidando el Validate método, que valida los datos y devuelve una adecuada ValidationResult.In this code, the validation logic of a validation rule is implemented by overriding the Validate method, which validates the data and returns an appropriate ValidationResult.

Para asociar la regla de validación con el control enlazado, use el siguiente marcado.To associate the validation rule with the bound control, you use the following markup.

<Window 
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    x:Class="SDKSample.MarginsDialogBox"
    xmlns:local="clr-namespace:SDKSample"
    Title="Margins"
    Height="190"
    Width="300"
    MinHeight="10"
    MinWidth="300"
    ResizeMode="CanResizeWithGrip"
    ShowInTaskbar="False"
    WindowStartupLocation="CenterOwner" 
    FocusManager.FocusedElement="{Binding ElementName=leftMarginTextBox}">

  <Grid>

    <!-- Left Margin -->
    <Label Grid.Column="0" Grid.Row="0">Left Margin:</Label>
    <TextBox Name="leftMarginTextBox" Grid.Column="1" Grid.Row="0">
      <TextBox.Text>
        <Binding Path="Left" UpdateSourceTrigger="PropertyChanged">
          <Binding.ValidationRules>
            <local:MarginValidationRule MinMargin="0" MaxMargin="10" />
          </Binding.ValidationRules>
        </Binding>
      </TextBox.Text>
    </TextBox>
  </Grid >
</Window>

Una vez que está asociada la regla de validación, WPF lo aplicará automáticamente cuando se escriben datos en el control enlazado.Once the validation rule is associated, WPF will automatically apply it when data is entered into the bound control. Cuando un control contiene datos no válidos, WPF mostrará un borde rojo alrededor del control no válido, tal como se muestra en la ilustración siguiente.When a control contains invalid data, WPF will display a red border around the invalid control, as shown in the following figure.

Un cuadro de diálogo márgenes con un borde rojo alrededor del valor del margen izquierdo no válido.

WPF no restringe un usuario para el control no válido hasta que haya especificado datos válidos.WPF does not restrict a user to the invalid control until they have entered valid data. Este es un buen comportamiento para un cuadro de diálogo; un usuario debe poder navegar libremente por los controles de un cuadro de diálogo sean los datos válidos o no.This is good behavior for a dialog box; a user should be able to freely navigate the controls in a dialog box whether or not data is valid. Sin embargo, esto significa que un usuario puede escribir datos no válidos y presionar el Aceptar botón.However, this means a user can enter invalid data and press the OK button. Por este motivo, el código también necesita validar todos los controles en un cuadro de diálogo cuadro cuando el Aceptar está presionado controlando el Click eventos.For this reason, your code also needs to validate all controls in a dialog box when the OK button is pressed by handling the Click event.

using System.Windows;
using System.Windows.Controls;
using System.Windows.Input;

namespace SDKSample
{
    public partial class MarginsDialogBox : Window
    {
        void okButton_Click(object sender, RoutedEventArgs e)
        {
            // Don't accept the dialog box if there is invalid data
            if (!IsValid(this)) return;
        }

        // Validate all dependency objects in a window
        bool IsValid(DependencyObject node)
        {
            // Check if dependency object was passed
            if (node != null)
            {
                // Check if dependency object is valid.
                // NOTE: Validation.GetHasError works for controls that have validation rules attached 
                bool isValid = !Validation.GetHasError(node);
                if (!isValid)
                {
                    // If the dependency object is invalid, and it can receive the focus,
                    // set the focus
                    if (node is IInputElement) Keyboard.Focus((IInputElement)node);
                    return false;
                }
            }

            // If this dependency object is valid, check all child dependency objects
            foreach (object subnode in LogicalTreeHelper.GetChildren(node))
            {
                if (subnode is DependencyObject)
                {   
                    // If a child dependency object is invalid, return false immediately,
                    // otherwise keep checking
                    if (IsValid((DependencyObject)subnode) == false) return false;
                }
            }

            // All dependency objects are valid
            return true;
        }
    }
}
Imports System.Windows
Imports System.Windows.Controls
Imports System.Windows.Input

Namespace SDKSample
    Public Class MarginsDialogBox
        Inherits Window

        Private Sub okButton_Click(ByVal sender As Object, ByVal e As RoutedEventArgs)
            ' Don't accept the dialog box if there is invalid data
            If Not Me.IsValid(Me) Then Return
        End Sub

        ' Validate all dependency objects in a window
        Private Function IsValid(ByVal node As DependencyObject) As Boolean
            ' Check if dependency object was passed and if dependency object is valid.
            ' NOTE: Validation.GetHasError works for controls that have validation rules attached 
            If ((Not node Is Nothing) AndAlso Validation.GetHasError(node)) Then
                ' If the dependency object is invalid, and it can receive the focus,
                ' set the focus
                If TypeOf node Is IInputElement Then
                    Keyboard.Focus(DirectCast(node, IInputElement))
                End If
                Return False
            End If

            ' If this dependency object is valid, check all child dependency objects
            Dim subnode As Object
            For Each subnode In LogicalTreeHelper.GetChildren(node)
                If (TypeOf subnode Is DependencyObject AndAlso Not Me.IsValid(DirectCast(subnode, DependencyObject))) Then
                    ' If a child dependency object is invalid, return false immediately,
                    ' otherwise keep checking
                    Return False
                End If
            Next

            ' All dependency objects are valid
            Return True
        End Function
    End Class
End Namespace

Este código enumera todos los objetos de dependencia en una ventana y, si alguno no es válido (tal como lo devuelve GetHasError, el control no válido obtiene el foco, el IsValid devuelve del método false, y la ventana se considera no válida.This code enumerates all dependency objects on a window and, if any are invalid (as returned by GetHasError, the invalid control gets the focus, the IsValid method returns false, and the window is considered invalid.

Una vez que un cuadro de diálogo es válido, puede cerrarse y devolverse de manera segura.Once a dialog box is valid, it can safely close and return. Como parte del proceso de retorno, necesita devolver un resultado a la función de llamada.As part of the return process, it needs to return a result to the calling function.

Establecer el resultado del cuadro de diálogo modalSetting the modal dialog result

Abrir un cuadro de diálogo mediante ShowDialog es prácticamente como llamar a un método: el código que abre el cuadro de diálogo mediante ShowDialog espera hasta que ShowDialog devuelve.Opening a dialog box using ShowDialog is fundamentally like calling a method: the code that opened the dialog box using ShowDialog waits until ShowDialog returns. Cuando ShowDialog devuelve, el código que realizó la llamada necesita decidir si continuar el procesamiento o detener el procesamiento, en función de si el usuario presionó el Aceptar botón o la cancelar botón.When ShowDialog returns, the code that called it needs to decide whether to continue processing or stop processing, based on whether the user pressed the OK button or the Cancel button. Para facilitar esta decisión, el cuadro de diálogo necesita devolver la elección del usuario como un Boolean valor devuelto desde el ShowDialog método.To facilitate this decision, the dialog box needs to return the user's choice as a Boolean value that is returned from the ShowDialog method.

Cuando el Aceptar se hace clic en el botón, ShowDialog debe devolver true.When the OK button is clicked, ShowDialog should return true. Esto se consigue estableciendo la DialogResult cuadro de propiedad del cuadro de diálogo cuando el Aceptar se hace clic en el botón.This is achieved by setting the DialogResult property of the dialog box when the OK button is clicked.

using System.Windows;
using System.Windows.Controls;
using System.Windows.Input;

namespace SDKSample
{
    public partial class MarginsDialogBox : Window
    {

        void okButton_Click(object sender, RoutedEventArgs e)
        {
            this.DialogResult = true;
        }
    }
}
Imports System.Windows
Imports System.Windows.Controls
Imports System.Windows.Input

Namespace SDKSample
    Public Class MarginsDialogBox
        Inherits Window

        Private Sub okButton_Click(ByVal sender As Object, ByVal e As RoutedEventArgs)
            ' Dialog box accepted
            MyBase.DialogResult = New Nullable(Of Boolean)(True)
        End Sub
    End Class
End Namespace

Tenga en cuenta esa configuración la DialogResult propiedad también hace que la ventana se cierre automáticamente, lo que alivia la necesidad de llamar explícitamente a Close.Note that setting the DialogResult property also causes the window to close automatically, which alleviates the need to explicitly call Close.

Cuando el cancelar se hace clic en el botón, ShowDialog debe devolver false, que también requiere la configuración de la DialogResult propiedad.When the Cancel button is clicked, ShowDialog should return false, which also requires setting the DialogResult property.

using System.Windows;
using System.Windows.Controls;
using System.Windows.Input;

namespace SDKSample
{
    public partial class MarginsDialogBox : Window
    {

        void cancelButton_Click(object sender, RoutedEventArgs e)
        {
            // Dialog box canceled
            this.DialogResult = false;
        }
    }
}
Imports System.Windows
Imports System.Windows.Controls
Imports System.Windows.Input

Namespace SDKSample
    Public Class MarginsDialogBox
        Inherits Window

        Private Sub cancelButton_Click(ByVal sender As Object, ByVal e As RoutedEventArgs)
            ' Dialog box canceled
            Me.DialogResult = False
        End Sub
    End Class
End Namespace

Cuando un botón IsCancel propiedad está establecida en true y el usuario presiona el cancelar botón o la tecla ESC, DialogResult se establece automáticamente en false.When a button's IsCancel property is set to true and the user presses either the Cancel button or the ESC key, DialogResult is automatically set to false. El siguiente marcado tiene el mismo efecto que el código anterior, sin necesidad de controlar la Click eventos.The following markup has the same effect as the preceding code, without the need to handle the Click event.

<Button Name="cancelButton" IsCancel="True">Cancel</Button>

Un cuadro de diálogo devuelve automáticamente false cuando un usuario presiona el cerrar situado en la barra de título o elige la cerrar elemento de menú de la sistema menú.A dialog box automatically returns false when a user presses the Close button in the title bar or chooses the Close menu item from the System menu.

Procesar los datos devueltos desde un cuadro de diálogo modalProcessing data returned from a modal dialog box

Cuando DialogResult se establece mediante un cuadro de diálogo, la función que se ha abierto puede obtener el resultado del cuadro de diálogo inspeccionando la DialogResult propiedad cuando ShowDialog devuelve.When DialogResult is set by a dialog box, the function that opened it can get the dialog box result by inspecting the DialogResult property when ShowDialog returns.

using System;
using System.ComponentModel;
using System.Windows;
using System.Windows.Controls;
using Microsoft.Win32;

namespace SDKSample
{
    public partial class MainWindow : Window
    {

        void formatMarginsMenuItem_Click(object sender, RoutedEventArgs e)
        {

            // Process data entered by user if dialog box is accepted
            if (dlg.DialogResult == true)
            {
                // Update fonts
                this.documentTextBox.Margin = dlg.DocumentMargin;
            }
        }
    }
}
Imports System.ComponentModel
Imports System.Windows
Imports System.Windows.Controls
Imports Microsoft.Win32

Namespace SDKSample
    Public Class MainWindow
        Inherits Window
        
        Private Sub formatMarginsMenuItem_Click(ByVal sender As Object, ByVal e As RoutedEventArgs)
            ' Process data entered by user if dialog box is accepted
            If (dlg.DialogResult.GetValueOrDefault = True) Then
                Me.documentTextBox.Margin = dlg.DocumentMargin
            End If
        End Sub
    End Class
End Namespace

Si el resultado del cuadro de diálogo es true, la función que utiliza como una indicación para recuperar y procesar los datos proporcionados por el usuario.If the dialog result is true, the function uses that as a cue to retrieve and process the data provided by the user.

Nota

Después de ShowDialog ha devuelto, no se puede abrir un cuadro de diálogo.After ShowDialog has returned, a dialog box cannot be reopened. En su lugar, necesita crear una instancia nueva.Instead, you need to create a new instance.

Si el resultado del cuadro de diálogo es false, la función debe finalizar el procesamiento correctamente.If the dialog result is false, the function should end processing appropriately.

Crear un cuadro de diálogo no modal personalizadoCreating a modeless custom dialog box

Un cuadro de diálogo no modal, como el cuadro de diálogo Buscar que se muestra en la figura siguiente, tiene el mismo aspecto fundamental que el cuadro de diálogo modal.A modeless dialog box, such as the Find Dialog Box shown in the following figure, has the same fundamental appearance as the modal dialog box.

Captura de pantalla que muestra un cuadro de diálogo Buscar.

En cambio, el comportamiento es un poco diferente, como se describe en las secciones siguientes.However, the behavior is slightly different, as described in the following sections.

Abrir un cuadro de diálogo no modalOpening a modeless dialog box

Se abre un cuadro de diálogo no modal mediante una llamada a la Show método.A modeless dialog box is opened by calling the Show method.

<!--Main Window-->
<MenuItem Name="editFindMenuItem" Header="_Find" InputGestureText="Ctrl+F" Click="editFindMenuItem_Click" />
using System;
using System.ComponentModel;
using System.Windows;
using System.Windows.Controls;
using Microsoft.Win32;

namespace SDKSample
{
    public partial class MainWindow : Window
    {
        void editFindMenuItem_Click(object sender, RoutedEventArgs e)
        {
            // Instantiate the dialog box
            FindDialogBox dlg = new FindDialogBox(this.documentTextBox);

            // Configure the dialog box
            dlg.Owner = this;
            dlg.TextFound += new TextFoundEventHandler(dlg_TextFound);

            // Open the dialog box modally
            dlg.Show();
        }
    }
}
Imports System.ComponentModel
Imports System.Windows
Imports System.Windows.Controls
Imports Microsoft.Win32

Namespace SDKSample
    Public Class MainWindow
        Inherits Window
        
        Private Sub editFindMenuItem_Click(ByVal sender As Object, ByVal e As RoutedEventArgs)
            Dim dlg As New FindDialogBox(Me.documentTextBox)
            dlg.Owner = Me
            AddHandler dlg.TextFound, New TextFoundEventHandler(AddressOf Me.dlg_TextFound)
            dlg.Show()
        End Sub
    End Class
End Namespace

A diferencia de ShowDialog, Show devuelve inmediatamente.Unlike ShowDialog, Show returns immediately. Por consiguiente, la ventana de llamada no puede indicar cuándo se cierra el cuadro de diálogo no modal y, por lo tanto, no sabe cuándo comprobar el resultado de un cuadro de diálogo u obtener los datos de este para un procesamiento posterior.Consequently, the calling window cannot tell when the modeless dialog box is closed and, therefore, does not know when to check for a dialog box result or get data from the dialog box for further processing. En su lugar, el cuadro de diálogo necesita crear una manera alternativa de devolver los datos a la ventana de llamada para su procesamiento.Instead, the dialog box needs to create an alternative way to return data to the calling window for processing.

Procesar los datos devueltos desde un cuadro de diálogo no modalProcessing data returned from a modeless dialog box

En este ejemplo, el FindDialogBox puede devolver uno o varios resultados de búsqueda a la ventana principal, según el texto que se está buscando sin ninguna frecuencia determinada.In this example, the FindDialogBox may return one or more find results to the main window, depending on the text being searched for without any specific frequency. Al igual que un cuadro de diálogo modal, un cuadro de diálogo no modal puede devolver resultados mediante propiedades.As with a modal dialog box, a modeless dialog box can return results using properties. En cambio, la ventana que tiene el cuadro de diálogo necesita saber cuándo comprobar esas propiedades.However, the window that owns the dialog box needs to know when to check those properties. Una manera de habilitar esto es que el cuadro de diálogo implemente un evento que se genera cuando se detecta texto.One way to enable this is for the dialog box to implement an event that is raised whenever text is found. FindDialogBox implementa el TextFoundEvent para este propósito, que necesita primero un delegado.FindDialogBox implements the TextFoundEvent for this purpose, which first requires a delegate.

using System;

namespace SDKSample
{
    public delegate void TextFoundEventHandler(object sender, EventArgs e);
}
Namespace SDKSample
   Public Delegate Sub TextFoundEventHandler(ByVal sender As Object, ByVal e As EventArgs)
End Namespace

Mediante el TextFoundEventHandler delegar, FindDialogBox implementa el TextFoundEvent.Using the TextFoundEventHandler delegate, FindDialogBox implements the TextFoundEvent.

using System;
using System.Windows;
using System.Windows.Controls;
using System.Text.RegularExpressions;

namespace SDKSample
{
    public partial class FindDialogBox : Window
    {
        public event TextFoundEventHandler TextFound;
        
        protected virtual void OnTextFound()
        {
            TextFoundEventHandler textFound = this.TextFound;
            if (textFound != null) textFound(this, EventArgs.Empty);
        }

    }
}
Imports System.Windows
Imports System.Windows.Controls
Imports System.Text.RegularExpressions

Namespace SDKSample

    Public Class FindDialogBox
        Inherits Window

        Public Event TextFound As TextFoundEventHandler

        Protected Overridable Sub OnTextFound()
            RaiseEvent TextFound(Me, EventArgs.Empty)
        End Sub

    End Class
End Namespace

Por lo tanto, Find puede generar el evento cuando se encuentra un resultado de búsqueda.Consequently, Find can raise the event when a search result is found.

using System;
using System.Windows;
using System.Windows.Controls;
using System.Text.RegularExpressions;

namespace SDKSample
{
    public partial class FindDialogBox : Window
    {

        void findNextButton_Click(object sender, RoutedEventArgs e)
        {
                // Text found
                this.index = match.Index;
                this.length = match.Length;
                OnTextFound();
        }
    }
}
Imports System.Windows
Imports System.Windows.Controls
Imports System.Text.RegularExpressions

Namespace SDKSample

    Public Class FindDialogBox
        Inherits Window



            Me.Index = match.Index
            Me.Length = match.Length
            RaiseEvent TextFound(Me, EventArgs.Empty)

    End Class
End Namespace

Después, la ventana propietaria necesita registrar y controlar este evento.The owner window then needs to register with and handle this event.

using System;
using System.ComponentModel;
using System.Windows;
using System.Windows.Controls;
using Microsoft.Win32;

namespace SDKSample
{
    public partial class MainWindow : Window
    {

        void dlg_TextFound(object sender, EventArgs e)
        {
            // Get the find dialog box that raised the event
            FindDialogBox dlg = (FindDialogBox)sender;

            // Get find results and select found text
            this.documentTextBox.Select(dlg.Index, dlg.Length);
            this.documentTextBox.Focus();
        }
    }
}
Imports System.ComponentModel
Imports System.Windows
Imports System.Windows.Controls
Imports Microsoft.Win32

Namespace SDKSample
    Public Class MainWindow
        Inherits Window
        
        Private Sub dlg_TextFound(ByVal sender As Object, ByVal e As EventArgs)
            Dim dlg As FindDialogBox = DirectCast(sender, FindDialogBox)
            Me.documentTextBox.Select(dlg.Index, dlg.Length)
            Me.documentTextBox.Focus()
        End Sub
    End Class
End Namespace

Cerrar un cuadro de diálogo no modalClosing a modeless dialog box

Dado que DialogResult no necesita establecerse, un cuadro de diálogo no modal puede cerrarse con sistema proporcionan mecanismos, incluido lo siguiente:Because DialogResult does not need to be set, a modeless dialog can be closed using system provide mechanisms, including the following:

  • Al hacer clic en el cerrar botón en la barra de título.Clicking the Close button in the title bar.

  • Presionar ALT+F4.Pressing ALT+F4.

  • Elegir cerrar desde el sistema menú.Choosing Close from the System menu.

Como alternativa, puede llamar su código Close cuando el cerrar se hace clic en el botón.Alternatively, your code can call Close when the Close button is clicked.

using System;
using System.Windows;
using System.Windows.Controls;
using System.Text.RegularExpressions;

namespace SDKSample
{
    public partial class FindDialogBox : Window
    {

        void closeButton_Click(object sender, RoutedEventArgs e)
        {
            // Close dialog box
            this.Close();
        }
    }
}
Imports System.Windows
Imports System.Windows.Controls
Imports System.Text.RegularExpressions

Namespace SDKSample

    Public Class FindDialogBox
        Inherits Window

        Private Sub closeButton_Click(ByVal sender As Object, ByVal e As RoutedEventArgs)
            MyBase.Close()
        End Sub
    End Class
End Namespace

Vea tambiénSee also