Manipulando notificações de personalização
Um controle comum de barra de ferramentas do Windows tem recursos de personalização internos, incluindo uma caixa de diálogo de personalização definida pelo sistema, que permite ao usuário inserir, excluir ou reorganizar os botões da barra de ferramentas. O aplicativo determina se os recursos de personalização ficam 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 dando à 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 os botões da barra de ferramentas. O aplicativo pode exibir a caixa de diálogo usando a função membro Customize.
O controle de barra de ferramentas envia mensagens de notificação para a janela pai a 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 tratará 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 capturará a entrada do mouse e aguardará o usuário soltar o botão do mouse.
Quando o usuário soltar o botão do mouse, o controle de barra de ferramentas determinará o local 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 poderá 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 sinal da operação de arrastar.
Se o usuário iniciar uma operação de arrastar sem segurar a tecla SHIFT, o controle de barra de ferramentas enviará a mensagem de notificação TBN_BEGINDRAG para a janela do proprietário. Um aplicativo que implementa o próprio código de arraste de botões 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 sinal 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 após o usuário clicar duas vezes na barra de ferramentas, mas antes que a caixa de diálogo seja 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 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 nenhum botão, a barra de ferramentas destruirá a caixa de diálogo.
Em seguida, o controle de barra de ferramentas determinará se algum botão pode ser excluído da barra de ferramentas enviando uma mensagem de notificação TBN_QUERYDELETE para cada botão na barra de ferramentas. A janela pai 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 esmaece os que não podem ser excluídos.
Sempre que o controle de barra de ferramentas precisar de informações sobre um botão na caixa de diálogo Personalizar Barra de Ferramentas, ele enviará a mensagem de notificação TBN_GETBUTTONINFO, especificando o índice do botão cujas informações são necessárias 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 de 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 Redefinir. Essa mensagem indica que a barra de ferramentas está prestes a reinicializar a caixa de diálogo.
Todas essas são mensagens WM_NOTIFY e podem ser tratadas na janela do proprietário adicionando entradas de mapa de mensagens no seguinte formato ao mapa de mensagens da janela do proprietário:
ON_NOTIFY( wNotifyCode, idControl, memberFxn )
wNotifyCode
Código identificador da 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 membro seria declarada com o seguinte protótipo:
afx_msg void memberFxn( NMHDR * pNotifyStruct, LRESULT * result );
Se o manipulador de mensagens da notificação retornar um valor, ele deverá colocá-lo no LRESULT para o qual result aponta.
Para cada mensagem, pNotifyStruct aponta para uma estrutura NMHDR ou uma estrutura TBNOTIFY. Essas 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.
code
Código de notificação. Esse membro pode ser um valor específico a um tipo de controle, como TBN_BEGINADJUST ou TTN_NEEDTEXT, ou pode ser um dos valores de notificação comuns listados abaixo:
NM_CLICK O usuário clicou no botão esquerdo do mouse dentro do controle.
NM_DBLCLK O usuário clicou duas vvezes 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
A 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.
lpszTexto
Ponteiro para o texto do botão.
As notificações enviadas pela barra de ferramentas são as seguintes:
TBN_BEGINADJUST
Enviada 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
Enviada 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
Enviada 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
Enviada 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. Retornará TRUE se as informações do botão forem copiadas para a estrutura; caso contrário, retornará FALSE.
TBN_QUERYDELETE
Enviada 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. Retornará TRUE para permitir que o botão seja excluído ou FALSE para impedir que ele seja excluído.
TBN_QUERYINSERT
Enviada 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. Retornará TRUE para permitir que um botão seja inserido na frente do botão especificado ou FALSE para impedir que ele seja inserido.
TBN_RESET
Enviada 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
Enviada depois que o usuário tiver personalizado 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.