Classe CDialog

A classe base usada para exibir caixas de diálogo na tela.

Sintaxe

class CDialog : public CWnd

Membros

Construtores Públicos

Métodos Públicos

Métodos Protegidos

Observações

As caixas de diálogo são de dois tipos: modal e sem modo. Uma caixa de diálogo modal deve ser fechada pelo usuário antes que o aplicativo continue. Uma caixa de diálogo sem janela restrita permite que o usuário exiba a caixa de diálogo e retorne a outra tarefa sem cancelar ou remover a caixa de diálogo.

Um CDialog objeto é uma combinação de um modelo de diálogo e uma CDialogclasse derivada. Use o editor de diálogo para criar o modelo de diálogo e armazená-lo em um recurso e, em seguida, use o assistente Adicionar classe para criar uma classe derivada de CDialog.

Uma caixa de diálogo, como qualquer outra janela, recebe mensagens do Windows. Em uma caixa de diálogo, você está particularmente interessado em lidar com mensagens de notificação dos controles da caixa de diálogo, pois é assim que o usuário interage com sua caixa de diálogo. Use o Assistente de classe para selecionar quais mensagens você deseja manipular e ele adicionará as entradas apropriadas do mapa de mensagens e as funções de membro do manipulador de mensagens à classe para você. Você só precisa escrever código específico do aplicativo nas funções de membro do manipulador.

Se preferir, você sempre pode escrever entradas de mapa de mensagens e funções de membro manualmente.

Em todas, exceto na caixa de diálogo mais trivial, você adiciona variáveis de membro à sua classe de diálogo derivada para armazenar dados inseridos nos controles da caixa de diálogo pelo usuário ou para exibir dados para o usuário. Você pode usar o assistente Adicionar variável para criar variáveis de membro e associá-las a controles. Ao mesmo tempo, você escolhe um tipo de variável e um intervalo de valores permitido para cada variável. O assistente de código adiciona as variáveis de membro à sua classe de diálogo derivada.

Um mapa de dados é gerado para lidar automaticamente com a troca de dados entre as variáveis de membro e os controles da caixa de diálogo. O mapa de dados fornece funções que inicializam os controles na caixa de diálogo com os valores adequados, recuperam os dados e validam os dados.

Para criar uma caixa de diálogo modal, construa um objeto na pilha usando o construtor para sua classe de diálogo derivada e, em seguida, chame DoModal para criar a janela de diálogo e seus controles. Se você deseja criar uma caixa de diálogo sem moderação, chame Create o construtor de sua classe de diálogo.

Você também pode criar um modelo na memória usando uma estrutura de dados DLGTEMPLATE conforme descrito no SDK do Windows. Depois de construir um CDialog objeto, chame CreateIndirect para criar uma caixa de diálogo sem moderação ou chame InitModalIndirect e DoModal para criar uma caixa de diálogo modal.

O mapa de dados de intercâmbio e validação é escrito em uma substituição do que é adicionado à sua nova classe de CWnd::DoDataExchange diálogo. Consulte a função de membro DoDataExchange para CWnd obter mais informações sobre a funcionalidade de intercâmbio e validação.

Tanto o programador quanto a estrutura chamam DoDataExchange indiretamente por meio de uma chamada para CWnd::UpdateData.

A estrutura chama UpdateData quando o usuário clica no botão OK para fechar uma caixa de diálogo modal. (Os dados não serão recuperados se o botão Cancelar for clicado.) A implementação padrão de OnInitDialog também chama UpdateData para definir os valores iniciais dos controles. Normalmente, você substitui OnInitDialog para inicializar ainda mais os controles. OnInitDialog é chamado depois que todos os controles de diálogo são criados e imediatamente antes da caixa de diálogo ser exibida.

Você pode chamar CWnd::UpdateData a qualquer momento durante a execução de uma caixa de diálogo modal ou sem moderação.

Se você desenvolver uma caixa de diálogo manualmente, você mesmo adicionará as variáveis de membro necessárias à classe de caixa de diálogo derivada e adicionará funções de membro para definir ou obter esses valores.

Uma caixa de diálogo modal fecha automaticamente quando o usuário pressiona os botões OK ou Cancelar ou quando seu código chama a EndDialog função de membro.

Quando você implementa uma caixa de diálogo sem moderação, sempre substitua a função de membro e chame OnCancel de DestroyWindow dentro dela. Não chame a classe CDialog::OnCancelbase , porque ela chama EndDialog, o que tornará a caixa de diálogo invisível, mas não a destruirá. Você também deve substituir PostNcDestroy por caixas de diálogo sem moderação para excluir this, já que as caixas de diálogo sem janela restrita geralmente são alocadas com new. As caixas de diálogo modais geralmente são construídas no quadro e não precisam de PostNcDestroy limpeza.

Para obter mais informações sobre CDialogo , consulte Caixas de diálogo.

Hierarquia de herança

CObject

CCmdTarget

CWnd

CDialog

Requerimentos

Cabeçalho: afxwin.h

CDialog::CDialog

Para construir uma caixa de diálogo modal baseada em recursos, chame qualquer forma pública do construtor.

explicit CDialog(
    LPCTSTR lpszTemplateName,
    CWnd* pParentWnd = NULL);

explicit CDialog(
    UINT nIDTemplate,
    CWnd* pParentWnd = NULL);

CDialog();

Parâmetros

lpszTemplateName
Contém uma cadeia de caracteres terminada em nulo que é o nome de um recurso de modelo de caixa de diálogo.

nIDTemplate
Contém o número de ID de um recurso de modelo de caixa de diálogo.

pParentWnd
Aponta para o objeto de janela pai ou proprietário (do tipo CWnd) ao qual o objeto de diálogo pertence. Se for NULL, a janela pai do objeto de diálogo será definida como a janela principal do aplicativo.

Observações

Uma forma do construtor fornece acesso ao recurso de diálogo pelo nome do modelo. O outro construtor fornece acesso por número de ID de modelo, geralmente com um prefixo IDD_ (por exemplo, IDD_DIALOG1).

Para construir uma caixa de diálogo modal a partir de um modelo na memória, primeiro invoque o construtor protegido e sem parâmetros e, em seguida, chame InitModalIndirect.

Depois de construir uma caixa de diálogo modal com um dos métodos acima, chame DoModal.

Para construir uma caixa de diálogo sem moderação, use a CDialog forma protegida do construtor. O construtor é protegido porque você deve derivar sua própria classe de caixa de diálogo para implementar uma caixa de diálogo sem moderação. A construção de uma caixa de diálogo sem janela restrita é um processo de duas etapas. Primeiro chame o construtor; Em seguida, chame a Create função de membro para criar uma caixa de diálogo baseada em recursos ou chame CreateIndirect para criar a caixa de diálogo a partir de um modelo na memória.

CDialog::Criar

Chamada Create para criar uma caixa de diálogo sem moderação usando um modelo de caixa de diálogo de um recurso.

virtual BOOL Create(
    LPCTSTR lpszTemplateName,
    CWnd* pParentWnd = NULL);

virtual BOOL Create(
    UINT nIDTemplate,
    CWnd* pParentWnd = NULL);

Parâmetros

lpszTemplateName
Contém uma cadeia de caracteres terminada em nulo que é o nome de um recurso de modelo de caixa de diálogo.

pParentWnd
Aponta para o objeto de janela pai (do tipo CWnd) ao qual o objeto de diálogo pertence. Se for NULL, a janela pai do objeto de diálogo será definida como a janela principal do aplicativo.

nIDTemplate
Contém o número de ID de um recurso de modelo de caixa de diálogo.

Valor de retorno

Ambos os formulários retornam diferente de zero se a criação e a inicialização da caixa de diálogo forem bem-sucedidas; caso contrário, 0.

Observações

Você pode colocar a chamada dentro Create do construtor ou chamá-la depois que o construtor é invocado.

Duas formas da função de membro são fornecidas para acesso ao recurso de modelo de caixa de diálogo pelo nome do modelo ou número de ID do Create modelo (por exemplo, IDD_DIALOG1).

Para qualquer um dos formulários, passe um ponteiro para o objeto da janela pai. Se pParentWnd for NULL, a caixa de diálogo será criada com sua janela pai ou proprietário definida para a janela principal do aplicativo.

A Create função de membro retorna imediatamente após criar a caixa de diálogo.

Use o estilo WS_VISIBLE no modelo de caixa de diálogo se a caixa de diálogo aparecer quando a janela pai for criada. Caso contrário, você deve ligar para ShowWindow. Para obter mais estilos de caixa de diálogo e seu aplicativo, consulte a estrutura DLGTEMPLATE no SDK do Windows e Estilos de janela na Referência MFC.

Use a CWnd::DestroyWindow função para destruir uma caixa de diálogo criada pela Create função.

Exemplo

void CMyDialog::OnMenuShowSimpleDialog()
{
   //m_pSimpleDialog initialized to NULL in the constructor of CMyDialog class
   m_pSimpleDlg = new CSimpleDlg();
   //Check if new succeeded and we got a valid pointer to a dialog object
   if (m_pSimpleDlg != NULL)
   {
      BOOL ret = m_pSimpleDlg->Create(IDD_SIMPLEDIALOG, this);

      if (!ret) //Create failed.
      {
         AfxMessageBox(_T("Error creating Dialog"));
      }

      m_pSimpleDlg->ShowWindow(SW_SHOW);
   }
   else
   {
      AfxMessageBox(_T("Error Creating Dialog Object"));
   }
}

CDialog::CriarIndireto

Chame essa função de membro para criar uma caixa de diálogo sem moderação a partir de um modelo de caixa de diálogo na memória.

virtual BOOL CreateIndirect(
    LPCDLGTEMPLATE lpDialogTemplate,
    CWnd* pParentWnd = NULL,
    void* lpDialogInit = NULL);

virtual BOOL CreateIndirect(
    HGLOBAL hDialogTemplate,
    CWnd* pParentWnd = NULL);

Parâmetros

lpDialogTemplate
Aponta para a memória que contém um modelo de caixa de diálogo usado para criar a caixa de diálogo. Este modelo está na forma de uma estrutura DLGTEMPLATE e informações de controle, conforme descrito no SDK do Windows.

pParentWnd
Aponta para o objeto de janela pai do objeto de diálogo (do tipo CWnd). Se for NULL, a janela pai do objeto de diálogo será definida como a janela principal do aplicativo.

lpDialogInit
Aponta para um recurso DLGINIT.

hDialogTemplate
Contém um identificador para a memória global contendo um modelo de caixa de diálogo. Este modelo está na forma de uma DLGTEMPLATE estrutura e dados para cada controle na caixa de diálogo.

Valor de retorno

Diferente de zero se a caixa de diálogo tiver sido criada e inicializada com êxito; caso contrário, 0.

Observações

A CreateIndirect função de membro retorna imediatamente após criar a caixa de diálogo.

Use o estilo WS_VISIBLE no modelo de caixa de diálogo se a caixa de diálogo aparecer quando a janela pai for criada. Caso contrário, você deve ligar ShowWindow para fazer com que ele apareça. Para obter mais informações sobre como você pode especificar outros estilos de caixa de diálogo no modelo, consulte a estrutura DLGTEMPLATE no SDK do Windows.

Use a CWnd::DestroyWindow função para destruir uma caixa de diálogo criada pela CreateIndirect função.

As caixas de diálogo que contêm controles ActiveX exigem informações adicionais fornecidas em um recurso DLGINIT.

CDialog::D oModal

Chame essa função de membro para invocar a caixa de diálogo modal e retornar o resultado da caixa de diálogo quando terminar.

virtual INT_PTR DoModal();

Valor de retorno

Um int valor que especifica o valor do parâmetro nResult que foi passado para a função de membro CDialog::EndDialog , que é usada para fechar a caixa de diálogo. O valor de retorno é -1 se a função não pôde criar a caixa de diálogo ou IDABORT se algum outro erro ocorreu, caso em que a janela de saída conterá informações de erro de GetLastError.

Observações

Esta função de membro lida com toda a interação com o usuário enquanto a caixa de diálogo está ativa. É isso que torna a caixa de diálogo modal; ou seja, o usuário não pode interagir com outras janelas até que a caixa de diálogo seja fechada.

Se o usuário clicar em um dos botões na caixa de diálogo, como OK ou Cancelar, uma função de membro do manipulador de mensagens, como OnOK ou OnCancel, será chamada para tentar fechar a caixa de diálogo. A função de membro padrão OnOK validará e atualizará os dados da caixa de diálogo e fechará a caixa de diálogo com o resultado IDOK, e a função de membro padrão OnCancel fechará a caixa de diálogo com o resultado IDCANCEL sem validar ou atualizar os dados da caixa de diálogo. Você pode substituir essas funções de manipulador de mensagens para alterar seu comportamento.

Exemplo

void CMyDialog::OnMenuShowAboutDialog()
{
   // Construct the dialog box passing the
   // ID of the dialog template resource
   CDialog aboutDlg(IDD_ABOUTBOX);

   // Create and show the dialog box
   INT_PTR nRet = -1;
   nRet = aboutDlg.DoModal();

   // Handle the return value from DoModal
   switch (nRet)
   {
   case -1:
      AfxMessageBox(_T("Dialog box could not be created!"));
      break;
   case IDABORT:
      // Do something
      break;
   case IDOK:
      // Do something
      break;
   case IDCANCEL:
      // Do something
      break;
   default:
      // Do something
      break;
   }
}

CDialog::EndDialog

Chame essa função de membro para encerrar uma caixa de diálogo modal.

void EndDialog(int nResult);

Parâmetros

nResultado
Contém o valor a ser retornado da caixa de diálogo para o chamador de DoModal.

Observações

Essa função de membro retorna nResult como o valor de retorno de DoModal. Você deve usar a função para concluir o EndDialog processamento sempre que uma caixa de diálogo modal for criada.

Você pode chamar EndDialog a qualquer momento, mesmo em OnInitDialog, caso em que você deve fechar a caixa de diálogo antes que ela seja mostrada ou antes que o foco de entrada seja definido.

EndDialog não fecha a caixa de diálogo imediatamente. Em vez disso, ele define um sinalizador que direciona a caixa de diálogo para fechar assim que o manipulador de mensagens atual retorna.

Exemplo

void CMyDialog::OnMenuShowSimpleModal()
{
   CSimpleDlg myDlg;
   INT_PTR nRet = myDlg.DoModal();

   if (nRet == IDOK || nRet == 5)
   {
      AfxMessageBox(_T("Dialog closed successfully"));
   }
}

void CSimpleDlg::OnRButtonUp(UINT nFlags, CPoint point)
{
   UNREFERENCED_PARAMETER(nFlags);
   // Do something

   int nRet = point.x; // Just any value would do!
   EndDialog(nRet);    // This value is returned by DoModal!

   // Do something

   return; // Dialog closed and DoModal returns only here!
}

CDialog::GetDefID

Chame a GetDefID função de membro para obter a ID do controle de botão padrão para uma caixa de diálogo.

DWORD GetDefID() const;

Valor de retorno

Um valor de 32 bits (DWORD). Se o botão padrão tiver um valor de ID, a palavra de ordem alta conterá DC_HASDEFID e a palavra de ordem baixa conterá o valor de ID. Se o botão padrão não tiver um valor de ID, o valor de retorno será 0.

Observações

Este é geralmente um botão OK.

CDialog::GotoDlgCtrl

Move o foco para o controle especificado na caixa de diálogo.

void GotoDlgCtrl(CWnd* pWndCtrl);

Parâmetros

pWndCtrl
Identifica a janela (controle) que deve receber o foco.

Observações

Para obter um ponteiro para o controle (janela filho) para passar como pWndCtrl, chame a CWnd::GetDlgItem função member, que retorna um ponteiro para um objeto CWnd .

Exemplo

Veja o exemplo de CWnd::GetDlgItem.

CDialog::InitModalIndirect

Chame essa função de membro para inicializar um objeto de diálogo modal usando um modelo de caixa de diálogo que você constrói na memória.

BOOL InitModalIndirect(
    LPCDLGTEMPLATE lpDialogTemplate,
    CWnd* pParentWnd = NULL,
    void* lpDialogInit = NULL);

    BOOL InitModalIndirect(
    HGLOBAL hDialogTemplate,
    CWnd* pParentWnd = NULL);

Parâmetros

lpDialogTemplate
Aponta para a memória que contém um modelo de caixa de diálogo usado para criar a caixa de diálogo. Este modelo está na forma de uma estrutura DLGTEMPLATE e informações de controle, conforme descrito no SDK do Windows.

hDialogTemplate
Contém um identificador para a memória global contendo um modelo de caixa de diálogo. Este modelo está na forma de uma DLGTEMPLATE estrutura e dados para cada controle na caixa de diálogo.

pParentWnd
Aponta para o objeto de janela pai ou proprietário (do tipo CWnd) ao qual o objeto de diálogo pertence. Se for NULL, a janela pai do objeto de diálogo será definida como a janela principal do aplicativo.

lpDialogInit
Aponta para um recurso DLGINIT.

Valor de retorno

Diferente de zero se o objeto de diálogo foi criado e inicializado com êxito; caso contrário, 0.

Observações

Para criar uma caixa de diálogo modal indiretamente, primeiro aloque um bloco global de memória e preencha-o com o modelo de caixa de diálogo. Em seguida, chame o construtor vazio CDialog para construir o objeto de caixa de diálogo. Em seguida, chame InitModalIndirect para armazenar seu identificador no modelo de caixa de diálogo na memória. A caixa de diálogo Windows é criada e exibida posteriormente, quando a função de membro DoModal é chamada.

As caixas de diálogo que contêm controles ActiveX exigem informações adicionais fornecidas em um recurso DLGINIT.

CDialog::MapDialogRect

Chamada para converter as unidades de caixa de diálogo de um retângulo em unidades de tela.

void MapDialogRect(LPRECT lpRect) const;

Parâmetros

lpRect
Aponta para uma estrutura RECT ou objeto CRect que contém as coordenadas da caixa de diálogo a serem convertidas.

Observações

As unidades de caixa de diálogo são declaradas em termos da unidade base da caixa de diálogo atual derivada da largura e altura médias dos caracteres na fonte usada para o texto da caixa de diálogo. Uma unidade horizontal é um quarto da unidade de largura da base da caixa de diálogo e uma unidade vertical é um oitavo da unidade de altura da base da caixa de diálogo.

A GetDialogBaseUnits função do Windows retorna informações de tamanho para a fonte do sistema, mas você pode especificar uma fonte diferente para cada caixa de diálogo se usar o estilo DS_SETFONT no arquivo de definição de recurso. A MapDialogRect função do Windows usa a fonte apropriada para essa caixa de diálogo.

A MapDialogRect função de membro substitui as unidades de caixa de diálogo em lpRect por unidades de tela (pixels) para que o retângulo possa ser usado para criar uma caixa de diálogo ou posicionar um controle dentro de uma caixa.

CDialog::NextDlgCtrl

Move o foco para o próximo controle na caixa de diálogo.

void NextDlgCtrl() const;

Observações

Se o foco estiver no último controle na caixa de diálogo, ele será movido para o primeiro controle.

CDialog::OnCancel

A estrutura chama esse método quando o usuário clica em Cancelar ou pressiona a tecla ESC em uma caixa de diálogo modal ou sem moda.

virtual void OnCancel();

Observações

Substitua esse método para executar ações (como restaurar dados antigos) quando um usuário fecha a caixa de diálogo clicando em Cancelar ou pressionando a tecla ESC. O padrão fecha uma caixa de diálogo modal chamando EndDialog e fazendo com que DoModal retorne IDCANCEL.

Se você implementar o botão Cancelar em uma caixa de diálogo sem moderação, deverá substituir o OnCancel método e chamar DestroyWindow dentro dele. Não chame o método de classe base, porque ele chama EndDialog, o que tornará a caixa de diálogo invisível, mas não a destruirá.

Exemplo

void CSimpleDlg::OnCancel()
{
   // TODO: Add extra cleanup here

   // Ensure that you reset all the values back to the
   // ones before modification. This handler is called
   // when the user doesn't want to save the changes.

   if (AfxMessageBox(_T("Are you sure you want to abort the changes?"),
                     MB_YESNO) == IDNO)
   {
      // Give the user a chance if he has unknowingly hit the
      // Cancel button. If he says No, return. Don't reset. If
      // Yes, go ahead and reset the values and close the dialog.
      return;
   }

   m_nMyValue = m_nPrevValue;
   m_pMyString = NULL;

   CDialog::OnCancel();
}

CDialog::OnInitDialog

Este método é chamado em resposta à WM_INITDIALOG mensagem.

virtual BOOL OnInitDialog();

Valor de retorno

Especifica se o aplicativo definiu o foco de entrada para um dos controles na caixa de diálogo. Se OnInitDialog retornar diferente de zero, o Windows define o foco de entrada para o local padrão, o primeiro controle na caixa de diálogo. O aplicativo pode retornar 0 somente se tiver definido explicitamente o foco de entrada para um dos controles na caixa de diálogo.

Observações

O Windows envia a WM_INITDIALOG mensagem para a caixa de diálogo durante as chamadas Create, CreateIndirect ou DoModal , que ocorrem imediatamente antes da caixa de diálogo ser exibida.

Substitua esse método se você deseja executar processamento especial quando a caixa de diálogo é inicializada. Na versão substituída, primeiro chame a classe OnInitDialog base, mas ignore seu valor de retorno. Normalmente, você retornará TRUE do seu método substituído.

O Windows chama a OnInitDialog função usando o procedimento de caixa de diálogo global padrão comum a todas as caixas de diálogo Microsoft Foundation Class Library. Ele não chama essa função através do seu mapa de mensagens e, portanto, você não precisa de uma entrada de mapa de mensagem para esse método.

Exemplo

BOOL CSimpleDlg::OnInitDialog()
{
   CDialog::OnInitDialog();

   // TODO: Add extra initialization here
   m_cMyEdit.SetWindowText(_T("My Name")); // Initialize control values
   m_cMyList.ShowWindow(SW_HIDE);          // Show or hide a control, etc.

   return TRUE; // return TRUE unless you set the focus to a control
   // EXCEPTION: OCX Property Pages should return FALSE
}

CDialog::OnOK

Chamado quando o usuário clica no botão OK (o botão com um ID de IDOK).

virtual void OnOK();

Observações

Substitua esse método para executar ações quando o botão OK estiver ativado. Se a caixa de diálogo incluir validação e troca automática de dados, a implementação padrão desse método validará os dados da caixa de diálogo e atualizará as variáveis apropriadas em seu aplicativo.

Se você implementar o botão OK em uma caixa de diálogo sem moderação, você deve substituir o OnOK método e chamar DestroyWindow dentro dele. Não chame o método de classe base, porque ele chama EndDialog que torna a caixa de diálogo invisível, mas não a destrói.

Exemplo

void CSimpleDlg::OnOK()
{
   // TODO: Add extra validation here

   // Ensure that your UI got the necessary input
   // from the user before closing the dialog. The
   // default OnOK will close this.
   if (m_nMyValue == 0) // Is a particular field still empty?
   {
      // Inform the user that he can't close the dialog without
      // entering the necessary values and don't close the
      // dialog.
      AfxMessageBox(_T("Please enter a value for MyValue"));
      return;
   }

   CDialog::OnOK(); // This will close the dialog and DoModal will return.
}

CDialog::OnSetFont

Especifica a fonte que um controle de caixa de diálogo usará ao desenhar texto.

Virtual void OnSetFont(CFont* pFont);

Parâmetros

pFonte
[em] Especifica um ponteiro para a fonte que será usada como a fonte padrão para todos os controles nessa caixa de diálogo.

Observações

A caixa de diálogo usará a fonte especificada como padrão para todos os seus controles.

O editor de diálogo normalmente define a fonte da caixa de diálogo como parte do recurso de modelo de caixa de diálogo.

CDialog::P revDlgCtrl

Define o foco para o controle anterior na caixa de diálogo.

void PrevDlgCtrl() const;

Observações

Se o foco estiver no primeiro controle na caixa de diálogo, ele será movido para o último controle na caixa.

CDialog::SetDefID

Altera o controle de botão padrão para uma caixa de diálogo.

void SetDefID(UINT nID);

Parâmetros

nID
Especifica a ID do controle de botão que se tornará o padrão.

CDialog::SetHelpID

Define uma ID de ajuda contextual para a caixa de diálogo.

void SetHelpID(UINT nIDR);

Parâmetros

nIDR
Especifica a ID de ajuda sensível ao contexto.

Ver também

Exemplo de DLGCBR32 MFC
MFC Exemplo DLGTEMPL
CWnd Classe
Gráfico de Hierarquia