Partilhar via

Classe CUserToolsManager

  • Artigo

Mantém a coleção de objetos da Classe CUserTool Class em um aplicativo. Uma ferramenta de usuário é um item de menu que executa um aplicativo externo. O objeto CUserToolsManager permite que o usuário ou desenvolvedor adicione ferramentas de usuário ao aplicativo. Dá suporte à execução dos comandos associados às ferramentas do usuário e também salva informações sobre ferramentas de usuário no Registro do Windows.

Sintaxe

class CUserToolsManager : public CObject

Membros

Construtores públicos

Nome Descrição
CUserToolsManager::CUserToolsManager Constrói um CUserToolsManager.

Métodos públicos

Nome Descrição
CUserToolsManager::CreateNewTool Cria uma nova ferramenta de usuário.
CUserToolsManager::FindTool Retorna o ponteiro para o objeto CMFCUserTool associado a uma ID de comando especificada.
CUserToolsManager::GetArgumentsMenuID Retorna a ID do recurso associada ao menu Argumentos na guia Ferramentas da caixa de diálogo Personalizar.
CUserToolsManager::GetDefExt Retorna a extensão padrão que a caixa de diálogo Abrir Arquivo ( CFileDialog) usa no campo Comando na guia Ferramentas da caixa de diálogo Personalizar.
CUserToolsManager::GetFilter Retorna o filtro de arquivo que a caixa de diálogo Abrir Arquivo ( CFileDialog Class) usa no campo Comando na guia Ferramentas da caixa de diálogo Personalizar.
CUserToolsManager::GetInitialDirMenuID Retorna a ID do recurso associada ao menu Diretório inicial na guia Ferramentas da caixa de diálogo Personalizar.
CUserToolsManager::GetMaxTools Retorna o número máximo de ferramentas de usuário que podem ser alocadas no aplicativo.
CUserToolsManager::GetToolsEntryCmd Retorna a ID de comando do espaço reservado do item de menu para ferramentas de usuário.
CUserToolsManager::GetUserTools Retorna uma referência à lista de ferramentas de usuário.
CUserToolsManager::InvokeTool Executa um aplicativo associado à ferramenta de usuário que tem uma ID de comando especificada.
CUserToolsManager::IsUserToolCmd Determina se uma ID de comando está associada a uma ferramenta de usuário.
CUserToolsManager::LoadState Carrega informações sobre ferramentas de usuário do Registro do Windows.
CUserToolsManager::MoveToolDown Move a ferramenta de usuário especificada para baixo na lista de ferramentas de usuário.
CUserToolsManager::MoveToolUp Move a ferramenta de usuário especificada para cima na lista de ferramentas de usuário.
CUserToolsManager::RemoveTool Remove a ferramenta de usuário especificada do aplicativo.
CUserToolsManager::SaveState Armazena informações sobre ferramentas de usuário no Registro do Windows.
CUserToolsManager::SetDefExt Especifica a extensão padrão que a caixa de diálogo Abrir Arquivo ( CFileDialog Class) usa no campo Comando na guia Ferramentas da caixa de diálogo Personalizar.
CUserToolsManager::SetFilter Especifica o filtro de arquivo que a caixa de diálogo Abrir Arquivo ( CFileDialog Class) usa no campo Comando na guia Ferramentas da caixa de diálogo Personalizar.

Comentários

Para incorporar ferramentas de usuário ao seu aplicativo, você deve:

  1. Reservar um item de menu e uma ID de comando associada para uma entrada de menu de ferramenta de usuário.

  2. Reservar uma ID de comando sequencial para cada ferramenta de usuário que um usuário pode definir em seu aplicativo.

  3. Chame o método CWinAppEx::EnableUserTools e forneça os seguintes parâmetros: ID de comando de menu, ID do primeiro comando de ferramenta de usuário e ID do último comando da ferramenta de usuário.

Deve existir apenas um objeto CUserToolsManager global por aplicativo.

Para obter um exemplo de ferramentas de usuário, consulte o projeto de amostra VisualStudioDemo.

Exemplo

O exemplo a seguir demonstra como recuperar uma referência a um objeto CUserToolsManager e como criar novas ferramentas de usuário. Esse snippet de código faz parte do exemplo de Demonstração do Visual Studio.

CUserToolsManager* pUserToolsManager = theApp.GetUserToolsManager();
if (pUserToolsManager != NULL && pUserToolsManager->GetUserTools().IsEmpty())
{
   // CUserToolsManager* pUserToolsManager
   CUserTool* pTool1 = pUserToolsManager->CreateNewTool();
   pTool1->m_strLabel = _T("&Notepad");
   pTool1->SetCommand(_T("notepad.exe"));

   CUserTool* pTool2 = pUserToolsManager->CreateNewTool();
   pTool2->m_strLabel = _T("Paint &Brush");
   pTool2->SetCommand(_T("mspaint.exe"));

   CUserTool* pTool3 = pUserToolsManager->CreateNewTool();
   pTool3->m_strLabel = _T("&Windows Explorer");
   pTool3->SetCommand(_T("explorer.exe"));

   CUserTool* pTool4 = pUserToolsManager->CreateNewTool();
   pTool4->m_strLabel = _T("Microsoft On-&Line");
   pTool4->SetCommand(_T("http://www.microsoft.com"));
}

Hierarquia de herança

CObject

CUserToolsManager

Requisitos

Cabeçalho: afxusertoolsmanager.h

CUserToolsManager::CreateNewTool

Cria uma nova ferramenta de usuário.

CUserTool* CreateNewTool();

Valor de retorno

Um ponteiro para a ferramenta de usuário recém-criada ou NULL se o número de ferramentas de usuário excedeu o máximo. O tipo retornado é o mesmo que o tipo que é passado para o parâmetro CWinAppEx::EnableUserTools como o pToolRTC.

Comentários

Esse método localiza a primeira ID de comando de menu disponível no intervalo fornecido na chamada para CWinAppEx::EnableUserTools e atribui a ferramenta de usuário a essa ID.

O método falhará se o número de ferramentas atingir o máximo. Isso ocorre quando todas as IDs de comando dentro do intervalo são atribuídas às ferramentas do usuário. Recupere o número máximo de ferramentas chamando CUserToolsManager::GetMaxTools. Obtenha acesso à lista de ferramentas chamando o método CUserToolsManager::GetUserTools.

CUserToolsManager::CUserToolsManager

Constrói um CUserToolsManager. Cada aplicativo deve ter no máximo um gerenciador de ferramentas de usuário.

CUserToolsManager();

CUserToolsManager(
    const UINT uiCmdToolsDummy,
    const UINT uiCmdFirst,
    const UINT uiCmdLast,
    CRuntimeClass* pToolRTC=RUNTIME_CLASS(CUserTool),
    UINT uArgMenuID=0,
    UINT uInitDirMenuID=0);

Parâmetros

uiCmdToolsDummy
[entrada] Um inteiro sem sinal que a estrutura usa como espaço reservado para a ID de comando do menu de ferramentas do usuário.

uiCmdFirst
[in] A ID de comando do primeiro comando de ferramenta do usuário.

uiCmdLast
[entrada] A ID de comando do último comando de ferramenta do usuário.

pToolRTC
[entrada] A classe que cria CUserToolsManager::CreateNewTool. Usando essa classe, use um tipo derivado de classe CUserTool em vez da implementação padrão.

uArgMenuID
[entrada] A ID do recurso de menu do menu pop-up de argumentos.

uInitDirMenuID
[entrada] A ID do recurso de menu do menu pop-up do diretório inicial.

Comentários

Não chame esse construtor. Em vez disso, chame CWinAppEx::EnableUserTools para habilitar ferramentas de usuário e chame CWinAppEx::GetUserToolsManager para obter um ponteiro para CUserToolsManager. Para obter mais informações, consulte Ferramentas definidas pelo usuário.

CUserToolsManager::FindTool

Retorna o ponteiro para o objeto CUserTool Class associado a uma ID de comando especificada.

CUserTool* FindTool(UINT uiCmdId) const;

Parâmetros

uiCmdId
[entrada] Um identificador de comando de menu.

Valor de retorno

Um ponteiro para uma classe CUserTool ou um objeto CUserTool-derivado se tiver êxito, caso contrário, NULL.

Comentários

Quando FindTool for bem-sucedido, o tipo retornado é o mesmo que o tipo do parâmetro pToolRTC para CWinAppEx::EnableUserTools.

CUserToolsManager::GetArgumentsMenuID

Retorna a ID do recurso associada ao menu Argumentos na guia Ferramentas da caixa de diálogo Personalizar.

UINT GetArgumentsMenuID() const;

Valor de retorno

O identificador de um recurso de menu.

Comentários

O parâmetro uArgMenuID de CWinAppEx::EnableUserTools especifica a ID do recurso.

CUserToolsManager::GetDefExt

Retorna a extensão padrão que a caixa de diálogo Abrir Arquivo ( CFileDialog) usa no campo Comando na guia Ferramentas da caixa de diálogo Personalizar.

const CString& GetDefExt() const;

Valor de retorno

Uma referência ao objeto CStringque contém a extensão.

CUserToolsManager::GetFilter

Retorna o filtro de arquivo que a caixa de diálogo Abrir Arquivo ( CFileDialog Class) usa no campo Comando na guia Ferramentas da caixa de diálogo Personalizar.

const CString& GetFilter() const;

Valor de retorno

Uma referência ao objeto CString que contém o filtro.

CUserToolsManager::GetInitialDirMenuID

Retorna a ID do recurso associada ao menu Diretório inicial na guia Ferramentas da caixa de diálogo Personalizar.

UINT GetInitialDirMenuID() const;

Valor de retorno

Um identificador de recurso de menu.

Comentários

A ID retornada é especificada no parâmetro uInitDirMenuID de CWinAppEx::EnableUserTools.

CUserToolsManager::GetMaxTools

Retorna o número máximo de ferramentas de usuário que podem ser alocadas no aplicativo.

int GetMaxTools() const;

Valor de retorno

O número máximo de ferramentas de usuário que podem ser alocados.

Comentários

Chame esse método para recuperar o número máximo de ferramentas que podem ser alocadas no aplicativo. Esse número é o número de IDs no intervalo do uiCmdFirst até os parâmetros uiCmdLast que você passa para CWinAppEx::EnableUserTools.

CUserToolsManager::GetToolsEntryCmd

Retorna a ID de comando do espaço reservado do item de menu para ferramentas de usuário.

UINT GetToolsEntryCmd() const;

Valor de retorno

A ID de comando do espaço reservado.

Comentários

Para habilitar as ferramentas de usuário, você chama CWinAppEx::EnableUserTools. O parâmetro uiCmdToolsDummy especifica a ID de comando do comando de entrada de ferramentas. Esse método retorna a ID do comando de entrada de ferramentas. Onde quer que essa ID seja usada em um menu, ela é substituída pela lista de ferramentas de usuário quando o menu é exibido.

CUserToolsManager::GetUserTools

Retorna uma referência à lista de ferramentas de usuário.

const CObList& GetUserTools() const;

Valor de retorno

Uma referência const a um objeto classe CObList que contém uma lista de ferramentas de usuário.

Comentários

Chame esse método para recuperar uma lista de ferramentas de usuário que o objeto CUserToolsManager mantém. Cada ferramenta de usuário é representada por um objeto do tipo Classe CUserTool ou um tipo derivado de CUserTool. O tipo é especificado pelo parâmetro pToolRTC ao chamar CWinAppEx::EnableUserTools para habilitar as ferramentas de usuário.

CUserToolsManager::InvokeTool

Executa um aplicativo associado à ferramenta de usuário que tem uma ID de comando especificada.

BOOL InvokeTool(UINT uiCmdId);

Parâmetros

uiCmdId
[entrada] A ID do comando do menu associada à ferramenta de usuário.

Valor de retorno

Diferente de zero se o comando associado à ferramenta de usuário foi executado com êxito, caso contrário, 0.

Comentários

Chame esse método para executar um aplicativo associado à ferramenta de usuário que tem a ID de comando especificada por uiCmdId.

CUserToolsManager::IsUserToolCmd

Determina se uma ID de comando está associada a uma ferramenta de usuário.

BOOL IsUserToolCmd(UINT uiCmdId) const;

Parâmetros

uiCmdId
[entrada] Uma ID de comando do item de menu.

Valor de retorno

Diferente de zero se uma determinada ID de comando estiver associada a uma ferramenta de usuário, caso contrário, 0.

Comentários

Esse método verifica se a ID de comando fornecida está no intervalo de ID de comando. Especifique o intervalo ao chamar CWinAppEx::EnableUserTools para habilitar as ferramentas de usuário.

CUserToolsManager::LoadState

Carrega informações sobre ferramentas de usuário do Registro do Windows.

BOOL LoadState(LPCTSTR lpszProfileName=NULL);

Parâmetros

lpszProfileName
[entrada] O caminho da chave do Registro do Windows.

Valor de retorno

Diferente de zero se o estado tiver sido carregado com êxito, caso contrário 0.

Comentários

Esse método carrega o estado do CUserToolsManager objeto do Registro do Windows.

Normalmente, você não chama este método diretamente. CWinAppEx::LoadState o chama como parte do processo de inicialização do workspace.

CUserToolsManager::MoveToolDown

Move a ferramenta de usuário especificada para baixo na lista de ferramentas de usuário.

BOOL MoveToolDown(CUserTool* pTool);

Parâmetros

pTool
[entrada] Especifica a ferramenta de usuário a ser movida.

Valor de retorno

Diferente de zero se a ferramenta de usuário foi movida para baixo com êxito, caso contrário, 0.

Comentários

O método falhará se a ferramenta especificada pelo pTool não estiver na lista interna ou se a ferramenta for a última na lista.

CUserToolsManager::MoveToolUp

Move a ferramenta de usuário especificada para cima na lista de ferramentas de usuário.

BOOL MoveToolUp(CUserTool* pTool);

Parâmetros

pTool
[entrada] Especifica a ferramenta de usuário a ser movida.

Valor de retorno

Diferente de zero se a ferramenta de usuário foi movida para cima com êxito, caso contrário, 0.

Comentários

O método falhará se a ferramenta especificar que o parâmetro pTool não está na lista interna ou se a ferramenta for o primeiro item de ferramenta na lista.

CUserToolsManager::RemoveTool

Remove a ferramenta de usuário especificada do aplicativo.

BOOL RemoveTool(CUserTool* pTool);

Parâmetros

pTool
[entrada, saída] Um ponteiro para uma ferramenta de usuário a ser removida.

Valor de retorno

TRUE se a ferramenta for removida com êxito. Caso contrário, FALSE.

Comentários

Se a ferramenta for removida com êxito, esse método excluirá o pTool.

CUserToolsManager::SaveState

Armazena informações sobre ferramentas de usuário no Registro do Windows.

BOOL SaveState(LPCTSTR lpszProfileName=NULL);

Parâmetros

lpszProfileName
[entrada] Um caminho para a chave do Registro do Windows.

Valor de retorno

Diferente de zero se o estado foi salvo com êxito, caso contrário, 0.

Comentários

O método armazena o estado atual do objeto CUserToolsManager no registro do Windows.

Normalmente, você não precisa chamar esse método diretamente, CWinAppEx::SaveState o chama automaticamente como parte do processo de serialização do workspace do aplicativo.

CUserToolsManager::SetDefExt

Especifica a extensão padrão que a caixa de diálogo Abrir Arquivo ( CFileDialog Class) usa no campo Comando na guia Ferramentas da caixa de diálogo Personalizar.

void SetDefExt(const CString& strDefExt);

Parâmetros

strDefExt
[entrada] Uma cadeia de caracteres de texto que contém a extensão de nome de arquivo padrão.

Comentários

Chame esse método para especificar uma extensão de nome de arquivo padrão na caixa de diálogo Abrir Arquivo, que é exibida quando o usuário seleciona um aplicativo para associar à ferramenta de usuário. O padrão é "exe".

CUserToolsManager::SetFilter

Especifica o filtro de arquivo que a caixa de diálogo Abrir Arquivo ( CFileDialog Class) usa no campo Comando na guia Ferramentas da caixa de diálogo Personalizar.

void SetFilter(const CString& strFilter);

Parâmetros

strFilter
[entrada] Especifica o filtro.

Confira também

Gráfico da hierarquia
Classes
Classe CWinAppEx
Classe CUserTool