Класс CUserToolsManager

Статья
10/12/2023

Поддерживает коллекцию объектов класса CUserTool в приложении. Пользовательский инструмент — это пункт меню, который запускает внешнее приложение. Объект 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 успешном выполнении возвращаемый тип совпадает с типом параметра pToolRTC для CWinAppEx::EnableUserTools.

CUserToolsManager::GetArgumentsMenuID

Возвращает идентификатор ресурса, связанный с меню "Аргументы" на вкладке "Сервис" диалогового окна "Настройка".

UINT GetArgumentsMenuID() const;

Возвращаемое значение

Идентификатор ресурса меню.

Замечания

Параметр uArgMenuID cWinAppEx ::EnableUserTools указывает идентификатор ресурса.

CUserToolsManager::GetDefExt

Возвращает расширение по умолчанию, которое использует диалоговое окно "Открыть файл" ( CFileDialog) в поле "Команда " на вкладке "Сервис " диалогового окна "Настройка ".

const CString& GetDefExt() const;

Возвращаемое значение

Ссылка на CString объект, содержащий расширение.

CUserToolsManager::GetFilter

Возвращает фильтр файлов, который использует диалоговое окно "Открыть файл" ( класс CFileDialog) в поле "Команды " на вкладке "Сервис " диалогового окна "Настройка ".

const CString& GetFilter() const;

Возвращаемое значение

Ссылка на CString объект, содержащий фильтр.

CUserToolsManager::GetInitialDirMenuID

Возвращает идентификатор ресурса, связанный с меню начального каталога на вкладке "Сервис " диалогового окна "Настройка ".

UINT GetInitialDirMenuID() const;

Возвращаемое значение

Идентификатор ресурса меню.

Замечания

Возвращенный идентификатор указан в параметре uInitDirMenuID CWinAppEx::EnableUserTools.

CUserToolsManager::GetMaxTools

Возвращает максимальное количество пользовательских средств, которые можно выделить в приложении.

int GetMaxTools() const;

Возвращаемое значение

Максимальное количество пользовательских средств, которые можно выделить.

Замечания

Вызовите этот метод, чтобы получить максимальное количество инструментов, которые можно выделить в приложении. Это число идентификаторов в диапазоне от uiCmdFirst через параметры uiCmdLast, передаваемые в CWinAppEx::EnableUserTools.

CUserToolsManager::GetToolsEntryCmd

Возвращает идентификатор команды заполнителя элемента меню для пользовательских инструментов.

UINT GetToolsEntryCmd() const;

Возвращаемое значение

Идентификатор команды заполнителя.

Замечания

Чтобы включить пользовательские средства, вызовите CWinAppEx::EnableUserTools. Параметр uiCmdToolsDummy указывает идентификатор команды команды инструментов. Этот метод возвращает идентификатор команды записи инструментов. Где бы этот идентификатор ни использовался в меню, он заменяется списком пользовательских инструментов при появлении меню.

CUserToolsManager::GetUserTools

Возвращает ссылку на список пользовательских инструментов.

const CObList& GetUserTools() const;

Возвращаемое значение

Ссылка const на объект класса CObList, содержащий список пользовательских средств.

Замечания

Вызовите этот метод, чтобы получить список пользовательских инструментов, которые поддерживает объект CUserToolsManager . Каждое пользовательское средство представлено объектом типа CUserTool Class или типом, производным от CUserTool. Тип указывается параметром pToolRTC при вызове CWinAppEx::EnableUserTools для включения пользовательских инструментов.

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.

Замечания

Этот метод загружает состояние CUserToolsManager объекта из реестра Windows.

Обычно этот метод не вызывается напрямую. 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

Поделиться через

Класс CUserToolsManager

Синтаксис

Участники

Открытые конструкторы

Открытые методы

Замечания

Пример

Иерархия наследования

Требования

CUserToolsManager::CreateNewTool

Возвращаемое значение

Замечания

CUserToolsManager::CUserToolsManager

Параметры

Замечания

CUserToolsManager::FindTool

Параметры

Возвращаемое значение

Замечания

CUserToolsManager::GetArgumentsMenuID

Возвращаемое значение

Замечания

CUserToolsManager::GetDefExt

Возвращаемое значение

CUserToolsManager::GetFilter

Возвращаемое значение

CUserToolsManager::GetInitialDirMenuID

Возвращаемое значение

Замечания

CUserToolsManager::GetMaxTools

Возвращаемое значение

Замечания

CUserToolsManager::GetToolsEntryCmd

Возвращаемое значение

Замечания

CUserToolsManager::GetUserTools

Возвращаемое значение

Замечания

CUserToolsManager::InvokeTool

Параметры

Возвращаемое значение

Замечания

CUserToolsManager::IsUserToolCmd

Параметры

Возвращаемое значение

Замечания

CUserToolsManager::LoadState

Параметры

Возвращаемое значение

Замечания

CUserToolsManager::MoveToolDown

Параметры

Возвращаемое значение

Замечания

CUserToolsManager::MoveToolUp

Параметры

Возвращаемое значение

Замечания

CUserToolsManager::RemoveTool

Параметры

Возвращаемое значение

Замечания

CUserToolsManager::SaveState

Параметры

Возвращаемое значение

Замечания

CUserToolsManager::SetDefExt

Параметры

Замечания

CUserToolsManager::SetFilter

Параметры

См. также

Обратная связь

Дополнительные ресурсы