Biblioteca de caixas de diálogo comuns
A Biblioteca de caixa de diálogo comum contém um conjunto de caixas de diálogo para executar tarefas comuns de aplicativos, como abrir arquivos, escolher valores de cores e imprimir documentos. As caixas de diálogo comuns permitem que você implemente uma abordagem consistente para a interface do usuário do seu aplicativo. Isso reduz a quantidade de esforço que os usuários gastam para aprender o comportamento da interface do usuário para seu aplicativo.
Esta seção descreve as caixas de diálogo comuns que incluem as caixas de diálogo dos arquivos Abrir e Salvar como; as caixas de diálogo de edição Localizar e Substituir; as caixas de diálogo de impressão Imprimir, Configuração de impressão, Folha de propriedade de impressão e Configurar Página ; e as caixas de diálogo Cor e Fonte.
Observação
A partir do Windows Vista, as caixas de diálogo comuns Abrir e Salvar como foram substituídas por Diálogo de itens comuns. Recomendamos que você use a API de Caixa de Diálogo de Item Comum em vez dessas caixas de diálogo da Biblioteca de Caixa de Diálogo Comum.
Nesta seção
| Nome | Descrição |
|---|---|
| Tipos de caixa de diálogo comum | Discute as diferentes caixas de diálogo. |
| Sinalizadores de inicialização de caixa de diálogo comuns | Discute como os sinalizadores são usados para modificar o comportamento e a aparência de uma caixa de diálogo comum. |
| Personalizar caixas de diálogo comuns | Discute como usar caixas de diálogo comuns. |
| Uso de caixas de diálogo comuns | Aborda tarefas que invocam caixas de diálogo comuns. |
| Referência de caixa de diálogo comum | Contém a referência de API. |
Funções
| Nome | Descrição |
|---|---|
| CCHookProc | Recebe mensagens ou notificações destinadas ao procedimento padrão da caixa de diálogo Cor. Essa é uma função de retorno de chamada definida pelo aplicativo ou pela biblioteca que é usada com a função ChooseColor. |
| CFHookProc | Recebe mensagens ou notificações destinadas ao procedimento padrão da caixa de diálogo Fonte. Esse é um procedimento de retorno de chamada definido pelo aplicativo ou pela biblioteca que é usado com a função ChooseFont. |
| ChooseColor | Cria uma caixa de diálogo Cor que habilita ao usuário selecionar uma cor. |
| ChooseFont | Cria uma caixa de diálogo Fonte que habilita ao usuário escolher atributos para uma fonte lógica. Esses atributos incluem uma família de fontes e um estilo de fonte associado, um tamanho de ponto, efeitos (sublinhado, riscado e cor do texto) e um script (ou conjunto de caracteres). |
| CommDlgExtendedError | Retorna um código de erro comum da caixa de diálogo. Esse código indica o erro mais recente que ocorreu durante a execução de uma das funções comuns da caixa de diálogo. |
| FindText | Cria uma caixa de diálogo Localizar sem modelo definido pelo sistema que permite ao usuário especificar uma cadeia de caracteres para pesquisar e opções a serem usadas ao pesquisar texto em um documento. |
| FRHookProc | Recebe mensagens ou notificações destinadas ao procedimento da caixa de diálogo padrão da caixa de diálogo Localizar ou Substituir. Essa é uma função de retorno de chamada definida pelo aplicativo ou pela biblioteca que é usada com a função FindText ou ReplaceText. |
| GetFileTitle | Recupera o nome do arquivo especificado. |
| GetOpenFileName | Cria uma caixa de diálogo Abrir que permite ao usuário especificar a unidade, o diretório e o nome de um arquivo ou conjunto de arquivos a serem abertos. |
| GetSaveFileName | Cria uma caixa de diálogo Salvar que permite ao usuário especificar a unidade, o diretório e o nome de um arquivo a ser salvo. |
| OFNHookProc | Recebe mensagens de notificação enviadas da caixa de diálogo. A função também recebe mensagens para quaisquer controles adicionais que você definiu especificando um modelo de caixa de diálogo filho. Essa é uma função de retorno de chamada definida pelo aplicativo ou pela biblioteca que é usada com as caixas de diálogo Abrir e Salvar como no estilo do Explorer. |
| OFNHookProcOldStyle | Recebe mensagens ou notificações destinadas ao procedimento da caixa de diálogo. Essa é uma função de retorno de chamada definida pelo aplicativo ou pela biblioteca que é usada com a caixa de diálogo Abrir e Salvar como. |
| PagePaintHook | Recebe mensagens que permitem personalizar o desenho da página de exemplo na caixa de diálogo Configurar Página. Essa é uma função de retorno de chamada definida pelo aplicativo ou pela biblioteca usada com a função PageSetupDlg. |
| PageSetupDlg | Cria uma caixa de diálogo Configurar página que habilita ao usuário especificar os atributos de uma página impressa. Esses atributos incluem o tamanho e a origem do papel, a orientação da página (retrato ou paisagem) e a largura das margens da página. |
| PageSetupHook | Recebe mensagens ou notificações destinadas ao procedimento padrão da caixa de diálogo Configurar página. Essa é uma função de retorno de chamada definida pelo aplicativo ou pela biblioteca usada com a funçãoPageSetupDlg. |
| PrintDlg | Exibe a caixa de diálogo Caixa de diálogo Imprimir. A caixa de diálogo Imprimir habilita que o usuário especifique as propriedades de um trabalho de impressão específico. |
| PrintDlgEx | Exibe uma folha de propriedades Imprimir que habilita o usuário a especificar as propriedades de um determinado trabalho de impressão. Uma folha de propriedades Imprimir tem uma página Geral que contém controles semelhantes aos da caixa de diálogo Imprimir. A folha de propriedades também pode ter páginas de propriedades adicionais específicas do aplicativo e do driver, bem como a página Geral. |
| PrintHookProc | Recebe mensagens ou notificações destinadas ao procedimento padrão da caixa de diálogo Imprimir. Essa é uma função de retorno de chamada definida pelo aplicativo ou pela biblioteca que é usada com a função PrintDlg. |
| ReplaceText | Cria uma caixa de diálogo sem janela restrita definida pelo sistema que permite ao usuário especificar uma cadeia de caracteres a ser pesquisada e uma cadeia de caracteres de substituição, bem como opções para controlar as operações de localização e substituição. |
| SetupHookProc | Uma função de retorno de chamada definida pelo aplicativo ou pela biblioteca que é usada com a função PrintDlg. O procedimento de gancho recebe mensagens ou notificações destinadas ao procedimento de caixa de diálogo padrão da caixa de diálogo Configuração de Impressão. |
Interfaces
| Nome | Descrição |
|---|---|
| IPrintDialogCallback | Fornece métodos que habilitam que um aplicativo receba notificações e mensagens da função PrintDlgEx enquanto a Folha de propriedade de impressão é exibida. |
| IPrintDialogServices | Fornece métodos que habilitam que um aplicativo que usa a função PrintDlgEx recupere informações sobre a impressora selecionada no momento. |
Mensagens
| Nome | Descrição |
|---|---|
| CDM_GETFILEPATH | Recupera o caminho e o nome do arquivo selecionado em uma caixa de diálogo Abrir ou Salvar como no estilo do Explorer. A caixa de diálogo deve ter sido criada com o sinalizador OFN_EXPLORER. Caso contrário, a mensagem falhará. |
| CDM_GETFOLDERIDLIST | Recupera o endereço da lista de identificadores de itens correspondente à pasta que um arquivo do tipo Explorer da caixa de diálogo Abrir ou Salvar como que está aberta no momento. A caixa de diálogo deve ter sido criada com o sinalizador OFN_EXPLORER. Caso contrário, a mensagem falhará. |
| CDM_GETFOLDERPATH | Recupera o caminho da pasta ou do diretório aberto no momento para uma caixa de diálogo Abrir ou Salvar como no estilo Explorer. A caixa de diálogo deve ter sido criada com o sinalizador OFN_EXPLORER. Caso contrário, a mensagem falhará. |
| CDM_GETSPEC | Recupera o nome do arquivo (sem incluir o caminho) do arquivo selecionado no momento em uma caixa de diálogo Abrir ou Salvar como no estilo Explorer. A caixa de diálogo deve ter sido criada com o sinalizador OFN_EXPLORER. Caso contrário, a mensagem falhará. |
| CDM_HIDECONTROL | Oculta o controle especificado em uma caixa de diálogo Abrir ou Salvar como no estilo Explorer. A caixa de diálogo deve ter sido criada com o sinalizador OFN_EXPLORER. Caso contrário, a mensagem falhará. |
| CDM_SETCONTROLTEXT | Define o texto do controle especificado em uma caixa de diálogo Abrir ou Salvar como no estilo Explorer. A caixa de diálogo deve ter sido criada com o sinalizador OFN_EXPLORER. Caso contrário, a mensagem falhará. |
| CDM_SETDEFEXT | Define a extensão de nome de arquivo padrão para uma caixa de diálogo Abrir ou Salvar como no estilo Explorer. A caixa de diálogo deve ter sido criada com o sinalizador OFN_EXPLORER. Caso contrário, a mensagem falhará. |
| SETRGBSTRING | O procedimento de gancho de uma caixa de diálogo Cor e CCHookProc, pode enviar a mensagem registrada SETRGBSTRING para a caixa de diálogo para definir a seleção da cor atual. |
| WM_CHOOSEFONT_GETLOGFONT | Um aplicativo envia a mensagem WM_CHOOSEFONT_GETLOGFONT para uma caixa de diálogo Fonte para recuperar informações sobre as seleções de fonte atuais do usuário. |
| WM_CHOOSEFONT_SETFLAGS | Um aplicativo envia a mensagem WM_CHOOSEFONT_SETFLAGS para uma caixa de diálogo Fonte para definir as opções de exibição da caixa de diálogo. |
| WM_CHOOSEFONT_SETLOGFONT | Um aplicativo envia a mensagem WM_CHOOSEFONT_SETLOGFONT para uma caixa de diálogo Fonte para definir as informações de fonte lógica atuais. |
Notificações
| Nome | Descrição |
|---|---|
| CDN_FILEOK | Enviado por uma caixa de diálogo Abrir ou Salvar como no estilo do Explorer, quando o usuário especifica um nome de arquivo e clica no botão OK. |
| CDN_FOLDERCHANGE | Enviado por uma caixa de diálogo Abrir ou Salvar como no estilo Explorer quando uma nova pasta é aberta. |
| CDN_HELP | Enviado por uma caixa de diálogo Abrir ou Salvar como no estilo Explorer quando o usuário clica no botão Ajuda. |
| CDN_INCLUDEITEM | Enviado por uma caixa de diálogo Abrir ou Salvar como para determinar se a caixa de diálogo deve exibir um item na lista de itens de uma pasta shell. Quando o usuário abre uma pasta, a caixa de diálogo envia uma notificação de CDN_INCLUDEITEM para cada item na pasta. A caixa de diálogo enviará essa notificação somente se o sinalizador OFN_ENABLEINCLUDENOTIFY tiver sido definido quando a caixa de diálogo foi criada. |
| CDN_INITDONE | Enviado por uma caixa de diálogo Abrir ou Salvar como no estilo Explorer quando o sistema tiver terminado de organizar os controles na caixa de diálogo. O sistema move os controles padrão para liberar espaço para os controles da caixa de diálogo filho. |
| CDN_SELCHANGE | Enviado por uma caixa de diálogo Abrir ou Salvar como no estilo Explorer, quando a seleção muda na caixa de listagem que exibe o conteúdo da pasta ou do diretório aberto no momento. |
| CDN_SHAREVIOLATION | Enviado por uma caixa de diálogo Abrir ou Salvar como no estilo Explorer quando o usuário clica no botão OK e ocorre uma violação de compartilhamento de rede para o arquivo selecionado. |
| CDN_TYPECHANGE | Enviado por uma caixa de diálogo Abrir ou Salvar como no estilo Explorer quando o usuário seleciona um novo tipo de arquivo na caixa de combinação de tipos de arquivo. |
| COLOROKSTRING | Uma caixa de diálogo Cor envia uma mensagem registrada COLOROKSTRING para seu procedimento de gancho, CCHookProc, quando o usuário seleciona uma cor e clica no botão OK. O procedimento de gancho pode aceitar a cor e permitir que a caixa de diálogo feche ou rejeitar a cor e forçar a caixa de diálogo a permanecer aberta. |
| FILEOKSTRING | Uma caixa de diálogo Abrir ou Salvar como envia uma mensagem registrada FILEOKSTRING para o seu procedimento de gancho, OFNHookProc quando o usuário especifica um nome de arquivo e clica no botão OK. O procedimento de gancho pode aceitar o nome do arquivo e permitir que a caixa de diálogo seja fechada, ou rejeitar o nome do arquivo e forçar a caixa de diálogo a permanecer aberta. |
| FINDMSGSTRING | Uma caixa de diálogo Localizar ou Substituir envia uma mensagem registrada FINDMSGSTRING para o procedimento de janela de sua janela principal quando o usuário clica no botão Localizar próximo, Substituir ou Substituir todos ou fecha a caixa de diálogo. |
| HELPMSGSTRING | Uma caixa de diálogo comum envia a mensagem registrada HELPMSGSTRING para o procedimento de janela de sua janela proprietária quando o usuário clica no botão Ajuda. |
| LBSELCHSTRING | Uma caixa de diálogo Abrir ou Salvar como envia a mensagem registrada LBSELCHSTRING para o procedimento de gancho quando a seleção é alterada em qualquer uma das caixas de listagem ou caixas de combinação da caixa de diálogo. |
| SHAREVISTRING | Uma caixa de diálogo Abrir ou Salvar como envia a mensagem registrada SHAREVISTRING para o procedimento de gancho, OFNHookProc, se ocorrer uma violação de compartilhamento para o arquivo selecionado quando o usuário clicar no botão OK. |
| WM_PSD_ENVSTAMPRECT | Notifica o procedimento de gancho de uma caixa de diálogo Configurar Página, PagePaintHook, que a caixa de diálogo está prestes a desenhar o retângulo de carimbo de envelope da página de exemplo. |
| WM_PSD_FULLPAGERECT | Notifica um procedimento de gancho PagePaintHook sobre as coordenadas do retângulo de página de exemplo na caixa de diálogo Configurar página. A caixa de diálogo envia essa mensagem quando está prestes a desenhar o conteúdo da página de exemplo. |
| WM_PSD_GREEKTEXTRECT | Notifica o procedimento de gancho de uma caixa de diálogo Configurar Página, PagePaintHook, que a caixa de diálogo está prestes a desenhar texto grego dentro do retângulo de margem da página de exemplo. |
| WM_PSD_MARGINRECT | Notifica o procedimento de gancho de uma caixa de diálogo Configurar Página, PagePaintHook, que a caixa de diálogo está prestes a desenhar o retângulo da margem da página de exemplo. |
| WM_PSD_MINMARGINRECT | Notifica um procedimento de gancho PagePaintHook das coordenadas do retângulo de margem na página de exemplo. Uma caixa de diálogo Configurar Página envia essa mensagem quando está prestes a desenhar o conteúdo da página de exemplo. |
| WM_PSD_PAGESETUPDLG | Notifica um procedimento de gancho PagePaintHook de que a caixa de diálogo Configurar Página está prestes a desenhar o conteúdo da página de exemplo. O procedimento de gancho pode usar essa mensagem para executar tarefas de inicialização relacionadas ao desenho do conteúdo da página de exemplo. |
| WM_PSD_YAFULLPAGERECT | Notifica o procedimento de gancho de uma caixa de diálogo Configurar Página, PagePaintHook, que a caixa de diálogo está prestes a desenhar a parte do endereço de retorno de uma página de exemplo de envelope. |
Estruturas
| Nome | Descrição |
|---|---|
| CHOOSECOLOR | Contém informações que a função ChooseColor usa para inicializar a caixa de diálogo Cor. 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. |
| CHOOSEFONT | Contém informações que a função ChooseFont usa para inicializar a caixa de diálogo Fonte. 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. |
| DEVNAMES | Contém cadeias de caracteres que identificam os nomes de driver, dispositivo e porta de saída de uma impressora. As funções PrintDlgEx e PrintDlg usam essas cadeias de caracteres para inicializar a Folha de propriedade de impressão ou Caixa de diálogo Imprimir. Quando o usuário fecha a folha de propriedades ou a caixa de diálogo, as informações sobre a impressora selecionada são retornadas nessa estrutura. |
| FINDREPLACE | Contém informações que as funções FindText e ReplaceText usam para inicializar as caixas de diálogo Localizar e Substituir. A mensagem registrada FINDMSGSTRING usa essa estrutura para passar a entrada de pesquisa ou substituição do usuário para a janela do proprietário de uma caixa de diálogo Localizar ou Substituir. |
| OFNOTIFY | Contém informações sobre uma mensagem WM_NOTIFY enviada para um procedimento de gancho OFNHookProc para uma caixa de diálogo Abrir ou Salvar como. O parâmetro lParam da mensagem WM_NOTIFY é um ponteiro para uma estrutura OFNOTIFY. |
| OFNOTIFYEX | Contém informações sobre uma mensagem de notificação CDN_INCLUDEITEM. |
| OPENFILENAME | 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. |
| OPENFILENAME_NT4 | Idêntico a OPENFILENAME com _WIN32_WINNT definido como 0x0400. |
| PAGESETUPDLG | Contém informações que a função PageSetupDlg usa para inicializar a caixa de diálogo Configurar Página. Depois que o usuário fecha a caixa de diálogo, o sistema retorna informações sobre os parâmetros de página definidos pelo usuário nessa estrutura. |
| PRINTDLG | Contém informações que a função PrintDlg usa para inicializar a Caixa de diálogo Imprimir. Depois que o usuário fecha a caixa de diálogo, o sistema usa essa estrutura para retornar informações sobre as seleções do usuário. |
| PRINTDLGEX | Contém informações que a função PrintDlgEx usa para inicializar a Folha de propriedade de impressão. Depois que o usuário fecha a folha de propriedades, o sistema usa essa estrutura para retornar informações sobre as seleções do usuário. |
| PRINTPAGERANGE | Especifica um intervalo de páginas em um trabalho de impressão. Um trabalho de impressão pode ter mais de um intervalo de páginas. Essas informações são fornecidas na estrutura PRINTDLGEX ao chamar a função PrintDlgEx. |