Caixas de diálogo Abrir e Salvar como
Observação
A função GetOpenFileName é demonstrada no exemplo Arquivo está em uso.
[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.]
A caixa de diálogo Abrir permite que o usuário especifique a unidade, o diretório e o nome de um arquivo ou conjunto de arquivos a serem abertos. Você cria e exibe uma caixa de diálogo Abrir inicializando uma estrutura OPENFILENAME e passando a estrutura para a função GetOpenFileName .
A caixa de diálogo Salvar como permite que o usuário especifique a unidade, o diretório e o nome de um arquivo a ser salvo. Você cria e exibe uma caixa de diálogo Salvar como inicializando uma estrutura OPENFILENAME e passando a estrutura para a função GetSaveFileName .
Explorer caixas de diálogo Abrir e Salvar como fornecem recursos de interface do usuário semelhantes à Explorer do Windows. No entanto, o sistema continua a dar suporte a caixas de diálogo Open e Save As de estilo antigo para aplicativos que devem ser consistentes com a interface do usuário de estilo antigo.
Além da diferença de aparência, as caixas de diálogo estilo Explorer e estilo antigo diferem no uso de modelos personalizados e procedimentos de gancho para personalizar as caixas de diálogo. No entanto, as caixas de diálogo estilo Explorer e estilo antigo têm o mesmo comportamento para a maioria das operações básicas, como especificar um filtro de nome de arquivo, validar a entrada do usuário e obter o nome de arquivo especificado pelo usuário. Para obter mais informações sobre as caixas de diálogo estilo Explorer e estilo antigo, consulte Abrir e salvar como personalização da caixa de diálogo.
A ilustração a seguir mostra uma caixa de diálogo Open de estilo Explorer típico.
A ilustração a seguir mostra uma caixa de diálogo salvar como no estilo Explorer típico.
Se o usuário especificar um nome de arquivo e clicar no botão OK , GetOpenFileName ou GetSaveFileName retornará TRUE. O buffer apontado pelo membro lpstrFile da estrutura OPENFILENAME contém o caminho completo e o nome do arquivo especificados pelo usuário.
Se o usuário cancelar a caixa de diálogo Abrir ou Salvar como ou ocorrer um erro, a função retornará FALSE. Para determinar a causa do erro, chame a função CommDlgExtendedError para recuperar o valor de erro estendido. Se o buffer lpstrFile for muito pequeno para receber o nome completo, CommDlgExtendedError retornará FNERR_BUFFERTOOSMALL e os dois primeiros bytes do buffer apontados pelo membro lpstrFile serão definidos como um valor inteiro especificando o tamanho necessário para receber o nome completo.
Os tópicos a seguir são discutidos nesta seção.
- Nomes e diretórios de arquivos
- Filtros
- Validação de arquivo e diretório
- Abrir e salvar como personalização da caixa de diálogo
- Procedimentos de gancho de estilo Explorer
- Modelos personalizados de estilo Explorer
- Identificadores de controle de estilo Explorer
- Personalizando caixas de diálogo Old-Style
Nomes e diretórios de arquivos
As informações nesta seção se aplicam às caixas de diálogo Abrir e Salvar como no estilo Explorer e no estilo antigo.
Antes de chamar as funções GetOpenFileName ou GetSaveFileName , o membro lpstrFile da estrutura OPENFILENAME deve apontar para o buffer para receber o nome do arquivo. O membro nMaxFile deve especificar o tamanho, em caracteres, do buffer lpstrFile . Para uma função ANSI, esse é o número de bytes, mas para uma função Unicode esse é o número de caracteres.
Se o usuário especificar um nome de arquivo e clicar no botão OK , a caixa de diálogo copiará a unidade, o diretório e o nome do arquivo selecionados para o buffer lpstrFile . A função também define os membros nFileOffset e nFileExtension para os deslocamentos, em caracteres, desde o início do buffer até o nome do arquivo e para a extensão de nome de arquivo, respectivamente.
Para recuperar apenas o nome e a extensão do arquivo, defina o membro lpstrFileTitle para apontar para um buffer e defina o membro nMaxFileTitle como o tamanho, em caracteres, do buffer. Como alternativa, você pode passar o buffer lpstrFile em uma chamada para a função GetFileTitle para obter o nome de exibição do arquivo selecionado. No entanto, observe que o nome do arquivo que GetFileTitle retorna incluirá uma extensão somente se essa for a preferência do usuário para exibir nomes de arquivo.
A caixa de diálogo usa o diretório atual para o processo de chamada como o diretório inicial do qual exibir arquivos e diretórios. Use as funções GetCurrentDirectory e SetCurrentDirectory para obter e alterar o diretório atual de um processo. Para especificar um diretório inicial diferente sem alterar o diretório atual, use o membro lpstrInitialDir para especificar o nome de um diretório. A caixa de diálogo altera automaticamente o diretório atual quando o usuário seleciona uma unidade ou diretório diferente. Para impedir que a caixa de diálogo altere o diretório atual, defina o sinalizador OFN_NOCHANGEDIR . Esse sinalizador não impede que o usuário altere diretórios para encontrar um arquivo.
Para especificar uma extensão de nome de arquivo padrão, use o membro lpstrDefExt . Se o usuário especificar um nome de arquivo que não tenha uma extensão, a caixa de diálogo adicionará sua extensão padrão. Se você especificar uma extensão padrão e o usuário especificar um nome de arquivo com uma extensão diferente, a caixa de diálogo definirá o sinalizador OFN_EXTENSIONDIFFERENT .
Para permitir que o usuário selecione mais de um arquivo de um diretório, defina o sinalizador OFN_ALLOWMULTISELECT . Para compatibilidade com aplicativos mais antigos, a caixa de diálogo de seleção múltipla padrão usa a interface do usuário de estilo antigo. Para exibir uma caixa de diálogo de seleção múltipla no estilo Explorer, você também deve definir o sinalizador OFN_EXPLORER.
Se o usuário selecionar mais de um arquivo, o buffer apontado pelo membro lpstrFile retornará o caminho para o diretório atual seguido pelos nomes de arquivo dos arquivos selecionados. O membro nFileOffset é o deslocamento para o primeiro nome de arquivo e o membro nFileExtension não é usado. A tabela a seguir descreve a diferença entre as caixas de diálogo estilo Explorer e estilo antigo no retorno de vários nomes de arquivo.
| Estilo da caixa de diálogo | Descrição |
|---|---|
| caixas de diálogo no estilo Explorer | As cadeias de caracteres de nome de arquivo e diretório são separadas por NULL , com um caractere NULL extra após o sobrenome do arquivo. Esse formato permite que as caixas de diálogo no estilo do Explorador retornem nomes de arquivos longos que incluem espaços. |
| Caixas de diálogo de estilo antigo | As cadeias de caracteres de diretório e nome de arquivo são separadas por espaços. Para nomes de arquivo com espaços, a função usa nomes de arquivo curtos. |
Você pode usar a função FindFirstFile para converter entre nomes de arquivo longos e curtos.
Se você especificar OFN_ALLOWMULTISELECT e 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.
Filtros
As informações nesta seção se aplicam às caixas de diálogo Abrir e Salvar como no estilo Explorer e antigas.
Você pode fornecer filtros de nome de arquivo para ajudar o usuário a limitar os nomes de arquivo exibidos pela caixa de diálogo. Um filtro de nome de arquivo consiste em um par de cadeias de caracteres terminadas em nulo, uma descrição e um padrão, um concatenado ao outro. A caixa de diálogo exibe a descrição para permitir que o usuário escolha qual filtro usar; e ele usa o padrão para selecionar os arquivos a serem exibidos.
Para especificar os filtros, defina o membro lpstrFilter da estrutura OPENFILENAME para apontar para um buffer que contém uma matriz de pares de cadeia de caracteres de filtro. A última cadeia de caracteres na matriz deve ser seguida por um caractere nulo extra.
Uma cadeia de caracteres padrão pode ser uma combinação de caracteres de nome de arquivo válidos e o asterisco (*). O asterisco é um curinga que representa qualquer combinação de caracteres de nome de arquivo válidos. A caixa de diálogo exibe apenas os arquivos que correspondem ao padrão. Para especificar vários padrões para a mesma descrição, você deve usar um ponto e vírgula (;) para separar os padrões. Observe que os caracteres de espaço na cadeia de caracteres padrão podem produzir resultados inesperados.
O fragmento de código a seguir especifica dois filtros. O filtro com a descrição "Origem" tem dois padrões. Se o usuário selecionar esse filtro, a caixa de diálogo exibirá apenas os arquivos que têm o . C e . Extensões CXX. Observe que, na linguagem de programação C, uma cadeia de caracteres entre aspas duplas é terminada em nulo.
OPENFILENAME ofn; // common dialog box structure
ofn.lpstrFilter = "Source\0*.C;*.CXX\0All\0*.*\0"
ofn.nFilterIndex = 1;
O membro nFilterIndex da estrutura OPENFILENAME especifica um índice que indica qual filtro a caixa de diálogo usa inicialmente. O primeiro filtro no buffer tem índice 1, o segundo 2 e assim por diante. Se o usuário alterar o filtro ao usar a caixa de diálogo, o membro nFilterIndex será definido como o índice do filtro selecionado no retorno.
Você pode criar um filtro personalizado definindo o membro lpstrCustomFilter como o endereço de um buffer que contém um único filtro e definindo o membro nMaxCustFilter como o tamanho do buffer, em caracteres ou bytes. A caixa de diálogo sempre coloca o filtro personalizado no início da lista de filtros e, no retorno, sempre atualiza a parte padrão do filtro com o padrão do filtro selecionado pelo usuário.
Para caixas de diálogo no estilo Explorer, a extensão padrão poderá ser alterada se o usuário selecionar um filtro diferente. Se o usuário selecionar um filtro cujo primeiro padrão é do formulário *. xxx (ou seja, a extensão não inclui um caractere curinga), a caixa de diálogo usa xxx como a extensão padrão. Isso ocorrerá somente se você tiver especificado uma extensão padrão no membro lpstrDefExt da estrutura OPENFILENAME . Por exemplo, se o usuário selecionar "Source\0*. C;*. Filtro CXX\0", a extensão padrão muda para "C". No entanto, se você tiver definido o filtro como "Source\0*. C*\0", a extensão padrão não seria alterada porque a extensão inclui um curinga.
A mensagem de notificação CDN_INCLUDEITEM fornece outra maneira de filtrar os nomes que a caixa de diálogo exibe. Para usar essa mensagem, forneça um procedimento de gancho OFNHookProc e especifique o sinalizador OFN_ENABLEINCLUDENOTIFY na estrutura OPENFILENAME ao criar a caixa de diálogo. Sempre que o usuário abre uma pasta, a caixa de diálogo envia uma notificação de CDN_INCLUDEITEM para o procedimento de gancho para cada item na pasta recém-aberta. O valor retornado do procedimento de gancho indica se a caixa de diálogo deve exibir o item na lista de itens da pasta.
Validação de arquivo e diretório
Exceto conforme observado, as informações nesta seção se aplicam às caixas de diálogo Abrir e Salvar como no estilo Explorer e à moda antiga.
A caixa de diálogo valida automaticamente os nomes de arquivo digitados pelo usuário para garantir que os nomes contenham apenas caracteres válidos. Para substituir a validação de caractere de nome de arquivo, defina o sinalizador OFN_NOVALIDATE .
Para forçar a caixa de diálogo a verificar se o usuário especificou o nome de um arquivo existente, defina o sinalizador OFN_FILEMUSTEXIST . Para forçar a verificação de que o caminho especificado existe, defina o sinalizador OFN_PATHMUSTEXIST . Se você definir o sinalizador OFN_CREATEPROMPT , a caixa de diálogo solicitará ao usuário permissão para criar um arquivo inexistente. Se esse sinalizador estiver definido e o usuário optar por criar um novo 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.
Ao usar a caixa de diálogo Salvar como , você pode direcionar a caixa de diálogo para solicitar ao usuário permissão para substituir um arquivo existente definindo o sinalizador OFN_OVERWRITEPROMPT .
Por padrão, a caixa de diálogo cria um arquivo de teste de comprimento zero para determinar se um novo arquivo pode ser criado no diretório selecionado. Para impedir a criação desse arquivo de teste, defina o sinalizador OFN_NOTESTFILECREATE .
Se você habilitar um procedimento de gancho, a caixa de diálogo notificará o procedimento de gancho quando ocorrer uma violação de compartilhamento de rede para o nome de 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á a mensagem registrada SHAREVISTRING para o procedimento de gancho. Para impedir que a caixa de diálogo envie quaisquer notificações de violações de compartilhamento, defina o sinalizador OFN_SHAREAWARE .
Se o usuário selecionar a caixa de marcar somente leitura, a caixa de diálogo definirá o sinalizador OFN_READONLY no retorno. Para ocultar a caixa Abrir como Somente Leitura marcar, defina o sinalizador OFN_HIDEREADONLY. Para impedir que a caixa de diálogo retorne nomes de arquivos existentes que têm o atributo somente leitura, defina o sinalizador OFN_NOREADONLYRETURN .
Para impedir que a caixa de diálogo desreferenciar arquivos de link, defina o valor OFN_NODEREFERENCELINKS . Nesse caso, a caixa de diálogo retorna o nome do arquivo de link em vez do nome do arquivo referenciado pelo arquivo de link.
Abrir e salvar como personalização da caixa de diálogo
Você pode personalizar uma caixa de diálogo Abrir ou Salvar como fornecendo um procedimento de gancho, um modelo personalizado ou ambos. No entanto, as versões de estilo Explorer e de estilo antigo das caixas de diálogo diferem no uso de modelos personalizados e procedimentos de gancho.
Para obter informações sobre como personalizar uma caixa de diálogo no estilo Explorer, consulte Explorer-Style Hook Procedures, Explorer-Style Custom Templates e Explorer-Style Control Identifiers. Para obter informações sobre como personalizar uma caixa de diálogo de estilo antigo, consulte Personalizando caixas de diálogo de Old-Style.
A tabela a seguir resume as diferenças entre os dois estilos.
| Personalização | Descrição |
|---|---|
| Explorer-style Hook procedure | O procedimento de gancho recebe mensagens de notificação enviadas da caixa de diálogo comum e 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 para os controles padrão da caixa de diálogo padrão. |
| modelo personalizado no estilo Explorer | O sistema usa o modelo personalizado para criar uma caixa de diálogo filho. O modelo pode definir controles adicionais e pode especificar o local do cluster de controles padrão. O modelo personalizado não substitui o modelo padrão. |
| Procedimento gancho de estilo antigo | O procedimento de gancho recebe todas as mensagens enviadas para a caixa de diálogo, incluindo mensagens para os controles padrão e quaisquer controles personalizados. O procedimento de gancho também recebe mensagens registradas enviadas da caixa de diálogo comum. |
| Modelo personalizado de estilo antigo | O modelo personalizado substitui o modelo padrão. Crie o modelo personalizado modificando o modelo padrão especificado no arquivo Fileopen.dlg. |
O título padrão para caixas de diálogo de estilo Explorer e estilo antigo é "Abrir" ou "Salvar como". Para alterar o título, especifique o novo título no membro lpstrTitle da estrutura OPENFILENAME.
O hive do registro HKEY_CURRENT_USER do usuário pode conter valores que personalizam o conteúdo das caixas de diálogo Abrir e Salvar como no estilo Explorer. Essas entradas do Registro afetam apenas as caixas de diálogo exibidas para o usuário associado ao hive do registro.
Para ocultar recursos das caixas de diálogo Abrir e Salvar como no estilo Explorer, um administrador pode definir os valores na tabela a seguir nesta subchave:
HKEY_CURRENT_USER
Software
Microsoft
Windows
CurrentVersion
Policies
Comdlg32
| Nome do valor | Valor | Significado |
|---|---|---|
| NoPlacesBar | 1 | Oculta a barra de lugares. |
| NoFileMRU | 1 | Oculta a lista MRU (usado mais recentemente). |
| NoBackButton | 1 | Oculta o botão Voltar . |
O conteúdo da barra Locais é determinado pelo conteúdo da seguinte subchave:
HKEY_CURRENT_USER
Software
Microsoft
Windows
CurrentVersion
Policies
Comdlg32
Placesbar
Atualmente, só pode haver cinco entradas sob essa chave e o índice de valor/nome é baseado em zero. Os nomes das entradas devem ser Place0, Place1, Place2, Place3 e Place4. Os valores das entradas podem ser valores REG_DWORD, REG_SZ ou REG_EXPAND_SZ que identificam locais a serem incluídos na barra de locais.
| Tipo de valor | Significado |
|---|---|
| REG_DWORD | Um valor CSIDL que identifica uma pasta. Para obter uma lista de valores CSIDL, consulte Valores CSIDL. |
| REG_SZ ou REG_EXPAND_SZ | Uma cadeia de caracteres terminada em nulo que especifica um caminho válido. |
Procedimentos de gancho de Explorer-Style
Você pode personalizar uma caixa de diálogo Abrir ou Salvar como no estilo Explorer fornecendo um procedimento de gancho, um modelo personalizado ou ambos. Se você fornecer um procedimento de gancho para uma caixa de diálogo no estilo Explorer, o sistema criará uma caixa de diálogo que é um filho da caixa de diálogo padrão. O procedimento de gancho atua como o procedimento de caixa de diálogo para a caixa de diálogo filho. Essa caixa de diálogo filho é baseada no modelo personalizado ou em um modelo padrão se nenhum for fornecido. Para obter mais informações, consulte Modelos personalizados de estilo Explorer.
Para habilitar um procedimento de gancho para uma caixa de diálogo Abrir ou Salvar como no estilo Explorer, use a estrutura OPENFILENAME ao criar a caixa de diálogo. Defina os sinalizadores OFN_ENABLEHOOK e OFN_EXPLORER no membro Flags e especifique o endereço de um procedimento de gancho OFNHookProc no membro lpfnHook . Se você fornecer um procedimento de gancho e omitir o sinalizador OFN_EXPLORER , deverá usar um procedimento de gancho OFNHookProcOldStyle e obterá a interface do usuário de estilo antigo. Para obter mais informações, consulte Personalizando caixas de diálogo de Old-Style.
Um procedimento de gancho no estilo Explorer recebe uma variedade de mensagens enquanto a caixa de diálogo está aberta. Isso inclui o seguinte:
- A mensagem WM_INITDIALOG e outras mensagens da caixa de diálogo padrão, como a mensagem de cor de controle WM_CTLCOLORDLG.
- Um conjunto de mensagens de notificação WM_NOTIFY indicando ações executadas pelo usuário ou outros eventos da caixa de diálogo.
- Mensagens para quaisquer controles adicionais que você definiu especificando um modelo de caixa de diálogo filho.
Além disso, há um conjunto de mensagens que você pode enviar para uma caixa de diálogo estilo Explorer para obter informações ou controlar o comportamento e a aparência da caixa de diálogo.
Se você fornecer um procedimento de gancho para uma caixa de diálogo no estilo Explorer, o procedimento da caixa de diálogo padrão criará uma caixa de diálogo filho quando o procedimento de diálogo padrão estiver processando sua mensagem de WM_INITDIALOG. O procedimento de gancho atua como o procedimento de caixa de diálogo para a caixa de diálogo filho. Neste momento, o procedimento de gancho recebe sua própria mensagem de WM_INITDIALOG com o parâmetro lParam definido como o endereço da estrutura OPENFILENAME usada para inicializar a caixa de diálogo. Depois que a caixa de diálogo filho terminar de processar sua própria mensagem de WM_INITDIALOG , o procedimento de diálogo padrão move os controles padrão, se necessário, para abrir espaço para quaisquer controles adicionais da caixa de diálogo filho. Em seguida, o procedimento de caixa de diálogo padrão envia a mensagem de notificação CDN_INITDONE para o procedimento de gancho.
O procedimento de gancho recebe WM_NOTIFY mensagens de notificação indicando as ações executadas pelo usuário na caixa de diálogo. Você pode usar algumas dessas mensagens para controlar o comportamento da caixa de diálogo. Por exemplo, o procedimento de gancho recebe a mensagem CDN_FILEOK quando o usuário escolhe um nome de arquivo e clica no botão OK . Em resposta a essa mensagem, o procedimento de gancho pode usar a função SetWindowLong para rejeitar o nome selecionado e forçar a caixa de diálogo a permanecer aberta.
O parâmetro lParam para cada mensagem WM_NOTIFY é um ponteiro para uma estrutura OFNOTIFY ou OFNOTIFYEX que define a ação. O membro de código no cabeçalho dessa estrutura contém uma das seguintes mensagens de notificação.
| Mensagem | Significado |
|---|---|
| CDN_FILEOK | O usuário clicou no botão OK ; a caixa de diálogo está prestes a ser fechada. |
| CDN_FOLDERCHANGE | O usuário abriu uma nova pasta ou diretório. |
| CDN_HELP | O usuário clicou no botão Ajuda . |
| CDN_INCLUDEITEM | Determina se um item deve ser exibido. Quando o usuário abre uma nova pasta ou diretório, o sistema envia essa notificação para cada item na pasta ou diretório. O sistema enviará essa notificação somente se o sinalizador de OFN_ENABLEINCLUDENOTIFY tiver sido definido. |
| CDN_INITDONE | O sistema terminou de inicializar a caixa de diálogo e a caixa de diálogo terminou de processar a mensagem WM_INITDIALOG . Além disso, o sistema terminou de organizar controles na caixa de diálogo comum para abrir espaço para os controles da caixa de diálogo filho (se houver). |
| CDN_SELCHANGE | O usuário selecionou um novo arquivo ou pasta na lista de arquivos. |
| CDN_SHAREVIOLATION | A caixa de diálogo comum encontrou uma violação de compartilhamento no arquivo prestes a ser retornado. |
| CDN_TYPECHANGE | O usuário selecionou um novo tipo de arquivo na lista de tipos de arquivo. |
Essas mensagens WM_NOTIFY substituem as mensagens registradas FILEOKSTRING, LBSELCHSTRING, SHAREVISTRING e HELPMSGSTRING usadas por versões anteriores das caixas de diálogo Abrir e Salvar como . No entanto, o procedimento de gancho também receberá a mensagem substituída após a mensagem WM_NOTIFY se o processamento de WM_NOTIFY não usar SetWindowLong para definir um valor diferente de zero DWL_MSGRESULT .
Para recuperar informações sobre o status da caixa de diálogo ou para controlar o comportamento e a aparência da caixa de diálogo, o procedimento de gancho pode enviar as mensagens a seguir para a caixa de diálogo.
| Mensagem | Significado |
|---|---|
| CDM_GETFILEPATH | Recupera o caminho e o nome do arquivo do arquivo selecionado. |
| CDM_GETFOLDERIDLIST | Recupera a lista de identificadores de item correspondente à pasta atual que a caixa de diálogo abriu. Para obter mais informações sobre listas de identificadores de item, consulte Introdução ao namespace do shell. |
| CDM_GETFOLDERPATH | Recupera o caminho da pasta ou diretório atual para a caixa de diálogo. |
| CDM_GETSPEC | Recupera o nome do arquivo (sem incluir o caminho) do arquivo selecionado atualmente na caixa de diálogo. |
| CDM_HIDECONTROL | Oculta o controle especificado. |
| CDM_SETCONTROLTEXT | Define o texto no controle especificado. |
| CDM_SETDEFEXT | Define a extensão de nome de arquivo padrão para a caixa de diálogo. |
Explorer-Style modelos personalizados
Para definir controles adicionais para uma caixa de diálogo Abrir ou Salvar como no estilo Explorer, use a estrutura OPENFILENAME para especificar um modelo para uma caixa de diálogo filho que contém os controles adicionais. Se o modelo de caixa de diálogo filho for um recurso em um aplicativo ou biblioteca de link dinâmico, defina o sinalizador OFN_ENABLETEMPLATE no membro Flags e use os membros hInstance e lpTemplateName da estrutura para identificar o módulo e o nome do recurso. Se o modelo já estiver na memória, defina o sinalizador OFN_ENABLETEMPLATEHANDLE e use o membro hInstance para identificar o objeto de memória que contém o modelo. Ao fornecer um modelo de caixa de diálogo filho para uma caixa de diálogo de estilo Explorer, você também deve definir o sinalizador OFN_EXPLORER; caso contrário, o sistema pressupõe que você esteja fornecendo um modelo de substituição para uma caixa de diálogo de estilo antigo. Normalmente, se você fornecer controles adicionais, também deverá fornecer um procedimento de gancho no estilo Explorer para processar mensagens para os novos controles.
Você pode criar seu modelo de caixa de diálogo filho como faz com qualquer outro modelo, exceto que você deve especificar os estilos de WS_CHILD e WS_CLIPSIBLINGS e deve especificar os estilos DS_3DLOOK e DS_CONTROL . O sistema requer o estilo WS_CHILD porque o modelo define uma caixa de diálogo filho da caixa de diálogo Abrir ou Salvar como padrão. O estilo WS_CLIPSIBLINGS garante que a caixa de diálogo filho não pinte sobre nenhum dos controles na caixa de diálogo padrão. O estilo DS_3DLOOK garante que a aparência dos controles na caixa de diálogo filho seja consistente com os controles na caixa de diálogo padrão. O estilo DS_CONTROL garante que o usuário possa usar a TAB e outras chaves de navegação para se mover entre todos os controles, padrão ou personalizado, na caixa de diálogo personalizada.
Para abrir espaço para os novos controles, o sistema expande a caixa de diálogo padrão pela largura e altura da caixa de diálogo personalizada. Por padrão, todos os controles da caixa de diálogo personalizada são posicionados abaixo dos controles na caixa de diálogo padrão. No entanto, você pode substituir esse posicionamento padrão incluindo um controle de texto estático em seu modelo de caixa de diálogo personalizada e atribuindo-lhe o valor do identificador de controle de stc32. (Esse valor é definido no arquivo de cabeçalho Dlgs.h.) Nesse caso, o sistema usa o controle como ponto de referência para determinar onde posicionar os novos controles. Todos os novos controles acima e à esquerda do controle stc32 são posicionados a mesma quantidade acima e à esquerda dos controles na caixa de diálogo padrão. Novos controles abaixo e à direita do controle stc32 são posicionados abaixo e à direita dos controles padrão. Em geral, cada novo controle é posicionado para que ele tenha a mesma posição em relação aos controles padrão que tinha para o controle stc32 . Para abrir espaço para esses novos controles, o sistema adiciona espaço à esquerda, à direita, à parte inferior e à parte superior da caixa de diálogo padrão, conforme necessário.
O sistema requer o procedimento de gancho para processar todas as mensagens destinadas à caixa de diálogo personalizada e, portanto, envia as mesmas mensagens de janela para o procedimento de gancho que para qualquer outro procedimento de caixa de diálogo. Por exemplo, o procedimento de gancho recebe mensagens WM_COMMAND quando o usuário clica em controles de botão na caixa de diálogo personalizada. O procedimento de gancho é responsável por inicializar esses controles e recuperar valores dos controles quando a caixa de diálogo é fechada. Observe que quando o procedimento de gancho recebe a mensagem WM_INITDIALOG , o sistema ainda não moveu os controles para suas posições finais.
O procedimento da caixa de diálogo padrão manipula mensagens para todos os controles na caixa de diálogo padrão, mas o procedimento de gancho recebe as mensagens de notificação para ações do usuário nesses controles, conforme descrito em procedimentos de gancho de estilo Explorer.
Identificadores de controle Explorer-Style
O SDK (Software Development Kit) do Windows fornece o modelo de caixa de diálogo padrão para as caixas de diálogo de estilo antigo, mas não inclui o modelo padrão para as caixas de diálogo estilo Explorer. Isso ocorre porque as caixas de diálogo estilo Explorer permitem adicionar seus próprios controles, mas não dão suporte à modificação do modelo para os controles padrão. No entanto, em alguns casos, talvez seja necessário conhecer os identificadores de controle usados nos modelos padrão. Por exemplo, as mensagens CDM_HIDECONTROL e CDM_SETCONTROLTEXT exigem um identificador de controle.
A tabela a seguir mostra os identificadores dos controles padrão nas caixas de diálogo Abrir e Salvar como no estilo Explorer. Os identificadores são constantes definidas em Dlgs.h e Winuser.h.
| Identificador do controle | Descrição do controle |
|---|---|
| chx1 | A caixa de marcar somente leitura |
| cmb1 | Caixa de combinação suspensa que exibe a lista de filtros de tipo de arquivo |
| stc2 | Rótulo para a caixa de combinação cmb1 |
| cmb2 | Caixa de combinação suspensa que exibe a unidade ou pasta atual e que permite que o usuário selecione uma unidade ou pasta para abrir |
| stc4 | Rótulo para a caixa de combinação cmb2 |
| cmb13 | A caixa de combinação suspensa que exibe o nome do arquivo atual, permite que o usuário digite o nome de um arquivo para abrir e selecione um arquivo que foi aberto ou salvo recentemente. Isso é para aplicativos compatíveis com Explorer anteriores sem gancho ou modelo de caixa de diálogo. Compare com edt1. |
| edt1 | Edite o controle que exibe o nome do arquivo atual ou permite que o usuário digite o nome do arquivo a ser aberto. Compare com cmb13. |
| stc3 | Rótulo para a caixa de combinação cmb13 e o controle de edição edt1 |
| lst1 | Caixa de listagem que exibe o conteúdo da unidade ou pasta atual |
| stc1 | Rótulo para a caixa de listagem lst1 |
| IDOK | O botão de comando OK (botão de push) |
| IDCANCEL | O botão Cancelar comando (botão de push) |
| pshHelp | O botão de comando Ajuda (botão de push) |
Personalizando caixas de diálogo Old-Style
Você pode personalizar uma caixa de diálogo Open ou Save As de estilo antigo fornecendo um procedimento de gancho OFNHookProcOldStyle que recebe mensagens ou notificações destinadas ao procedimento da caixa de diálogo padrão. Você também pode fornecer um modelo personalizado para usar no lugar do modelo padrão. Os procedimentos e modelos de gancho usados com as caixas de diálogo de estilo antigo são semelhantes aos usados com as outras caixas de diálogo comuns. Para obter mais informações, consulte Procedimentos de gancho para caixas de diálogo comuns e modelos personalizados.
Para habilitar um procedimento de gancho para uma caixa de diálogo Open ou Save As de estilo antigo, use a estrutura OPENFILENAME ao criar a caixa de diálogo. Defina o sinalizador OFN_ENABLEHOOK no membro Flags e especifique o endereço de um procedimento de gancho OFNHookProcOldStyle no membro lpfnHook . O procedimento da caixa de diálogo envia uma mensagem WM_INITDIALOG para o procedimento de gancho com o parâmetro Param definido como o endereço da estrutura OPENFILENAME usada para inicializar a caixa de diálogo.
Você pode usar a estrutura OPENFILENAME para especificar um modelo personalizado para a caixa de diálogo Abrir ou Salvar como a ser usada no lugar do modelo padrão. Se o modelo personalizado for um recurso em um aplicativo ou biblioteca de link dinâmico, defina o sinalizador OFN_ENABLETEMPLATE no membro Flags e use os membros hInstance e lpTemplateName da estrutura para identificar o módulo e o nome do recurso. Se o modelo personalizado já estiver na memória, defina o sinalizador OFN_ENABLETEMPLATEHANDLE e use o membro hInstance para identificar o objeto de memória que contém o modelo. Crie o modelo personalizado modificando o modelo padrão especificado no arquivo Fileopen.dlg. Os identificadores de controle usados nos modelos de caixa de diálogo Localizar e Substituir padrão são definidos no arquivo Dlgs.h.
Por padrão, as funções GetOpenFileName e GetSaveFileName exibem as caixas de diálogo estilo Explorer. Se quiser exibir uma caixa de diálogo de estilo antigo, forneça um procedimento de gancho OFNHookProcOldStyle e verifique se o sinalizador OFN_EXPLORER não está definido no membro Flags da estrutura OPENFILENAME .
Se você definir o sinalizador OFN_EXPLORER, o sistema tratará um procedimento de gancho ou um modelo personalizado como uma personalização no estilo Explorer. Para obter informações sobre como personalizar uma caixa de diálogo no estilo Explorer, consulte Modelos personalizados de estilo Explorer.