Classe CFileDialog

Artigo
04/03/2023

Encapsula a caixa de diálogo comum usada para operações de salvamento ou abertura de arquivos.

Sintaxe

class CFileDialog : public CCommonDialog

Membros

Construtores públicos

Nome	Descrição
CFileDialog::CFileDialog	Constrói um objeto `CFileDialog`.

Métodos públicos

Nome	Descrição
CFileDialog::AddCheckButton	Adiciona um botão de seleção à caixa de diálogo.
CFileDialog::AddComboBox	Adiciona uma caixa de combinação à caixa de diálogo.
CFileDialog::AddControlItem	Adiciona um item a um controle de contêiner no diálogo.
CFileDialog::AddEditBox	Adiciona uma caixa de edição ao diálogo.
CFileDialog::AddMenu	Adiciona um menu ao diálogo.
CFileDialog::AddPlace	Sobrecarregado. Adiciona uma pasta à lista de locais disponíveis para o usuário abrir ou salvar itens.
CFileDialog::AddPushButton	Adiciona um botão ao diálogo.
CFileDialog::AddRadioButtonList	Adiciona um grupo de botões de opção ao diálogo.
CFileDialog::AddSeparator	Adiciona um separador ao diálogo.
CFileDialog::AddText	Adiciona conteúdo de texto ao diálogo.
CFileDialog::ApplyOFNToShellDialog	Atualiza o estado de `CFileDialog` para corresponder aos parâmetros e sinalizadores armazenados na variável de membro `m_ofn`.
CFileDialog::DoModal	Exibe a caixa de diálogo e permite que o usuário faça uma seleção.
CFileDialog::EnableOpenDropDown	Habilita uma lista suspensa no botão Abrir ou Salvar no diálogo.
CFileDialog::EndVisualGroup	Interrompe a adição de elementos a um grupo visual no diálogo.
CFileDialog::GetCheckButtonState	Obtém o estado atual de um botão de seleção (caixa de seleção) no diálogo.
CFileDialog::GetControlItemState	Obtém o estado atual de um item em um controle de contêiner encontrado no diálogo.
CFileDialog::GetControlState	Obtém a visibilidade atual e os estados habilitados de determinado controle.
CFileDialog::GetEditBoxText	Obtém o texto atual em um controle de caixa de edição.
CFileDialog::GetFileExt	Retorna a extensão do arquivo selecionado.
CFileDialog::GetFileName	Retorna o nome do arquivo selecionado.
CFileDialog::GetFileTitle	Retorna o título do arquivo selecionado.
CFileDialog::GetFolderPath	Recupera o caminho da pasta ou do diretório aberto no momento para uma caixa de diálogo Abrir ou Salvar como comum no estilo do Explorador.
CFileDialog::GetIFileDialogCustomize	Recupera o objeto COM interno para um objeto `CFileDialog` personalizado.
CFileDialog::GetIFileOpenDialog	Recupera o objeto COM interno para um `CFileDialog` que é usado como uma caixa de diálogo Abrir arquivo.
CFileDialog::GetIFileSaveDialog	Recupera o objeto COM interno para um `CFileDialog` que é usado como uma caixa de diálogo Salvar arquivo.
CFileDialog::GetNextPathName	Retorna o caminho completo do próximo arquivo selecionado.
CFileDialog::GetOFN	Recupera a estrutura `OPENFILENAME` do objeto `CFileDialog`.
CFileDialog::GetPathName	Retorna o caminho completo do arquivo selecionado.
CFileDialog::GetReadOnlyPref	Retorna o status somente leitura do arquivo selecionado.
CFileDialog::GetResult	Obtém a escolha feita pelo usuário no diálogo.
CFileDialog::GetResults	Obtém as escolhas do usuário em um diálogo que permite várias seleções.
CFileDialog::GetSelectedControlItem	Obtém um item específico de controles de contêiner especificados no diálogo.
CFileDialog::GetStartPosition	Retorna a posição do primeiro elemento da lista de nomes de arquivo.
CFileDialog::HideControl	Oculta o controle especificado em uma caixa de diálogo Abrir ou Salvar como comum no estilo do Explorador.
CFileDialog::IsPickFoldersMode	Determina o diálogo atual no modo seletor de pastas.
CFileDialog::MakeProminent	Coloca um controle no diálogo para que ele se destaque em comparação com outros controles adicionados.
CFileDialog::RemoveControlItem	Remove um item de um controle de contêiner no diálogo.
CFileDialog::SetCheckButtonState	Define o estado atual de um botão de seleção (caixa de seleção) no diálogo.
CFileDialog::SetControlItemState	Define o estado atual de um item em um controle de contêiner encontrado no diálogo.
CFileDialog::SetControlItemText	Define o texto de um item de controle. Por exemplo, o texto que acompanha um botão de opção ou um item em um menu.
CFileDialog::SetControlLabel	Define o texto associado a um controle, como texto de botão ou rótulo de caixa de edição.
CFileDialog::SetControlState	Define a visibilidade atual e os estados habilitados de determinado controle.
CFileDialog::SetControlText	Define o texto do controle especificado em uma caixa de diálogo Abrir ou Salvar como comum no estilo do Explorador.
CFileDialog::SetDefExt	Define a extensão de nome de arquivo padrão para uma caixa de diálogo Abrir ou Salvar como comum no estilo do Explorador.
CFileDialog::SetEditBoxText	Define o texto atual em um controle de caixa de edição.
CFileDialog::SetProperties	Fornece um repositório de propriedades que define os valores padrão a serem usados para o item que está sendo salvo.
CFileDialog::SetSelectedControlItem	Define o estado selecionado de um item específico em um grupo de botões de opção ou em uma caixa de combinação encontrada no diálogo.
CFileDialog::SetTemplate	Define o modelo da caixa de diálogo para o objeto `CFileDialog`.
CFileDialog::StartVisualGroup	Declara um grupo visual no diálogo. Chamadas subsequentes a qualquer método "add" adicionam esses elementos a esse grupo.
CFileDialog::UpdateOFNFromShellDialog	Atualiza os dados armazenados na variável de membro `m_ofn` para corresponder ao estado atual da caixa de diálogo do arquivo.

Métodos protegidos

Nome	Descrição
CFileDialog::OnButtonClicked	Chamado quando o botão é clicado.
CFileDialog::OnCheckButtonToggled	Chamado quando a caixa de seleção é marcada/desmarcada.
CFileDialog::OnControlActivating	Chamado quando o controle está ativo.
CFileDialog::OnFileNameChange	Manipula a mensagem WM_NOTIFY CDN_SELCHANGE.
CFileDialog::OnFileNameOK	Valida o nome do arquivo inserido na caixa de diálogo.
CFileDialog::OnFolderChange	Manipula a mensagem WM_NOTIFY CDN_FOLDERCHANGE.
CFileDialog::OnInitDone	Manipula a mensagem WM_NOTIFY CDN_INITDONE.
CFileDialog::OnItemSelected	Chamado quando o item de contêiner está sendo selecionado.
CFileDialog::OnLBSelChangedNotify	Permite que você execute ações personalizadas quando a seleção de arquivo é alterada.
CFileDialog::OnShareViolation	Manipula violações de compartilhamento.
CFileDialog::OnTypeChange	Manipula a mensagem WM_NOTIFY CDN_TYPECHANGE.

Membros de Dados Públicos

Nome	Descrição
CFileDialog::m_ofn	A estrutura `OPENFILENAME` do Windows. Fornece acesso aos parâmetros básicos da caixa de diálogo de arquivo.

Comentários

As caixas de diálogo de arquivo comuns permitem implementar caixas de diálogo de seleção de arquivos, por exemplo, Abrir Arquivo e Salvar como, de uma maneira consistente com os padrões do Windows.

Você pode usar CFileDialog da forma em que se encontra com o construtor fornecido ou pode derivar sua própria classe de caixa de diálogo de CFileDialog e escrever um construtor de acordo com suas necessidades. Em ambos os casos, essas caixas de diálogo se comportarão como caixas de diálogo MFC padrão porque são derivadas da Classe CCommonDialog. CFileDialog depende do arquivo COMMDLG.DLL incluído no Windows.

Tanto a aparência quanto a funcionalidade do CFileDialog com Windows Vista ou versão posterior diferem das versões anteriores do Windows. O padrão CFileDialog usa automaticamente o novo estilo do Windows Vista ou versão posterior sem alterações de código se um programa é compilado e executado no Windows Vista ou versão posterior. Use o parâmetro bVistaStyle no construtor para substituir manualmente essa atualização automática. A exceção à atualização automática envolve caixas de diálogo personalizadas. Elas não serão convertidas no novo estilo. Para saber mais sobre o construtor, confira CFileDialog::CFileDialog.

Observação

O sistema de ID de controle difere no Windows Vista ou versão posterior das versões anteriores do Windows quando você usa um CFileDialog. Você precisa atualizar todas as referências aos controles CFileDialog no código antes de poder portar seu projeto de uma versão anterior do Windows.

Não há suporte a alguns métodos CFileDialog no Windows Vista ou versão posterior. Confira o tópico do método específico para saber se o método tem suporte. Além disso, as seguintes funções herdadas não têm suporte no Windows Vista ou versão posterior:

As mensagens do Windows para a classe CFileDialog variam de acordo com o sistema operacional que você está usando. Por exemplo, o Windows XP não dá suporte a CDialog::OnCancel e CDialog::OnOK para a classe CFileDialog. No entanto, o Windows Vista e os sistemas operacionais posteriores dão suporte a eles. Para saber mais sobre as diferentes mensagens geradas e a ordem em que elas são recebidas, confira CFileDialog Sample: Logging Event Order.

Para usar um objeto CFileDialog, primeiro crie o objeto usando o construtor CFileDialog. Depois que a caixa de diálogo for construída, você poderá definir ou modificar valores na estrutura CFileDialog::m_ofn para inicializar os valores ou estados dos controles da caixa de diálogo. A estrutura m_ofn é do tipo OPENFILENAME. Para mais informações, confira a estrutura OPENFILENAME no SDK do Windows.

Depois de inicializar os controles da caixa de diálogo, chame o método CFileDialog::DoModal para exibir a caixa de diálogo e permitir que o usuário digite o caminho e o nome do arquivo. DoModal retorna se o usuário clicou no botão OK (IDOK) ou Cancelar (IDCANCEL). Se DoModal retornar IDOK, você poderá usar uma das funções de membro público de CFileDialog para recuperar a entrada de informações pelo usuário.

Observação

No Windows Vista ou versão posterior, várias chamadas para IFileDialog::SetFileTypes causam um erro. A segunda chamada para SetFileTypes de qualquer instância de um CFileDialog retornará E_UNEXPECTED no Windows Vista ou posterior. Algumas funções de método CFileDialog chamam SetFileTypes. Por exemplo, duas chamadas para CFileDialog::DoModal da mesma instância de um CFileDialog gera ASSERT.

CFileDialog inclui vários membros protegidos que permitem que você faça o tratamento personalizado de violações de compartilhamento, validação de nome de arquivo e notificação de alteração de caixa de listagem. Esses membros protegidos são funções de retorno de chamada que a maioria dos aplicativos não precisa usar porque o tratamento padrão é executado automaticamente. As entradas de mapa de mensagens para essas funções não são obrigatórias porque são funções virtuais padrão.

É possível usar a função CommDlgExtendedError do Windows para determinar se ocorreu um erro durante a inicialização da caixa de diálogo e para saber mais sobre o erro.

A destruição de objetos CFileDialog é tratada automaticamente. Você não precisa chamar CDialog::EndDialog.

Para permitir que o usuário selecione vários arquivos, defina o sinalizador OFN_ALLOWMULTISELECT antes de chamar DoModal. Você deve fornecer seu próprio buffer de nome de arquivo para acomodar a lista retornada com vários nomes de arquivo. Faça isso substituindo m_ofn.lpstrFile por um ponteiro para um buffer que você alocou, depois de construir o CFileDialog, mas antes de chamar DoModal.

Além disso, você precisa definir m_ofn.nMaxFile usando o número de caracteres no buffer apontado por m_ofn.lpstrFile. Se você definir o número máximo de arquivos a serem selecionados como n, o tamanho do buffer exigido será n * (_MAX_PATH + 1) + 1. O primeiro item retornado no buffer é o caminho para a pasta em que os arquivos foram selecionados. Para o Windows Vista ou caixas de diálogo de estilo posterior, as cadeias de caracteres de nome de diretório e de arquivo são terminadas em nulo, com um caractere nulo extra após o nome do último arquivo. Esse formato permite que as caixas de diálogo no estilo do Explorador retornem nomes de arquivos longos que incluem espaços. Para caixas de diálogo de estilo antigo, as cadeias de caracteres de nome de arquivo e diretório são separadas por espaços e a função usa nomes de arquivo curtos para nomes de arquivo com espaços.

O exemplo a seguir demonstra como usar um buffer para recuperar e listar vários nomes de arquivo.

#define MAX_CFileDialog_FILE_COUNT 99
#define FILE_LIST_BUFFER_SIZE ((MAX_CFileDialog_FILE_COUNT * (MAX_PATH + 1)) + 1)

CString fileName;
wchar_t* p = fileName.GetBuffer( FILE_LIST_BUFFER_SIZE );
CFileDialog dlgFile(TRUE);
OPENFILENAME& ofn = dlgFile.GetOFN( );
ofn.Flags |= OFN_ALLOWMULTISELECT;
ofn.lpstrFile = p;
ofn.nMaxFile = FILE_LIST_BUFFER_SIZE;

dlgFile.DoModal();
fileName.ReleaseBuffer();

wchar_t* pBufEnd = p + FILE_LIST_BUFFER_SIZE - 2;
wchar_t* start = p;
while( ( p < pBufEnd ) && ( *p ) )
  p++;
if( p > start )
{
  _tprintf(_T("Path to folder where files were selected:  %s\r\n\r\n"), start );
  p++;

  int fileCount = 1;
  while( ( p < pBufEnd ) && ( *p ) )
  {
    start = p;
    while( ( p < pBufEnd ) && ( *p ) )
      p++;
    if( p > start )
      _tprintf(_T("%2d. %s\r\n"), fileCount, start );
    p++;
    fileCount++;
  }
}

Para alterar o tamanho do buffer em resposta ao usuário que seleciona vários nomes de arquivo, você deve derivar uma nova classe CFileDialog e substituir o método CFileDialog::OnFileNameChange.

Se você derivar uma nova classe de CFileDialog, poderá usar um mapa de mensagens para lidar com qualquer mensagem. Para estender o tratamento de mensagens padrão, derive uma classe de CFileDialog, adicione um mapa de mensagens à nova classe e forneça funções de membro para as novas mensagens. Você não precisa fornecer uma função de gancho para personalizar a caixa de diálogo.

Para personalizar a caixa de diálogo, derive uma classe de CFileDialog, forneça um modelo de caixa de diálogo personalizado e adicione um mapa de mensagem para processar as mensagens de notificação dos controles estendidos. Transmita mensagens não processadas à classe base. Você não precisa personalizar a função de gancho.

Quando você estiver usando o estilo do Windows Vista ou posterior de CFileDialog, não será possível usar mapas de mensagens e modelos de caixa de diálogo. Você precisará usar as interfaces COM para uma funcionalidade semelhante.

Para saber mais sobre como usar CFileDialog, confira Classes comuns de diálogo.

Hierarquia de herança

CFileDialog

Requisitos

Cabeçalho: afxdlgs.h

CFileDialog::AddCheckButton

Adiciona um botão de seleção à caixa de diálogo.

HRESULT AddCheckButton(
    DWORD dwIDCtl,
    const CString& strLabel,
    BOOL bChecked);

Parâmetros

dwIDCtl
A ID do botão de seleção a ser adicionado.

strLabel
O nome do botão de seleção.

bChecked
Um booliano que indica o estado atual do botão de seleção. TRUE se marcado; caso contrário, FALSE

Comentários

CFileDialog::AddComboBox

Adiciona uma caixa de combinação à caixa de diálogo.

HRESULT AddComboBox(DWORD dwIDCtl);

Parâmetros

dwIDCtl
A ID da caixa de combinação a ser adicionada.

Comentários

CFileDialog::AddControlItem

Adiciona um item a um controle de contêiner no diálogo.

HRESULT AddControlItem(
    DWORD dwIDCtl,
    DWORD dwIDItem,
    const CString& strLabel);

Parâmetros

dwIDCtl
A ID do controle de contêiner ao qual adicionar o item.

dwIDItem
A ID do item.

strLabel
Texto do item.

Comentários

CFileDialog::AddEditBox

Adiciona uma caixa de edição ao diálogo.

HRESULT AddEditBox(
    DWORD dwIDCtl,
    const CString& strText);

Parâmetros

dwIDCtl
A ID da caixa de edição a ser adicionada.

strText
O nome da caixa de edição.

Comentários

CFileDialog::AddMenu

Adiciona um menu ao diálogo.

HRESULT AddMenu(
    DWORD dwIDCtl,
    const CString& strLabel);

Parâmetros

dwIDCtl
A ID do menu a ser adicionado.

strLabel
O nome do menu.

Comentários

CFileDialog::AddPlace

Adiciona uma pasta à lista de locais disponíveis para o usuário abrir ou salvar itens.

void AddPlace(
    LPCWSTR lpszFolder,
    FDAP fdap = FDAP_TOP) throw();

void AddPlace(
    IShellItem* psi,
    FDAP fdap = FDAP_TOP) throw();

Parâmetros

lpszFolder
Um caminho para a pasta a ser disponibilizada para o usuário. Isso só pode ser uma pasta.

fdap
Especifica onde a pasta é colocada na lista.

Psi
Um ponteiro para um IShellItem que representa a pasta a ser disponibilizada para o usuário. Isso só pode ser uma pasta.

Comentários

CFileDialog::AddPushButton

Adiciona um botão ao diálogo.

HRESULT AddPushButton(
    DWORD dwIDCtl,
    const CString& strLabel);

Parâmetros

dwIDCtl
A ID do botão a ser adicionado.

strLabel
O nome do botão.

Comentários

CFileDialog::AddRadioButtonList

Adiciona um grupo de botões de opção ao diálogo.

HRESULT AddRadioButtonList(DWORD dwIDCtl);

Parâmetros

dwIDCtl
A ID do grupo de botões de opção a ser adicionado.

Comentários

CFileDialog::AddSeparator

Adiciona um separador ao diálogo.

HRESULT AddSeparator(DWORD dwIDCtl);

Parâmetros

dwIDCtl
A ID da adição do separador.

Comentários

CFileDialog::AddText

Adiciona texto ao diálogo.

HRESULT AddText(
    DWORD dwIDCtl,
    const CString& strText);

Parâmetros

dwIDCtl
A ID do texto a ser adicionado.

strText
O nome do texto.

Comentários

CFileDialog::ApplyOFNToShellDialog

Atualiza o estado atual do CFileDialog com base nos valores armazenados na estrutura de dados m_ofn.

void ApplyOFNToShellDialog();

Comentários

Nas versões do Windows antes do Windows Vista, a estrutura de dados OPENFILENAME do membro era sincronizada continuamente com o estado do CFileDialog. Todas as alterações na variável de membro m_ofn foram refletidas imediatamente no estado da caixa de diálogo. Além disso, todas as alterações no estado da caixa de diálogo atualizam imediatamente a variável de membro m_ofn.

No Windows Vista ou posterior, os valores na variável de membro m_ofn e no estado do CFileDialog não têm garantia de serem sincronizados. Essa função força o estado do CFileDialog a ser atualizado para corresponder à estrutura de m_ofn. O Windows chama essa função automaticamente durante CFileDialog::DoModal.

Para saber mais sobre como usar a classe CFileDialog no Windows Vista ou posterior, confira Classe CFileDialog.

Exemplo

Confira o exemplo de CFileDialog::UpdateOFNFromShellDialog.

CFileDialog::CFileDialog

Chame essa função para construir uma caixa de diálogo de arquivo padrão do Windows.

explicit CFileDialog(
    BOOL bOpenFileDialog,
    LPCTSTR lpszDefExt = NULL,
    LPCTSTR lpszFileName = NULL,
    DWORD dwFlags = OFN_HIDEREADONLY | OFN_OVERWRITEPROMPT,
    LPCTSTR lpszFilter = NULL,
    CWnd* pParentWnd = NULL,
    DWORD dwSize = 0,
    BOOL bVistaStyle = TRUE);

Parâmetros

bOpenFileDialog
[in] O parâmetro que especifica o tipo de caixa de diálogo a ser criada. Defina-o como TRUE para construir uma caixa de diálogo Abrir Arquivo. Defina-o como FALSE para construir uma caixa de diálogo Salvar Arquivo Como.

lpszDefExt
[in] A extensão de nome de arquivo padrão. Se o usuário não incluir uma extensão conhecida (uma que tenha uma associação no computador do usuário) na caixa Nome do arquivo, a extensão especificada por lpszDefExt será automaticamente acrescentada ao nome do arquivo. Se esse parâmetro for NULL, nenhuma extensão será acrescentada.

lpszFileName
[in] O nome do arquivo inicial que aparece na caixa Nome do arquivo. Se NULL, nenhum nome de arquivo inicial será exibido.

dwFlags
[in] Uma combinação de um ou mais sinalizadores que você pode usar para personalizar a caixa de diálogo. Para obter uma descrição desses sinalizadores, confira a estrutura OPENFILENAME no SDK do Windows. Se você modificar o membro da estrutura m_ofn.Flags, use um operador bit a bit OR em suas alterações para manter o comportamento padrão intacto.

lpszFilter
[in] Uma série de pares de cadeia de caracteres que especificam filtros que você pode aplicar ao arquivo. Se você especificar filtros de arquivo, somente arquivos que correspondem aos critérios de filtro serão exibidos na lista Arquivos. Confira a seção Comentários para saber mais sobre como trabalhar com filtros de arquivo.

pParentWnd
[in] Um ponteiro para a janela pai ou de proprietário da caixa de diálogo do arquivo.

dwSize
[in] O tamanho da estrutura OPENFILENAME. Esse valor depende da versão do sistema operacional. O MFC usou esse parâmetro para determinar o tipo apropriado de caixa de diálogo a ser criada. O tamanho padrão 0 significa que o código MFC determinará o tamanho correto da caixa de diálogo a ser usada com base na versão do sistema operacional na qual o programa é executado.

bVistaStyle
[in] Nota Esse parâmetro está disponível no Visual Studio 2008 e versão posterior e faz com que o diálogo de novo estilo seja usado somente se você estiver executando no Windows Vista ou posterior.

O parâmetro que especifica o estilo do diálogo do arquivo. Defina-o como TRUE para usar os novos diálogos de arquivo de estilo Vista. Caso contrário, o estilo antigo de caixas de diálogo será usado. Confira a seção Comentários para saber mais sobre como executar no Vista.

Comentários

Uma caixa de diálogo Abrir Arquivo ou Salvar Arquivo Como é construída, dependendo do valor de bOpenFileDialog.

Especificar uma extensão padrão usando lpszDefExt pode não produzir o comportamento esperado, pois raramente é previsível quais extensões têm associações de arquivo no computador do usuário. Se você precisar de mais controle sobre a anexação de uma extensão padrão, poderá derivar sua própria classe de CFileDialog e substituir o método CFileDialog::OnFileNameOK para executar sua própria manipulação de extensão.

Para permitir que o usuário selecione vários arquivos, defina o sinalizador OFN_ALLOWMULTISELECT antes de chamar DoModal. Você deve fornecer seu próprio buffer de nome de arquivo para armazenar a lista retornada com vários nomes de arquivo. Faça isso substituindo m_ofn.lpstrFile por um ponteiro para um buffer que você alocou, depois de construir o CFileDialog, mas antes de chamar DoModal. Além disso, você precisa definir m_ofn.nMaxFile usando o número de caracteres no buffer apontado por m_ofn.lpstrFile. Se você definir o número máximo de arquivos a serem selecionados como n, o tamanho do buffer exigido será n*(_MAX_PATH + 1) + 1. Por exemplo:

#define MAX_CFileDialog_FILE_COUNT 99
#define FILE_LIST_BUFFER_SIZE ((MAX_CFileDialog_FILE_COUNT * (MAX_PATH + 1)) + 1)

CString fileName;
wchar_t* p = fileName.GetBuffer( FILE_LIST_BUFFER_SIZE );
CFileDialog dlgFile(TRUE);
OPENFILENAME& ofn = dlgFile.GetOFN( );
ofn.Flags |= OFN_ALLOWMULTISELECT;
ofn.lpstrFile = p;
ofn.nMaxFile = FILE_LIST_BUFFER_SIZE;

dlgFile.DoModal();
fileName.ReleaseBuffer();

wchar_t* pBufEnd = p + FILE_LIST_BUFFER_SIZE - 2;
wchar_t* start = p;
while( ( p < pBufEnd ) && ( *p ) )
  p++;
if( p > start )
{
  _tprintf(_T("Path to folder where files were selected:  %s\r\n\r\n"), start );
  p++;

  int fileCount = 1;
  while( ( p < pBufEnd ) && ( *p ) )
  {
    start = p;
    while( ( p < pBufEnd ) && ( *p ) )
      p++;
    if( p > start )
      _tprintf(_T("%2d. %s\r\n"), fileCount, start );
    p++;
    fileCount++;
  }
}

Para permitir que o usuário redimensione uma caixa de diálogo no estilo do Explorador usando o mouse ou o teclado, defina o sinalizador OFN_ENABLESIZING. A configuração desse sinalizador só será necessária se você fornecer um procedimento de gancho ou um modelo personalizado. O sinalizador funciona apenas com uma caixa de diálogo no estilo do Explorador; caixas de diálogo de estilo antigo não podem ser redimensionadas.

O parâmetro lpszFilter é usado para determinar o tipo de nome de arquivo que um arquivo precisa ter para ser exibido na lista de arquivos. A primeira cadeia de caracteres no par de cadeias de caracteres descreve o filtro; a segunda cadeia de caracteres indica a extensão de nome de arquivo a ser usada. Várias extensões podem ser especificadas usando um ponto e vírgula (o caractere ';') como delimitador. A cadeia de caracteres termina com dois caracteres de barra vertical (||), seguidos por um caractere NULL. Você também pode usar um objeto CString para esse parâmetro.

Por exemplo, o Microsoft Excel permite que os usuários abram arquivos com extensões .xlc (gráfico) ou .xls (planilha), entre outros. O filtro para Excel pode ser gravado como:

static TCHAR BASED_CODE szFilter[] = _T("Chart Files (*.xlc)|*.xlc|")
   _T("Worksheet Files (*.xls)|*.xls|Data Files (*.xlc;*.xls)|")
   _T("*.xlc; *.xls|All Files (*.*)|*.*||");

No entanto, se você planeja usar essa cadeia de caracteres para atualizar diretamente a estrutura OPENFILENAME, deve delimitar suas cadeias de caracteres com o caractere nulo, '\0', em vez das barras verticais ('|').

O parâmetro bVistaStyle é aplicável somente quando executado no Windows Vista ou posterior. Em versões anteriores do Windows, esse parâmetro é ignorado. Se bVistaStyle estiver definido como TRUE, quando você compilar um programa com o Visual Studio 2008 ou versão posterior, o novo Diálogo de Arquivo de estilo Vista será usado. Caso contrário, o Diálogo de Arquivo de estilo MFC anterior será usado.

Não há suporte a modelos de diálogo em diálogos com base em bVistaStyle

Exemplo

Confira o exemplo de CFileDialog::DoModal.

CFileDialog::DoModal

Chame essa função para exibir a caixa de diálogo de arquivo comum do Windows e permitir que o usuário navegue por arquivos e diretórios e insira um nome de arquivo.

virtual INT_PTR DoModal();

Valor de retorno

IDOK ou IDCANCEL. Se IDCANCEL for retornado, chame a função CommDlgExtendedError do Windows para determinar se ocorreu um erro.

IDOK e IDCANCEL são constantes que indicam se o usuário selecionou o botão OK ou Cancelar.

Comentários

Se você quiser inicializar as várias opções de caixa de diálogo de arquivo definindo membros da estrutura m_ofn, faça isso antes de chamar DoModal, mas depois que o objeto de diálogo for construído.

Por exemplo, se você quiser permitir que o usuário selecione vários arquivos, defina o sinalizador OFN_ALLOWMULTISELECT antes de chamar DoModal, conforme mostrado no exemplo de código neste tópico.

Quando o usuário clica nos botões OK ou Cancelar da caixa de diálogo ou seleciona a opção Fechar no menu de controle da caixa de diálogo, o controle é retornado ao seu aplicativo. Em seguida, você pode chamar outras funções de membro para recuperar as configurações ou informações que o usuário inseriu na caixa de diálogo.

DoModal é uma função virtual substituída na classe CDialog.

Exemplo

void CMyClass::OnFileOpen()
{
   // szFilters is a text string that includes two file name filters:
   // "*.my" for "MyType Files" and "*.*' for "All Files."
   TCHAR szFilters[]= _T("MyType Files (*.my)|*.my|All Files (*.*)|*.*||");

   // Create an Open dialog; the default file name extension is ".my".
   CFileDialog fileDlg(TRUE, _T("my"), _T("*.my"),
      OFN_FILEMUSTEXIST | OFN_HIDEREADONLY, szFilters);
   
   // Display the file dialog. When user clicks OK, fileDlg.DoModal() 
   // returns IDOK.
   if(fileDlg.DoModal() == IDOK)
   {
      CString pathName = fileDlg.GetPathName();
   
      // Implement opening and reading file in here.

      //Change the window's title to the opened file's title.
      CString fileName = fileDlg.GetFileTitle();
   
      SetWindowText(fileName);
   }
}

CFileDialog::EnableOpenDropDown

Habilita uma lista suspensa no botão Abrir ou Salvar no diálogo.

HRESULT EnableOpenDropDown(DWORD dwIDCtl);

Parâmetros

dwIDCtl
A ID da lista suspensa.

Comentários

CFileDialog::EndVisualGroup

Interrompe a adição de elementos a um grupo visual no diálogo.

HRESULT EndVisualGroup();

Valor de retorno

Retorna S_OK se tiver êxito; caso contrário, um valor de erro.

Comentários

CFileDialog::GetCheckButtonState

Recupera o estado atual de um botão de seleção (caixa de seleção) no diálogo.

HRESULT GetCheckButtonState(
    DWORD dwIDCtl,
    BOOL& bChecked);

Parâmetros

dwIDCtl
A ID da caixa de seleção.

bChecked
O estado da caixa de seleção. TRUE indica marcado; FALSE indica desmarcado.

Comentários

CFileDialog::GetControlItemState

Recupera o estado atual de um item em um controle de contêiner encontrado no diálogo.

HRESULT GetControlItemState(
    DWORD dwIDCtl,
    DWORD dwIDItem,
    CDCONTROLSTATEF& dwState);

Parâmetros

dwIDCtl
A ID do controle de contêiner.

dwIDItem
A ID do item.

dwState
Uma referência a uma variável que recebe um de mais valores da enumeração CDCONTROLSTATE que indica o estado atual do controle.

Comentários

CFileDialog::GetControlState

Recupera a visibilidade atual e os estados habilitados de determinado controle.

HRESULT GetControlState(
    DWORD dwIDCtl,
    CDCONTROLSTATEF& dwState);

Parâmetros

dwIDCtl
O ID do controle.

dwState
Uma referência a uma variável que recebe um ou mais valores da enumeração CDCONTROLSTATE que indica o estado atual do controle.

Comentários

CFileDialog::GetEditBoxText

Recupera o texto atual em um controle de caixa de edição.

HRESULT GetEditBoxText(
    DWORD dwIDCtl,
    CString& strText);

Parâmetros

dwIDCtl
A ID da caixa de edição.

strText
O valor do texto.

Comentários

CFileDialog::GetFileExt

Chame essa função para recuperar a extensão do nome de arquivo inserido na caixa de diálogo.

CString GetFileExt() const;

Valor de retorno

A extensão do nome do arquivo.

Comentários

Por exemplo, se o nome do arquivo inserido for DATA.TXT, GetFileExt retornará "TXT".

Se m_ofn.Flags tiver o sinalizador OFN_ALLOWMULTISELECT definido, essa cadeia de caracteres conterá uma sequência de cadeias de caracteres terminadas em nulo, sendo a primeira cadeia de caracteres o caminho de diretório do grupo de arquivos selecionado, seguido pelos nomes de todos os arquivos selecionados pelo usuário. Para recuperar nomes de caminho de arquivo, use as funções de membro GetStartPosition e GetNextPathName.

CFileDialog::GetFileName

Chame essa função para recuperar o nome do arquivo inserido na caixa de diálogo.

CString GetFileName() const;

Valor de retorno

O nome do arquivo.

Comentários

O nome do arquivo inclui o prefixo e a extensão. Por exemplo, GetFileName retornará "TEXT.DAT" para o arquivo C:\FILES\TEXT.DAT.

Se m_ofn.Flags tiver o sinalizador OFN_ALLOWMULTISELECT definido, você deverá chamar GetStartPosition e GetNextPathName para recuperar um nome de caminho de arquivo.

CFileDialog::GetFileTitle

Chame essa função para recuperar o título do arquivo inserido na caixa de diálogo.

CString GetFileTitle() const;

Valor de retorno

O título do arquivo.

Comentários

O título do arquivo inclui apenas seu prefixo, sem o caminho ou a extensão. Por exemplo, GetFileTitle retornará "TEXT" para o arquivo C:\FILES\TEXT.DAT.

Se m_ofn.Flags tiver o sinalizador OFN_ALLOWMULTISELECT definido, essa cadeia de caracteres conterá uma sequência de cadeias de caracteres terminadas em nulo, sendo a primeira cadeia de caracteres o caminho de diretório do grupo de arquivos selecionado, seguido pelos nomes de todos os arquivos selecionados pelo usuário. Por esse motivo, use as funções de membro GetStartPosition e GetNextPathName para recuperar o próximo nome de arquivo na lista.

Exemplo

Confira o exemplo de CFileDialog::DoModal.

CFileDialog::GetFolderPath

Chame essa função de membro para recuperar o caminho da pasta ou diretório aberto no momento para uma caixa de diálogo Abrir ou Salvar como comum no estilo do Explorador.

CString GetFolderPath() const;

Valor de retorno

Um objeto CString que contém a pasta ou o diretório aberto no momento.

Comentários

A caixa de diálogo precisa ter sido criada com o estilo OFN_EXPLORER; caso contrário, o método falhará com uma instrução.

Você só pode chamar esse método enquanto a caixa de diálogo está sendo exibida. Depois que a caixa de diálogo for fechada, essa função não operará mais e o método falhará com uma instrução assert.

CFileDialog::GetIFileDialogCustomize

Recupera um ponteiro para o objeto COM interno de determinado CFileDialog.

IFileDialogCustomize* GetIFileDialogCustomize();

Valor de retorno

O ponteiro para o objeto COM interno do CFileDialog. É sua responsabilidade liberar esse ponteiro adequadamente.

Comentários

Use essa função somente no Windows Vista ou posterior com um objeto que tenha bVistaStyle definido como TRUE. Se você usar essa função quando bVistaStyle for FALSE, ela retornará NULL no modo de versão e lançará uma declaração no modo de depuração.

Para saber mais sobre a interface IFileDialogCustomize, confira IFileDialogCustomize.

Exemplo

Este exemplo recupera o objeto COM interno. Para executar este exemplo de código, você precisará compilá-lo no Windows Vista ou posterior.

// Get the interface pointer
IFileDialogCustomize *customDlgPtr = m_myFileDialogPtr->GetIFileDialogCustomize();

// Make sure that it is not null
if (customDlgPtr != NULL)
{
   //
   // Perform any interface functionality here
   //

   // Release the pointer
   customDlgPtr->Release();
}

CFileDialog::GetIFileOpenDialog

Recupera um ponteiro para o objeto COM interno de determinado CFileDialog.

IFileOpenDialog* GetIFileOpenDialog();

Valor de retorno

O ponteiro para o objeto COM interno do CFileDialog. É sua responsabilidade liberar esse ponteiro adequadamente.

Comentários

Use essa função somente no Windows Vista ou posterior com um objeto que tenha bVistaStyle definido como TRUE. Essa função retornará NULL se CFileDialog não for uma caixa de diálogo Abrir ou se bVistaStyle estiver definido como FALSE. Nesse caso final, a função retorna apenas NULL no modo de versão; no modo de depuração, ela gerará uma instrução assert.

Para saber mais sobre a interface IFileOpenDialog, confira IFileOpenDialog.

Exemplo

Este exemplo recupera o objeto COM interno. Para executar esse código, você precisará compilá-lo no Windows Vista ou posterior.

// Get the interface pointer
IFileOpenDialog * openDlgPtr = m_myFileDialogPtr->GetIFileOpenDialog();

// Make sure that it is not null
if ( openDlgPtr != NULL )
{
    //
    // Perform any interface functionality here
    //

    // Release the pointer
    openDlgPtr->Release();
}

CFileDialog::GetIFileSaveDialog

Recupera um ponteiro para o objeto COM interno de determinado CFileDialog.

IFileSaveDialog* GetIFileSaveDialog();

Valor de retorno

O ponteiro para o objeto COM interno do CFileDialog. É sua responsabilidade liberar esse ponteiro adequadamente.

Comentários

Use essa função somente no Windows Vista ou posterior com um objeto que tenha bVistaStyle definido como TRUE. Essa função retornará NULL se CFileDialog não for uma caixa de diálogo Salvar ou se bVistaStyle estiver definido como FALSE. Nesse caso final, a função retorna apenas NULL no modo de versão; no modo de depuração, ela gerará uma instrução assert.

Para saber mais sobre a interface IFileSaveDialog, confira IFileSaveDialog.

Exemplo

Este exemplo recupera o objeto COM interno. Para executar este exemplo de código, você precisará compilá-lo no Windows Vista ou posterior.

// Get the interface pointer
IFileSaveDialog *saveDlgPtr = m_myFileDialogPtr->GetIFileSaveDialog();

// Make sure that it is not null
if (saveDlgPtr != NULL)
{
   //
   // Perform any interface functionality here
   //

   // Release the pointer
   saveDlgPtr->Release();
}

CFileDialog::GetNextPathName

Chame essa função para recuperar o próximo nome de arquivo do grupo selecionado na caixa de diálogo.

CString GetNextPathName(POSITION& pos) const;

Parâmetros

pos
Uma referência a um valor POSITION retornado por uma chamada de função GetNextPathName ou GetStartPosition anterior. NULL se o final da lista tiver sido alcançado.

Valor de retorno

O caminho completo do arquivo.

Comentários

O caminho do nome do arquivo inclui o título do arquivo mais o caminho de diretório inteiro. Por exemplo, GetNextPathName retornará "C:\FILES\TEXT.DAT" para o arquivo C:\FILES\TEXT.DAT. Você poderá usar GetNextPathName em um loop de iteração para frente se estabelecer a posição inicial com uma chamada para GetStartPosition.

Se a seleção consistir em apenas um arquivo, esse nome de arquivo será retornado.

CFileDialog::GetOFN

Recupera a estrutura OPENFILENAME associada.

const OPENFILENAME& GetOFN() const;

OPENFILENAME& GetOFN();

Valor de retorno

Uma estrutura OPENFILENAME.

Comentários

Use a segunda versão dessa função para inicializar a aparência de uma caixa de diálogo Abrir Arquivo ou Salvar Arquivo Como depois que ela for construída, mas antes de ser exibida com a função de membro DoModal. Por exemplo, você pode definir o membro lpstrTitle de m_ofn como a legenda que deseja que a caixa de diálogo tenha.

CFileDialog::GetPathName

Chame essa função para recuperar o caminho completo do arquivo inserido na caixa de diálogo.

CString GetPathName() const;

Valor de retorno

O caminho completo do arquivo.

Comentários

O caminho do nome do arquivo inclui o título do arquivo mais o caminho de diretório inteiro. Por exemplo, GetPathName retornará "C:\FILES\TEXT.DAT" para o arquivo C:\FILES\TEXT.DAT.

Se m_ofn.Flags tiver o sinalizador OFN_ALLOWMULTISELECT definido, essa cadeia de caracteres conterá uma sequência de cadeias de caracteres terminadas em nulo, sendo a primeira cadeia de caracteres o caminho de diretório do grupo de arquivos selecionado, seguido pelos nomes de todos os arquivos selecionados pelo usuário. Por esse motivo, use as funções de membro GetStartPosition e GetNextPathName para recuperar o próximo nome de arquivo na lista.

Exemplo

Confira o exemplo de CFileDialog::DoModal.

CFileDialog::GetReadOnlyPref

Chame essa função para determinar se a caixa de seleção Somente Leitura foi marcada nas caixas de diálogo Abrir e Salvar Arquivo Como padrão do Windows.

BOOL GetReadOnlyPref() const;

Valor de retorno

Diferente de zero se a caixa de seleção Somente Leitura na caixa de diálogo estiver selecionada; caso contrário, 0.

Comentários

Você pode ocultar a caixa de seleção Somente Leitura definindo o estilo OFN_HIDEREADONLY no construtor CFileDialog.

Observação

O Windows Vista ou objetos CFileDialog de estilos posteriores não dão suporte a essa função. A tentativa de usar essa função em um estilo de CFileDialog do Windows Vista ou posterior gerará CNotSupportedException.

CFileDialog::GetResult

Recupera a escolha feita pelo usuário no diálogo.

IShellItem* GetResult() throw();

Valor de retorno

Um ponteiro para um IShellItem que representa a escolha do usuário.

Comentários

CFileDialog::GetResults

Recupera as escolhas do usuário em um diálogo que permite várias seleções.

IShellItemArray* GetResults() throw();

Valor de retorno

Um ponteiro para um IShellItemArray por meio do qual os itens selecionados no diálogo podem ser acessados.

Comentários

CFileDialog::GetSelectedControlItem

Recupera um item específico do controle de contêiner especificado na caixa de diálogo.

HRESULT GetSelectedControlItem(
    DWORD dwIDCtl,
    DWORD& dwIDItem);

Parâmetros

dwIDCtl
A ID do controle de contêiner.

dwIDItem
A ID do item que o usuário selecionou no controle.

Comentários

CFileDialog::GetStartPosition

Chame essa função de membro para recuperar a posição do primeiro nome de caminho de arquivo na lista se m_ofn.Flags tiver o sinalizador OFN_ALLOWMULTISELECT definido.

POSITION GetStartPosition() const;

Valor de retorno

Um valor POSITION que pode ser usado para iteração; NULL se a lista estiver vazia.

CFileDialog::HideControl

Chame essa função de membro para ocultar o controle especificado em uma caixa de diálogo Abrir ou Salvar como comum no estilo do Explorador.

void HideControl(int nID);

Parâmetros

Nid
A ID do controle a ser ocultado.

Comentários

A caixa de diálogo precisa ter sido criada com o estilo OFN_EXPLORER; caso contrário, a função falhará com uma instrução assert.

CFileDialog::IsPickFoldersMode

Determina se o diálogo atual está no modo seletor de pastas.

BOOL IsPickFoldersMode() const;

Valor de retorno

TRUE se o diálogo estiver no modo seletor de pastas; caso contrário, FALSE.

Comentários

CFileDialog::m_ofn

m_ofn é uma estrutura de tipo OPENFILENAME. Os dados nessa estrutura representam o estado atual do CFileDialog.

Comentários

Use essa estrutura para inicializar a aparência de uma caixa de diálogo Abrir Arquivo ou Salvar Arquivo Como depois de construí-la, mas antes de exibi-la com o método DoModal. Por exemplo, você pode definir o membro lpstrTitle de m_ofn como a legenda que deseja que a caixa de diálogo tenha.

Com o estilo do Windows Vista ou posterior do CFileDialog, não é garantido que m_ofn sempre corresponda ao estado da caixa de diálogo. Ele é sincronizado com a caixa de diálogo em versões anteriores do Windows. Confira CFileDialog::ApplyOFNToShellDialog e CFileDialog::UpdateOFNFromShellDialog para saber mais sobre como sincronizar a estrutura m_ofn e o estado CFileDialog no Windows Vista ou posterior.

Os diálogos de arquivo de estilo do Windows Vista ou posterior não dão suporte a determinados membros e sinalizadores do CFileDialog. Por conta disso, eles não terão efeito.

Veja abaixo uma lista dos membros que não têm suporte no Windows Vista ou posterior:

lpstrCustomFilter
lpstrInitialDir
lCustData
lpfnHook
lpTemplateName

Não há suporte aos sinalizadores abaixo e, portanto, eles não têm efeito quando você usa o estilo do Windows Vista ou posterior de CFileDialog:

OFN_ENABLEHOOK
OFN_ENABLEINCLUDENOTIFY
OFN_ENABLETEMPLATE
OFN_ENABLETEMPLATEHANDLE
OFN_EXPLORER
OFN_EXTENSIONDIFFERENT
OFN_HIDEREADONLY
OFN_LONGNAMES – sempre ativado no Windows Vista ou posterior
OFN_NOLONGNAMES – sempre desativado no Windows Vista ou posterior
OFN_NONETWORKBUTTON – sempre ativado no Windows Vista ou posterior
OFN_READONLY
OFN_SHOWHELP

Para saber mais sobre essa estrutura, confira a estrutura OPENFILENAME no SDK do Windows.

CFileDialog::MakeProminent

Coloca um controle no diálogo para que ele se destaque em comparação com outros controles.

HRESULT MakeProminent(DWORD dwIDCtl);

Parâmetros

dwIDCtl
O ID do controle.

Comentários

CFileDialog::OnButtonClicked

Chamado quando o botão é clicado.

virtual void OnButtonClicked(DWORD dwIDCtl);

Parâmetros

dwIDCtl
A ID do botão.

Comentários

CFileDialog::OnCheckButtonToggled

Chamado quando a caixa de seleção é marcada ou desmarcada.

virtual void OnCheckButtonToggled(
    DWORD dwIDCtl,
    BOOL bChecked);

Parâmetros

dwIDCtl
A ID da caixa de seleção.

bChecked
Marcado ou desmarcado.

Comentários

CFileDialog::OnControlActivating

Ocorre quando o controle é ativado.

virtual void OnControlActivating(DWORD dwIDCtl);

Parâmetros

dwIDCtl
O ID do controle.

Comentários

CFileDialog::OnFileNameChange

Substitua esse método se você quiser manipular a mensagem de WM_NOTIFY CDN_SELCHANGE.

virtual void OnFileNameChange();

Comentários

O sistema envia a mensagem CDN_SELCHANGE quando o usuário seleciona um novo arquivo ou pasta na lista de arquivos da caixa de diálogo Abrir ou Salvar como. Substitua esse método se você quer executar alguma ação em resposta a essa mensagem.

O sistema enviará essa mensagem somente se a caixa de diálogo tiver sido criada com o sinalizador OFN_EXPLORER ativado. Para saber mais sobre a notificação, confira CDN_SELCHANGE. Para saber mais sobre o sinalizador OFN_EXPLORER, confira a estrutura OPENFILENAME e Caixas de diálogo Abrir e Salvar como.

CFileDialog::OnFileNameOK

Substitua essa função somente se você quiser fornecer validação personalizada de nomes de arquivo que são inseridos em uma caixa de diálogo de arquivo comum.

virtual BOOL OnFileNameOK();

Valor de retorno

1 se o nome do arquivo não for um nome de arquivo válido; caso contrário, 0.

Comentários

Essa função permite rejeitar um nome de arquivo por algum motivo específico do aplicativo. Normalmente, você não precisa usar essa função porque a estrutura fornece validação padrão de nomes de arquivo e exibe uma caixa de mensagem se um nome de arquivo inválido é inserido.

Se 1 for retornado, a caixa de diálogo permanecerá exibida para o usuário inserir outro nome de arquivo. O procedimento de diálogo ignorará o diálogo se o retorno for 0. Outros valores retornados diferentes de zero estão reservados no momento e não devem ser usados.

CFileDialog::OnFolderChange

Substitua essa função para lidar com a mensagem WM_NOTIFYCDN_FOLDERCHANGE.

virtual void OnFolderChange();

Comentários

A mensagem de notificação é enviada quando uma nova pasta é aberta na caixa de diálogo Abrir ou Salvar como.

A notificação será enviada somente se a caixa de diálogo tiver sido criada com o estilo OFN_EXPLORER. Para saber mais sobre a notificação, confira CDN_FOLDERCHANGE. Para saber mais sobre o estilo OFN_EXPLORER, confira a estrutura OPENFILENAME e Caixas de diálogo Abrir e Salvar como.

CFileDialog::OnInitDone

Substitua essa função para lidar com a mensagem WM_NOTIFY CDN_INITDONE.

virtual void OnInitDone();

Comentários

O sistema envia essa mensagem de notificação quando o sistema termina de organizar controles na caixa de diálogo Abrir ou Salvar como a fim de abrir espaço para os controles da caixa de diálogo filho.

O sistema enviará isso somente se a caixa de diálogo tiver sido criada com o estilo OFN_EXPLORER. Para saber mais sobre a notificação, confira CDN_INITDONE. Para saber mais sobre o estilo OFN_EXPLORER, confira a estrutura OPENFILENAME e Caixas de diálogo Abrir e Salvar como.

Observação

Os diálogos de arquivo de estilo do Windows Vista ou posterior não dão suporte a essa função. A tentativa de usar essa função em um diálogo de arquivo em estilo do Windows Vista ou posterior gerará CNotSupportedException.

CFileDialog::OnItemSelected

Chamado quando o item de contêiner é selecionado.

virtual void OnItemSelected(
    DWORD dwIDCtl,
    DWORD dwIDItem);

Parâmetros

dwIDCtl
A ID do controle de contêiner.

dwIDItem
A ID do item.

Comentários

CFileDialog::OnLBSelChangedNotify

Essa função é chamada sempre que a seleção atual em uma caixa de listagem está prestes a ser alterada.

virtual void OnLBSelChangedNotify(
    UINT nIDBox,
    UINT iCurSel,
    UINT nCode);

Parâmetros

nIDBox
A ID da caixa de listagem ou caixa de combinação na qual a seleção ocorreu.

iCurSel
O índice da seleção atual.

nCode
O código de notificação de controle. Esse parâmetro pode ter um dos seguintes valores:

CD_LBSELCHANGE Especifica que iCurSel é o item selecionado em uma caixa de listagem de opção única.
CD_LBSELSUB Especifica que iCurSel não está mais selecionado em uma caixa de listagem de várias opções.
CD_LBSELADD Especifica que iCurSel não está mais selecionado em uma caixa de listagem de várias opções.
CD_LBSELNOITEMS Especifica que nenhuma seleção existe em uma caixa de listagem de várias opções.

Comentários

Substitua essa função para fornecer tratamento personalizado de alterações de opção na caixa de listagem. Por exemplo, você pode usar essa função para exibir os direitos de acesso ou a última modificação de cada arquivo selecionado pelo usuário.

CFileDialog::OnShareViolation

Substitua essa função para fornecer tratamento personalizado de violações de compartilhamento.

virtual UINT OnShareViolation(LPCTSTR lpszPathName);

Parâmetros

lpszPathName
O caminho do arquivo no qual ocorreu a violação do compartilhamento.

Valor de retorno

Um dos seguintes valores:

OFN_SHAREFALLTHROUGH O nome do arquivo é retornado da caixa de diálogo.
OFN_SHARENOWARN Nenhuma ação adicional precisa ser realizada.
OFN_SHAREWARN O usuário recebe a mensagem de aviso padrão para esse erro.

Comentários

Normalmente, você não precisa usar essa função porque a estrutura fornece verificação padrão de violações de compartilhamento e exibe uma caixa de mensagem em caso de violação de compartilhamento.

Se você quiser desabilitar a verificação de violação de compartilhamento, use o operador OR bit a bit para combinar o sinalizador OFN_SHAREAWARE com m_ofn.Flags.

CFileDialog::OnTypeChange

Substitua essa função para lidar com a mensagem WM_NOTIFYCDN_TYPECHANGE.

virtual void OnTypeChange();

Comentários

A mensagem de notificação é enviada quando o usuário seleciona um novo tipo de arquivo na lista de tipos de arquivo na caixa de diálogo Abrir ou Salvar como.

A notificação será enviada somente se a caixa de diálogo tiver sido criada com o estilo OFN_EXPLORER. Para saber mais sobre a notificação, confira CDN_TYPECHANGE. Para saber mais sobre o estilo OFN_EXPLORER, confira a estrutura OPENFILENAME e Caixas de diálogo Abrir e Salvar como.

CFileDialog::RemoveControlItem

Remove um item de um controle de contêiner no diálogo.

HRESULT RemoveControlItem(
    DWORD dwIDCtl,
    DWORD dwIDItem);

Parâmetros

dwIDCtl
A ID do controle de contêiner do qual remover o item.

dwIDItem
A ID do item.

Comentários

CFileDialog::SetCheckButtonState

Define o estado atual de um botão de seleção (caixa de seleção) no diálogo.

HRESULT SetCheckButtonState(
    DWORD dwIDCtl,
    BOOL bChecked);

Parâmetros

dwIDCtl
A ID da caixa de seleção.

bChecked
O estado da caixa de seleção. TRUE indica marcado; FALSE indica desmarcado.

Comentários

CFileDialog::SetControlItemState

Define o estado atual de um item em um controle de contêiner encontrado no diálogo.

HRESULT SetControlItemState(
    DWORD dwIDCtl,
    DWORD dwIDItem,
    CDCONTROLSTATEF dwState);

Parâmetros

dwIDCtl
A ID do controle de contêiner.

dwIDItem
A ID do item.

dwState
Um ou mais valores da enumeração CDCONTROLSTATE que indicam o novo estado do controle.

Comentários

CFileDialog::SetControlItemText

Define o texto de um item de controle. Por exemplo, o texto que acompanha um botão de opção ou um item em um menu.

HRESULT SetControlItemText(
    DWORD dwIDCtl,
    DWORD dwIDItem,
    const CString& strLabel);

Parâmetros

dwIDCtl
A ID do controle de contêiner.

dwIDItem
A ID do item.

strLabel
Texto do item.

Comentários

CFileDialog::SetControlLabel

Define o texto associado a um controle, como texto de botão ou rótulo de caixa de edição.

HRESULT SetControlLabel(
    DWORD dwIDCtl,
    const CString& strLabel);

Parâmetros

dwIDCtl
O ID do controle.

strLabel
O nome do controle.

Comentários

CFileDialog::SetControlState

Define a visibilidade atual e os estados habilitados de determinado controle.

HRESULT SetControlState(
    DWORD dwIDCtl,
    CDCONTROLSTATEF dwState);

Parâmetros

dwIDCtl
O ID do controle.

dwState
Um ou mais valores da enumeração CDCONTROLSTATE que indicam o estado atual do controle.

Comentários

CFileDialog::SetControlText

Chame esse método a fim de definir o texto para o controle especificado em uma caixa de diálogo Abrir ou Salvar como no estilo do Explorador.

void SetControlText(
    int nID,
    LPCSTR lpsz);

void SetControlText(
    int nID,
    const wchar_t *lpsz);

Parâmetros

Nid
[in] A ID do controle para o qual definir o texto.

lpsz
[in] Um ponteiro para a cadeia de caracteres que contém o texto a ser definido para o controle.

Comentários

Ambas as versões dessa função são válidas para aplicativos que usam Unicode. No entanto, somente a versão com o tipo LPCSTR é válida para aplicativos que usam ANSI.

Para usar esse método, você precisa criar a caixa de diálogo com o estilo OFN_EXPLORER. Caso contrário, a função falhará com uma instrução assert.

CFileDialog::SetDefExt

Chame essa função para definir a extensão de nome de arquivo padrão para uma caixa de diálogo Abrir ou Salvar como comum no estilo do Explorador.

void SetDefExt(LPCSTR lpsz);

Parâmetros

lpsz
Um ponteiro para uma cadeia de caracteres que contém a extensão padrão a ser usada para o objeto da caixa de diálogo. Essa cadeia de caracteres não deve conter um ponto (.).

Comentários

A caixa de diálogo precisa ter sido criada com o estilo OFN_EXPLORER; caso contrário, a função falhará com uma instrução assert.

CFileDialog::SetEditBoxText

Define o texto atual em um controle de caixa de edição.

HRESULT SetEditBoxText(
    DWORD dwIDCtl,
    const CString& strText);

Parâmetros

dwIDCtl
A ID da caixa de edição.

strText
O valor do texto.

Comentários

CFileDialog::SetProperties

Fornece um repositório de propriedades que define os valores padrão a serem usados para o item que está sendo salvo.

BOOL SetProperties(LPCWSTR lpszPropList);

Parâmetros

lpszPropList
Uma lista de propriedades predefinidas separadas por ";". Para obter uma lista dos sinalizadores, confira a seção Sinalizadores de OPENFILENAME.

Comentários

CFileDialog::SetSelectedControlItem

Define o estado selecionado de um item específico em um grupo de botões de opção ou em uma caixa de combinação encontrada no diálogo.

HRESULT SetSelectedControlItem(
    DWORD dwIDCtl,
    DWORD dwIDItem);

Parâmetros

dwIDCtl
A ID do controle de contêiner.

dwIDItem
A ID do item que o usuário selecionou no controle.

Comentários

CFileDialog::SetTemplate

Define o modelo da caixa de diálogo para o objeto CFileDialog.

void SetTemplate(
    UINT nWin3ID,
    UINT nWin4ID);

void SetTemplate(
    LPCTSTR lpWin3ID,
    LPCTSTR lpWin4ID);

Parâmetros

nWin3ID
[in] Contém o número de ID do recurso de modelo para o objeto CFileDialog não Explorador. Esse modelo só é usado no Windows NT 3.51 ou quando o estilo OFN_EXPLORER não está presente.

nWin4ID
[in] Contém o número de ID do recurso de modelo para o objeto CFileDialog do Explorador. Esse modelo é usado apenas em versões do Windows NT 4.0 e versões posteriores, do Windows 95 e versões posteriores ou quando o estilo OFN_EXPLORER está presente.

lpWin3ID
[in] Contém o nome do recurso de modelo para o objeto CFileDialog não Explorador. Esse modelo só é usado no Windows NT 3.51 ou quando o estilo OFN_EXPLORER não está presente.

lpWin4ID
[in] Contém o nome do recurso de modelo do objeto CFileDialog do Explorador. Esse modelo é usado apenas em versões do Windows NT 4.0 e versões posteriores, do Windows 95 e versões posteriores ou quando o estilo OFN_EXPLORER está presente.

Comentários

O sistema usará apenas um dos modelos especificados. O sistema determina qual modelo usar com base na presença do estilo OFN_EXPLORER e no sistema operacional no qual o aplicativo está em execução. Ao especificar tanto um modelo de estilo do Explorador quanto não Explorador, é fácil dar suporte a Windows NT 3.51, Windows NT 4.0 e versões posteriores, e ao Windows 95 e versões posteriores.

Observação

As caixas de diálogo de arquivo de estilo do Windows Vista ou posterior não dão suporte a essa função. A tentativa de usar essa função em uma caixa de diálogo em estilo do Windows Vista ou posterior gerará CNotSupportedException. Uma alternativa é usar um diálogo personalizado. Para saber mais sobre como usar um personalizado CFileDialog, confira IFileDialogCustomize.

CFileDialog::StartVisualGroup

Declara um grupo visual no diálogo. Chamadas subsequentes a qualquer método "add" adicionam esses elementos a esse grupo.

HRESULT StartVisualGroup(
    DWORD dwIDCtl,
    const CString& strLabel);

Parâmetros

dwIDCtl
A ID do grupo visual.

strLabel
O nome do grupo.

Comentários

CFileDialog::UpdateOFNFromShellDialog

Atualiza a estrutura de dados m_ofn do CFileDialog com base no estado atual do objeto interno.

void UpdateOFNFromShellDialog();

Comentários

Nas versões do Windows antes do Windows Vista, a estrutura de dados OPENFILENAME do membro era sincronizada continuamente com o estado do CFileDialog. Todas as alterações na variável de membro m_ofn afetaram diretamente o estado da caixa de diálogo. Além disso, todas as alterações no estado do diálogo atualizaram imediatamente a variável de membro m_ofn.

No Windows Vista ou posterior, a estrutura de dados m_ofn não é atualizada automaticamente. Para garantir a precisão dos dados na variável de membro m_ofn, você deve chamar a função UpdateOFNFromShellDialog antes de acessar os dados. O Windows chama essa função automaticamente durante o processamento de IFileDialog::OnFileOK.

Para saber mais sobre como usar a classe CFileDialog no Windows Vista ou posterior, confira Classe CFileDialog.

Exemplo

Este exemplo atualiza o CFileDialog antes de exibi-lo. Antes de atualizar a variável de membro m_ofn, precisamos sincronizá-la com o estado atual da caixa de diálogo.

// Update the m_ofn variable
m_myFileDialogPtr->UpdateOFNFromShellDialog();

// Change the title
m_myFileDialogPtr->m_ofn.lpstrTitle = L"New Dialog Title";

// Apply the changes
m_myFileDialogPtr->ApplyOFNToShellDialog();

// Show the window
LRESULT result = m_myFileDialogPtr->DoModal();

Confira também

Classe CCommonDialog
Gráfico da hierarquia

Compartilhar via

Classe CFileDialog

Sintaxe

Membros

Construtores públicos

Métodos públicos

Métodos protegidos

Membros de Dados Públicos

Comentários

Hierarquia de herança

Requisitos

CFileDialog::AddCheckButton

Parâmetros

Comentários

CFileDialog::AddComboBox

Parâmetros

Comentários

CFileDialog::AddControlItem

Parâmetros

Comentários

CFileDialog::AddEditBox

Parâmetros

Comentários

CFileDialog::AddMenu

Parâmetros

Comentários

CFileDialog::AddPlace

Parâmetros

Comentários

CFileDialog::AddPushButton

Parâmetros

Comentários

CFileDialog::AddRadioButtonList

Parâmetros

Comentários

CFileDialog::AddSeparator

Parâmetros

Comentários

CFileDialog::AddText

Parâmetros

Comentários

CFileDialog::ApplyOFNToShellDialog

Comentários

Exemplo

CFileDialog::CFileDialog

Parâmetros

Comentários

Exemplo

CFileDialog::DoModal

Valor de retorno

Comentários

Exemplo

CFileDialog::EnableOpenDropDown

Parâmetros

Comentários

CFileDialog::EndVisualGroup

Valor de retorno

Comentários

CFileDialog::GetCheckButtonState

Parâmetros

Comentários

CFileDialog::GetControlItemState

Parâmetros

Comentários

CFileDialog::GetControlState

Parâmetros

Comentários

CFileDialog::GetEditBoxText

Parâmetros

Comentários

CFileDialog::GetFileExt

Valor de retorno

Comentários

CFileDialog::GetFileName

Valor de retorno

Comentários

CFileDialog::GetFileTitle

Valor de retorno

Comentários

Exemplo