Função TaskDialog (commctrl.h)
A função TaskDialog cria, exibe e opera uma caixa de diálogo de tarefa. A caixa de diálogo da tarefa contém texto e título da mensagem definidos pelo aplicativo, ícones e qualquer combinação de botões de push predefinidos. Essa função não dá suporte ao registro de uma função de retorno de chamada para receber notificações.
Sintaxe
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
Manipule para a janela proprietário da caixa de diálogo de tarefa a ser criada. Se esse parâmetro for NULL, a caixa de diálogo da tarefa não terá nenhuma janela de proprietário.
[in] hInstance
Tipo: HINSTANCE
Manipule para o módulo que contém o recurso de ícone identificado pelo membro pszIcon e os recursos de cadeia de caracteres identificados pelos membros pszWindowTitle e pszMainInstruction . Se esse parâmetro for NULL, pszIcon deverá ser NULL ou um ponteiro para uma cadeia de caracteres Unicode terminada em nulo que contenha um identificador de recurso do sistema, por exemplo, TD_ERROR_ICON.
[in] pszWindowTitle
Tipo: PCWSTR
Ponteiro para a cadeia de caracteres a ser usada para o título da caixa de diálogo da tarefa. Esse parâmetro é uma cadeia de caracteres Unicode terminada em nulo que contém texto ou um identificador de recurso inteiro passado pela macro MAKEINTRESOURCE . Se esse parâmetro for NULL, o nome do programa executável será usado.
[in] pszMainInstruction
Tipo: PCWSTR
Ponteiro para a cadeia de caracteres a ser usada para a instrução main. Esse parâmetro é uma cadeia de caracteres Unicode terminada em nulo que contém texto ou um identificador de recurso inteiro passado pela macro MAKEINTRESOURCE . Esse parâmetro poderá ser NULL se nenhuma instrução main for desejada.
[in] pszContent
Tipo: PCWSTR
Ponteiro para uma cadeia de caracteres usada para texto adicional que aparece abaixo da instrução main, em uma fonte menor. Esse parâmetro é uma cadeia de caracteres Unicode terminada em nulo que contém texto ou um identificador de recurso inteiro passado pela macro MAKEINTRESOURCE . Pode ser NULL se nenhum texto adicional for desejado.
[in] dwCommonButtons
Tipo: TASKDIALOG_COMMON_BUTTON_FLAGS
Especifica os botões de push exibidos na caixa de diálogo. Esse parâmetro pode ser uma combinação de sinalizadores do grupo a seguir.
[in] pszIcon
Tipo: PCWSTR
Ponteiro para uma cadeia de caracteres que identifica o ícone a ser exibido na caixa de diálogo da tarefa. Esse parâmetro deve ser um identificador de recurso inteiro passado para a macro MAKEINTRESOURCE ou um dos valores predefinidos a seguir. Se esse parâmetro for NULL, nenhum ícone será exibido. Se o parâmetro hInstance for NULL e um dos valores predefinidos não for usado, a função TaskDialog falhará.
[out] pnButton
Tipo: int*
Quando essa função retorna, contém um ponteiro para um local inteiro que recebe um dos seguintes valores:
| Valor | Descrição |
|---|---|
| 0 | Falha na chamada de função. Consulte o valor retornado para obter mais informações. |
| IDCANCEL | O botão Cancelar foi selecionado, Alt-F4 foi pressionado, Escape foi pressionado ou o usuário clicou no botão fechar janela . |
| IDNO | Nenhum botão foi selecionado. |
| IDOK | O botão OK foi selecionado. |
| IDRETRY | O botão Repetir foi selecionado. |
| IDYES | O botão Sim foi selecionado. |
| IDCLOSE | O botão Fechar foi selecionado. |
Se esse valor for NULL, nenhum valor será retornado.
Retornar valor
Tipo: HRESULT
Essa função pode retornar um desses valores.
| Código de retorno | Descrição |
|---|---|
|
A operação foi concluída com sucesso. |
|
Não há memória suficiente para concluir a operação. |
|
Um ou mais argumentos não são válidos. |
|
Falha na operação. |
Comentários
Quando você usa uma caixa de diálogo de tarefa para indicar que o sistema está com pouca memória, as cadeias de caracteres apontadas pelos parâmetros pszMainInstruction e pszWindowTitle não devem ser retiradas de um arquivo de recurso, pois uma tentativa de carregar o recurso pode falhar.
Se você criar uma caixa de diálogo de tarefa enquanto uma caixa de diálogo estiver presente, use um identificador para a caixa de diálogo como o parâmetro hWndParent . O parâmetro hWndParent não deve identificar uma janela filho, como um controle em uma caixa de diálogo.
Como as caixas de diálogo da tarefa usam os elementos corretos da interface do usuário definidos pelo sistema, você deve usá-los em vez de usar caixas de mensagem criadas com a função MessageBox . Para obter mais funcionalidade, use TaskDialogIndirect.
O código de exemplo a seguir, a ser incluído como parte de um programa maior, mostra como criar uma caixa de diálogo de tarefa e capturar a 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 | Valor |
|---|---|
| Cliente mínimo com suporte | Windows Vista [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2008 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | commctrl.h (inclua Commctrl.h) |
| Biblioteca | Comctl32.lib |
| DLL | Comctl32.dll (versão 6) |