Función TaskDialog (commctrl.h)

La función TaskDialog crea, muestra y opera un cuadro de diálogo de tarea. El cuadro de diálogo de tarea contiene texto y título del mensaje definido por la aplicación, iconos y cualquier combinación de botones de inserción predefinidos. Esta función no admite el registro de una función de devolución de llamada para recibir notificaciones.

Sintaxis

HRESULT TaskDialog(
  [in]  HWND                           hwndOwner,
  [in]  HINSTANCE                      hInstance,
  [in]  PCWSTR                         pszWindowTitle,
  [in]  PCWSTR                         pszMainInstruction,
  [in]  PCWSTR                         pszContent,
  [in]  TASKDIALOG_COMMON_BUTTON_FLAGS dwCommonButtons,
  [in]  PCWSTR                         pszIcon,
  [out] int                            *pnButton
);

Parámetros

[in] hwndOwner

Tipo: HWND

Controle la ventana de propietario del cuadro de diálogo de tarea que se va a crear. Si este parámetro es NULL, el cuadro de diálogo de tarea no tiene ninguna ventana de propietario.

[in] hInstance

Tipo: HINSTANCE

Identificador del módulo que contiene el recurso de icono identificado por el miembro pszIcon y los recursos de cadena identificados por los miembros pszWindowTitle y pszMainInstruction . Si este parámetro es NULL, pszIcon debe ser NULL o un puntero a una cadena Unicode terminada en null que contiene un identificador de recursos del sistema, por ejemplo, TD_ERROR_ICON.

[in] pszWindowTitle

Tipo: PCWSTR

Puntero a la cadena que se va a usar para el título del cuadro de diálogo de tarea. Este parámetro es una cadena Unicode terminada en null que contiene texto o un identificador de recurso entero pasado a través de la macro MAKEINTRESOURCE . Si este parámetro es NULL, se usa el nombre de archivo del programa ejecutable.

[in] pszMainInstruction

Tipo: PCWSTR

Puntero a la cadena que se va a usar para la instrucción principal. Este parámetro es una cadena Unicode terminada en null que contiene texto o un identificador de recurso entero pasado a través de la macro MAKEINTRESOURCE . Este parámetro puede ser NULL si no se desea ninguna instrucción principal.

[in] pszContent

Tipo: PCWSTR

Puntero a una cadena usada para texto adicional que aparece debajo de la instrucción principal, en una fuente más pequeña. Este parámetro es una cadena Unicode terminada en null que contiene texto o un identificador de recurso entero pasado a través de la macro MAKEINTRESOURCE . Puede ser NULL si no se desea texto adicional.

[in] dwCommonButtons

Tipo: TASKDIALOG_COMMON_BUTTON_FLAGS

Especifica los botones de inserción que se muestran en el cuadro de diálogo. Este parámetro puede ser una combinación de marcas del siguiente grupo.

Nota Si no se especifica ningún botone, el cuadro de diálogo contendrá el botón Aceptar de forma predeterminada.
 
Valor Significado
TDCBF_OK_BUTTON
El cuadro de diálogo de tarea contiene el botón de inserción: Aceptar.
TDCBF_YES_BUTTON
El cuadro de diálogo de tarea contiene el botón de inserción: .
TDCBF_NO_BUTTON
El cuadro de diálogo de tarea contiene el botón de inserción: No.
TDCBF_CANCEL_BUTTON
El cuadro de diálogo de tarea contiene el botón de inserción: Cancelar. Este botón debe especificarse para que el cuadro de diálogo responda a las acciones de cancelación típicas (Alt-F4 y Escape).
TDCBF_RETRY_BUTTON
El cuadro de diálogo de tarea contiene el botón de inserción: Reintentar.
TDCBF_CLOSE_BUTTON
El cuadro de diálogo de tarea contiene el botón de inserción: Cerrar.

[in] pszIcon

Tipo: PCWSTR

Puntero a una cadena que identifica el icono que se va a mostrar en el cuadro de diálogo de tarea. Este parámetro debe ser un identificador de recurso entero pasado a la macro MAKEINTRESOURCE o uno de los siguientes valores predefinidos. Si este parámetro es NULL, no se mostrará ningún icono. Si el parámetro hInstance es NULL y no se usa uno de los valores predefinidos, se produce un error en la función TaskDialog .

Valor Significado
TD_ERROR_ICON
Aparece un icono de inicio de sesión de detención en el cuadro de diálogo de tareas.
TD_INFORMATION_ICON
Un icono que consta de una letra minúscula i en un círculo aparece en el cuadro de diálogo de tarea.
TD_SHIELD_ICON
Aparece un icono de escudo de seguridad en el cuadro de diálogo de tareas.
TD_WARNING_ICON
Aparece un icono de signo de signo de exclamación en el cuadro de diálogo de tarea.

[out] pnButton

Tipo: int*

Cuando esta función devuelve , contiene un puntero a una ubicación entera que recibe uno de los valores siguientes:

Valor Descripción
0 Error en la llamada de función. Consulte el valor devuelto para obtener más información.
IDCANCEL Se ha seleccionado el botón Cancelar, se ha presionado Alt-F4, se ha presionado Escape o el usuario hizo clic en el botón cerrar ventana .
IDNO No se seleccionó ningún botón.
IDOK Se seleccionó el botón Aceptar.
IDRETRY Se seleccionó el botón Reintentar.
IDYES Se seleccionó el botón Sí.
 

Si este valor es NULL, no se devuelve ningún valor.

Valor devuelto

Tipo: HRESULT

Esta función puede devolver uno de estos valores.

Código devuelto Descripción
S_OK
La operación se ha completado correctamente.
E_OUTOFMEMORY
No hay memoria suficiente para completar la operación.
E_INVALIDARG
Uno o varios argumentos no son válidos.
E_FAIL
Error en la operación.

Comentarios

Cuando se usa un cuadro de diálogo de tareas para indicar que el sistema tiene poca memoria, las cadenas a las que apunta la pszMainInstruction y los parámetros pszWindowTitle no deben tomarse de un archivo de recursos, ya que se puede producir un error en un intento de cargar el recurso.

Si crea un cuadro de diálogo de tarea mientras hay un cuadro de diálogo, use un identificador para el cuadro de diálogo como parámetro hWndParent . El parámetro hWndParent no debe identificar una ventana secundaria, como un control en un cuadro de diálogo.

Dado que los cuadros de diálogo de tareas usan los elementos de interfaz de usuario definidos por el sistema correctos, debe usarlos en lugar de usar cuadros de mensaje creados con la función MessageBox . Para lograr más funcionalidad, use TaskDialogIndirect.

En el código de ejemplo siguiente, que se incluirá como parte de un programa mayor, se muestra cómo crear un cuadro de diálogo de tarea y capturar la entrada.


int nButtonPressed = 0;
TaskDialog(NULL, hInst, 
    MAKEINTRESOURCE(IDS_APPLICATION_TITLE),
    MAKEINTRESOURCE(IDS_DOSOMETHING), 
    MAKEINTRESOURCE(IDS_SOMECONTENT), 
    TDCBF_OK_BUTTON | TDCBF_CANCEL_BUTTON,
    TD_WARNING_ICON, 
    &nButtonPressed);

if (IDOK == nButtonPressed)
{
    // OK button pressed
}
else if (IDCANCEL == nButtonPressed)
{
    // Cancel pressed
}

Requisitos

   
Cliente mínimo compatible Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado commctrl.h (include Commctrl.h)
Library Comctl32.lib
Archivo DLL Comctl32.dll (versión 6)

Consulte también

Cuadros de diálogo