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

Регистрация и реализация обработчика страниц свойств для типа файла

  • Статья

Когда пользователь щелкает правой кнопкой мыши элемент типа файла, чтобы отобразить страницу свойств Свойства, оболочка вызывает обработчики страниц свойств, зарегистрированные для этого типа файла. Каждый обработчик может добавить одну пользовательскую страницу на страницу свойств по умолчанию.

Это важно знать

Технологии

  • Оболочка

Предварительные требования

  • Общие сведения о контекстных меню

Инструкции

Шаг 1. Регистрация обработчика страниц свойств для типа файла

В дополнение к обычной регистрации модели COM добавьте подраздел PropertySheetHandlers в подраздел shellex ключа ProgID приложения, связанного с типом файла. Создайте подраздел PropertySheetHandlers с именем обработчика и задайте значение по умолчанию в строковой форме ИДЕНТИФИКАТОРа класса (CLSID) обработчика страниц свойств.

Чтобы добавить несколько страниц на страницу свойств, зарегистрируйте обработчик для каждой страницы. Максимальное количество страниц, которое может поддерживать лист свойств, равно 32. Чтобы зарегистрировать несколько обработчиков, создайте ключ под ключом shellex для каждого обработчика со значением по умолчанию, равным ИДЕНТИФИКАТОРу CLSID обработчика. Нет необходимости создавать отдельный объект для каждого обработчика, что означает, что несколько обработчиков могут иметь одно и то же значение GUID. Страницы будут отображаться в том порядке, в котором их ключи указаны в разделе shellex.

В следующем примере показана запись реестра, которая включает два обработчика расширений страниц свойств для примера myp-типа файла. В этом примере для каждой страницы используется отдельный объект, но один объект также может использоваться для обеих страниц.

HKEY_CLASSES_ROOT
   .myp
      (Default) = MyProgram.1
   CLSID
      {Page 1 Property Sheet Handler CLSID GUID}
         InProcServer32
            (Default) = C:\MyDir\MyPropSheet1.dll
            ThreadingModel = Apartment
      {Page 2 Property Sheet Handler CLSID GUID}
         InProcServer32
            (Default) = C:\MyDir\MyPropSheet2.dll
            ThreadingModel = Apartment
   MyProgram.1
      (Default) = MyProgram Application
      shellex
         PropertySheetHandlers
            MyPropSheet1
               (Default) = {Page1 Property Sheet Handler CLSID GUID}
            MyPropSheet2
               (Default) = {Page2 Property Sheet Handler CLSID GUID}

Шаг 2. Реализация обработчика страниц свойств для типа файла

Помимо общей реализации, описанной в разделе Работа обработчиков листов свойств, обработчик страниц свойств для типа файла также должен иметь соответствующую реализацию интерфейса IShellPropSheetExt . Только метод IShellPropSheetExt::AddPages нуждается в реализации nontoken. Оболочка не вызывает IShellPropSheetExt::ReplacePage.

Метод IShellPropSheetExt::AddPages позволяет обработчику страницы свойств добавлять страницу в лист свойств. Метод имеет два входных параметра. Первый, lpfnAddPage, является указателем на функцию обратного вызова AddPropSheetPageProc , которая используется для предоставления оболочке сведений, необходимых для добавления страницы на страницу свойств. Второй, lParam, является определяемым оболочкой значением, которое не обрабатывается обработчиком. Он просто передается обратно в оболочку при вызове функции обратного вызова.

Общая процедура реализации AddPages выглядит следующим образом.

Реализация метода AddPages

  1. Назначьте соответствующие значения членам структуры PROPSHEETPAGE . В частности:
    • Назначьте переменную, содержащую количество ссылок обработчика, члену pcRefParent . Эта практика предотвращает выгрузку объекта обработчика во время отображения страницы свойств.
    • Можно также реализовать функцию обратного вызова PropSheetPageProc и назначить ее указатель на член pfnCallback . Эта функция вызывается при создании страницы и ее уничтожении.
  2. Создайте дескриптор HPAGE страницы, передав структуру PROPSHEETPAGE в функцию CreatePropertySheetPage .
  3. Вызовите функцию, на которую указывает lpfnAddPage. Присвойте первому параметру дескриптор HPAGE, созданный на предыдущем шаге. Задайте для второго параметра значение lParam , переданное в AddPages оболочкой.
  4. Все сообщения, связанные со страницей, будут переданы в процедуру диалогового окна, назначенную члену pfnDlgProc структуры PROPSHEETPAGE .
  5. Если вы назначили функцию обратного вызова PropSheetPageProcдля pfnCallback, она будет вызываться, когда страница будет уничтожена. Затем обработчик может выполнять любые необходимые операции очистки, например освобождать все ссылки, которые он содержит.

В следующем примере кода показана простая реализация AddPages .

STDMETHODIMP CShellPropSheetExt::AddPages(LPFNADDPROPSHEETPAGE, lpfnAddPage, LPARAM lParam)
{
    PROPSHEETPAGE  psp;
    HPROPSHEETPAGE hPage;

    psp.dwSize        = sizeof(psp);
    psp.dwFlags       = PSP_USEREFPARENT | PSP_USETITLE | PSP_USECALLBACK;
    psp.hInstance     = g_hInst;
    psp.pszTemplate   = MAKEINTRESOURCE(IDD_PAGEDLG);
    psp.hIcon         = 0;
    psp.pszTitle      = TEXT("Extension Page");
    psp.pfnDlgProc    = (DLGPROC)PageDlgProc;
    psp.pcRefParent   = &g_DllRefCount;
    psp.pfnCallback   = PageCallbackProc;
    psp.lParam        = (LPARAM)this;

    hPage = CreatePropertySheetPage(&psp);
            
    if(hPage) 
    {
        if(lpfnAddPage(hPage, lParam))
        {
            this->AddRef();
            return S_OK;
        }
        else
        {
            DestroyPropertySheetPage(hPage);
        }
    }
    else
    {
        return E_OUTOFMEMORY;
    }
    return E_FAIL;
}

Переменная g_hInst является дескриптором экземпляра библиотеки DLL, а IDD_PAGEDLG — идентификатором ресурса шаблона диалогового окна страницы. Функция PageDlgProc — это процедура диалогового окна, которая обрабатывает сообщения страницы. Переменная g_DllRefCount содержит количество ссылок объекта. Метод AddPages вызывает AddRef для увеличения количества. Однако количество ссылок освобождается функцией обратного вызова PageCallbackProc, когда страница будет уничтожена.

Комментарии

Общие сведения о регистрации обработчиков расширений оболочки см. в статье Создание обработчиков расширений оболочки.

IShellPropSheetExt