Personalizando caixas de diálogo comuns
Você pode usar as caixas de diálogo comuns no formulário padrão ou personalizá-las. Da perspectiva do usuário, o principal benefício da caixa de diálogo comum é sua aparência e funcionalidade consistentes de aplicativo para aplicativo. Portanto, é importante que você personalize uma caixa de diálogo comum somente quando ela for absolutamente necessária para um aplicativo. Caso contrário, a aparência consistente e a interface de codificação simples serão perdidas. As personalizações apropriadas deixam intactos o maior número possível de controles originais. Aumentar o tamanho da caixa de diálogo ou adicionar novos controles no espaço já disponível na caixa de diálogo é uma personalização apropriada. Ocultar controles originais ou alterar a funcionalidade pretendida dos controles originais é uma personalização menos apropriada.
Esta seção discute os seguintes métodos para personalizar uma caixa de diálogo comum:
- Modelos personalizados
- Procedimentos de gancho para caixas de diálogo comuns
- Mensagens de caixa de diálogo comuns
- Suporte à Ajuda
Modelos personalizados
As caixas de diálogo comuns têm modelos padrão que definem o número, o tipo e a posição dos controles padrão na caixa de diálogo. Você pode definir um modelo personalizado para dar aos usuários acesso a controles adicionais exclusivos ao seu aplicativo.
Para todas as caixas de diálogo comuns, exceto as caixas de diálogo Abrir e Salvar como no estilo Explorer, modifique o modelo padrão para criar um modelo personalizado que substitua o modelo padrão. O modelo personalizado define o tipo e a posição dos controles padrão, bem como quaisquer controles adicionais.
Ao criar um modelo de caixa de diálogo personalizado modificando o modelo de caixa de diálogo padrão, verifique se os identificadores de quaisquer controles adicionados são exclusivos e não entram em conflito com os identificadores dos controles padrão. A tabela a seguir lista o nome do arquivo de modelo padrão e o arquivo de inclusão para cada um dos tipos de caixa de diálogo comuns.
| Tipo de caixa de diálogo | Arquivo de modelo | Incluir arquivo |
|---|---|---|
| Color | Color.dlg | ColorDlg.h |
| Localizar | Findtext.dlg | Dlgs.h |
| Fonte | Font.dlg | Dlgs.h |
| Abrir (seleção múltipla) | Fileopen.dlg | Dlgs.h |
| Abrir (seleção única) | Fileopen.dlg | Dlgs.h |
| Configuração de Página | Prnsetup.dlg | Dlgs.h |
| Imprimir | Prnsetup.dlg | Dlgs.h |
| Configuração de Impressão (obsoleta) | Prnsetup.dlg | Dlgs.h |
| Substituir | Findtext.dlg | Dlgs.h |
Para habilitar um modelo personalizado, você deve definir um sinalizador no membro Flags da estrutura correspondente para a caixa de diálogo. Se o modelo for um recurso em um aplicativo ou biblioteca de link dinâmico, defina um sinalizador 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 um sinalizador ENABLETEMPLATEHANDLE no membro Flags e use o membro hInstance para identificar o objeto de memória que contém o modelo.
Na maioria dos casos, você também deve habilitar um procedimento de gancho para a caixa de diálogo para dar suporte e processar a entrada para os controles adicionais em seu modelo personalizado.
Para as caixas de diálogo Abrir e Salvar como no estilo Explorer, os modelos padrão não estão disponíveis para modificação. Em vez disso, seu modelo personalizado define uma caixa de diálogo filho que inclui apenas os itens a serem adicionados à caixa de diálogo padrão. O modelo personalizado também pode definir um controle estático que especifica o local do cluster de controles padrão na caixa de diálogo filho. Para obter mais informações, consulte Modelos personalizados de estilo Explorer.
Procedimentos de gancho para caixas de diálogo comuns
Para cada uma das caixas de diálogo comuns, você pode habilitar um procedimento de gancho para processar mensagens do procedimento da caixa de diálogo padrão. Há dois tipos gerais de procedimentos comuns de gancho de caixa de diálogo:
- O procedimento de gancho padrão usado com caixas de diálogo mais comuns
- O procedimento de gancho de estilo Explorer com suporte nas caixas de diálogo Abrir e Salvar como
Quando você fornece um procedimento de gancho padrão para uma das caixas de diálogo comuns, o procedimento da caixa de diálogo padrão manipula suas mensagens da seguinte maneira.
| Mensagem | Tratamento |
|---|---|
| WM_INITDIALOG | O procedimento da caixa de diálogo padrão processa a mensagem antes de passá-la para o procedimento de gancho. O parâmetro lParam da mensagem é um ponteiro para a estrutura de inicialização especificada quando a caixa de diálogo foi criada. |
| Todas as outras mensagens | O procedimento de gancho recebe a mensagem primeiro. Em seguida, o valor retornado do procedimento de gancho determina se o procedimento de diálogo padrão processa a mensagem ou a ignora. |
Para as caixas de diálogo Abrir e Salvar como no estilo Explorer, o procedimento de gancho não recebe mensagens destinadas aos controles padrão na caixa de diálogo. Em vez disso, ele recebe mensagens de notificação da caixa de diálogo e mensagens para quaisquer controles adicionais que você definiu em um modelo personalizado. Para obter mais informações, consulte Procedimentos de gancho de estilo Explorer.
Para habilitar um procedimento de gancho, defina um valor ENABLEHOOK no membro Flags da estrutura correspondente para a caixa de diálogo. Se um sinalizador ENABLEHOOK for definido, um membro lpfnHook da estrutura deverá especificar o endereço do procedimento de gancho.
A tabela a seguir mostra o tipo de procedimento de gancho a ser fornecido para cada uma das caixas de diálogo comuns.
| Tipo de caixa de diálogo | Procedimento de gancho |
|---|---|
| Color | CCHookProc |
| Localizar ou substituir | FRHookProc |
| Fonte | Cfhookproc |
| Abrir ou Salvar como (estilo Explorer) | OFNHookProc |
| Abrir ou Salvar como (estilo antigo) | OFNHookProcOldStyle |
| Imprimir | PrintHookProc |
| Configuração de Página | PageSetupHook |
Para a caixa de diálogo Configuração de Página , você também pode especificar um procedimento de gancho PagePaintHook . Este é um procedimento de gancho especial que você pode usar para personalizar a aparência da página de exemplo exibida pela caixa de diálogo Configuração de Página .
Observação
A caixa de diálogo Configuração de Impressão foi substituída pela caixa de diálogo Configuração de Página . Os aplicativos devem usar a caixa de diálogo Configuração de Página . No entanto, para compatibilidade, a função PrintDlg continua a dar suporte à exibição da caixa de diálogo Configuração de Impressão . Você pode fornecer um procedimento de gancho SetupHookProc para a caixa de diálogo Configuração de Impressão .
Mensagens de caixa de diálogo comuns
As caixas de diálogo comuns usam mensagens para notificar o procedimento de janela ou o procedimento de gancho quando determinados eventos ocorrem. Além disso, há mensagens que você pode enviar para uma caixa de diálogo comum para recuperar informações ou para controlar o comportamento ou a aparência da caixa de diálogo. Esta seção descreve as mensagens de diálogo comuns registradas pela função RegisterWindowMessage, as mensagens usadas pela caixa de diálogo Fonte e a caixa de diálogo Configuração de Página e as mensagens usadas pelas caixas de diálogo Abrir e Salvar como no estilo Explorer.
A Biblioteca de Caixas de Diálogo Comuns define um conjunto de cadeias de caracteres de mensagem. Você pode passar uma constante associada a uma dessas cadeias de caracteres de mensagem para RegisterWindowMessage para obter um identificador de mensagem. Em seguida, você pode usar o identificador para detectar e processar mensagens enviadas de uma caixa de diálogo comum ou para enviar mensagens para uma caixa de diálogo comum. A tabela a seguir mostra as constantes de mensagem e descreve seu uso.
| Contantes | Uso |
|---|---|
| COLOROKSTRING | Uma caixa de diálogo Cor envia essa mensagem para o procedimento de gancho quando o usuário seleciona uma cor e clica no botão OK . O procedimento de gancho pode aceitar a cor ou rejeitá-la e forçar a caixa de diálogo a permanecer aberta. |
| FILEOKSTRING | Uma caixa de diálogo Abrir ou Salvar como envia essa mensagem para o procedimento de gancho quando o usuário seleciona um nome de arquivo e clica no botão OK . O procedimento de gancho pode aceitar o nome do arquivo ou rejeitá-lo e forçar a caixa de diálogo a permanecer aberta. Para caixas de diálogo Abrir e Salvar como no estilo Explorer, essa mensagem foi substituída pela mensagem de notificação CDN_FILEOK. |
| FINDMSGSTRING | Uma caixa de diálogo Localizar ou Substituir envia essa mensagem para o procedimento de janela de sua janela pai quando o usuário clica na caixa de diálogo Localizar Próximo, Substituir ou Substituir Tudo ou fecha a caixa de diálogo. O parâmetro lParam da mensagem é um ponteiro para uma estrutura FINDREPLACE que contém a entrada do usuário. |
| HELPMSGSTRING | Todas as caixas de diálogo comuns enviam essa mensagem para o procedimento de janela da janela pai quando o usuário clica no botão Ajuda . Para caixas de diálogo Abrir e Salvar como no estilo Explorer, essa mensagem foi substituída pela mensagem de notificação CDN_HELP. |
| LBSELCHSTRING | Uma caixa de diálogo Abrir ou Salvar como envia essa mensagem para o procedimento de gancho quando o usuário altera a seleção na caixa de listagem Nome do Arquivo . Para caixas de diálogo Abrir e Salvar como no estilo Explorer, essa mensagem foi substituída pela mensagem de notificação CDN_SELCHANGE. |
| SETRGBSTRING | Um procedimento de gancho pode enviar essa mensagem para uma caixa de diálogo Cor para definir a seleção de cores atual. |
| SHAREVISTRING | Uma caixa de diálogo Abrir ou Salvar como enviará essa mensagem para o procedimento de gancho se ocorrer uma violação de compartilhamento para o arquivo selecionado quando o usuário clicar no botão OK . Para caixas de diálogo Abrir e Salvar como no estilo Explorer, essa mensagem foi substituída pela mensagem de notificação CDN_SHAREVIOLATION. |
Algumas caixas de diálogo comuns enviam e recebem outras mensagens de janela. O procedimento de gancho de uma caixa de diálogo Fonte pode enviar qualquer uma das mensagens WM_CHOOSEFONT_* para a caixa de diálogo Fonte . Para obter mais informações, consulte Caixa de diálogo Fonte. A caixa de diálogo Configuração de Página enviará as mensagens WM_PSD_* se você tiver habilitado um procedimento de gancho PagePaintHook . Para obter mais informações, consulte Caixa de diálogo Configuração de Página.
As caixas de diálogo Abrir e Salvar como no estilo Explorer dão suporte a um conjunto de mensagens predefinidas. Elas incluem mensagens de notificação enviadas na forma de uma mensagem de WM_NOTIFY para o procedimento de gancho e mensagens que o procedimento de gancho pode enviar para a caixa de diálogo. Para obter uma lista completa dessas mensagens, consulte Explorer-Style Hook Procedures.
Suporte à Ajuda
As caixas de diálogo comuns fornecem ajuda contextual para os controles padrão da caixa de diálogo. Para fornecer ajuda adicional para uma caixa de diálogo comum, você pode exibir um botão ajuda e processar mensagens geradas quando o usuário clica no botão. O botão Ajuda é um suplemento para a ajuda contextual padrão. O botão Ajuda é útil para descrever a finalidade geral da caixa de diálogo conforme ela se aplica ao seu aplicativo.
Ajuda Context-Sensitive
Todas as caixas de diálogo comuns fornecem ajuda contextual para os controles padrão da caixa de diálogo. O usuário pode exibir ajuda para controles individuais por qualquer um dos seguintes métodos:
- Selecionando o controle e pressionando a tecla F1.
- Clicando no botão ? na barra de título e, posteriormente, clicando em um controle.
- Clicando no botão direito do mouse sobre um controle.
Se você personalizar uma caixa de diálogo adicionando novos controles, também deverá estender o suporte de ajuda para esses controles processando solicitações de ajuda no procedimento de gancho. O procedimento de gancho recebe as seguintes mensagens quando o usuário solicita ajuda.
| Ação do usuário | Mensagem |
|---|---|
| Clique no botão direito do mouse sobre um controle. | WM_CONTEXTMENU |
| Pressionei a tecla F1. | WM_HELP |
| Clique no botão ? na barra de título e, em seguida, clique em um controle. | WM_HELP |
Você deve processar essas mensagens para os controles adicionados, mas permitir que o procedimento da caixa de diálogo padrão processe as mensagens para os controles padrão. Para obter mais informações sobre como processar essas mensagens, consulte Ajuda.
O botão Ajuda
Você pode exibir um botão Ajuda em qualquer uma das caixas de diálogo comuns definindo um valor SHOWHELP no membro Flags da estrutura de inicialização da caixa de diálogo. Se você exibir o botão Ajuda , deverá processar a solicitação de ajuda do usuário. O processamento pode ser feito em um dos procedimentos de janela do aplicativo ou em um procedimento de gancho para a caixa de diálogo. Normalmente, você processaria a solicitação de ajuda chamando a função WinHelp .
Para processar mensagens de ajuda em um de seus procedimentos de janela, você deve obter um identificador de mensagem para a cadeia de caracteres definida pelo valor HELPMSGSTRING e identificar a janela para receber mensagens. Para obter o identificador de mensagem, especifique HELPMSGSTRING como o parâmetro em uma chamada para a função RegisterWindowMessage . Ao criar a caixa de diálogo, use o membro hwndOwner da estrutura de inicialização da caixa de diálogo para identificar a janela que deve receber as mensagens. O procedimento da caixa de diálogo envia a mensagem para o procedimento de janela sempre que o usuário clica no botão Ajuda .
Para processar mensagens de ajuda em um procedimento de gancho, você deve processar a mensagem WM_COMMAND . O procedimento de gancho fornecerá ajuda se o parâmetro wParam desta mensagem indicar que o usuário clicou no botão Ajuda . O identificador do botão Ajuda é a constante pshHelp definida no arquivo Dlgs.h.
Os procedimentos de gancho para as caixas de diálogo Abrir e Salvar como no estilo Explorer não recebem mensagens WM_COMMAND para o botão Ajuda. Em vez disso, a caixa de diálogo envia uma mensagem de notificação CDN_HELP para o procedimento de gancho quando o botão Ajuda é clicado.