Estrutura OPENFILENAMEA (commdlg.h)

[A partir do Windows Vista, as caixas de diálogo abrir e salvar como comuns foram substituídas pela caixa de diálogo Item Comum. Recomendamos que você use a API de Caixa de Diálogo de Item Comum em vez dessas caixas de diálogo da Biblioteca de 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

Digite: 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 OFN_ENABLETEMPLATEHANDLE estiver definido no membro Flags , hInstance será um identificador para um objeto de memória que contém um modelo de caixa de diálogo. Se o sinalizador OFN_ENABLETEMPLATE estiver definido, hInstance será um identificador para um módulo que contém um modelo de caixa de diálogo chamado pelo membro lpTemplateName . Se nenhum dos sinalizadores estiver definido, esse membro será ignorado. Se o sinalizador OFN_EXPLORER estiver definido, o sistema usará o modelo especificado para criar uma caixa de diálogo que seja um filho da caixa de diálogo padrão de estilo Explorer. 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.

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 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 na ordem especificada em lpstrFilter.

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 o nome do arquivo .lnk, não seu destino. Esse comportamento é o mesmo que definir o sinalizador OFN_NODEREFERENCELINKS no membro Flags . Para recuperar o destino de um atalho sem filtragem, use a cadeia de caracteres "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 vazia. 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 membro nFilterIndex for zero, a caixa de diálogo usará o filtro personalizado.

Se esse membro for NULL, a caixa de diálogo não preservará os padrões de filtro definidos pelo usuário.

Se esse membro não for 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 lpstrCustomFilter for NULL ou apontar para uma cadeia de caracteres NULL .

nFilterIndex

Tipo: DWORD

O índice do filtro selecionado no momento no controle Tipos de Arquivo . O buffer apontado por lpstrFilter contém pares de cadeias de caracteres que definem os filtros. O primeiro par de cadeias de caracteres tem um valor de índice de 1, o segundo par 2 e assim por diante. Um índice de zero indica o filtro personalizado especificado por lpstrCustomFilter. Você pode especificar um índice na entrada para indicar a descrição inicial do filtro e o padrão de filtro para a caixa de diálogo. Quando o usuário seleciona um arquivo, nFilterIndex retorna o índice do filtro exibido no momento. Se nFilterIndex for zero e lpstrCustomFilter for NULL, o sistema usará o primeiro filtro no buffer lpstrFilter . Se todos os três membros forem zero ou NULL, o sistema não usará filtros e não mostrará nenhum arquivo no controle de lista de arquivos da caixa de diálogo.

lpstrFile

Tipo: LPTSTR

O nome do arquivo usado para inicializar o controle de edição Nome do Arquivo . 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 de estilo Explorer, as cadeias de caracteres de diretório e nome de arquivo são separadas null, com um caractere NULL extra após o sobrenome do arquivo. 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, a cadeia de caracteres lpstrFile 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 o caractere NULL de terminação. 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 for NULL.

lpstrInitialDir

Tipo: LPCTSTR

O diretório inicial. O algoritmo para selecionar o diretório inicial varia em diferentes plataformas.

Windows 7:

1. Se lpstrInitialDir tiver o mesmo valor que foi passado na primeira vez que o aplicativo usou uma caixa de diálogo Abrir ou Salvar como , o caminho selecionado mais recentemente pelo usuário será usado como o diretório inicial.
2. Caso contrário, se lpstrFile contiver um caminho, esse caminho será o diretório inicial.
3. Caso contrário, se lpstrInitialDir não for NULL, ele especificará o diretório inicial.
4. Se lpstrInitialDir for NULL e o diretório atual contiver arquivos dos tipos de filtro especificados, o diretório inicial será o diretório atual.
5. Caso contrário, o diretório inicial é o diretório de arquivos pessoais do usuário atual.
6. Caso contrário, o diretório inicial será a pasta Desktop.

1. Se lpstrFile contiver um caminho, esse caminho será o diretório inicial.
2. Caso contrário, lpstrInitialDir especifica o diretório inicial.
3. Caso contrário, se o aplicativo tiver usado uma 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.
4. Se lpstrInitialDir for NULL e o diretório atual contiver arquivos dos tipos de filtro especificados, o diretório inicial será o diretório atual.
5. Caso contrário, o diretório inicial é o diretório de arquivos pessoais do usuário atual.
6. Caso contrário, o diretório inicial será 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 for 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 retorna, ela define esses sinalizadores para indicar a entrada do usuário. Esse membro pode ser uma combinação dos sinalizadores a seguir.

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 cadeia de caracteres a seguir, "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 de ponto ("."). Por exemplo, txt é a extensão do nome de 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 apontar para uma cadeia de caracteres que não contenha nenhum caractere ".", como "c:\dir1\dir2\readme", esse membro conterá zero.

lpstrDefExt

Tipo: LPCTSTR

A extensão padrão. GetOpenFileName e GetSaveFileName acrescentam 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 ponto (.). Se esse membro for 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 . Quando o sistema envia a mensagem WM_INITDIALOG para o procedimento de gancho, o parâmetro lParam da mensagem é um ponteiro para a estrutura OPENFILENAME especificada quando a caixa de diálogo foi criada. O procedimento de gancho pode usar esse ponteiro para obter o valor lCustData .

lpfnHook

Tipo: LPOFNHOOKPROC

Um ponteiro para um procedimento de gancho. Esse membro é ignorado, a menos que o membro Flags inclua o sinalizador OFN_ENABLEHOOK .

Se o sinalizador OFN_EXPLORER não estiver definido no membro Flags , lpfnHook será um ponteiro para um procedimento de gancho OFNHookProcOldStyle que recebe mensagens destinadas à caixa de diálogo. O procedimento de gancho retorna FALSE para passar uma mensagem para o procedimento da caixa de diálogo padrão ou TRUE para descartar a mensagem.

Se OFN_EXPLORER estiver definido, lpfnHook será um ponteiro para um procedimento de gancho OFNHookProc . O procedimento de gancho recebe mensagens de notificação enviadas da caixa de diálogo. O procedimento de gancho também recebe mensagens para quaisquer controles adicionais que você definiu especificando um modelo de caixa de diálogo filho. O procedimento de gancho não recebe mensagens destinadas aos controles padrão da caixa de diálogo padrão.

lpTemplateName

Tipo: LPCTSTR

O nome do recurso de modelo de caixa de diálogo no módulo identificado pelo membro hInstance . Para recursos de caixa de diálogo numerados, esse pode ser um valor retornado pela macro MAKEINTRESOURCE . Esse membro é ignorado, a menos que o sinalizador OFN_ENABLETEMPLATE seja definido no membro Flags . 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 padrão de estilo Explorer. 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.

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.

Comentários

Por motivos de compatibilidade, a Barra de Locais ficará oculta se Flags estiver definido como OFN_ENABLEHOOK e lStructSizefor OPENFILENAME_SIZE_VERSION_400.

Requisitos

Confira também

Biblioteca de caixas de diálogo comuns

Conceitual

Getopenfilename

Getsavefilename

Outros recursos

Referência

SHGetSpecialFolderLocation