Classe CUserToolsManager

Mantém a coleção de objetos de classe CUserTool numa aplicação. Uma ferramenta de utilizador é um item de menu que executa uma aplicação externa. O CUserToolsManager objeto permite que o utilizador ou programador adicione novas ferramentas de utilizador à aplicação. Suporta a execução dos comandos associados às ferramentas de utilizador e também guarda informações sobre ferramentas de utilizador no registo do Windows.

Sintaxe

class CUserToolsManager : public CObject

Membros

Construtores Públicos

Métodos Públicos

Observações

Para incorporar ferramentas de utilizador na sua aplicação, deve:

1. Reserve um item de menu e um ID de comando associado para uma entrada de menu de ferramenta de utilizador.

2. Reserve um ID de comando sequencial para cada ferramenta de utilizador que um utilizador possa definir na sua aplicação.

3. Chame o método CWinAppEx::EnableUserTools e forneça os seguintes parâmetros: ID de comando de menu, ID de comando de primeira ferramenta de utilizador e ID de comando de última ferramenta de utilizador.

Deveria haver apenas um objeto global CUserToolsManager por aplicação.

Para um exemplo de ferramentas de utilizador, veja o projeto de exemplo VisualStudioDemo.

Example

O exemplo seguinte demonstra como recuperar uma referência a um CUserToolsManager objeto e como criar novas ferramentas de utilizador. Este excerto 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

Requerimentos

Cabeçalho: afxusertoolsmanager.h

CUserToolsManager::CreateNewTool

Cria uma nova ferramenta de utilizador.

CUserTool* CreateNewTool();

Valor de retorno

Um ponteiro para a ferramenta de utilizador recém-criada, ou NULL se o número de ferramentas de utilizador tiver excedido o máximo. O tipo devolvido é o mesmo do tipo que é passado CWinAppEx::EnableUserTools como parâmetro pToolRTC .

Observações

Este método encontra o primeiro ID de comando de menu disponível no intervalo fornecido na chamada a CWinAppEx::EnableUserTools e atribui este ID à ferramenta de utilizador.

O método falha se o número de ferramentas atingir o máximo. Isto ocorre quando todos os IDs de comando dentro do intervalo são atribuídos a ferramentas de utilizador. Pode obter o máximo de ferramentas ligando para CUserToolsManager::GetMaxTools. Pode aceder à lista de ferramentas chamando o método CUserToolsManager::GetUserTools .

CUserToolsManager::CUserToolsManager

Constrói um CUserToolsManager. Cada aplicação deve ter, no máximo, um gestor de ferramentas de utilizador.

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
[dentro] Um inteiro não assinado que a framework usa como marcador para o ID de comando do menu de ferramentas de utilizador.

uiCmdFirst
[dentro] O ID do comando para o primeiro comando da ferramenta de utilizador.

uiCmdLast
[dentro] O ID do comando para o último comando da ferramenta de utilizador.

pToolRTC
[dentro] A classe que o CUserToolsManager::CreateNewTool cria. Ao usar esta classe, pode usar um tipo derivado de classe CUserTool em vez da implementação padrão.

uArgMenuID
[dentro] O ID do recurso do menu de argumentos aparece no menu.

uInitDirMenuID
[dentro] O ID do recurso do menu pop-up do diretório inicial.

Observações

Não chames a isto construtor. Em vez disso, chame CWinAppEx::EnableUserTools para ativar as ferramentas de utilizador, e chame CWinAppEx::GetUserToolsManager para obter um ponteiro para o CUserToolsManager. Para mais informações, consulte Ferramentas definidas pelo utilizador.

CUserToolsManager::FindTool

Devolve o ponteiro para o objeto CUserTool Class que está associado a um ID de comando especificado.

CUserTool* FindTool(UINT uiCmdId) const;

Parâmetros

uiCmdId
[dentro] Um identificador de comando de menu.

Valor de retorno

Um apontador para uma Classe CUserTool ou CUserToolobjeto derivado em se houver sucesso; caso contrário, NULL.

Observações

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

CUserToolsManager::GetArgumentsMenuID

Devolve o ID de recurso associado ao menu Argumentos no separador Ferramentas da caixa de diálogo Personalizar .

UINT GetArgumentsMenuID() const;

Valor de retorno

O identificador de um recurso de menu.

Observações

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

CUserToolsManager::GetDefExt

Devolve a extensão padrão que a caixa de diálogo Abrir Ficheiro ( CFileDialog) usa no campo Command do separador Ferramentas da caixa de diálogo Personalizar .

const CString& GetDefExt() const;

Valor de retorno

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

CUserToolsManager::GetFilter

Devolve o filtro de ficheiro que a caixa de diálogo Abrir Ficheiro ( CFileDialog Class) usa no campo Command no separador Ferramentas da caixa de diálogo Personalizar .

const CString& GetFilter() const;

Valor de retorno

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

CUserToolsManager::GetInitialDirMenuID

Devolve o ID de recurso associado ao menu de diretórios Iniciais no separador Ferramentas da caixa de diálogo Personalizar .

UINT GetInitialDirMenuID() const;

Valor de retorno

Um identificador de recurso de menu.

Observações

O ID devolvido é especificado no parâmetro uInitDirMenuID de CWinAppEx::EnableUserTools.

CUserToolsManager::GetMaxTools

Devolve o número máximo de ferramentas de utilizador que podem ser alocadas na aplicação.

int GetMaxTools() const;

Valor de retorno

O número máximo de ferramentas de utilizador que podem ser alocadas.

Observações

Chame este método para recuperar o número máximo de ferramentas que podem ser alocadas na aplicação. Este número é o número de IDs no intervalo desde uiCmdFirst até aos parâmetros uiCmdLast que passa para CWinAppEx::EnableUserTools.

CUserToolsManager::GetToolsEntryCmd

Devolve o ID do comando do elemento de menu reservado para as ferramentas do utilizador.

UINT GetToolsEntryCmd() const;

Valor de retorno

O ID de comando do marcador de lugar.

Observações

Para ativar ferramentas de utilizador, chama CWinAppEx::EnableUserTools. O parâmetro uiCmdToolsDummy especifica o ID do comando de entrada das ferramentas. Este método devolve o ID do comando de entrada da ferramenta. Onde quer que esse ID seja usado num menu, é substituído pela lista de ferramentas de utilizador quando o menu aparece.

CUserToolsManager::GetUserTools

Retorna uma referência à lista de ferramentas de utilizador.

const CObList& GetUserTools() const;

Valor de retorno

Uma referência const a um objeto de Classe CObList que contém uma lista de ferramentas de utilizador.

Observações

Chame este método para recuperar uma lista de ferramentas de utilizador que o objeto CUserToolsManager mantém. Cada ferramenta de utilizador é representada por um objeto do tipo CUserTool Class ou por um tipo derivado de CUserTool. O tipo é especificado pelo parâmetro pToolRTC quando chama CWinAppEx::EnableUserTools para ativar as ferramentas de utilizador.

CUserToolsManager::InvokeTool

Executa uma aplicação associada à ferramenta de utilizador que tem um ID de comando especificado.

BOOL InvokeTool(UINT uiCmdId);

Parâmetros

uiCmdId
[dentro] O ID do comando do menu associado à ferramenta do utilizador.

Valor de retorno

Diferente de zero se o comando associado à ferramenta de utilizador foi executado com sucesso; caso contrário, 0.

Observações

Chame este método para executar uma aplicação associada à ferramenta de utilizador que tenha o ID de comando especificado por uiCmdId.

CUserToolsManager::IsUserToolCmd

Determina se um ID de comando está associado a uma ferramenta de utilizador.

BOOL IsUserToolCmd(UINT uiCmdId) const;

Parâmetros

uiCmdId
[dentro] Um ID de comando do item do menu.

Valor de retorno

Não nulo se um determinado ID de comando estiver associado a uma ferramenta de utilizador; caso contrário, 0.

Observações

Este método verifica se o ID de comando dado está dentro do intervalo de ID de comando. Especifica o intervalo quando chama o CWinAppEx::EnableUserTools para ativar as ferramentas do utilizador.

CUserToolsManager::LoadState

Carrega informação sobre ferramentas de utilizador a partir do registo do Windows.

BOOL LoadState(LPCTSTR lpszProfileName=NULL);

Parâmetros

lpszProfileName
[dentro] O caminho da chave de registo do Windows.

Valor de retorno

Não nulo se o estado fosse carregado com sucesso; caso contrário, 0.

Observações

Este método carrega o estado do CUserToolsManager objeto a partir do registo do Windows.

Normalmente, não se chama este método diretamente. O CWinAppEx::LoadState chama-o como parte do processo de inicialização do espaço de trabalho.

CUserToolsManager::MoveToolDown

Move a ferramenta de utilizador especificada para baixo na lista de ferramentas de utilizador.

BOOL MoveToolDown(CUserTool* pTool);

Parâmetros

pTool
[dentro] Especifica a ferramenta do utilizador para se mover.

Valor de retorno

Diferente de zero se a ferramenta de utilizador for movida com sucesso; caso contrário, 0.

Observações

O método falha 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 utilizador especificada para cima na lista de ferramentas de utilizador.

BOOL MoveToolUp(CUserTool* pTool);

Parâmetros

pTool
[dentro] Especifica a ferramenta do utilizador para se mover.

Valor de retorno

Diferente de zero se a ferramenta do utilizador foi movida com sucesso; caso contrário, 0.

Observações

O método falha se a ferramenta especificada pelo parâmetro pTool não estiver na lista interna ou se a ferramenta for o primeiro item da lista.

CUserToolsManager::RemoveTool

Remove a ferramenta de utilizador especificada da aplicação.

BOOL RemoveTool(CUserTool* pTool);

Parâmetros

pTool
[inspira, expira] Um apontador para uma ferramenta de utilizador a ser removida.

Valor de retorno

VERDADE se a ferramenta for removida com sucesso. Caso contrário, é FALSE.

Observações

Se a ferramenta for removida com sucesso, este método elimina o pTool.

CUserToolsManager::SaveState

Armazena informação sobre ferramentas de utilizador no registo do Windows.

BOOL SaveState(LPCTSTR lpszProfileName=NULL);

Parâmetros

lpszProfileName
[dentro] Um caminho para a chave de registo do Windows.

Valor de retorno

Diferente de zero se o estado fosse salvo com sucesso; caso contrário, 0.

Observações

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

Normalmente, não é necessário chamar este método diretamente, o CWinAppEx::SaveState chama-o automaticamente como parte do processo de serialização do workspace da aplicação.

CUserToolsManager::SetDefExt

Especifica a extensão padrão que a caixa de diálogo Abrir Ficheiro ( CFileDialog Class) usa no campo Command no separador Ferramentas da caixa de diálogo Personalizar .

void SetDefExt(const CString& strDefExt);

Parâmetros

strDefExt
[dentro] Uma cadeia de texto que contém a extensão padrão do nome do ficheiro.

Observações

Chame este método para especificar uma extensão de nome de ficheiro por defeito na caixa de diálogo Abrir Ficheiro , que é exibida quando o utilizador seleciona uma aplicação para associar à ferramenta do utilizador. O padrão é "exe".

CUserToolsManager::SetFilter

Especifica o filtro de ficheiro que a caixa de diálogo Abrir Ficheiro ( CFileDialog Class) usa no campo Command do separador Ferramentas da caixa de diálogo Personalizar .

void SetFilter(const CString& strFilter);

Parâmetros

strFilter
[dentro] Especifica o filtro.

Consulte também

Gráfico de Hierarquia
Classes
CWinAppEx Classe
CUserTool Classe