CUserToolsManager-Klasse

Verwaltet die Auflistung von CUserTool-Klassenobjekten in einer Anwendung. Ein Benutzertool ist ein Menüelement, das eine externe Anwendung ausführt. Mithilfe des Objekts CUserToolsManager können Benutzer oder Entwickler der Anwendung neue Benutzertools hinzuzufügen. Es unterstützt die Ausführung der Befehle, die Benutzertools zugeordnet sind, und speichert außerdem Informationen über Benutzertools in der Windows-Registrierung.

Syntax

class CUserToolsManager : public CObject

Member

Öffentliche Konstruktoren

Name	Beschreibung
CUserToolsManager::CUserToolsManager	Erstellt ein Objekt vom Typ CUserToolsManager.

Öffentliche Methoden

Name	Beschreibung
CUserToolsManager::CreateNewTool	Erstellt ein neues Benutzertool.
CUserToolsManager::FindTool	Gibt den Zeiger auf das CMFCUserTool Objekt zurück, das einer angegebenen Befehls-ID zugeordnet ist.
CUserToolsManager::GetArgumentsMenuID	Gibt die Ressourcen-ID zurück, die dem Menü "Argumente " auf der Registerkarte "Extras " des Dialogfelds "Anpassen " zugeordnet ist.
CUserToolsManager::GetDefExt	Gibt die Standarderweiterung zurück, die im Dialogfeld "Datei öffnen " ( CFileDialog) im Feld "Befehl " auf der Registerkarte "Extras " des Dialogfelds "Anpassen " verwendet wird.
CUserToolsManager::GetFilter	Gibt den Dateifilter zurück, den das Dialogfeld "Datei öffnen " ( CFileDialog-Klasse) im Feld "Befehl " auf der Registerkarte "Extras " des Dialogfelds "Anpassen " verwendet.
CUserToolsManager::GetInitialDirMenuID	Gibt die Ressourcen-ID zurück, die dem Menü "Ursprüngliches Verzeichnis " auf der Registerkarte "Extras " des Dialogfelds "Anpassen " zugeordnet ist.
CUserToolsManager::GetMaxTools	Gibt die maximale Anzahl von Benutzertools zurück, die in der Anwendung zugeordnet werden können.
CUserToolsManager::GetToolsEntryCmd	Gibt die Befehls-ID des Menüelementplatzhalters für Benutzertools zurück.
CUserToolsManager::GetUserTools	Gibt einen Verweis auf die Liste der Benutzertools zurück.
CUserToolsManager::InvokeTool	Führt eine Anwendung aus, die dem Benutzertool zugeordnet ist, das über eine angegebene Befehls-ID verfügt.
CUserToolsManager::IsUserToolCmd	Bestimmt, ob eine Befehls-ID einem Benutzertool zugeordnet ist.
CUserToolsManager::LoadState	Lädt Informationen zu Benutzertools aus der Windows-Registrierung.
CUserToolsManager::MoveToolDown	Verschiebt das angegebene Benutzertool in der Liste der Benutzertools nach unten.
CUserToolsManager::MoveToolUp	Verschiebt das angegebene Benutzertool in der Liste der Benutzertools nach oben.
CUserToolsManager::RemoveTool	Entfernt das angegebene Benutzertool aus der Anwendung.
CUserToolsManager::SaveState	Speichert Informationen zu Benutzertools in der Windows-Registrierung.
CUserToolsManager::SetDefExt	Gibt die Standarderweiterung an, die im Dialogfeld "Datei öffnen " ( CFileDialog-Klasse) im Befehlsfeld auf der Registerkarte "Extras " des Dialogfelds "Anpassen " verwendet wird.
CUserToolsManager::SetFilter	Gibt den Dateifilter an, den das Dialogfeld "Datei öffnen " ( CFileDialog-Klasse) im Feld "Befehl " auf der Registerkarte "Extras " des Dialogfelds "Anpassen " verwendet.

Hinweise

Um Benutzertools in Ihre Anwendung zu integrieren, müssen Sie:

1. Reservieren Sie ein Menüelement und eine zugeordnete Befehls-ID für einen Benutzertoolmenüeintrag.

2. Reservieren Sie eine sequenzielle Befehls-ID für jedes Benutzertool, das ein Benutzer in Ihrer Anwendung definieren kann.

3. Rufen Sie die CWinAppEx::EnableUserTools-Methode auf, und geben Sie die folgenden Parameter an: Menübefehls-ID, Befehls-ID des ersten Benutzertools und letzte Benutzertool-Befehls-ID.

Pro Anwendung sollte nur ein globales CUserToolsManager Objekt vorhanden sein.

Ein Beispiel für Benutzertools finden Sie im VisualStudioDemo-Beispielprojekt.

Beispiel

Im folgenden Beispiel wird das Abrufen eines Verweises auf ein CUserToolsManager Objekt und das Erstellen neuer Benutzertools veranschaulicht. Dieser Codeausschnitt ist Teil des Visual Studio Demo-Beispiels.

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"));
}

Vererbungshierarchie

CObject

CUserToolsManager

Anforderungen

Header: afxusertoolsmanager.h

CUserToolsManager::CreateNewTool

Erstellt ein neues Benutzertool.

CUserTool* CreateNewTool();

Rückgabewert

Ein Zeiger auf das neu erstellte Benutzertool oder NULL, wenn die Anzahl der Benutzertools das Maximum überschritten hat. Der zurückgegebene Typ entspricht dem Typ, an den der pToolRTC-Parameter übergeben CWinAppEx::EnableUserTools wird.

Hinweise

Diese Methode findet die erste verfügbare Menübefehls-ID im Bereich, der im Aufruf von CWinAppEx::EnableUserTools angegeben wird, und weist dem Benutzertool diese ID zu.

Die Methode schlägt fehl, wenn die Anzahl der Tools das Maximum erreicht hat. Dies tritt auf, wenn allen Befehls-IDs innerhalb des Bereichs Benutzertools zugewiesen werden. Sie können die maximale Anzahl von Tools abrufen, indem Sie CUserToolsManager::GetMaxTools aufrufen. Sie können zugriff auf die Toolsliste erhalten, indem Sie die CUserToolsManager::GetUserTools-Methode aufrufen.

CUserToolsManager::CUserToolsManager

Erstellt ein Objekt vom Typ CUserToolsManager. Jede Anwendung muss über höchstens einen Benutzertools-Manager verfügen.

CUserToolsManager();

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

Parameter

uiCmdToolsDummy
[Eingabe] Eine ganze Zahl ohne Vorzeichen, die das Framework als Platzhalter für die Befehls-ID des Menüs „Benutzertools“ verwendet

uiCmdFirst
[Eingabe] Die Befehls-ID für den ersten Benutzertoolbefehl

uiCmdLast
[Eingabe] Die Befehls-ID für den letzten Benutzertoolbefehl

pToolRTC
[in] Die Klasse, die CUserToolsManager::CreateNewTool erstellt. Mithilfe dieser Klasse können Sie anstelle der Standardimplementierung einen abgeleiteten CUserTool-Klassentyp verwenden.

uArgMenuID
[in] Die Menüressourcen-ID des Popupmenüs für Argumente.

uInitDirMenuID
[in] Die Menüressourcen-ID des anfänglichen Popupmenüs des Verzeichnisses.

Hinweise

Rufen Sie diesen Konstruktor nicht auf. Rufen Sie stattdessen CWinAppEx::EnableUserTools auf, um Benutzertools zu aktivieren, und rufen Sie CWinAppEx::GetUserToolsManager auf, um einen Zeiger auf die CUserToolsManager. Weitere Informationen finden Sie unter "Benutzerdefinierte Tools".

CUserToolsManager::FindTool

Gibt den Zeiger auf das CUserTool Class -Objekt zurück, das einer angegebenen Befehls-ID zugeordnet ist.

CUserTool* FindTool(UINT uiCmdId) const;

Parameter

uiCmdId
[in] Ein Menübefehlsbezeichner.

Rückgabewert

Ein Zeiger auf eine CUserTool-Klasse oder CUserToolein -abgeleitetes Objekt, falls erfolgreich; andernfalls NULL.

Hinweise

Bei FindTool erfolgreicher Ausführung entspricht der zurückgegebene Typ dem Typ des pToolRTC-Parameters zu CWinAppEx::EnableUserTools.

CUserToolsManager::GetArgumentsMenuID

Gibt die Ressourcen-ID zurück, die dem Menü "Argumente " auf der Registerkarte "Extras " des Dialogfelds "Anpassen " zugeordnet ist.

UINT GetArgumentsMenuID() const;

Rückgabewert

Der Bezeichner einer Menüressource.

Hinweise

Der Parameter "uArgMenuID " von CWinAppEx::EnableUserTools gibt die ID der Ressource an.

CUserToolsManager::GetDefExt

Gibt die Standarderweiterung zurück, die im Dialogfeld "Datei öffnen " ( CFileDialog) im Feld "Befehl " auf der Registerkarte "Extras " des Dialogfelds "Anpassen " verwendet wird.

const CString& GetDefExt() const;

Rückgabewert

Ein Verweis auf das CString Objekt, das die Erweiterung enthält.

CUserToolsManager::GetFilter

Gibt den Dateifilter zurück, den das Dialogfeld "Datei öffnen " ( CFileDialog-Klasse) im Feld "Befehl " auf der Registerkarte "Extras " des Dialogfelds "Anpassen " verwendet.

const CString& GetFilter() const;

Rückgabewert

Ein Verweis auf das CString Objekt, das den Filter enthält.

CUserToolsManager::GetInitialDirMenuID

Gibt die Ressourcen-ID zurück, die dem Menü "Ursprüngliches Verzeichnis " auf der Registerkarte "Extras " des Dialogfelds "Anpassen " zugeordnet ist.

UINT GetInitialDirMenuID() const;

Rückgabewert

Ein Menüressourcenbezeichner.

Hinweise

Die zurückgegebene ID wird im Parameter "uInitDirMenuID " von CWinAppEx::EnableUserTools angegeben.

CUserToolsManager::GetMaxTools

Gibt die maximale Anzahl von Benutzertools zurück, die in der Anwendung zugeordnet werden können.

int GetMaxTools() const;

Rückgabewert

Die maximale Anzahl von Benutzertools, die zugewiesen werden können.

Hinweise

Rufen Sie diese Methode auf, um die maximale Anzahl von Tools abzurufen, die in der Anwendung zugeordnet werden können. Diese Zahl ist die Anzahl der IDs im Bereich von uiCmdFirst über die uiCmdLast-Parameter, die Sie an CWinAppEx::EnableUserTools übergeben.

CUserToolsManager::GetToolsEntryCmd

Gibt die Befehls-ID des Menüelementplatzhalters für Benutzertools zurück.

UINT GetToolsEntryCmd() const;

Rückgabewert

Die Befehls-ID des Platzhalters.

Hinweise

Um Benutzertools zu aktivieren, rufen Sie CWinAppEx::EnableUserTools auf. Der Parameter "uiCmdToolsDummy " gibt die Befehls-ID des Tools-Eintragsbefehls an. Diese Methode gibt die Befehls-ID des Tools-Eintrags zurück. Unabhängig davon, wo diese ID in einem Menü verwendet wird, wird sie durch die Liste der Benutzertools ersetzt, wenn das Menü angezeigt wird.

CUserToolsManager::GetUserTools

Gibt einen Verweis auf die Liste der Benutzertools zurück.

const CObList& GetUserTools() const;

Rückgabewert

Ein Konstverweis auf ein CObList Class -Objekt, das eine Liste der Benutzertools enthält.

Hinweise

Rufen Sie diese Methode auf, um eine Liste der Benutzertools abzurufen, die das CUserToolsManager -Objekt verwaltet. Jedes Benutzertool wird durch ein Objekt vom Typ CUserTool Class oder einem typ abgeleiteten CUserToolTyp dargestellt. Der Typ wird vom pToolRTC-Parameter angegeben, wenn Sie CWinAppEx::EnableUserTools aufrufen, um Benutzertools zu aktivieren.

CUserToolsManager::InvokeTool

Führt eine Anwendung aus, die dem Benutzertool zugeordnet ist, das über eine angegebene Befehls-ID verfügt.

BOOL InvokeTool(UINT uiCmdId);

Parameter

uiCmdId
[in] Die Menübefehls-ID, die dem Benutzertool zugeordnet ist.

Rückgabewert

Nonzero, wenn der dem Benutzertool zugeordnete Befehl erfolgreich ausgeführt wurde; andernfalls 0.

Hinweise

Rufen Sie diese Methode auf, um eine Anwendung auszuführen, die dem Benutzertool zugeordnet ist, das die befehls-ID enthält, die von "uiCmdId" angegeben ist.

CUserToolsManager::IsUserToolCmd

Bestimmt, ob eine Befehls-ID einem Benutzertool zugeordnet ist.

BOOL IsUserToolCmd(UINT uiCmdId) const;

Parameter

uiCmdId
[in] Eine Befehls-ID des Menüelements.

Rückgabewert

Nonzero, wenn eine bestimmte Befehls-ID einem Benutzertool zugeordnet ist; andernfalls 0.

Hinweise

Diese Methode überprüft, ob sich die angegebene Befehls-ID im Befehls-ID-Bereich befindet. Sie geben den Bereich an, wenn Sie CWinAppEx::EnableUserTools aufrufen, um Benutzertools zu aktivieren.

CUserToolsManager::LoadState

Lädt Informationen zu Benutzertools aus der Windows-Registrierung.

BOOL LoadState(LPCTSTR lpszProfileName=NULL);

Parameter

lpszProfileName
[in] Der Pfad des Windows-Registrierungsschlüssels.

Rückgabewert

Nonzero, wenn der Zustand erfolgreich geladen wurde; andernfalls 0.

Hinweise

Diese Methode lädt den Status des CUserToolsManager Objekts aus der Windows-Registrierung.

In der Regel rufen Sie diese Methode nicht direkt auf. CWinAppEx::LoadState ruft sie als Teil des Arbeitsbereichsinitialisierungsprozesses auf.

CUserToolsManager::MoveToolDown

Verschiebt das angegebene Benutzertool in der Liste der Benutzertools nach unten.

BOOL MoveToolDown(CUserTool* pTool);

Parameter

pTool
[in] Gibt das zu verschiebende Benutzertool an.

Rückgabewert

Nonzero, wenn das Benutzertool erfolgreich nach unten verschoben wurde; andernfalls 0.

Hinweise

Die Methode schlägt fehl, wenn das vom pTool angegebene Tool nicht in der internen Liste enthalten ist oder das Tool zuletzt in der Liste enthalten ist.

CUserToolsManager::MoveToolUp

Verschiebt das angegebene Benutzertool in der Liste der Benutzertools nach oben.

BOOL MoveToolUp(CUserTool* pTool);

Parameter

pTool
[in] Gibt das zu verschiebende Benutzertool an.

Rückgabewert

Nonzero, wenn das Benutzertool erfolgreich nach oben verschoben wurde; andernfalls 0.

Hinweise

Die Methode schlägt fehl, wenn das tool, das der pTool-Parameter angibt, nicht in der internen Liste enthalten ist oder wenn das Tool das erste Toolelement in der Liste ist.

CUserToolsManager::RemoveTool

Entfernt das angegebene Benutzertool aus der Anwendung.

BOOL RemoveTool(CUserTool* pTool);

Parameter

pTool
[in, out] Ein Zeiger auf ein Benutzertool, das entfernt werden soll.

Rückgabewert

TRUE, wenn das Tool erfolgreich entfernt wurde. Andernfalls FALSE.

Hinweise

Wenn das Tool erfolgreich entfernt wurde, löscht diese Methode pTool.

CUserToolsManager::SaveState

Speichert Informationen zu Benutzertools in der Windows-Registrierung.

BOOL SaveState(LPCTSTR lpszProfileName=NULL);

Parameter

lpszProfileName
[in] Ein Pfad zum Windows-Registrierungsschlüssel.

Rückgabewert

Nonzero, wenn der Zustand erfolgreich gespeichert wurde; andernfalls 0.

Hinweise

Die Methode speichert den aktuellen Status des CUserToolsManager Objekts in der Windows-Registrierung.

In der Regel müssen Sie diese Methode nicht direkt aufrufen, CWinAppEx::SaveState ruft sie automatisch als Teil des Arbeitsbereich serialisierungsprozesses der Anwendung auf.

CUserToolsManager::SetDefExt

Gibt die Standarderweiterung an, die im Dialogfeld "Datei öffnen " ( CFileDialog-Klasse) im Befehlsfeld auf der Registerkarte "Extras " des Dialogfelds "Anpassen " verwendet wird.

void SetDefExt(const CString& strDefExt);

Parameter

strDefExt
[in] Eine Textzeichenfolge, die die Standarddateierweiterung enthält.

Hinweise

Rufen Sie diese Methode auf, um eine Standarddateierweiterung im Dialogfeld "Datei öffnen " anzugeben, die angezeigt wird, wenn der Benutzer eine Anwendung auswählt, die dem Benutzertool zugeordnet werden soll. Der Standardwert ist "exe".

CUserToolsManager::SetFilter

Gibt den Dateifilter an, den das Dialogfeld "Datei öffnen " ( CFileDialog-Klasse) im Feld "Befehl " auf der Registerkarte "Extras " des Dialogfelds "Anpassen " verwendet.

void SetFilter(const CString& strFilter);

Parameter

strFilter
[in] Gibt den Filter an.

Siehe auch

Hierarchiediagramm
Klassen
CWinAppEx-Klasse
CUserTool-Klasse