Manipulando notificações de personalização

Um controle comum da barra de ferramentas do Windows tem recursos internos de personalização, incluindo uma caixa de diálogo de personalização definida pelo sistema, que permite que o usuário insira, exclua ou reorganize botões da barra de ferramentas. O aplicativo determina se os recursos de personalização estão disponíveis e controla até que ponto o usuário pode personalizar a barra de ferramentas.

Você pode disponibilizar esses recursos de personalização para o usuário fornecendo à barra de ferramentas o estilo CCS_ADJUSTABLE . Os recursos de personalização permitem que o usuário arraste um botão para uma nova posição ou remova um botão arrastando-o para fora da barra de ferramentas. Além disso, o usuário pode clicar duas vezes na barra de ferramentas para exibir a caixa de diálogo Personalizar Barra de Ferramentas , que permite ao usuário adicionar, excluir e reorganizar botões da barra de ferramentas. O aplicativo pode exibir a caixa de diálogo usando a função membro Customize.

O controle da barra de ferramentas envia mensagens de notificação para a janela pai em cada etapa do processo de personalização. Se o usuário mantiver a tecla SHIFT pressionada e começar a arrastar um botão, a barra de ferramentas manipulará automaticamente a operação de arrastar. A barra de ferramentas envia a mensagem de notificação TBN_QUERYDELETE para a janela pai para determinar se o botão pode ser excluído. A operação de arrastar terminará se a janela pai retornar FALSE. Caso contrário, a barra de ferramentas captura a entrada do mouse e aguarda o usuário liberar o botão do mouse.

Quando o usuário libera o botão do mouse, o controle da barra de ferramentas determina a localização do cursor do mouse. Se o cursor estiver fora da barra de ferramentas, o botão será excluído. Se o cursor estiver em outro botão de barra de ferramentas, a barra de ferramentas enviará a mensagem de notificação TBN_QUERYINSERT para a janela pai para determinar se um botão pode ser inserido à esquerda do botão especificado. O botão será inserido se a janela pai retornar TRUE; caso contrário, não será. A barra de ferramentas envia a mensagem de notificação TBN_TOOLBARCHANGE para sinalizar o fim da operação de arrastar.

Se o usuário iniciar uma operação de arrastar sem segurar a tecla SHIFT, o controle da barra de ferramentas enviará a mensagem de notificação TBN_BEGINDRAG para a janela do proprietário. Um aplicativo que implementa seu próprio código de arrastar botão pode usar essa mensagem como um sinal para iniciar uma operação de arrastar. A barra de ferramentas envia a mensagem de notificação TBN_ENDDRAG para sinalizar o fim da operação de arrastar.

Um controle de barra de ferramentas envia mensagens de notificação quando o usuário personaliza uma barra de ferramentas usando a caixa de diálogo Personalizar Barra de Ferramentas . A barra de ferramentas envia a mensagem de notificação TBN_BEGINADJUST depois que o usuário clica duas vezes na barra de ferramentas, mas antes da caixa de diálogo ser criada. Em seguida, a barra de ferramentas começa a enviar uma série de mensagens de notificação TBN_QUERYINSERT para determinar se a barra de ferramentas permite que os botões sejam inseridos. Quando a janela pai retorna TRUE, a barra de ferramentas para de enviar mensagens de notificação TBN_QUERYINSERT. Se a janela pai não retornar TRUE para qualquer botão, a barra de ferramentas destruirá a caixa de diálogo.

Em seguida, o controle da barra de ferramentas determina se algum botão pode ser excluído da barra de ferramentas enviando um TBN_QUERYDELETE mensagem de notificação para cada botão na barra de ferramentas. A janela principal retorna TRUE para indicar que um botão pode ser excluído; caso contrário, retorna FALSE. A barra de ferramentas adiciona todos os botões da barra de ferramentas à caixa de diálogo, mas cinzas aqueles que podem não ser excluídos.

Sempre que o controle da barra de ferramentas precisar de informações sobre um botão na caixa de diálogo Personalizar Barra de Ferramentas, ele envia a mensagem de notificação TBN_GETBUTTONINFO , especificando o índice do botão para o qual ele precisa de informações e o endereço de uma estrutura TBNOTIFY . A janela pai deve preencher a estrutura com as informações relevantes.

A caixa de diálogo Personalizar Barra de Ferramentas inclui um botão Ajuda e um botão Redefinir. Quando o usuário escolhe o botão Ajuda, o controle da barra de ferramentas envia a mensagem de notificação TBN_CUSTHELP . A janela pai deve responder exibindo informações de ajuda. A caixa de diálogo envia a mensagem de notificação TBN_RESET quando o usuário seleciona o botão Restaurar. Essa mensagem sinaliza que a barra de ferramentas está prestes a reinicializar a caixa de diálogo.

Todas essas mensagens são mensagens WM_NOTIFY e podem ser tratadas em sua janela proprietária, adicionando entradas no mapa de mensagens de sua janela proprietária, conforme o seguinte formato.

ON_NOTIFY( wNotifyCode, idControl, memberFxn )

• wNotifyCode

  Código do identificador de mensagem de notificação, como TBN_BEGINADJUST.

• idControl

  O identificador do controle que envia a notificação.

• memberFxn

  A função membro a ser chamada quando essa notificação for recebida.

Sua função de membro seria declarada com o seguinte protótipo:

afx_msg void memberFxn( NMHDR * pNotifyStruct, LRESULT * result );

Se o manipulador de mensagens de notificação retornar um valor, ele deverá colocá-lo no LRESULT apontado pelo resultado.

Para cada mensagem, pNotifyStruct aponta para uma estrutura NMHDR ou uma estrutura TBNOTIFY . Estas estruturas são descritas abaixo:

A estrutura NMHDR contém os seguintes membros:

typedef struct tagNMHDR {
    HWND hwndFrom;  // handle of control sending message
    UINT idFrom;// identifier of control sending message
    UINT code;  // notification code; see below
} NMHDR;

• hwndFrom

  Identificador de janela do controle que está enviando a notificação. Para converter esse identificador em um ponteiro CWnd, use CWnd::FromHandle.

• idFrom

  Identificador do controle que envia a notificação.

• código

  Código de notificação. Esse membro pode ser um valor específico para um tipo de controle, como TBN_BEGINADJUST ou TTN_NEEDTEXT, ou pode ser um dos valores comuns de notificação listados abaixo:

  • NM_CLICK O usuário clicou no botão esquerdo do mouse dentro do controle.

  • NM_DBLCLK O usuário clicou duas vezes no botão esquerdo do mouse dentro do controle.

  • NM_KILLFOCUS O controle perdeu o foco de entrada.

  • NM_OUTOFMEMORY O controle não pôde concluir uma operação porque não há memória suficiente disponível.

  • NM_RCLICK O usuário clicou no botão direito do mouse dentro do controle.

  • NM_RDBLCLK O usuário clicou duas vezes no botão direito do mouse dentro do controle.

  • NM_RETURN O controle tem o foco de entrada e o usuário pressionou a tecla ENTER.

  • NM_SETFOCUS O controle recebeu o foco de entrada.

A estrutura TBNOTIFY contém os seguintes membros:

typedef struct {
    NMHDR hdr; // information common to all WM_NOTIFY messages
    int iItem; // index of button associated with notification
    TBBUTTON tbButton; // info about button associated withnotification
    int cchText;   // count of characters in button text
    LPSTR lpszText;// address of button text
} TBNOTIFY, FAR* LPTBNOTIFY;

• Hdr

  Informações comuns a todas as mensagens WM_NOTIFY .

• iItem

  Índice do botão associado à notificação.

• tbButton

  Estrutura TBBUTTON que contém informações sobre o botão de barra de ferramentas associado à notificação.

• cchText

  Contagem de caracteres no texto do botão.

• lpszText

  Ponteiro para texto do botão.

As notificações enviadas pela barra de ferramentas são as seguintes:

• TBN_BEGINADJUST

  Enviado quando o usuário começa a personalizar um controle de barra de ferramentas. O ponteiro aponta para uma estrutura NMHDR que contém informações sobre a notificação. O manipulador não precisa retornar nenhum valor específico.

• TBN_BEGINDRAG

  Enviado quando o usuário começa a arrastar um botão em um controle de barra de ferramentas. O ponteiro aponta para uma estrutura TBNOTIFY . O membro iItem contém o índice baseado em zero do botão que está sendo arrastado. O manipulador não precisa retornar nenhum valor específico.

• TBN_CUSTHELP

  Enviado quando o usuário escolhe o botão Ajuda na caixa de diálogo Personalizar Barra de Ferramentas. Sem valor de retorno. O ponteiro aponta para uma estrutura NMHDR que contém informações sobre a mensagem de notificação. O manipulador não precisa retornar nenhum valor específico.

• TBN_ENDADJUST

  Enviado quando o usuário para de personalizar um controle de barra de ferramentas. O ponteiro aponta para uma estrutura NMHDR que contém informações sobre a mensagem de notificação. O manipulador não precisa retornar nenhum valor específico.

• TBN_ENDDRAG

  Enviado quando o usuário para de arrastar um botão em um controle de barra de ferramentas. O ponteiro aponta para uma estrutura TBNOTIFY . O membro iItem contém o índice baseado em zero do botão que está sendo arrastado. O manipulador não precisa retornar nenhum valor específico.

• TBN_GETBUTTONINFO

  Enviado quando o usuário está personalizando um controle de barra de ferramentas. A barra de ferramentas usa essa mensagem de notificação para recuperar as informações de que a caixa de diálogo Personalizar Barra de Ferramentas precisa. O ponteiro aponta para uma estrutura TBNOTIFY . O membro iItem especifica o índice baseado em zero de um botão. Os membros pszText e cchText especificam o endereço e o comprimento, em caracteres, do texto do botão atual. Um aplicativo deve preencher a estrutura com informações sobre o botão. Retorne TRUE se informações do botão foram copiadas para a estrutura, ou FALSE caso contrário.

• TBN_QUERYDELETE

  Enviado enquanto o usuário está personalizando uma barra de ferramentas para determinar se um botão pode ser excluído de um controle de barra de ferramentas. O ponteiro aponta para uma estrutura TBNOTIFY . O membro iItem contém o índice baseado em zero do botão a ser excluído. Retorne TRUE para permitir que o botão seja excluído ou FALSE para impedir que o botão seja excluído.

• TBN_QUERYINSERT

  Enviado enquanto o usuário está personalizando um controle de barra de ferramentas para determinar se um botão pode ser inserido à esquerda do botão especificado. O ponteiro aponta para uma estrutura TBNOTIFY . O membro iItem contém o índice baseado em zero do botão a ser inserido. Retorne TRUE para permitir que um botão seja inserido na frente do botão especificado ou FALSE para impedir que o botão seja inserido.

• TBN_RESET

  Enviado quando o usuário redefine o conteúdo da caixa de diálogo Personalizar Barra de Ferramentas. O ponteiro aponta para uma estrutura NMHDR que contém informações sobre a mensagem de notificação. O manipulador não precisa retornar nenhum valor específico.

• TBN_TOOLBARCHANGE

  Enviado depois que o usuário personalizou um controle de barra de ferramentas. O ponteiro aponta para uma estrutura NMHDR que contém informações sobre a mensagem de notificação. O manipulador não precisa retornar nenhum valor específico.

Consulte também

Usando CToolBarCtrl
Controles