Método IExtendContextMenu::AddMenuItems (mmc.h)

Artigo
03/13/2024

O método IExtendContextMenu::AddMenuItems permite que um snap-in adicione itens a um menu de contexto.

Sintaxe

HRESULT AddMenuItems(
  [in]      LPDATAOBJECT          piDataObject,
  [in]      LPCONTEXTMENUCALLBACK piCallback,
  [in, out] long                  *pInsertionAllowed
);

Parâmetros

[in] piDataObject

Um ponteiro para a interface IDataObject no objeto de dados do menu ao qual os itens são adicionados.

[in] piCallback

Um ponteiro para um IContextMenuCallback que pode adicionar itens ao menu de contexto.

[in, out] pInsertionAllowed

Um valor que identifica pontos de inserção de item de menu definidos pelo MMC que podem ser usados. Isso pode ser uma combinação dos seguintes sinalizadores:

CCM_INSERTIONALLOWED_TOP

Os itens podem ser inseridos na parte superior de um menu de contexto.

CCM_INSERTIONALLOWED_NEW

Os itens podem ser inseridos no submenu Novo.

CCM_INSERTIONALLOWED_TASK

Os itens podem ser inseridos no submenu Todas as Tarefas.

CCM_INSERTIONALLOWED_VIEW

Os itens podem ser inseridos no menu de exibição da barra de ferramentas ou no submenu Exibir do menu de contexto do painel de resultados.

Retornar valor

Esse método pode retornar um desses valores.

Comentários

Uma implementação de IExtendContextMenu::AddMenuItems normalmente lê o tipo de nó e quaisquer outros parâmetros necessários chamando IDataObject::GetDataHere no piDataObject e adiciona itens de menu de contexto conforme apropriado chamando IContextMenuCallback::AddItem no piCallback.

Seu snap-in deve marcar os sinalizadores pInsertionsAllowed para obter permissão antes de tentar adicionar itens de menu nos pontos de inserção definidos pelo MMC. Por exemplo, um snap-in não deve adicionar itens de menu a CCM_INSERTIONPOINTID_PRIMARY_NEW ou CCM_INSERTIONPOINTID_3RDPARTY_NEW, a menos que o sinalizador CCM_INSERTIONALLOWED_NEW esteja definido.

Os sinalizadores pInsertionsAllowed permitem os dois seguintes recursos:

Se o usuário selecionar um item de escopo e exibir seu menu de contexto, o MMC dará às implementações IComponentData e IComponent do snap-in (que possui o modo de exibição atual) a oportunidade de adicionar itens de menu. O MMC chama o método IExtendContextMenu::AddMenuItems implementado pela implementação IComponent do snap-in para permitir que o snap-in adicione itens de menu ao menu Exibir . O MMC chama o método IExtendContextMenu::AddMenuItems implementado pelo IComponentData do snap-in para permitir que o snap-in adicione itens de menu a todos os outros menus. Somente a implementação do IComponent do snap-in pode adicionar itens ao menu Exibir .

Se o usuário exibir o menu de contexto de um item de escopo sem primeiro selecionar o item de escopo, o MMC dará apenas à implementação IComponentData do snap-in a oportunidade de adicionar itens de menu a todos os menus, exceto para o menu Exibir . Consequentemente, o menu Exibir só será exibido para um item de escopo se o usuário primeiro selecionar um item.

Anotações para chamadores

O método AddMenuItems não deve chamar AddRef no ponteiro piDataObject ou no ponteiro piCallback, nem deve chamar os métodos dessas interfaces após o retorno. Em vez disso, ele deve fazer todas as chamadas necessárias para os métodos dessas interfaces antes de retornar. Se qualquer um desses itens estiver selecionado, você receberá de volta o ponteiro para IDataObject em IExtendContextMenu::Command, portanto, não mantenha esse ponteiro após o retorno desse método. Você não será notificado se o menu for ignorado sem que nenhum de seus itens seja selecionado. Além disso, não consulte interfaces alternativas do piCallback porque o método IContextMenuCallback::AddItem deve ser suficiente.