Función TaskDialog (commctrl.h)

  • Artículo

La función TaskDialog crea, muestra y opera un cuadro de diálogo de tareas. El cuadro de diálogo de tarea contiene texto y título de mensaje definidos 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 botón, 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: Sí.
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 tareas. 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 en el cuadro de diálogo de la tarea.
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 tarea.
TD_WARNING_ICON
 Aparece un icono de signo de exclamación en el cuadro de diálogo de tarea.

[out] pnButton

Tipo: int*

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

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

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 apuntan los parámetros pszMainInstruction y pszWindowTitle no deben tomarse de un archivo de recursos, ya que se puede producir un error al intentar cargar el recurso.

Si crea un cuadro de diálogo de tareas 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 va a incluir como parte de un programa más grande, se muestra cómo crear un cuadro de diálogo de tareas 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

Requisito Value
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