Estrutura OPENFILENAMEA (commdlg.h)
[A partir do Windows Vista, as caixas de diálogo comuns
Contém informações que as funções GetOpenFileName e GetSaveFileName usam para inicializar uma caixa de diálogo Abrir ou Salvar como. Depois que o usuário fecha a caixa de diálogo, o sistema retorna informações sobre a seleção do usuário nessa estrutura.
Sintaxe
typedef struct tagOFNA {
DWORD lStructSize;
HWND hwndOwner;
HINSTANCE hInstance;
LPCSTR lpstrFilter;
LPSTR lpstrCustomFilter;
DWORD nMaxCustFilter;
DWORD nFilterIndex;
LPSTR lpstrFile;
DWORD nMaxFile;
LPSTR lpstrFileTitle;
DWORD nMaxFileTitle;
LPCSTR lpstrInitialDir;
LPCSTR lpstrTitle;
DWORD Flags;
WORD nFileOffset;
WORD nFileExtension;
LPCSTR lpstrDefExt;
LPARAM lCustData;
LPOFNHOOKPROC lpfnHook;
LPCSTR lpTemplateName;
LPEDITMENU lpEditInfo;
LPCSTR lpstrPrompt;
void *pvReserved;
DWORD dwReserved;
DWORD FlagsEx;
} OPENFILENAMEA, *LPOPENFILENAMEA;
Membros
lStructSize
Tipo: DWORD
O comprimento, em bytes, da estrutura.
Use sizeof (OPENFILENAME) para esse parâmetro.
hwndOwner
Tipo: HWND
Um identificador para a janela que possui a caixa de diálogo. Esse membro pode ser qualquer identificador de janela válido ou pode ser NULL se a caixa de diálogo não tiver proprietário.
hInstance
Tipo: HINSTANCE
Se o sinalizador
lpstrFilter
Tipo: LPCTSTR
Um buffer que contém pares de cadeias de caracteres de filtro terminadas em nulo. A última cadeia de caracteres no buffer deve ser encerrada por dois caracteres de NULL
A primeira cadeia de caracteres em cada par é uma cadeia de caracteres de exibição que descreve o filtro (por exemplo, "Arquivos de Texto") e a segunda cadeia de caracteres especifica o padrão de filtro (por exemplo, ".TXT"). Para especificar vários padrões de filtro para uma única cadeia de caracteres de exibição, use um ponto-e-vírgula para separar os padrões (por exemplo, ".TXT;.DOC;. BAK"). Uma cadeia de caracteres padrão pode ser uma combinação de caracteres de nome de arquivo válidos e o caractere curinga asterisco (*). Não inclua espaços na cadeia de caracteres padrão.
O sistema não altera a ordem dos filtros. Ele os exibe na caixa de combinação tipos de arquivo
Se lpstrFilter for NULL, a caixa de diálogo não exibirá nenhum filtro.
No caso de um atalho, se nenhum filtro estiver definido, GetOpenFileName e GetSaveFileName recuperar o nome do arquivo .lnk, não seu destino. Esse comportamento é o mesmo que definir o sinalizador de "All Files\0*.*\0\0".
lpstrCustomFilter
Tipo: LPTSTR
Um buffer estático que contém um par de cadeias de caracteres de filtro terminadas em nulo para preservar o padrão de filtro escolhido pelo usuário. A primeira cadeia de caracteres é a cadeia de caracteres de exibição que descreve o filtro personalizado e a segunda cadeia de caracteres é o padrão de filtro selecionado pelo usuário. Na primeira vez que o aplicativo cria a caixa de diálogo, você especifica a primeira cadeia de caracteres, que pode ser qualquer cadeia de caracteres não úmida. Quando o usuário seleciona um arquivo, a caixa de diálogo copia o padrão de filtro atual para a segunda cadeia de caracteres. O padrão de filtro preservado pode ser um dos padrões especificados no buffer lpstrFilter ou pode ser um padrão de filtro digitado pelo usuário. O sistema usa as cadeias de caracteres para inicializar o filtro de arquivo definido pelo usuário na próxima vez que a caixa de diálogo for criada. Se o nFilterIndex membro for zero, a caixa de diálogo usará o filtro personalizado.
Se esse membro estiver NULL, a caixa de diálogo não preservará os padrões de filtro definidos pelo usuário.
Se esse membro não estiver NULL, o valor do membro nMaxCustFilter deverá especificar o tamanho, em caracteres, do buffer lpstrCustomFilter.
nMaxCustFilter
Tipo: DWORD
O tamanho, em caracteres, do buffer identificado por lpstrCustomFilter. Esse buffer deve ter pelo menos 40 caracteres. Esse membro será ignorado se
nFilterIndex
Tipo: DWORD
O índice do filtro atualmente selecionado no controle tipos de arquivo
lpstrFile
Tipo: LPTSTR
O nome do arquivo usado para inicializar o o nome do arquivo controle de edição. O primeiro caractere desse buffer deve ser NULL se a inicialização não for necessária. Quando a função GetOpenFileName ou GetSaveFileName retorna com êxito, esse buffer contém o designador da unidade, o caminho, o nome do arquivo e a extensão do arquivo selecionado.
Se o sinalizador OFN_ALLOWMULTISELECT estiver definido e o usuário selecionar vários arquivos, o buffer conterá o diretório atual seguido pelos nomes de arquivo dos arquivos selecionados. Para caixas de diálogo no estilo Explorer, as cadeias de caracteres de nome de arquivo e diretório são NULL separadas, com um caractere NULL após o sobrenome. Para caixas de diálogo de estilo antigo, as cadeias de caracteres são separadas por espaço e a função usa nomes de arquivo curtos para nomes de arquivo com espaços. Você pode usar a função FindFirstFile para converter entre nomes de arquivo longos e curtos. Se o usuário selecionar apenas um arquivo, o lpstrFile cadeia de caracteres não terá um separador entre o caminho e o nome do arquivo.
Se o buffer for muito pequeno, a função retornará FALSE e a função CommDlgExtendedError retornará FNERR_BUFFERTOOSMALL. Nesse caso, os dois primeiros bytes do buffer lpstrFile contêm o tamanho necessário, em bytes ou caracteres.
nMaxFile
Tipo: DWORD
O tamanho, em caracteres, do buffer apontado por lpstrFile. O buffer deve ser grande o suficiente para armazenar o caminho e a cadeia de caracteres ou cadeias de caracteres de nome de arquivo, incluindo a terminação caractere NULL. As funções GetOpenFileName e GetSaveFileName retornarão FALSE se o buffer for muito pequeno para conter as informações do arquivo. O buffer deve ter pelo menos 256 caracteres.
lpstrFileTitle
Tipo: LPTSTR
O nome do arquivo e a extensão (sem informações de caminho) do arquivo selecionado. Esse membro pode ser NULL.
nMaxFileTitle
Tipo: DWORD
O tamanho, em caracteres, do buffer apontado por lpstrFileTitle. Esse membro será ignorado se lpstrFileTitle estiver NULL.
lpstrInitialDir
Tipo: LPCTSTR
O diretório inicial. O algoritmo para selecionar o diretório inicial varia em plataformas diferentes.
Windows 7:
- Se lpstrInitialDir tiver o mesmo valor que foi passado na primeira vez que o aplicativo usou um caixa de diálogo Abrir ou Salvar como, o caminho mais recentemente selecionado pelo usuário será usado como o diretório inicial.
- Caso contrário, se lpstrFile contiver um caminho, esse caminho será o diretório inicial.
- Caso contrário, se lpstrInitialDir não estiver NULL, ele especifica o diretório inicial.
- Se lpstrInitialDir for NULL e o diretório atual contiver quaisquer arquivos dos tipos de filtro especificados, o diretório inicial será o diretório atual.
- Caso contrário, o diretório inicial é o diretório de arquivos pessoais do usuário atual.
- Caso contrário, o diretório inicial é a pasta Desktop.
- Se lpstrFile contiver um caminho, esse caminho será o diretório inicial.
- Caso contrário, lpstrInitialDir especifica o diretório inicial.
- Caso contrário, se o aplicativo tiver usado um caixa de diálogo Abrir ou Salvar como no passado, o caminho usado mais recentemente será selecionado como o diretório inicial. No entanto, se um aplicativo não for executado por muito tempo, seu caminho selecionado salvo será descartado.
- Se lpstrInitialDir for NULL e o diretório atual contiver quaisquer arquivos dos tipos de filtro especificados, o diretório inicial será o diretório atual.
- Caso contrário, o diretório inicial é o diretório de arquivos pessoais do usuário atual.
- Caso contrário, o diretório inicial é a pasta Desktop.
lpstrTitle
Tipo: LPCTSTR
Uma cadeia de caracteres a ser colocada na barra de título da caixa de diálogo. Se esse membro estiver NULL, o sistema usará o título padrão (ou seja, Salvar como ou Abrir).
Flags
Tipo: DWORD
Um conjunto de sinalizadores de bits que você pode usar para inicializar a caixa de diálogo. Quando a caixa de diálogo é retornada, ela define esses sinalizadores para indicar a entrada do usuário. Esse membro pode ser uma combinação dos sinalizadores a seguir.
| Valor | Significado |
|---|---|
|
A caixa de listagem nome do arquivo Se o usuário selecionar mais de um arquivo, o lpstrFile buffer retornará o caminho para o diretório atual seguido pelos nomes de arquivo dos arquivos selecionados. O membro nFileOffset é o deslocamento, em bytes ou caracteres, para o nome do primeiro arquivo e o membro nFileExtension não é usado. Para caixas de diálogo no estilo Explorer, as cadeias de caracteres de nome de arquivo e diretório são NULL separadas, com um caractere NULL após o sobrenome. Esse formato permite que as caixas de diálogo estilo Explorer retornem nomes de arquivo 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. Você pode usar a função FindFirstFile para converter entre nomes de arquivo longos e curtos. Se você especificar um modelo personalizado para uma caixa de diálogo de estilo antigo, a definição da caixa de listagem nome do arquivo |
|
Se o usuário especificar um arquivo que não existe, esse sinalizador fará com que a caixa de diálogo solicite ao usuário permissão para criar o arquivo. Se o usuário optar por criar o arquivo, a caixa de diálogo será fechada e a função retornará o nome especificado; caso contrário, a caixa de diálogo permanecerá aberta. Se você usar esse sinalizador com o sinalizador OFN_ALLOWMULTISELECT, a caixa de diálogo permitirá que o usuário especifique apenas um arquivo inexistente. |
|
Impede que o sistema adicione um link ao arquivo selecionado no diretório do sistema de arquivos que contém os documentos usados mais recentemente pelo usuário. Para recuperar o local desse diretório, chame a função |
|
Habilita a função de gancho especificada no membro lpfnHook |
|
Faz com que a caixa de diálogo envie mensagens de notificação |
|
Permite que a caixa de diálogo estilo Explorer seja redimensionada usando o mouse ou o teclado. Por padrão, as caixas de diálogo Abrir e Salvar como permitem que a caixa de diálogo seja redimensionada independentemente de esse sinalizador estar definido. Esse sinalizador só será necessário se você fornecer um procedimento de gancho ou um modelo personalizado. A caixa de diálogo de estilo antigo não permite redimensionamento. |
|
O membro |
|
O membro hInstance identifica um bloco de dados que contém um modelo de caixa de diálogo pré-carregado. O sistema ignorará lpTemplateName se esse sinalizador for especificado. Se o sinalizador OFN_EXPLORER estiver definido, o sistema usará o modelo especificado para criar uma caixa de diálogo que seja filho da caixa de diálogo estilo Explorer padrão. Se o sinalizador OFN_EXPLORER não estiver definido, o sistema usará o modelo para criar uma caixa de diálogo de estilo antigo que substitui a caixa de diálogo padrão. |
|
Indica que todas as personalizações feitas na caixa de diálogo Abrir ou Salvar como usam os métodos de personalização no estilo Explorer. Para obter mais informações, consulte Explorer-Style de procedimentos de gancho e modelos personalizados Explorer-Style.
Por padrão, as caixas de diálogo Abrir e Salvar como usam a interface do usuário no estilo Explorer, independentemente de esse sinalizador ser definido. Esse sinalizador será necessário somente se você fornecer um procedimento de gancho ou um modelo personalizado ou definir o sinalizador de OFN_ALLOWMULTISELECT. Se você quiser a interface do usuário de estilo antigo, omita o sinalizador OFN_EXPLORER e forneça um modelo de estilo antigo de substituição ou procedimento de gancho. Se você quiser o estilo antigo, mas não precisar de um modelo ou procedimento de gancho personalizado, basta fornecer um procedimento de gancho que sempre retorna false. |
|
O usuário digitou uma extensão de nome de arquivo diferente da extensão especificada por lpstrDefExt. A função não usará esse sinalizador se lpstrDefExt estiver NULL. |
|
O usuário pode digitar apenas nomes de arquivos existentes no campo de entrada nome de arquivo |
|
Força a exibição de arquivos ocultos e do sistema, substituindo assim a configuração do usuário para mostrar ou não arquivos ocultos. No entanto, um arquivo marcado como sistema e oculto não é mostrado. |
|
Oculta a caixa de seleção Somente Leitura. |
|
Para caixas de diálogo de estilo antigo, esse sinalizador faz com que a caixa de diálogo use nomes de arquivo longos. Se esse sinalizador não for especificado ou se o sinalizador de OFN_ALLOWMULTISELECT também estiver definido, as caixas de diálogo de estilo antigo usarão nomes de arquivo curtos (formato 8.3) para nomes de arquivo com espaços. As caixas de diálogo no estilo explorer ignoram esse sinalizador e sempre exibem nomes de arquivo longos. |
|
Restaura o diretório atual para seu valor original se o usuário alterou o diretório durante a pesquisa de arquivos. |
|
Direciona a caixa de diálogo para retornar o caminho e o nome do arquivo do atalho selecionado (. Arquivo LNK). Se esse valor não for especificado, a caixa de diálogo retornará o caminho e o nome do arquivo referenciado pelo atalho. |
|
Para caixas de diálogo de estilo antigo, esse sinalizador faz com que a caixa de diálogo use nomes de arquivo curtos (formato 8.3). As caixas de diálogo no estilo explorer ignoram esse sinalizador e sempre exibem nomes de arquivo longos. |
|
Oculta e desabilita o botão rede |
|
O arquivo retornado não tem a caixa de seleção Somente Leitura selecionada e não está em um diretório protegido por gravação. |
|
O arquivo não é criado antes que a caixa de diálogo seja fechada. Esse sinalizador deverá ser especificado se o aplicativo salvar o arquivo em um compartilhamento de rede create-nonmodify. Quando um aplicativo especifica esse sinalizador, a biblioteca não verifica se há proteção de gravação, um disco completo, uma porta de unidade aberta ou proteção de rede. Os aplicativos que usam esse sinalizador devem executar operações de arquivo com cuidado, pois um arquivo não pode ser reaberto depois de fechado. |
|
As caixas de diálogo comuns permitem caracteres inválidos no nome do arquivo retornado. Normalmente, o aplicativo de chamada usa um procedimento de gancho que verifica o nome do arquivo usando a mensagem FILEOKSTRING. Se a caixa de texto no controle de edição estiver vazia ou não contiver nada além de espaços, as listas de arquivos e diretórios serão atualizadas. Se a caixa de texto no controle de edição contiver qualquer outra coisa, nFileOffset e nFileExtension serão definidos como valores gerados pela análise do texto. Nenhuma extensão padrão é adicionada ao texto, nem o texto é copiado para o buffer especificado por lpstrFileTitle. Se o valor especificado por nFileOffset for menor que zero, o nome do arquivo será inválido. Caso contrário, o nome do arquivo é válido e nFileExtension e nFileOffset podem ser usados como se o sinalizador de OFN_NOVALIDATE não tivesse sido especificado. |
|
Faz com que a caixa de diálogo Salvar como gere uma caixa de mensagem se o arquivo selecionado já existir. O usuário deve confirmar se deseja substituir o arquivo. |
|
O usuário pode digitar apenas caminhos válidos e nomes de arquivo. Se esse sinalizador for usado e o usuário digitar um caminho inválido e um nome de arquivo no campo de entrada Nome do Arquivo |
|
Faz com que a caixa de seleção Somente Leitura seja selecionada inicialmente quando a caixa de diálogo for criada. Esse sinalizador indica o estado da caixa de seleção Somente Leitura quando a caixa de diálogo é fechada. |
|
Especifica que, se uma chamada para a função OpenFile falhar devido a uma violação de compartilhamento de rede, o erro será ignorado e a caixa de diálogo retornará o nome do arquivo selecionado. Se esse sinalizador não estiver definido, a caixa de diálogo notificará o procedimento de gancho quando ocorrer uma violação de compartilhamento de rede para o nome do arquivo especificado pelo usuário. Se você definir o sinalizador OFN_EXPLORER, a caixa de diálogo enviará a mensagem CDN_SHAREVIOLATION para o procedimento de gancho. Se você não definir OFN_EXPLORER, a caixa de diálogo enviará o SHAREVISTRING mensagem registrada para o procedimento de gancho. |
|
Faz com que a caixa de diálogo exiba o botão Ajuda. O membro hwndOwner deve especificar a janela para receber o HELPMSGSTRING mensagens registradas que a caixa de diálogo envia quando o usuário clica no botão Ajuda. Uma caixa de diálogo estilo Explorer envia uma mensagem de notificação CDN_HELP para o procedimento de gancho quando o usuário clica no botão Ajuda. |
nFileOffset
Tipo: word
O deslocamento baseado em zero, em caracteres, desde o início do caminho até o nome do arquivo na cadeia de caracteres apontada por lpstrFile. Para a versão ANSI, esse é o número de bytes; para a versão Unicode, esse é o número de caracteres. Por exemplo, se lpstrFile apontar para a seguinte cadeia de caracteres, "c:\dir1\dir2\file.ext", esse membro conterá o valor 13 para indicar o deslocamento da cadeia de caracteres "file.ext". Se o usuário selecionar mais de um arquivo, nFileOffset será o deslocamento para o nome do primeiro arquivo.
nFileExtension
Tipo: word
O deslocamento baseado em zero, em caracteres, desde o início do caminho até a extensão de nome de arquivo na cadeia de caracteres apontada por lpstrFile. Para a versão ANSI, esse é o número de bytes; para a versão Unicode, esse é o número de caracteres. Normalmente, a extensão de nome de arquivo é a subcadeia de caracteres que segue a última ocorrência do caractere do ponto ("."). Por exemplo, txt é a extensão do nome do arquivo readme.txt, html a extensão de readme.txt.html. Portanto, se lpstrFile apontar para a cadeia de caracteres "c:\dir1\dir2\readme.txt", esse membro conterá o valor 20. Se lpstrFile apontar para a cadeia de caracteres "c:\dir1\dir2\readme.txt.html", esse membro conterá o valor 24. Se lpstrFile apontar para a cadeia de caracteres "c:\dir1\dir2\readme.txt.html.", esse membro conterá o valor 29. Se lpstrFile aponta para uma cadeia de caracteres que não contém nenhum caractere ".", como "c:\dir1\dir2\readme", esse membro contém zero.
lpstrDefExt
Tipo: LPCTSTR
A extensão padrão. GetOpenFileName e GetSaveFileName acrescentar essa extensão ao nome do arquivo se o usuário não digitar uma extensão. Essa cadeia de caracteres pode ter qualquer comprimento, mas apenas os três primeiros caracteres são acrescentados. A cadeia de caracteres não deve conter um período (.). Se esse membro estiver NULL e o usuário não digitar uma extensão, nenhuma extensão será acrescentada.
lCustData
Tipo: LPARAM
Dados definidos pelo aplicativo que o sistema passa para o procedimento de gancho identificado pelo membro lpfnHook
lpfnHook
Tipo: LPOFNHOOKPROC
Um ponteiro para um procedimento de gancho. Esse membro é ignorado, a menos que o membro sinalizadores do
Se o sinalizador
Se
lpTemplateName
Tipo: LPCTSTR
O nome do recurso de modelo de caixa de diálogo no módulo identificado pelo membro do hInstance. Para recursos da caixa de diálogo numerada, esse pode ser um valor retornado pela macro
lpEditInfo
Esse membro é compilado condicionalmente (usando #ifdef _MAC) para que ele seja aplicável somente aos computadores Macintosh do Motorola 68K e não aos sistemas operacionais cliente Windows.
lpstrPrompt
Esse membro é compilado condicionalmente (usando #ifdef _MAC) para que ele seja aplicável somente aos computadores Macintosh do Motorola 68K e não aos sistemas operacionais cliente Windows.
pvReserved
Tipo: void*
Este membro é reservado.
dwReserved
Tipo: DWORD
Este membro é reservado.
FlagsEx
Tipo: DWORD
Um conjunto de sinalizadores de bits que você pode usar para inicializar a caixa de diálogo. Atualmente, esse membro pode ser zero ou o sinalizador a seguir.
Observações
Por motivos de compatibilidade, a Barra de Locais ficará oculta se Sinalizadores estiver definido como OFN_ENABLEHOOK e lStructSize for OPENFILENAME_SIZE_VERSION_400.
Nota
O cabeçalho commdlg.h define OPENFILENAME como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows 2000 Professional [somente aplicativos da área de trabalho] |
| servidor com suporte mínimo | Windows 2000 Server [somente aplicativos da área de trabalho] |
| cabeçalho | commdlg.h (inclua Windows.h) |
Consulte também
da Biblioteca de Caixas de Diálogo Comuns
Conceitual
outros recursos
de referência de