Instruções passo a passo: adicionando um CTaskDialog a um aplicativo

Artigo
06/16/2023

Este passo a passo apresenta a Classe CTaskDialog e mostra como adicionar uma ao seu aplicativo.

O CTaskDialog é uma caixa de diálogo de tarefa que substitui a caixa de mensagem do Windows no Windows Vista ou posterior. O CTaskDialog aprimora a caixa de mensagem original e adiciona funcionalidades. A caixa de mensagem do Windows ainda tem suporte no Visual Studio.

Observação

Versões do Windows anteriores ao Windows Vista não dão suporte ao CTaskDialog. Você deve programar uma opção alternativa de caixa de diálogo se quiser mostrar uma mensagem a um usuário que executa seu aplicativo em uma versão anterior do Windows. Você pode usar o método estático CTaskDialog::IsSupported para determinar em tempo de execução se o computador de um usuário pode exibir um CTaskDialog. Além disso, o CTaskDialog só estará disponível quando seu aplicativo for criado com a biblioteca Unicode.

O CTaskDialog dá suporte a vários elementos opcionais para coletar e exibir informações. Por exemplo, um CTaskDialog pode exibir links de comando, botões personalizados, ícones personalizados e um rodapé. O CTaskDialog também tem vários métodos que permitem consultar o estado da caixa de diálogo de tarefa para determinar quais elementos opcionais o usuário selecionou.

Pré-requisitos

Você precisará dos seguintes componentes para concluir este passo a passo:

Visual Studio 2010 ou posterior
Windows Vista ou posterior

Substituir uma caixa de mensagem do Windows por um CTaskDialog

O procedimento a seguir demonstra o uso mais básico do CTaskDialog, que é substituir a caixa de mensagem do Windows. Este exemplo também altera o ícone associado à caixa de diálogo de tarefa. Alterar o ícone faz com que CTaskDialog pareça igual à caixa de mensagem do Windows.

Para substituir uma caixa de mensagem do Windows por um CTaskDialog

Use o Assistente para Aplicativo do MFC para criar um aplicativo MFC com todas as configurações padrão. Confira Guia passo a passo: usar os novos controles de shell do MFC para instruções sobre como abrir o assistente em sua versão do Visual Studio.
Chame-o de MyProject.
Use o Gerenciador de Soluções para abrir o arquivo MyProject.cpp.
Adicione #include "afxtaskdialog.h" após a lista de inclusões.
Encontre o método CMyProjectApp::InitInstance. Insira as seguintes linhas de código antes da instrução return TRUE;. Esse código cria as cadeias de caracteres que usamos na caixa de mensagem do Windows ou no CTaskDialog.
```
CString message("My message to the user");
CString dialogTitle("My Task Dialog title");
CString emptyString;
```
Adicione o seguinte código após o código da etapa 4. Esse código garante que o computador do usuário dê suporte ao CTaskDialog. Se não houver suporte para a caixa de diálogo, o aplicativo exibirá uma caixa de mensagem do Windows.
```
if (CTaskDialog::IsSupported())
{

}
else
{
    AfxMessageBox(message);
}
```
Insira o código a seguir entre os colchetes após a instrução if da etapa 5. Esse código cria o CTaskDialog.
```
CTaskDialog taskDialog(message, emptyString, dialogTitle, TDCBF_OK_BUTTON);
```
Na próxima linha, adicione o código a seguir. Esse código define o ícone de aviso.
```
taskDialog.SetMainIcon(TD_WARNING_ICON);
```
Na próxima linha, adicione o código a seguir. Esse código exibe a caixa de diálogo de tarefa.
```
taskDialog.DoModal();
```

Você pode pular a etapa 7 se não quiser que o CTaskDialog exiba o mesmo ícone que a caixa de mensagem do Windows. Se você pular essa etapa, o CTaskDialog não terá nenhum ícone quando o aplicativo a exibir.

Compile e execute o aplicativo. O aplicativo exibe a caixa de diálogo da tarefa após o início.

Adicionar funcionalidade ao CTaskDialog

O procedimento a seguir mostra como adicionar funcionalidade ao CTaskDialog que você criou no procedimento anterior. O código de exemplo mostra como executar instruções específicas com base nas seleções do usuário.

Para adicionar funcionalidade ao CTaskDialog

Vá até o Modo de Exibição de Recursos. Se você não conseguir ver o Modo de Exibição de Recursos, poderá abri-lo no menu Exibir.
Expanda o Modo de Exibição de Recursos até que você possa selecionar a pasta Tabela de Cadeia de Caracteres. Expanda-a e clique duas vezes na entrada da Tabela de cadeia de caracteres.
Role até a parte inferior da tabela de cadeia de caracteres e adicione uma nova entrada. Altere a ID para TEMP_LINE1. Defina o título como Linha de Comando 1.
Adicione outra nova entrada. Altere a ID para TEMP_LINE2. Defina o título como Linha de Comando 2.
Volte para MyProject.cpp.

Depois de CString emptyString;, adicione o seguinte código:

CString expandedLabel("Hide extra information");
CString collapsedLabel("Show extra information");
CString expansionInfo("This is the additional information to the user,\nextended over two lines.");

Encontre a instrução taskDialog.DoModal() e substitua pelo código a seguir. Esse código atualiza a caixa de diálogo de tarefa e adiciona novos controles:

taskDialog.SetMainInstruction(L"Warning");
taskDialog.SetCommonButtons(
    TDCBF_YES_BUTTON | TDCBF_NO_BUTTON | TDCBF_CANCEL_BUTTON);
taskDialog.LoadCommandControls(TEMP_LINE1, TEMP_LINE2);
taskDialog.SetExpansionArea(
    expansionInfo, collapsedLabel, expandedLabel);
taskDialog.SetFooterText(L"This is a small footnote to the user");
taskDialog.SetVerificationCheckboxText(L"Remember your selection");

Adicione a seguinte linha de código que exibe a caixa de diálogo de tarefa ao usuário e recupera a seleção do usuário:
```
INT_PTR result = taskDialog.DoModal();
```

Insira o seguinte código após a chamada para taskDialog.DoModal(). Esta seção de código processa a entrada do usuário:

if (taskDialog.GetVerificationCheckboxState())
{
    // PROCESS IF the user selects the verification checkbox
}

switch (result)
{
case TEMP_LINE1:
    // PROCESS IF the first command line
    break;
case TEMP_LINE2:
    // PROCESS IF the second command line
    break;
case IDYES:
    // PROCESS IF the user clicks yes
    break;
case IDNO:
    // PROCESS IF the user clicks no
    break;
case IDCANCEL:
    // PROCESS IF the user clicks cancel
    break;
default:
    // This case should not be hit because closing
    // the dialog box results in IDCANCEL
    break;
}

No código na etapa 9, substitua os comentários que começam com PROCESS IF pelo código que você deseja executar nas condições especificadas.

Compile e execute o aplicativo. O aplicativo exibe a caixa de diálogo de tarefa que usa os novos controles e informações adicionais.

Exibir um CTaskDialog sem criar um objeto CTaskDialog

O procedimento a seguir mostra como exibir um CTaskDialog sem criar antes um objeto CTaskDialog. Este exemplo continua os procedimentos anteriores.

Para exibir um CTaskDialog sem criar um objeto CTaskDialog

Abra o arquivo MyProject.cpp se ele ainda não estiver aberto.
Vá até o colchete de fechamento da instrução if (CTaskDialog::IsSupported()).

Insira o código a seguir imediatamente antes do colchete de fechamento da instrução if (antes do bloco else):

HRESULT result2 = CTaskDialog::ShowDialog(L"My error message",
    L"Error",
    L"New Title",
    TEMP_LINE1,
    TEMP_LINE2);

Compile e execute o aplicativo. O aplicativo exibe duas caixas de diálogo de tarefa. A primeira caixa de diálogo é do procedimento Para Adicionar Funcionalidade ao CTaskDialog; a segunda caixa de diálogo é do último procedimento.

Esses exemplos não demonstram todas as opções disponíveis para um CTaskDialog, mas devem ajudá-lo a ter uma noção básica. Consulte Classe CTaskDialog para obter uma descrição completa da classe.

Confira também

Caixas de diálogo
Classe CTaskDialog
CTaskDialog::CTaskDialog