CUserToolsManager 類別

發行項
08/04/2024

維護應用程式中 CUserTool Class 物件的集合。使用者工具是執行外部應用程式的功能表項目。 CUserToolsManager 物件可讓使用者或開發人員將新的使用者工具加入至應用程式。它支援執行與使用者工具相關聯的命令，也會在 Windows 登錄中儲存使用者工具的相關資訊。

語法

class CUserToolsManager : public CObject

成員

公用建構函式

名稱	描述
CUserToolsManager：：CUserToolsManager	建構 `CUserToolsManager`。

公用方法

名稱	描述
CUserToolsManager：：CreateNewTool	建立新的使用者工具。
CUserToolsManager：：FindTool	傳回與指定之命令標識符相關聯的對象指標 `CMFCUserTool` 。
CUserToolsManager：：GetArgumentsMenuID	傳回與 [自定義] 對話方塊之 [工具] 索引標籤上 [自變數] 功能表相關聯的資源識別碼。
CUserToolsManager：：GetDefExt	會傳回 [開啟檔案] 對話框（CFileDialog）在 [自定義] 對話方塊之 [工具] 索引標籤的 [命令] 字段中使用的預設擴展名。
CUserToolsManager：：GetFilter	會傳回 [檔案開啟] 對話框（CFileDialog 類別）在 [自定義] 對話方塊之 [工具] 索引標籤標的 [命令] 字段中所使用的檔案篩選。
CUserToolsManager：：GetInitialDirMenuID	傳回與 [自定義] 對話方塊之 [工具] 索引標籤上 [初始目錄] 選單相關聯的資源識別碼。
CUserToolsManager：：GetMaxTools	傳回可在應用程式中配置的使用者工具數目上限。
CUserToolsManager：：GetToolsEntryCmd	傳回使用者工具功能表項佔位元的命令標識碼。
CUserToolsManager：：GetUserTools	傳回使用者工具清單的參考。
CUserToolsManager：：InvokeTool	執行與具有指定命令標識碼的使用者工具相關聯的應用程式。
CUserToolsManager：：IsUserToolCmd	判斷命令標識碼是否與使用者工具相關聯。
CUserToolsManager：：LoadState	從 Windows 登錄載入使用者工具的相關信息。
CUserToolsManager：：MoveToolDown	在使用者工具清單中，將指定的使用者工具向下移動。
CUserToolsManager：：MoveToolUp	在使用者工具清單中向上移動指定的使用者工具。
CUserToolsManager：：RemoveTool	從應用程式移除指定的使用者工具。
CUserToolsManager：：SaveState	將使用者工具的相關信息儲存在 Windows 登錄中。
CUserToolsManager：：SetDefExt	指定 [檔案開啟] 對話框（CFileDialog 類別）在 [自定義] 對話方塊之 [工具] 索引標籤的 [命令] 字段中所使用的預設擴展名。
CUserToolsManager：：SetFilter	指定 [檔案開啟] 對話框（CFileDialog 類別）在 [自定義] 對話方塊之 [工具] 索引標籤的 [命令] 字段中所使用的檔案篩選。

備註

若要將使用者工具併入您的應用程式，您必須：

為使用者工具功能表項保留功能表項和相關聯的命令標識碼。
為使用者可以在應用程式中定義的每個使用者工具保留循序命令標識碼。
呼叫 CWinAppEx：：EnableUserTools 方法，並提供下列參數：功能表命令標識碼、第一個使用者工具命令標識碼，以及最後一個使用者工具命令標識符。

每個應用程式應該只有一個全域 CUserToolsManager 物件。

如需使用者工具的範例，請參閱VisualStudioDemo範例專案。

範例

下列範例示範如何擷取對象的參考 CUserToolsManager ，以及如何建立新的使用者工具。此代碼段是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"));
}

繼承階層架構

CObject

CUserToolsManager

需求

標頭： afxusertoolsmanager.h

CUserToolsManager：：CreateNewTool

建立新的使用者工具。

CUserTool* CreateNewTool();

傳回值

新建立使用者工具的指標，如果使用者工具數目超過最大值，則為 NULL。傳回的類型與傳遞至 CWinAppEx::EnableUserTools pToolRTC 參數的類型相同。

備註

這個方法會在呼叫 CWinAppEx：：EnableUserTools 中提供的範圍中尋找第一個可用的功能表命令標識碼，並指派使用者工具此標識碼。

如果工具數目達到最大值，方法就會失敗。當範圍內的所有命令標識碼都指派給使用者工具時，就會發生這種情況。您可以呼叫 CUserToolsManager：：GetMaxTools 來擷取工具數目上限。您可以呼叫 CUserToolsManager：：GetUserTools 方法來存取工具列表。

CUserToolsManager：：CUserToolsManager

建構 CUserToolsManager。每個應用程式最多都必須有一個使用者工具管理員。

CUserToolsManager();

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

參數

uiCmdToolsDummy
[in] 架構用來作為使用者工具功能表命令識別碼預留位置之不帶正負號的整數。

uiCmdFirst
[in] 第一個使用者工具命令的命令識別碼。

uiCmdLast
[in] 最後一個使用者工具命令的命令識別碼。

pToolRTC
[in]CUserToolsManager：：CreateNewTool 所建立的類別。藉由使用此類別，您可以使用 CUserTool 類別的衍生類型，而不是預設實作。

uArgMenuID
[in]自變數快捷功能表的功能表資源標識碼。

uInitDirMenuID
[in]初始目錄快捷功能表的功能表資源識別碼。

備註

請勿呼叫此建構函式。請改為呼叫 CWinAppEx：：EnableUserTools 以啟用使用者工具，並呼叫 CWinAppEx：：GetUserToolsManager 以取得的 CUserToolsManager指標。如需詳細資訊，請參閱使用者定義的工具。

CUserToolsManager：：FindTool

傳回與指定命令標識符相關聯的 CUserTool 類別物件的指標。

CUserTool* FindTool(UINT uiCmdId) const;

參數

uiCmdId
[in]功能表命令標識碼。

傳回值

如果成功，則為 CUserTool 類別或 CUserTool衍生物件的指標，否則為 NULL。

備註

成功時FindTool，傳回的類型與 CWinAppEx：：EnableUserTools 的 pToolRTC 參數類型相同。

CUserToolsManager：：GetArgumentsMenuID

傳回與 [自定義] 對話方塊之 [工具] 索引標籤上 [自變數] 功能表相關聯的資源識別碼。

UINT GetArgumentsMenuID() const;

傳回值

功能表資源的標識碼。

備註

CWinAppEx：：EnableUserTools 的 uArgMenuID 參數會指定資源的標識符。

CUserToolsManager：：GetDefExt

會傳回 [開啟檔案] 對話框（CFileDialog）在 [自定義] 對話方塊之 [工具] 索引標籤的 [命令] 字段中使用的預設擴展名。

const CString& GetDefExt() const;

傳回值

包含延伸模組之對象的參考 CString 。

CUserToolsManager：：GetFilter

會傳回 [檔案開啟] 對話框（CFileDialog 類別）在 [自定義] 對話方塊之 [工具] 索引標籤標的 [命令] 字段中所使用的檔案篩選。

const CString& GetFilter() const;

傳回值

包含篩選之 CString 對象的參考。

CUserToolsManager：：GetInitialDirMenuID

傳回與 [自定義] 對話方塊之 [工具] 索引標籤上 [初始目錄] 選單相關聯的資源識別碼。

UINT GetInitialDirMenuID() const;

傳回值

功能表資源標識碼。

備註

傳回的標識碼是在 CWinAppEx：：EnableUserTools 的 uInitDirMenuID 參數中指定。

CUserToolsManager：：GetMaxTools

傳回可在應用程式中配置的使用者工具數目上限。

int GetMaxTools() const;

傳回值

可配置的使用者工具數目上限。

備註

呼叫此方法，以擷取可在應用程式中配置的最大工具數目。這個數位是從 uiCmdFirst 到您傳遞至 CWinAppEx：：EnableUserTools 的 uiCmdLast 參數範圍中的標識符數目。

CUserToolsManager：：GetToolsEntryCmd

傳回使用者工具功能表項佔位元的命令標識碼。

UINT GetToolsEntryCmd() const;

傳回值

佔位元的命令標識碼。

備註

若要啟用使用者工具，請呼叫 CWinAppEx：：EnableUserTools。 uiCmdToolsDummy 參數會指定工具專案命令的命令標識碼。這個方法會傳回工具專案命令標識碼。只要在功能表中使用該標識碼，當功能表出現時，就會由使用者工具清單取代。

CUserToolsManager：：GetUserTools

傳回使用者工具清單的參考。

const CObList& GetUserTools() const;

傳回值

CObList 類別物件的常數參考，其中包含使用者工具的清單。

備註

呼叫此方法以擷取 CUserToolsManager 物件所維護的使用者工具清單。每個使用者工具都會以 CUserTool 類別類型的物件或衍生自 CUserTool的類型來表示。當您呼叫 CWinAppEx：：EnableUserTools 以啟用使用者工具時，pToolRTC 參數會指定類型。

CUserToolsManager：：InvokeTool

執行與具有指定命令標識碼的使用者工具相關聯的應用程式。

BOOL InvokeTool(UINT uiCmdId);

參數

uiCmdId
[in]與使用者工具相關聯的功能表命令標識碼。

傳回值

如果已成功執行與使用者工具相關聯的命令，則為非零;否則為 0。

備註

呼叫這個方法，以執行與使用者工具相關聯的應用程式，其中包含 uiCmdId 所指定的命令標識符。

CUserToolsManager：：IsUserToolCmd

判斷命令標識碼是否與使用者工具相關聯。

BOOL IsUserToolCmd(UINT uiCmdId) const;

參數

uiCmdId
[in]功能表項的命令標識碼。

傳回值

如果指定的命令標識碼與使用者工具相關聯，則為非零;否則為 0。

備註

這個方法會檢查指定的命令標識碼是否在命令標識元範圍中。當您呼叫 CWinAppEx：：EnableUserTools 以啟用使用者工具時，您可以指定範圍。

CUserToolsManager：：LoadState

從 Windows 登錄載入使用者工具的相關信息。

BOOL LoadState(LPCTSTR lpszProfileName=NULL);

參數

lpszProfileName
[in]Windows 登錄機碼的路徑。

傳回值

如果狀態已成功載入，則為非零;否則為 0。

備註

這個方法會從 Windows 登錄載入物件的狀態 CUserToolsManager 。

通常，您不會直接呼叫此方法。 CWinAppEx：：LoadState 會將其呼叫為工作區初始化程式的一部分。

CUserToolsManager：：MoveToolDown

在使用者工具清單中，將指定的使用者工具向下移動。

BOOL MoveToolDown(CUserTool* pTool);

參數

pTool
[in]指定要移動的使用者工具。

傳回值

如果使用者工具已成功下移，則為非零;否則為 0。

備註

如果 pTool 指定的工具不在內部清單中，或是工具在清單中最後一個，則方法會失敗。

CUserToolsManager：：MoveToolUp

在使用者工具清單中向上移動指定的使用者工具。

BOOL MoveToolUp(CUserTool* pTool);

參數

pTool
[in]指定要移動的使用者工具。

傳回值

如果使用者工具已成功上移，則為非零;否則為 0。

備註

如果 pTool 參數指定的工具不在內部清單中，或工具是清單中的第一個工具專案，則方法會失敗。

CUserToolsManager：：RemoveTool

從應用程式移除指定的使用者工具。

BOOL RemoveTool(CUserTool* pTool);

參數

pTool
[in， out]要移除之使用者工具的指標。

傳回值

如果已成功移除工具，則為TRUE。否則為 FALSE。

備註

如果已成功移除此工具，此方法會 刪除 pTool。

CUserToolsManager：：SaveState

將使用者工具的相關信息儲存在 Windows 登錄中。

BOOL SaveState(LPCTSTR lpszProfileName=NULL);

參數

lpszProfileName
[in]Windows 登錄機碼的路徑。

傳回值

如果已成功儲存狀態，則為非零;否則為 0。

備註

方法會將物件的目前狀態 CUserToolsManager 儲存在 Windows 登錄中。

通常，您不需要直接呼叫此方法， CWinAppEx：：SaveState 會自動將其呼叫為應用程式的工作區串行化程式的一部分。

CUserToolsManager：：SetDefExt

指定 [檔案開啟] 對話框（CFileDialog 類別）在 [自定義] 對話方塊之 [工具] 索引標籤的 [命令] 字段中所使用的預設擴展名。

void SetDefExt(const CString& strDefExt);

參數

strDefExt
[in]包含預設擴展名的文字字串。

備註

呼叫這個方法，在 [ 開啟檔案] 對話框中指定預設擴展名，當使用者選取要與使用者工具關聯的應用程式時，就會顯示這個擴展名。預設值為「exe」。

CUserToolsManager：：SetFilter

指定 [檔案開啟] 對話框（CFileDialog 類別）在 [自定義] 對話方塊之 [工具] 索引標籤的 [命令] 字段中所使用的檔案篩選。

void SetFilter(const CString& strFilter);

參數

strFilter
[in]指定篩選條件。

另請參閱

階層架構圖表
 類別
 CWinAppEx 類別
 CUserTool 類別

共用方式為