Classe CUserToolsManager

  • Articolo

Gestisce l'insieme di oggetti CUserTool Class in un'applicazione. Uno strumento utente è una voce di menu che esegue un'applicazione esterna. L'oggetto CUserToolsManager consente all'utente o allo sviluppatore di aggiungere nuovi strumenti utente all'applicazione. Supporta l'esecuzione di comandi associati a strumenti utente e inoltre salva le informazioni sugli strumenti utente nel Registro di sistema di Windows.

Sintassi

class CUserToolsManager : public CObject

Membri

Costruttori pubblici

Nome Descrizione
CUserToolsManager::CUserToolsManager Costruisce un oggetto CUserToolsManager.

Metodi pubblici

Nome Descrizione
CUserToolsManager::CreateNewTool Crea un nuovo strumento utente.
CUserToolsManager::FindTool Restituisce il puntatore all'oggetto CMFCUserTool associato a un ID comando specificato.
CUserToolsManager::GetArgumentsMenuID Restituisce l'ID risorsa associato al menu Argomenti della scheda Strumenti della finestra di dialogo Personalizza .
CUserToolsManager::GetDefExt Restituisce l'estensione predefinita utilizzata dalla finestra di dialogo Apri file ( CFileDialog) nel campo Comando della scheda Strumenti della finestra di dialogo Personalizza .
CUserToolsManager::GetFilter Restituisce il filtro file utilizzato dalla finestra di dialogo Apri file ( classe CFileDialog) nel campo Comando della scheda Strumenti della finestra di dialogo Personalizza .
CUserToolsManager::GetInitialDirMenuID Restituisce l'ID risorsa associato al menu Directory iniziale nella scheda Strumenti della finestra di dialogo Personalizza .
CUserToolsManager::GetMaxTools Restituisce il numero massimo di strumenti utente che possono essere allocati nell'applicazione.
CUserToolsManager::GetToolsEntryCmd Restituisce l'ID comando del segnaposto della voce di menu per gli strumenti utente.
CUserToolsManager::GetUserTools Restituisce un riferimento all'elenco di strumenti utente.
CUserToolsManager::InvokeTool Esegue un'applicazione associata allo strumento utente con un ID comando specificato.
CUserToolsManager::IsUserToolCmd Determina se un ID comando è associato a uno strumento utente.
CUserToolsManager::LoadState Carica informazioni sugli strumenti utente dal Registro di sistema di Windows.
CUserToolsManager::MoveToolDown Sposta lo strumento utente specificato verso il basso nell'elenco degli strumenti utente.
CUserToolsManager::MoveToolUp Sposta lo strumento utente specificato verso l'alto nell'elenco degli strumenti utente.
CUserToolsManager::RemoveTool Rimuove lo strumento utente specificato dall'applicazione.
CUserToolsManager::SaveState Archivia informazioni sugli strumenti utente nel Registro di sistema di Windows.
CUserToolsManager::SetDefExt Specifica l'estensione predefinita usata dalla finestra di dialogo Apri file ( classe CFileDialog) nel campo Comando della scheda Strumenti della finestra di dialogo Personalizza .
CUserToolsManager::SetFilter Specifica il filtro file utilizzato dalla finestra di dialogo Apri file ( classe CFileDialog) nel campo Comando della scheda Strumenti della finestra di dialogo Personalizza .

Osservazioni:

Per incorporare gli strumenti utente nell'applicazione, è necessario:

  1. Riservare una voce di menu e un ID comando associato per una voce di menu dello strumento utente.

  2. Riservare un ID comando sequenziale per ogni strumento utente che un utente può definire nell'applicazione.

  3. Chiamare il metodo CWinAppEx::EnableUserTools e specificare i parametri seguenti: ID comando menu, ID comando del primo strumento utente e ULTIMO ID comando dello strumento utente.

Deve essere presente un solo oggetto globale CUserToolsManager per applicazione.

Per un esempio di strumenti utente, vedere il progetto di esempio VisualStudioDemo.

Esempio

Nell'esempio seguente viene illustrato come recuperare un riferimento a un CUserToolsManager oggetto e come creare nuovi strumenti utente. Questo frammento di codice fa parte dell'esempio demo di 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"));
}

Gerarchia di ereditarietà

CObject

CUserToolsManager

Requisiti

Intestazione: afxusertoolsmanager.h

CUserToolsManager::CreateNewTool

Crea un nuovo strumento utente.

CUserTool* CreateNewTool();

Valore restituito

Puntatore allo strumento utente appena creato o NULL se il numero di strumenti utente ha superato il valore massimo. Il tipo restituito corrisponde al tipo passato al CWinAppEx::EnableUserTools parametro pToolRTC .

Osservazioni:

Questo metodo trova il primo ID comando di menu disponibile nell'intervallo fornito nella chiamata a CWinAppEx::EnableUserTools e assegna questo ID allo strumento utente.

Il metodo ha esito negativo se il numero di strumenti ha raggiunto il valore massimo. Ciò si verifica quando tutti gli ID comando all'interno dell'intervallo vengono assegnati agli strumenti utente. È possibile recuperare il numero massimo di strumenti chiamando CUserToolsManager::GetMaxTools. È possibile accedere all'elenco degli strumenti chiamando il metodo CUserToolsManager::GetUserTools .

CUserToolsManager::CUserToolsManager

Costruisce un oggetto CUserToolsManager. Ogni applicazione deve avere al massimo un gestore strumenti utente.

CUserToolsManager();

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

Parametri

uiCmdToolsDummy
[in] Intero senza segno utilizzato dal framework come segnaposto per l'ID comando del menu degli strumenti utente.

uiCmdFirst
[in] ID comando per il primo comando dello strumento utente.

uiCmdLast
[in] ID comando per l'ultimo comando dello strumento utente.

pToolRTC
[in] Classe creata da CUserToolsManager::CreateNewTool . Usando questa classe, è possibile usare un tipo derivato della classe CUserTool anziché l'implementazione predefinita.

uArgMenuID
[in] ID risorsa del menu del menu popup degli argomenti.

uInitDirMenuID
[in] ID risorsa del menu del menu popup della directory iniziale.

Osservazioni:

Non chiamare questo costruttore. Chiamare invece CWinAppEx::EnableUserTools per abilitare gli strumenti utente e chiamare CWinAppEx::GetUserToolsManager per ottenere un puntatore a CUserToolsManager. Per altre informazioni, vedere Strumenti definiti dall'utente.

CUserToolsManager::FindTool

Restituisce il puntatore all'oggetto classe CUserTool associato a un ID comando specificato.

CUserTool* FindTool(UINT uiCmdId) const;

Parametri

uiCmdId
[in] Identificatore del comando di menu.

Valore restituito

Puntatore a una classe CUserTool o CUserToola un oggetto derivato da se ha esito positivo; in caso contrario, NULL.

Osservazioni:

Quando FindTool ha esito positivo, il tipo restituito corrisponde al tipo del parametro pToolRTC a CWinAppEx::EnableUserTools.

CUserToolsManager::GetArgumentsMenuID

Restituisce l'ID risorsa associato al menu Argomenti della scheda Strumenti della finestra di dialogo Personalizza .

UINT GetArgumentsMenuID() const;

Valore restituito

Identificatore di una risorsa di menu.

Osservazioni:

Il parametro uArgMenuID di CWinAppEx::EnableUserTools specifica l'ID della risorsa.

CUserToolsManager::GetDefExt

Restituisce l'estensione predefinita utilizzata dalla finestra di dialogo Apri file ( CFileDialog) nel campo Comando della scheda Strumenti della finestra di dialogo Personalizza .

const CString& GetDefExt() const;

Valore restituito

Riferimento all'oggetto CString che contiene l'estensione.

CUserToolsManager::GetFilter

Restituisce il filtro file utilizzato dalla finestra di dialogo Apri file ( classe CFileDialog) nel campo Comando della scheda Strumenti della finestra di dialogo Personalizza .

const CString& GetFilter() const;

Valore restituito

Riferimento all'oggetto CString che contiene il filtro.

CUserToolsManager::GetInitialDirMenuID

Restituisce l'ID risorsa associato al menu Directory iniziale nella scheda Strumenti della finestra di dialogo Personalizza .

UINT GetInitialDirMenuID() const;

Valore restituito

Identificatore di risorsa del menu.

Osservazioni:

L'ID restituito viene specificato nel parametro uInitDirMenuID di CWinAppEx::EnableUserTools.

CUserToolsManager::GetMaxTools

Restituisce il numero massimo di strumenti utente che possono essere allocati nell'applicazione.

int GetMaxTools() const;

Valore restituito

Numero massimo di strumenti utente che possono essere allocati.

Osservazioni:

Chiamare questo metodo per recuperare il numero massimo di strumenti che è possibile allocare nell'applicazione. Questo numero è il numero di ID nell'intervallo compreso tra uiCmdFirst e i parametri uiCmdLast passati a CWinAppEx::EnableUserTools.

CUserToolsManager::GetToolsEntryCmd

Restituisce l'ID comando del segnaposto della voce di menu per gli strumenti utente.

UINT GetToolsEntryCmd() const;

Valore restituito

ID comando del segnaposto.

Osservazioni:

Per abilitare gli strumenti utente, chiamare CWinAppEx::EnableUserTools. Il parametro uiCmdToolsDummy specifica l'ID comando del comando di immissione degli strumenti. Questo metodo restituisce l'ID comando di immissione degli strumenti. Ovunque questo ID venga usato in un menu, viene sostituito dall'elenco degli strumenti utente quando viene visualizzato il menu.

CUserToolsManager::GetUserTools

Restituisce un riferimento all'elenco di strumenti utente.

const CObList& GetUserTools() const;

Valore restituito

Riferimento const a un oggetto Classe CObList che contiene un elenco di strumenti utente.

Osservazioni:

Chiamare questo metodo per recuperare un elenco di strumenti utente che l'oggetto CUserToolsManager gestisce. Ogni strumento utente è rappresentato da un oggetto di tipo CUserTool Class o da un tipo derivato da CUserTool. Il tipo viene specificato dal parametro pToolRTC quando si chiama CWinAppEx::EnableUserTools per abilitare gli strumenti utente.

CUserToolsManager::InvokeTool

Esegue un'applicazione associata allo strumento utente con un ID comando specificato.

BOOL InvokeTool(UINT uiCmdId);

Parametri

uiCmdId
[in] ID del comando di menu associato allo strumento utente.

Valore restituito

Diverso da zero se il comando associato allo strumento utente è stato eseguito correttamente; in caso contrario, 0.

Osservazioni:

Chiamare questo metodo per eseguire un'applicazione associata allo strumento utente con l'ID comando specificato da uiCmdId.

CUserToolsManager::IsUserToolCmd

Determina se un ID comando è associato a uno strumento utente.

BOOL IsUserToolCmd(UINT uiCmdId) const;

Parametri

uiCmdId
[in] ID comando della voce di menu.

Valore restituito

Diverso da zero se un ID di comando specificato è associato a uno strumento utente; in caso contrario, 0.

Osservazioni:

Questo metodo controlla se l'ID di comando specificato si trova nell'intervallo di ID comando. Specificare l'intervallo quando si chiama CWinAppEx::EnableUserTools per abilitare gli strumenti utente.

CUserToolsManager::LoadState

Carica informazioni sugli strumenti utente dal Registro di sistema di Windows.

BOOL LoadState(LPCTSTR lpszProfileName=NULL);

Parametri

lpszProfileName
[in] Percorso della chiave del Registro di sistema di Windows.

Valore restituito

Diverso da zero se lo stato è stato caricato correttamente; in caso contrario, 0.

Osservazioni:

Questo metodo carica lo stato dell'oggetto CUserToolsManager dal Registro di sistema di Windows.

In genere, questo metodo non viene chiamato direttamente. CWinAppEx::LoadState lo chiama come parte del processo di inizializzazione dell'area di lavoro.

CUserToolsManager::MoveToolDown

Sposta lo strumento utente specificato verso il basso nell'elenco degli strumenti utente.

BOOL MoveToolDown(CUserTool* pTool);

Parametri

pTool
[in] Specifica lo strumento utente da spostare.

Valore restituito

Diverso da zero se lo strumento utente è stato spostato correttamente; in caso contrario, 0.

Osservazioni:

Il metodo ha esito negativo se lo strumento specificato da pTool non si trova nell'elenco interno o se lo strumento è l'ultimo nell'elenco.

CUserToolsManager::MoveToolUp

Sposta lo strumento utente specificato verso l'alto nell'elenco degli strumenti utente.

BOOL MoveToolUp(CUserTool* pTool);

Parametri

pTool
[in] Specifica lo strumento utente da spostare.

Valore restituito

Diverso da zero se lo strumento utente è stato spostato correttamente; in caso contrario, 0.

Osservazioni:

Il metodo ha esito negativo se lo strumento specificato dal parametro pTool non si trova nell'elenco interno o se lo strumento è il primo elemento dello strumento nell'elenco.

CUserToolsManager::RemoveTool

Rimuove lo strumento utente specificato dall'applicazione.

BOOL RemoveTool(CUserTool* pTool);

Parametri

pTool
[in, out] Puntatore a uno strumento utente da rimuovere.

Valore restituito

TRUE se lo strumento viene rimosso correttamente. In caso contrario, FALSE.

Osservazioni:

Se lo strumento viene rimosso correttamente, questo metodo elimina pTool.

CUserToolsManager::SaveState

Archivia informazioni sugli strumenti utente nel Registro di sistema di Windows.

BOOL SaveState(LPCTSTR lpszProfileName=NULL);

Parametri

lpszProfileName
[in] Percorso della chiave del Registro di sistema di Windows.

Valore restituito

Diverso da zero se lo stato è stato salvato correttamente; in caso contrario, 0.

Osservazioni:

Il metodo archivia lo stato corrente dell'oggetto CUserToolsManager nel Registro di sistema di Windows.

In genere, non è necessario chiamare direttamente questo metodo, CWinAppEx::SaveState lo chiama automaticamente come parte del processo di serializzazione dell'area di lavoro dell'applicazione.

CUserToolsManager::SetDefExt

Specifica l'estensione predefinita usata dalla finestra di dialogo Apri file ( classe CFileDialog) nel campo Comando della scheda Strumenti della finestra di dialogo Personalizza .

void SetDefExt(const CString& strDefExt);

Parametri

strDefExt
[in] Stringa di testo contenente l'estensione del nome file predefinita.

Osservazioni:

Chiamare questo metodo per specificare un'estensione di file predefinita nella finestra di dialogo Apri file, visualizzata quando l'utente seleziona un'applicazione da associare allo strumento utente. Il valore predefinito è "exe".

CUserToolsManager::SetFilter

Specifica il filtro file utilizzato dalla finestra di dialogo Apri file ( classe CFileDialog) nel campo Comando della scheda Strumenti della finestra di dialogo Personalizza .

void SetFilter(const CString& strFilter);

Parametri

strFilter
[in] Specifica il filtro.

Vedi anche

Grafico della gerarchia
Classi
Classe CWinAppEx
Classe CUserTool