Classe CUserToolsManager
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:
Reservar um item de menu e uma ID de comando associada para uma entrada de menu de ferramenta de usuário.
Reservar uma ID de comando sequencial para cada ferramenta de usuário que um usuário pode definir em seu aplicativo.
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
CUserToolsManager
Requisitos
Cabeçalho: afxusertoolsmanager.h
CUserToolsManager::CreateNewTool
Cria uma nova ferramenta de usuário.
CUserTool* CreateNewTool();
Valor de Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de