Compartilhar via

Sobre caixas de diálogo

  • Artigo

Há muitas funções, mensagens e controles predefinidos para ajudar a criar e gerenciar caixas de diálogo, facilitando o desenvolvimento da interface do usuário para um aplicativo. Essa visão geral descreve as funções e mensagens da caixa de diálogo e explica como usá-las para criar e usar caixas de diálogo.

Essa visão geral inclui os seguintes tópicos:

Para obter mais informações sobre as caixas de diálogo comuns, consulte Biblioteca de Caixas de Diálogo Comuns.

Quando usar uma caixa de diálogo

A maioria dos aplicativos usa caixas de diálogo para solicitar informações adicionais para itens de menu que exigem entrada do usuário. Usar uma caixa de diálogo é a única maneira recomendada para um aplicativo recuperar a entrada. Por exemplo, um item de menu Open típico requer o nome de um arquivo para abrir, portanto, um aplicativo deve usar uma caixa de diálogo para solicitar o nome ao usuário. Nesses casos, o aplicativo cria a caixa de diálogo quando o usuário clica no item de menu e destrói a caixa de diálogo imediatamente após o usuário fornecer as informações.

Muitos aplicativos também usam caixas de diálogo para exibir informações ou opções enquanto o usuário trabalha em outra janela. Por exemplo, os aplicativos de processamento de palavras geralmente usam uma caixa de diálogo com uma opção de pesquisa de texto. Enquanto o aplicativo pesquisa o texto, a caixa de diálogo permanece na tela. Em seguida, o usuário pode retornar à caixa de diálogo e pesquisar a mesma palavra novamente; ou o usuário pode alterar a entrada na caixa de diálogo e pesquisar uma nova palavra. Os aplicativos que usam caixas de diálogo dessa maneira normalmente criam uma quando o usuário clica no item de menu e continua a exibi-lo enquanto o aplicativo é executado ou até que o usuário feche explicitamente a caixa de diálogo.

Para dar suporte às diferentes maneiras como os aplicativos usam caixas de diálogo, há dois tipos de caixa de diálogo: modal e modeless. Uma caixa de diálogo modal exige que o usuário forneça informações ou cancele a caixa de diálogo antes de permitir que o aplicativo continue. Os aplicativos usam caixas de diálogo modais em conjunto com itens de menu que exigem informações adicionais antes que possam continuar. Uma caixa de diálogo de modelagem permite que o usuário forneça informações e retorne à tarefa anterior sem fechar a caixa de diálogo. As caixas de diálogo modais são mais simples de gerenciar do que as caixas de diálogo modeless porque são criadas, executam suas tarefas e são destruídas chamando uma única função.

Para criar uma caixa de diálogo modal ou modeless, um aplicativo deve fornecer um modelo de caixa de diálogo para descrever o estilo e o conteúdo da caixa de diálogo; o aplicativo também deve fornecer um procedimento de caixa de diálogo para realizar tarefas. O modelo da caixa de diálogo é uma descrição binária da caixa de diálogo e dos controles que ele contém. O desenvolvedor pode criar esse modelo como um recurso a ser carregado do arquivo executável do aplicativo ou criado na memória enquanto o aplicativo é executado. O procedimento da caixa de diálogo é uma função de retorno de chamada definida pelo aplicativo que o sistema chama quando tem entrada para a caixa de diálogo ou tarefas para que a caixa de diálogo seja executada. Embora um procedimento de caixa de diálogo seja semelhante a um procedimento de janela, ele não tem as mesmas responsabilidades.

Um aplicativo normalmente cria uma caixa de diálogo usando a função DialogBox ou CreateDialog . DialogBox cria uma caixa de diálogo modal; CreateDialog cria uma caixa de diálogo modeless. Essas duas funções carregam um modelo de caixa de diálogo do arquivo executável do aplicativo e criam uma janela pop-up que corresponde às especificações do modelo. Há outras funções que criam uma caixa de diálogo usando modelos na memória; eles passam informações adicionais para o procedimento da caixa de diálogo à medida que a caixa de diálogo é criada.

As caixas de diálogo geralmente pertencem a uma classe de janela predefinida e exclusiva. O sistema usa essa classe de janela e seu procedimento de janela correspondente para caixas de diálogo modal e modeless. Quando a função é chamada, ela cria a janela para a caixa de diálogo, bem como as janelas para os controles na caixa de diálogo e envia mensagens selecionadas para o procedimento da caixa de diálogo. Embora a caixa de diálogo esteja visível, o procedimento de janela predefinido gerencia todas as mensagens, processando algumas mensagens e passando outras para o procedimento da caixa de diálogo para que o procedimento possa realizar tarefas. Os aplicativos não têm acesso direto à classe de janela ou ao procedimento de janela predefinido, mas podem usar o modelo da caixa de diálogo e o procedimento da caixa de diálogo para modificar o estilo e o comportamento de uma caixa de diálogo.

Janela Proprietário da Caixa de Diálogo

A maioria das caixas de diálogo tem uma janela de proprietário (ou, mais simplesmente, um proprietário). Ao criar a caixa de diálogo, o aplicativo define o proprietário especificando o identificador de janela do proprietário. O sistema usa o proprietário para determinar a posição da caixa de diálogo na ordem Z para que a caixa de diálogo seja sempre posicionada acima de seu proprietário. Além disso, o sistema pode enviar mensagens para o procedimento de janela do proprietário, notificando-o de eventos na caixa de diálogo.

O sistema oculta ou destrói automaticamente a caixa de diálogo sempre que seu proprietário está oculto ou destruído. Isso significa que o procedimento da caixa de diálogo não requer processamento especial para detectar alterações no estado da janela de proprietário.

Como a caixa de diálogo típica é usada em conjunto com um item de menu, a janela do proprietário geralmente é a janela que contém o menu. Embora seja possível criar uma caixa de diálogo sem proprietário, não é recomendável. Por exemplo, quando uma caixa de diálogo modal não tem proprietário, o sistema não desabilita nenhuma das outras janelas do aplicativo e permite que o usuário continue a realizar trabalhos nas outras janelas, derrotando a finalidade da caixa de diálogo modal.

Quando uma caixa de diálogo modeless não tem proprietário, o sistema não oculta nem destrói a caixa de diálogo quando outras janelas do aplicativo são ocultas ou destruídas. Embora isso não derrote a finalidade da caixa de diálogo modeless, isso exige que o aplicativo realize processamento especial para garantir que a caixa de diálogo seja ocultada e destruída em momentos apropriados.

Caixas de mensagem

Uma caixa de mensagem é uma caixa de diálogo especial que um aplicativo pode usar para exibir mensagens e solicitar uma entrada simples. Uma caixa de mensagem normalmente contém uma mensagem de texto e um ou mais botões. Um aplicativo cria a caixa de mensagem usando a função MessageBox ou MessageBoxEx , especificando o texto e o número e os tipos de botões a serem exibidos. Observe que atualmente não há diferença entre como MessageBox e MessageBoxEx funcionam.

Embora a caixa de mensagem seja uma caixa de diálogo, o sistema assume o controle completo da criação e do gerenciamento da caixa de mensagem. Isso significa que o aplicativo não fornece um modelo de caixa de diálogo e um procedimento de caixa de diálogo. O sistema cria seu próprio modelo com base no texto e nos botões especificados para a caixa de mensagem e fornece seu próprio procedimento de caixa de diálogo.

Uma caixa de mensagem é uma caixa de diálogo modal e o sistema a cria usando as mesmas funções internas que o DialogBox usa. Se o aplicativo especificar uma janela de proprietário ao chamar MessageBox ou MessageBoxEx, o sistema desabilita o proprietário. Um aplicativo também pode direcionar o sistema para desabilitar todas as janelas de nível superior pertencentes ao thread atual especificando o valor MB_TASKMODAL ao criar a caixa de diálogo.

O sistema pode enviar mensagens para o proprietário, como WM_CANCELMODE e WM_ENABLE, assim como faz ao criar uma caixa de diálogo modal. A janela do proprietário deve executar todas as ações solicitadas por essas mensagens.

Uma caixa de diálogo modal deve ser uma janela pop-up com um menu de janela, uma barra de título e uma borda grossa; ou seja, o modelo da caixa de diálogo deve especificar os estilos WS_POPUP, WS_SYSMENU, WS_CAPTION e DS_MODALFRAME . Embora um aplicativo possa designar o estilo WS_VISIBLE , o sistema sempre exibe uma caixa de diálogo modal, independentemente de o modelo da caixa de diálogo especificar o estilo WS_VISIBLE . Um aplicativo não deve criar uma caixa de diálogo modal com o estilo WS_CHILD . Uma caixa de diálogo modal com esse estilo desabilita a si mesma, impedindo que qualquer entrada subsequente chegue ao aplicativo.

Um aplicativo cria uma caixa de diálogo modal usando a função DialogBox ou DialogBoxIndirect . DialogBox requer o nome ou o identificador de um recurso que contém um modelo de caixa de diálogo; DialogBoxIndirect requer um identificador para um objeto de memória que contém um modelo de caixa de diálogo. As funções DialogBoxParam e DialogBoxIndirectParam também criam caixas de diálogo modais; elas são idênticas às funções mencionadas anteriormente, mas passam um parâmetro especificado para o procedimento da caixa de diálogo quando a caixa de diálogo é criada.

Ao criar a caixa de diálogo modal, o sistema a torna a janela ativa. A caixa de diálogo permanece ativa até que o procedimento da caixa de diálogo chame a função EndDialog ou o sistema ative uma janela em outro aplicativo. Nem o usuário nem o aplicativo podem tornar a janela do proprietário ativa até que a caixa de diálogo modal seja destruída.

Quando a janela do proprietário ainda não está desabilitada, o sistema desabilita automaticamente a janela e as janelas filho que pertencem a ela quando cria a caixa de diálogo modal. A janela do proprietário permanece desabilitada até que a caixa de diálogo seja destruída. Embora um procedimento de caixa de diálogo possa potencialmente habilitar a janela do proprietário a qualquer momento, habilitar o proprietário derrota a finalidade da caixa de diálogo modal e não é recomendado. Quando o procedimento da caixa de diálogo é destruído, o sistema habilita a janela do proprietário novamente, mas somente se a caixa de diálogo modal fez com que o proprietário fosse desabilitado.

À medida que o sistema cria a caixa de diálogo modal, ele envia a mensagem WM_CANCELMODE para a janela (se houver) capturando a entrada do mouse no momento. Um aplicativo que recebe essa mensagem deve liberar a captura do mouse para que o usuário possa mover o mouse na caixa de diálogo modal. Como o sistema desabilita a janela do proprietário, toda a entrada do mouse será perdida se o proprietário não liberar o mouse ao receber essa mensagem.

Para processar mensagens para a caixa de diálogo modal, o sistema inicia seu próprio loop de mensagem, tomando o controle temporário da fila de mensagens para todo o aplicativo. Quando o sistema recupera uma mensagem que não é explicitamente para a caixa de diálogo, ele envia a mensagem para a janela apropriada. Se recuperar uma mensagem WM_QUIT, ela postará a mensagem de volta na fila de mensagens do aplicativo para que o loop de mensagem main do aplicativo possa eventualmente recuperar a mensagem.

O sistema envia a mensagem WM_ENTERIDLE para a janela do proprietário sempre que a fila de mensagens do aplicativo estiver vazia. O aplicativo pode usar essa mensagem para realizar uma tarefa em segundo plano enquanto a caixa de diálogo permanece na tela. Quando um aplicativo usa a mensagem dessa forma, o aplicativo deve frequentemente produzir controle (por exemplo, usando a função PeekMessage ) para que a caixa de diálogo modal possa receber qualquer entrada do usuário. Para impedir que a caixa de diálogo modal envie as mensagens WM_ENTERIDLE , o aplicativo pode especificar o estilo DS_NOIDLEMSG ao criar a caixa de diálogo.

Um aplicativo destrói uma caixa de diálogo modal usando a função EndDialog . Na maioria dos casos, o procedimento da caixa de diálogo chama EndDialog quando o usuário clica em Fechar no menu da janela da caixa de diálogo ou clica no botão OK ou Cancelar na caixa de diálogo. A caixa de diálogo pode retornar um valor por meio da função DialogBox (ou outras funções de criação) especificando um valor ao chamar a função EndDialog . O sistema retorna esse valor depois de destruir a caixa de diálogo. A maioria dos aplicativos usa esse valor retornado para determinar se a caixa de diálogo concluiu sua tarefa com êxito ou foi cancelada pelo usuário. O sistema não retorna o controle da função que cria a caixa de diálogo até que o procedimento da caixa de diálogo tenha chamado a função EndDialog .

Caixas de diálogo Modeless

Uma caixa de diálogo de modelagem deve ser uma janela pop-up com um menu de janela, uma barra de título e uma borda fina; ou seja, o modelo da caixa de diálogo deve especificar os estilos WS_POPUP, WS_CAPTION, WS_BORDER e WS_SYSMENU . O sistema não exibe automaticamente a caixa de diálogo, a menos que o modelo especifique o estilo WS_VISIBLE .

Um aplicativo cria uma caixa de diálogo modeless usando a função CreateDialog ou CreateDialogIndirect . CreateDialog requer o nome ou o identificador de um recurso que contém um modelo de caixa de diálogo; CreateDialogIndirect requer um identificador para um objeto de memória que contém um modelo de caixa de diálogo. Duas outras funções, CreateDialogParam e CreateDialogIndirectParam, também criam caixas de diálogo modeless; eles passam um parâmetro especificado para o procedimento da caixa de diálogo quando a caixa de diálogo é criada.

CreateDialog e outras funções de criação retornam um identificador de janela para a caixa de diálogo. O aplicativo e o procedimento da caixa de diálogo podem usar esse identificador para gerenciar a caixa de diálogo. Por exemplo, se WS_VISIBLE não for especificado no modelo da caixa de diálogo, o aplicativo poderá exibir a caixa de diálogo passando o identificador de janela para a função ShowWindow .

Uma caixa de diálogo de modelagem não desabilita a janela do proprietário nem envia mensagens para ela. Ao criar a caixa de diálogo, o sistema a torna a janela ativa, mas o usuário ou o aplicativo podem alterar a janela ativa a qualquer momento. Se a caixa de diálogo ficar inativa, ela permanecerá acima da janela proprietário na ordem Z, mesmo que a janela do proprietário esteja ativa.

O aplicativo é responsável por recuperar e expedir mensagens de entrada para a caixa de diálogo. A maioria dos aplicativos usa o loop de mensagem main para isso. Para permitir que o usuário se mova para e selecione controles usando o teclado, no entanto, o aplicativo deve chamar a função IsDialogMessage . Para obter mais informações sobre essa função, consulte Interface de teclado da caixa de diálogo.

Uma caixa de diálogo modeless não pode retornar um valor para o aplicativo como faz uma caixa de diálogo modal, mas o procedimento da caixa de diálogo pode enviar informações para a janela do proprietário usando a função SendMessage .

Um aplicativo deve destruir todas as caixas de diálogo de modelagem antes de encerrar. Ele pode destruir uma caixa de diálogo de modelagem usando a função DestroyWindow . Na maioria dos casos, o procedimento da caixa de diálogo chama DestroyWindow em resposta à entrada do usuário, como clicar no botão Cancelar . Se o usuário nunca fechar a caixa de diálogo dessa forma, o aplicativo deverá chamar DestroyWindow.

DestroyWindow invalida o identificador de janela para a caixa de diálogo, portanto, todas as chamadas subsequentes para funções que usam o identificador retornam valores de erro. Para evitar erros, o procedimento da caixa de diálogo deve notificar o proprietário de que a caixa de diálogo foi destruída. Muitos aplicativos mantêm uma variável global que contém o identificador para a caixa de diálogo. Quando o procedimento da caixa de diálogo destrói a caixa de diálogo, ele também define a variável global como NULL, indicando que a caixa de diálogo não é mais válida.

O procedimento da caixa de diálogo não deve chamar a função EndDialog para destruir uma caixa de diálogo de modelagem.

Modelos de caixa de diálogo

Um modelo de caixa de diálogo são dados binários que descrevem a caixa de diálogo, definindo sua altura, largura, estilo e os controles que ele contém. Para criar uma caixa de diálogo, o sistema carrega um modelo de caixa de diálogo dos recursos no arquivo executável do aplicativo ou usa o modelo passado para ele na memória global pelo aplicativo. Em ambos os casos, o aplicativo deve fornecer um modelo ao criar uma caixa de diálogo.

Um desenvolvedor cria recursos de modelo usando um compilador de recursos ou um editor de caixa de diálogo. Um compilador de recursos converte uma descrição de texto em um recurso binário e um editor de caixa de diálogo salva uma caixa de diálogo interativamente construída como um recurso binário.

Observação

Uma explicação de como criar recursos de modelo e adicioná-los ao arquivo executável do aplicativo está além do escopo dessa visão geral. Para obter mais informações sobre como criar recursos de modelo e adicioná-los a um arquivo executável, consulte a documentação fornecida com suas ferramentas de desenvolvimento de aplicativos.

 

Para criar uma caixa de diálogo sem usar recursos de modelo, você deve criar um modelo na memória e passá-lo para a função CreateDialogIndirectParam ou DialogBoxIndirectParam ou para a macro CreateDialogIndirect ou DialogBoxIndirect .

Um modelo de caixa de diálogo na memória consiste em um cabeçalho que descreve a caixa de diálogo, seguido por um ou mais blocos adicionais de dados que descrevem cada um dos controles na caixa de diálogo. O modelo pode usar o formato padrão ou o formato estendido. Em um modelo padrão, o cabeçalho é uma estrutura DLGTEMPLATE seguida por matrizes de comprimento variável adicionais; e os dados de cada controle consistem em uma estrutura DLGITEMTEMPLATE seguida por matrizes de comprimento variável adicionais. Em um modelo de caixa de diálogo estendido, o cabeçalho usa o formato DLGTEMPLATEEX e as definições de controle usam o formato DLGITEMTEMPLATEEX .

Você pode criar um modelo de memória alocando um objeto de memória global e preenchendo-o com as definições de cabeçalho e controle padrão ou estendido. Um modelo de memória é idêntico no formato e no conteúdo de um recurso de modelo. Muitos aplicativos que usam modelos de memória primeiro usam a função LoadResource para carregar um recurso de modelo na memória e, em seguida, modificam o recurso carregado para criar um novo modelo de memória. Para obter mais informações sobre como criar um modelo de caixa de diálogo na memória, consulte Modelos na memória.

As seções a seguir descrevem os estilos, as medidas e outros valores usados em um modelo de caixa de diálogo.

Estilos de modelo da caixa de diálogo

Cada modelo de caixa de diálogo especifica uma combinação de valores de estilo que definem a aparência e os recursos da caixa de diálogo. Os valores de estilo podem ser estilos de janela, como WS_POPUP e WS_SYSMENU, e estilos de caixa de diálogo, como DS_MODALFRAME. O número e o tipo de estilos de um modelo dependem do tipo e da finalidade da caixa de diálogo. Para obter uma lista de valores, consulte Estilos da Caixa de Diálogo.

O sistema passa todos os estilos de janela especificados no modelo para a função CreateWindowEx ao criar a caixa de diálogo. O sistema pode passar um ou mais estilos estendidos dependendo dos estilos de caixa de diálogo especificados. Por exemplo, quando o modelo especifica DS_MODALFRAME, o sistema usa WS_EX_DLGMODALFRAME ao criar a caixa de diálogo.

A maioria das caixas de diálogo são janelas pop-up que têm um menu de janela e uma barra de título. Portanto, o modelo típico especifica os estilos WS_POPUP, WS_SYSMENU e WS_CAPTION . O modelo também especifica um estilo de borda: WS_BORDER para caixas de diálogo de modelagem e DS_MODALFRAME para caixas de diálogo modais. Um modelo poderá especificar um tipo de janela diferente de pop-up (como WS_OVERLAPPED) se ele criar uma janela personalizada em vez de uma caixa de diálogo.

O sistema sempre exibe uma caixa de diálogo modal, independentemente de o estilo WS_VISIBLE ser especificado. Quando o modelo de uma caixa de diálogo modeless especifica o estilo WS_VISIBLE , o sistema exibe automaticamente a caixa de diálogo quando é criada. Caso contrário, o aplicativo será responsável por exibir a caixa de diálogo usando a função ShowWindow .

Medidas da caixa de diálogo

Cada modelo de caixa de diálogo contém medidas que especificam a posição, a largura e a altura da caixa de diálogo e os controles que ela contém. Essas medidas são independentes do dispositivo, portanto, um aplicativo pode usar um único modelo para criar a mesma caixa de diálogo para todos os tipos de dispositivos de exibição. Isso garante que uma caixa de diálogo tenha as mesmas proporções e aparência em todas as telas, apesar de resoluções e proporções diferentes entre telas.

As medidas em um modelo de caixa de diálogo são especificadas em unidades de modelo de caixa de diálogo. Para converter medidas de unidades de modelo de caixa de diálogo em unidades de tela (pixels), use a função MapDialogRect , que leva em conta a fonte usada pela caixa de diálogo e converte corretamente um retângulo de unidades de modelo de caixa de diálogo em pixels. Para caixas de diálogo que usam a fonte do sistema, você pode usar a função GetDialogBaseUnits para executar os cálculos de conversão por conta própria, embora usar MapDialogRect seja mais simples.

O modelo deve especificar as coordenadas iniciais do canto superior esquerdo da caixa de diálogo. Normalmente, as coordenadas são relativas ao canto superior esquerdo da área de cliente da janela do proprietário. Quando o modelo especifica o estilo DS_ABSALIGN ou a caixa de diálogo não tem proprietário, a posição é relativa ao canto superior esquerdo da tela. O sistema define essa posição inicial ao criar a caixa de diálogo, mas permite que um aplicativo ajuste a posição antes de exibir a caixa de diálogo. Por exemplo, um aplicativo pode recuperar as dimensões da janela do proprietário, calcular uma nova posição que centralize a caixa de diálogo na janela proprietário e, em seguida, definir a posição usando a função SetWindowPos .

O modelo deve especificar uma largura e altura de caixa de diálogo que não excedam a largura e a altura da tela e garante que todos os controles estejam dentro da área do cliente da caixa de diálogo. Embora o sistema permita que uma caixa de diálogo seja de qualquer tamanho, criar uma que seja muito pequena ou muito grande pode impedir que o usuário forneça entrada, derrotando a finalidade da caixa de diálogo. Muitos aplicativos usam mais de uma caixa de diálogo quando há um grande número de controles. Nesses casos, a caixa de diálogo inicial geralmente contém um ou mais botões que o usuário pode optar por exibir a próxima caixa de diálogo.

Controles da caixa de diálogo

O modelo especifica a posição, largura, altura, estilo, identificador e classe de janela para cada controle na caixa de diálogo. O sistema cria cada controle passando esses dados para a função CreateWindowEx . Os controles são criados na ordem em que são especificados no modelo. O modelo deve especificar o número, o tipo e a ordem apropriados dos controles para garantir que o usuário possa inserir a entrada necessária para concluir a tarefa associada à caixa de diálogo.

Para cada controle, o modelo especifica valores de estilo que definem a aparência e a operação do controle. Cada controle é uma janela filho e, portanto, deve ter o estilo WS_CHILD . Para garantir que o controle esteja visível quando a caixa de diálogo é exibida, cada controle também deve ter o estilo WS_VISIBLE . Outros estilos de janela comumente usados são WS_BORDER para controles que têm bordas opcionais, WS_DISABLED para controles que devem ser desabilitados quando a caixa de diálogo é criada inicialmente e WS_TABSTOP e WS_GROUP para controles que podem ser acessados usando o teclado. Os estilos WS_TABSTOP e WS_GROUP são usados em conjunto com a interface do teclado de diálogo descrita posteriormente neste tópico.

O modelo também pode especificar estilos de controle específicos para a classe de janela do controle. Por exemplo, um modelo que especifica um controle de botão deve fornecer um estilo de controle de botão, como BS_PUSHBUTTON ou BS_CHECKBOX. O sistema passa os estilos de controle para o procedimento da janela de controle por meio da mensagem WM_CREATE , permitindo que o procedimento adapte a aparência e a operação do controle.

O sistema converte as coordenadas de posição e as medidas de largura e altura de unidades base da caixa de diálogo em pixels, antes de passá-las para CreateWindowEx. Quando o sistema cria um controle, ele especifica a caixa de diálogo como a janela pai. Isso significa que o sistema sempre interpreta as coordenadas de posição do controle como coordenadas do cliente, em relação ao canto superior esquerdo da área do cliente da caixa de diálogo.

O modelo especifica a classe de janela para cada controle. Uma caixa de diálogo típica contém controles que pertencem às classes de janela de controle predefinidas, como o botão e as classes de janela de controle de edição. Nesse caso, o modelo especifica classes de janela fornecendo os valores atom predefinidos correspondentes para as classes. Quando uma caixa de diálogo contém um controle que pertence a uma classe de janela de controle personalizada, o modelo fornece o nome dessa classe de janela registrada ou o valor atom atualmente associado ao nome.

Cada controle em uma caixa de diálogo deve ter um identificador exclusivo para distingui-lo de outros controles. Os controles enviam informações para o procedimento da caixa de diálogo por meio de mensagens WM_COMMAND , portanto, os identificadores de controle são essenciais para que o procedimento determine qual controle enviou uma mensagem especificada. A única exceção a essa regra são os identificadores de controle para controles estáticos. Os controles estáticos não exigem identificadores exclusivos porque não enviam mensagens WM_COMMAND .

Para permitir que o usuário feche a caixa de diálogo, o modelo deve especificar pelo menos um botão de push e fornecer a ele o identificador de controle IDCANCEL. Para permitir que o usuário escolha entre concluir ou cancelar a tarefa associada à caixa de diálogo, o modelo deve especificar dois botões de push, rotulados como OK e Cancelar, com identificadores de controle de IDOK e IDCANCEL, respectivamente.

Um modelo também especifica dados opcionais de texto e criação para um controle. O texto normalmente fornece rótulos para controles de botão ou especifica o conteúdo inicial de um controle de texto estático. Os dados de criação são um ou mais bytes de dados que o sistema passa para o procedimento da janela de controle ao criar o controle. Os dados de criação são úteis para controles que exigem mais informações sobre seu conteúdo ou estilo inicial do que o especificado por outros dados. Por exemplo, um aplicativo pode usar dados de criação para definir a configuração inicial e o intervalo para um controle de barra de rolagem.

Menu Da Janela da Caixa de Diálogo

O sistema fornece uma caixa de diálogo a um menu de janela quando o modelo especifica o estilo de WS_SYSMENU . Para evitar entrada inadequada, o sistema desabilita automaticamente todos os itens no menu, exceto Mover e Fechar. O usuário pode clicar em Mover para mover a caixa de diálogo. Quando o usuário clica em Fechar, o sistema envia uma mensagem WM_COMMAND para o procedimento da caixa de diálogo com o parâmetro wParam definido como IDCANCEL. Isso é idêntico à mensagem enviada pelo botão Cancelar quando o usuário clica nela. A ação recomendada para essa mensagem é fechar a caixa de diálogo e cancelar a tarefa solicitada.

Embora outros menus em caixas de diálogo não sejam recomendados, um modelo de caixa de diálogo pode especificar um menu fornecendo o identificador ou o nome de um recurso de menu. Nesse caso, o sistema carrega o recurso e cria o menu para a caixa de diálogo. Os aplicativos normalmente usam identificadores de menu ou nomes em modelos ao usar os modelos para criar janelas personalizadas em vez de caixas de diálogo.

Fontes da caixa de diálogo

O sistema usa a largura média do caractere da fonte da caixa de diálogo para calcular a posição e as dimensões da caixa de diálogo. Por padrão, o sistema desenha todo o texto em uma caixa de diálogo usando a fonte SYSTEM_FONT .

Para especificar uma fonte para uma caixa de diálogo diferente do padrão, você deve criar a caixa de diálogo usando um modelo de caixa de diálogo. Em um recurso de modelo, use a instrução FONT. Em um modelo de caixa de diálogo, defina o estilo DS_SETFONT ou DS_SHELLFONT e especifique um tamanho de ponto e um nome de face de tipo. Mesmo que um modelo de caixa de diálogo especifique uma fonte dessa maneira, o sistema sempre usará a fonte do sistema para os menus de caixa de diálogo e título da caixa de diálogo.

Quando a caixa de diálogo tem o estilo DS_SETFONT ou DS_SHELLFONT , o sistema envia uma mensagem WM_SETFONT para o procedimento da caixa de diálogo e para cada controle à medida que cria o controle. O procedimento da caixa de diálogo é responsável por salvar o identificador de fonte passado com a mensagem WM_SETFONT e selecionar o identificador no contexto do dispositivo de exibição sempre que ele gravar texto na janela. Controles predefinidos fazem isso por padrão.

A fonte do sistema pode variar entre diferentes versões do Windows. Para que o aplicativo use a fonte do sistema independentemente do sistema em que ele está sendo executado, use DS_SHELLFONT com a face de tipo MS Shell Dlg e use o recurso DIALOGEX em vez do recurso DIALOG. O sistema mapeia essa face de tipo de modo que sua caixa de diálogo use a fonte Tahoma. Observe que DS_SHELLFONT não terá efeito se a face de tipo não for MS Shell Dlg.

Modelos na memória

Um modelo de caixa de diálogo na memória consiste em um cabeçalho que descreve a caixa de diálogo, seguido por um ou mais blocos de dados adicionais que descrevem cada um dos controles na caixa de diálogo. O modelo pode usar o formato padrão ou o formato estendido. Em um modelo padrão, o cabeçalho é uma estrutura DLGTEMPLATE seguida por matrizes de comprimento variável adicionais. Os dados de cada controle consistem em uma estrutura DLGITEMTEMPLATE seguida por matrizes de comprimento variável adicionais. Em um modelo de caixa de diálogo estendido, o cabeçalho usa o formato DLGTEMPLATEEX e as definições de controle usam o formato DLGITEMTEMPLATEEX .

Para distinguir entre um modelo padrão e um modelo estendido, marcar os primeiros 16 bits de um modelo de caixa de diálogo. Em um modelo estendido, o primeiro WORD é 0xFFFF; qualquer outro valor indica um modelo padrão.

Se você criar um modelo de caixa de diálogo na memória, deverá garantir que cada uma das definições de controle DLGITEMTEMPLATE ou DLGITEMTEMPLATEEX esteja alinhada nos limites DWORD . Além disso, todos os dados de criação que seguem uma definição de controle devem ser alinhados em um limite DWORD . Todas as outras matrizes de comprimento variável em um modelo de caixa de diálogo devem ser alinhadas nos limites do WORD .

Cabeçalho de modelo

Nos modelos padrão e estendido para caixas de diálogo, o cabeçalho inclui as seguintes informações gerais:

  • O local e as dimensões da caixa de diálogo
  • A janela e os estilos da caixa de diálogo para a caixa de diálogo
  • O número de controles na caixa de diálogo. Esse valor determina o número de definições de controle DLGITEMTEMPLATE ou DLGITEMTEMPLATEEX no modelo.
  • Um recurso de menu opcional para a caixa de diálogo. O modelo pode indicar que a caixa de diálogo não tem um menu ou pode especificar um valor ordinal ou uma cadeia de caracteres Unicode terminada em nulo que identifica um recurso de menu em um arquivo executável.
  • A classe de janela da caixa de diálogo. Pode ser a classe de caixa de diálogo predefinida ou um valor ordinal ou uma cadeia de caracteres Unicode terminada em nulo que identifica uma classe de janela registrada.
  • Uma cadeia de caracteres Unicode terminada em nulo que especifica o título da janela da caixa de diálogo. Se a cadeia de caracteres estiver vazia, a barra de título da caixa de diálogo ficará em branco. Se a caixa de diálogo não tiver o estilo WS_CAPTION , o sistema definirá o título como a cadeia de caracteres especificada, mas não o exibirá.
  • Se a caixa de diálogo tiver o estilo DS_SETFONT , o cabeçalho especificará o tamanho do ponto e o nome da face de tipo da fonte a ser usada para o texto na área do cliente e os controles da caixa de diálogo.

Em um modelo estendido, o cabeçalho DLGTEMPLATEEX também especifica as seguintes informações adicionais:

  • O identificador de contexto de ajuda da janela da caixa de diálogo quando o sistema envia uma mensagem de WM_HELP .
  • Se a caixa de diálogo tiver o estilo DS_SETFONT ou DS_SHELLFONT , o cabeçalho especificará o peso da fonte e indicará se a fonte é itálica.

Definições de controle

Após o cabeçalho do modelo, há uma ou mais definições de controle que descrevem os controles da caixa de diálogo. Nos modelos padrão e estendido, o cabeçalho da caixa de diálogo tem um membro que indica o número de definições de controle no modelo. Em um modelo padrão, cada definição de controle consiste em uma estrutura DLGITEMTEMPLATE seguida por matrizes de comprimento variável adicionais. Em um modelo estendido, as definições de controle usam o formato DLGITEMTEMPLATEEX .

Nos modelos padrão e estendido, a definição de controle inclui as seguintes informações:

  • O local e as dimensões do controle.
  • A janela e os estilos de controle para o controle.
  • O identificador de controle.
  • A classe de janela do controle . Isso pode ser o valor ordinal de uma classe de sistema predefinida ou uma cadeia de caracteres Unicode terminada em nulo que especifica o nome de uma classe de janela registrada.
  • Uma cadeia de caracteres Unicode terminada em nulo que especifica o texto inicial do controle ou um valor ordinal que identifica um recurso, como um ícone, em um arquivo executável.
  • Um bloco opcional de comprimento variável de dados de criação. Quando o sistema cria o controle, ele passa um ponteiro para esses dados no parâmetro lParam do WM_CREATE mensagem que ele envia para o controle.

Em um modelo estendido, a definição de controle também especifica um identificador de contexto de ajuda para o controle quando o sistema envia uma mensagem de WM_HELP .