Mescla do menu Ajuda
Quando um objeto está ativo dentro de um contêiner, o protocolo de mesclagem de menu de Documentos OLE fornece ao objeto controle completo do menu Ajuda. Como resultado, os tópicos de Ajuda do contêiner não estão disponíveis, a menos que o usuário desative o objeto. A arquitetura de contenção de documentos ativos se expande nas regras para a mesclagem de menu in-loco para permitir que o contêiner e um documento ativo que esteja ativo compartilhem o menu. As novas regras são simplesmente convenções adicionais sobre qual componente possui a parte do menu e como o menu compartilhado é construído.
A nova convenção é simples. Em documentos ativos, o menu Ajuda tem dois itens de menu de nível superior organizados da seguinte maneira:
Help
Container Help >
Object Help >
Por exemplo, quando uma seção do Word estiver ativa no Office Binder, o menu Ajuda aparecerá da seguinte forma:
Help
Binder Help >
Word Help >
Ambos os itens de menu são menus em cascata sob os quais quaisquer itens de menu adicionais específicos para o contêiner e o objeto são fornecidos ao usuário. Os itens exibidos aqui variam de acordo com o contêiner e os objetos envolvidos.
Para construir esse menu Ajuda mesclado, a arquitetura de independência de documentos ativos modifica o procedimento normal de Documentos OLE. De acordo com documentos OLE, a barra de menus mesclada pode ter seis grupos de menus, ou seja, Arquivo, Editar, Contêiner, Objeto, Janela, Ajuda, nessa ordem. Em cada grupo, pode haver zero ou mais menus. Os grupos Arquivo, Contêiner e Janela pertencem ao contêiner e os grupos Editar, Objeto, e Ajuda que pertencem ao objeto. Quando o objeto quiser fazer a mesclagem do menu, ele cria uma barra de menus em branco e a passa para o contêiner. Em seguida, o contêiner insere seus menus, chamando IOleInPlaceFrame::InsertMenus. O objeto também passa uma estrutura que é uma matriz de seis valores LONG (OLEMENUGROUPWIDTHS). Depois de inserir os menus, o contêiner marca quantos menus foram adicionados em cada um de seus grupos e retorna. Em seguida, o objeto insere seus menus, prestando atenção à contagem de menus em cada grupo de contêineres. Por fim, o objeto passa a barra de menus mesclada e a matriz (que contém a contagem de menus em cada grupo) para o OLE, que retorna um identificador opaco de "descritor de menu". Posteriormente, o objeto passa esse identificador e a barra de menus mesclada para o contêiner, por meio de IOleInPlaceFrame::SetMenu. Neste momento, o contêiner exibe a barra de menus mesclada e também passa o identificador para o OLE, para que o OLE possa fazer o envio adequado de mensagens de menu.
No procedimento de documento ativo modificado, o objeto deve primeiro inicializar os elementos OLEMENUGROUPWIDTHS como zero antes de passá-los para o contêiner. Em seguida, o contêiner executa uma inserção de menu normal com uma exceção: o contêiner insere um menu Ajuda como o último item e armazena um valor de 1 na última (sexta) entrada da matriz OLEMENUGROUPWIDTHS (ou seja, largura[5], que pertence ao grupo de Ajuda do objeto). Esse menu Ajuda terá apenas um item que é um submenu, o menu em cascata "Ajuda de Contêiner>", conforme descrito anteriormente.
Em seguida, o objeto executa seu código de inserção de menu normal, exceto que antes de inserir seu menu Ajuda, ele verifica a sexta entrada da matriz OLEMENUGROUPWIDTHS. Se o valor for 1 e o nome do último menu for Ajuda (ou a cadeia de caracteres localizada apropriada), o objeto inserirá seu menu Ajuda como submenu do menu Ajuda do contêiner.
Em seguida, o objeto define o sexto elemento de OLEMENUGROUPWIDTHS como zero e incrementa o quinto elemento por um. Isso permite que o OLE saiba que o menu Ajuda pertence ao contêiner e as mensagens de menu correspondentes a esse menu (e seu submenus) devem ser roteadas para o contêiner. Em seguida, é responsabilidade do contêiner encaminhar WM_INITMENUPOPUP, WM_SELECT, WM_COMMAND e outras mensagens relacionadas ao menu que pertencem à parte do objeto do menu Ajuda. Isso é feito usando WM_INITMENU para limpar um sinalizador que informa ao contêiner se o usuário navegou no menu Ajuda do objeto. Em seguida, o contêiner observa WM_MENUSELECT para entrada ou saída de qualquer item no menu Ajuda que o contêiner não adicionou a si mesmo. Na entrada, significa que o usuário navegou em um menu de objeto, portanto, o contêiner define o sinalizador "menu Ajuda no objeto" e usa o estado desse sinalizador para encaminhar qualquer mensagem WM_MENUSELECT, WM_INITMENUPOPUP e WM_COMMAND, no mínimo, para a janela do objeto. (Na saída, o contêiner limpa o sinalizador e processa essas mesmas mensagens em si.) O contêiner deve usar a janela retornada da função IOleInPlaceActiveObejct::GetWindow do objeto como o destino dessas mensagens.
Se o objeto detectar um zero no sexto elemento de OLEMENUGROUPWIDTHS, ele continuará de acordo com as regras normais de Documentos OLE. Este procedimento abrange contêineres que participam da mesclagem do menu Ajuda, bem como aqueles que não participam.
Quando o objeto chama IOleInPlaceFrame::SetMenu, antes de exibir a barra de menus mesclada, o contêiner verifica se o menu Ajuda tem um submenu adicional, além do inserido no contêiner. Nesse caso, o contêiner deixará seu menu Ajuda na barra de menus mesclada. Se o menu Ajuda não tiver um submenu adicional, o contêiner removerá seu menu Ajuda da barra de menus mesclada. Este procedimento abrange objetos que participam da mesclagem do menu Ajuda, bem como aqueles que não participam.
Por fim, quando for hora de desmontar o menu, o objeto remove o menu Ajuda inserido, além de remover os outros menus inseridos. Quando o contêiner remover seus menus, ele removerá o menu de Ajuda, além dos outros menus inseridos.