Classe CContextMenuManager

O objeto CContextMenuManager gerencia menus de atalho, também conhecidos como menus de contexto.

Sintaxe

class CContextMenuManager : public CObject

Membros

Construtores públicos

Métodos públicos

Comentários

CContextMenuManager gerencia menus de atalho e garante que eles tenham uma aparência consistente.

Você não deve criar um objeto CContextMenuManager manualmente. A estrutura do aplicativo cria o objeto CContextMenuManager. No entanto, você deve chamar CWinAppEx::InitContextMenuManager quando seu aplicativo for inicializado. Depois de inicializar o gerenciador de contexto, use o método CWinAppEx::GetContextMenuManager para obter um ponteiro para o gerenciador de contexto do aplicativo.

Você pode criar menus de atalho no runtime chamando AddMenu. Se você quiser mostrar o menu sem receber primeiro uma entrada do usuário, chame ShowPopupMenu. TrackPopupMenu é usado quando você deseja criar um menu e aguardar uma entrada do usuário. TrackPopupMenu retornará o índice do comando selecionado ou 0 se o usuário tiver saído sem selecionar nada.

O CContextMenuManager também pode salvar e carregar seu estado no Registro do Windows.

Exemplo

O exemplo a seguir demonstra como adicionar um menu a um objeto CContextMenuManager e como não fechar o menu pop-up ativo quando o objeto CContextMenuManager exibir um novo menu pop-up. Este snippet de código faz parte da amostra de Páginas personalizadas.

// The GetContextMenuManager method is inherited from the CWinAppEx class.
GetContextMenuManager()->AddMenu(_T("My menu"), IDR_CONTEXT_MENU);
GetContextMenuManager()->SetDontCloseActiveMenu(true);

Hierarquia de herança

CObject

CContextMenuManager

Requisitos

Cabeçalho: afxcontextmenumanager.h

CContextMenuManager::AddMenu

Adiciona um novo menu de atalho ao CContextMenuManager.

BOOL AddMenu(
    UINT uiMenuNameResId,
    UINT uiMenuResId);

BOOL AddMenu(
    LPCTSTR lpszName,
    UINT uiMenuResId);

Parâmetros

uiMenuNameResId
[in] Uma ID de recurso para uma cadeia de caracteres que contém o nome do novo menu.

uiMenuResId
[in] A ID do recurso de menu.

lpszName
[in] Uma cadeia de caracteres que contém o nome do novo menu.

Valor de retorno

Diferente de zero se o método foi bem-sucedido; zero se o método falhar.

Comentários

Esse método falhará se uiMenuResId for inválido ou se outro menu com o mesmo nome já estiver no CContextMenuManager.

CContextMenuManager::CContextMenuManager

Constrói um objeto CContextMenuManager.

CContextMenuManager();

Comentários

Na maioria dos casos, você não deve criar um CContextMenuManager manualmente. A estrutura do aplicativo cria o objeto CContextMenuManager. Você deve chamar CWinAppEx::InitContextMenuManager durante a inicialização do aplicativo. Para obter um ponteiro para o gerenciador de contexto, chame CWinAppEx::GetContextMenuManager.

CContextMenuManager::GetMenuById

Retorna um identificador para o menu associado a uma determinada ID do recurso.

HMENU GetMenuById(UINT nMenuResId) const;

Parâmetros

nMenuResId
[in] A ID do recurso para o menu.

Valor de retorno

Um identificador para o menu associado ou NULL se o menu não for encontrado.

CContextMenuManager::GetMenuByName

Retorna um identificador para um menu específico.

HMENU GetMenuByName(
    LPCTSTR lpszName,
    UINT* puiOrigResID = NULL) const;

Parâmetros

lpszName
[in] Uma cadeia de caracteres que contém o nome do menu a ser recuperado.

puiOrigResID
[out] Um ponteiro para um UINT. Esse parâmetro contém a ID do recurso do menu especificado, se encontrado.

Valor de retorno

Um identificador para o menu que corresponde ao nome especificado pelo lpszName. NULL se não houver nenhum menu chamado lpszName.

Comentários

Se esse método encontrar um menu que corresponda a lpszName, GetMenuByName armazenará a ID do recurso de menu no parâmetro puiOrigResID.

CContextMenuManager::GetMenuNames

Retorna a lista de nomes de menu adicionados ao CContextMenuManager.

void GetMenuNames(CStringList& listOfNames) const;

Parâmetros

listOfNames
[out] Uma referência a um parâmetro CStringList. Esse método grava a lista de nomes de menu nesse parâmetro.

CContextMenuManager::LoadState

Carrega informações associadas à classe CContextMenuManager do Registro do Windows.

virtual BOOL LoadState(LPCTSTR lpszProfileName = NULL);

Parâmetros

lpszProfileName
[in] Uma cadeia de caracteres que contém o caminho relativo de uma chave do registro.

Valor de retorno

Um valor diferente de zero, se o método tiver êxito. Caso contrário, 0.

Comentários

O parâmetro lpszProfileName não é o caminho absoluto para uma entrada de registro. Ele é um caminho relativo adicionado ao final da chave do Registro padrão para o aplicativo. Para obter ou definir a chave do Registro padrão, use os métodos CWinAppEx::GetRegistryBase e CWinAppEx::SetRegistryBase, respectivamente.

Use o método CContextMenuManager::SaveState para salvar os menus de atalho no registro.

CContextMenuManager::ResetState

Limpa todos os itens dos menus de atalho associados à Classe CContextMenuManager.

virtual BOOL ResetState();

Valor de retorno

TRUE se o método for bem-sucedido; FALSE se ocorrer uma falha.

Comentários

Esse método limpa os menus pop-up e os remove do CContextMenuManager.

CContextMenuManager::SaveState

Salva informações associadas à Classe CContextMenuManager no Registro do Windows.

virtual BOOL SaveState(LPCTSTR lpszProfileName = NULL);

Parâmetros

lpszProfileName
[in] Uma cadeia de caracteres que contém o caminho relativo de uma chave do registro.

Valor de retorno

Um valor diferente de zero, se o método tiver êxito. Caso contrário, 0.

Comentários

O parâmetro lpszProfileName não é o caminho absoluto para uma entrada de registro. Ele é um caminho relativo adicionado ao final da chave do Registro padrão para o aplicativo. Para obter ou definir a chave do Registro padrão, use os métodos CWinAppEx::GetRegistryBase e CWinAppEx::SetRegistryBase, respectivamente.

Use o método CContextMenuManager::LoadState para carregar os menus de atalho do registro.

CContextMenuManager::SetDontCloseActiveMenu

Controla se o CContextMenuManager fecha o menu pop-up ativo quando exibir um novo menu pop-up.

void SetDontCloseActiveMenu (BOOL bSet = TRUE);

Parâmetros

bSet
[in] Um parâmetro booliano que controla se o menu pop-up ativo deve ser fechado. Um valor TRUE indica que o menu pop-up ativo não está fechado. FALSE indica que o menu pop-up ativo está fechado.

Comentários

Por padrão, o CContextMenuManager fecha o menu pop-up ativo.

CContextMenuManager::ShowPopupMenu

Exibe o menu de atalho especificado.

virtual BOOL ShowPopupMenu(
    UINT uiMenuResId,
    int x,
    int y,
    CWnd* pWndOwner,
    BOOL bOwnMessage = FALSE,
    BOOL bRightAlign = FALSE);

virtual CMFCPopupMenu* ShowPopupMenu(
    HMENU hmenuPopup,
    int x,
    int y,
    CWnd* pWndOwner,
    BOOL bOwnMessage = FALSE,
    BOOL bAutoDestroy = TRUE,
    BOOL bRightAlign = FALSE);

Parâmetros

uiMenuResId
[in] A ID do recurso do menu que esse método exibirá.

x
[in] O deslocamento horizontal para o menu de atalho nas coordenadas de cliente.

y
[in] O deslocamento vertical para o menu de atalho nas coordenadas de cliente

pWndOwner
[in] Um ponteiro para a janela pai do menu de atalho.

bOwnMessage
[in] Um parâmetro booliano que indica como as mensagens são roteadas. Se bOwnMessage for FALSE, o roteamento MFC padrão será usado. Caso contrário, pWndOwner receberá as mensagens.

hmenuPopup
[in] O identificador do menu que este método exibirá.

bAutoDestroy
[in] Um parâmetro booliano que indica se o menu será destruído automaticamente.

bRightAlign
[in] Um parâmetro booliano que indica como os itens de menu são alinhados. Se bRightAlign for TRUE, o menu será alinhado à direita para a ordem de leitura da direita para a esquerda.

Valor de retorno

A sobrecarga do primeiro método retornará diferente de zero se o método mostrar o menu com êxito; caso contrário, zero. A sobrecarga do segundo método retorna um ponteiro para CMFCPopupMenu se o menu de atalho for exibido corretamente; caso contrário, NULL.

Comentários

Esse método se assemelha ao método CContextMenuManager::TrackPopupMenu, pois ambos os métodos exibem um menu de atalho. No entanto, TrackPopupMenu retorna o índice do comando de menu selecionado.

Se o parâmetro bAutoDestroy for FALSE, você deverá chamar manualmente o método herdado DestroyMenu para liberar recursos de memória. A implementação padrão de ShowPopupMenu não usa o parâmetro bAutoDestroy. Ela é fornecida para uso futuro ou para classes personalizadas derivadas da classe CContextMenuManager.

CContextMenuManager::TrackPopupMenu

Exibe o menu de atalho especificado e retorna o índice do comando de menu de atalho selecionado.

virtual UINT TrackPopupMenu(
    HMENU hmenuPopup,
    int x,
    int y,
    CWnd* pWndOwner,
    BOOL bRightAlign = FALSE);

Parâmetros

hmenuPopup
[in] O identificador do menu de atalho exibido por esse método.

x
[in] O deslocamento horizontal para o menu de atalho nas coordenadas de cliente.

y
[in] O deslocamento vertical para o menu de atalho nas coordenadas de cliente.

pWndOwner
[in] Um ponteiro para a janela pai do menu de atalho.

bRightAlign
[in] Um parâmetro booliano que indica como os itens de menu são alinhados. Se bRightAlign for TRUE, o menu será alinhado à direita para a ordem de leitura da direita para a esquerda. Se bRightAlign for FALSE, o menu será alinhado à esquerda para a ordem de leitura da esquerda para a direita.

Valor de retorno

A ID de comando do menu do comando escolhido pelo usuário; zero se o usuário fechar o menu de atalho sem selecionar um comando de menu.

Comentários

Esse método funciona como uma chamada modal para exibir um menu de atalho. O aplicativo não continuará para a linha seguinte no código até que o usuário feche o menu de atalho ou selecione um comando. Um método alternativo que você pode usar para exibir um menu de atalho é CContextMenuManager::ShowPopupMenu. Esse método não é uma chamada modal e não retornará a ID do comando selecionado.

Confira também

Gráfico da hierarquia
Classes
Classe CWinAppEx