Cara Mendaftar dan Mengimplementasikan Handler Lembar Properti untuk Jenis File

Saat pengguna mengklik kanan anggota jenis file untuk menampilkan lembar properti Properti, Shell memanggil penangan lembar properti yang terdaftar untuk jenis file. Setiap handler dapat menambahkan satu halaman kustom ke lembar properti default.

Apa yang perlu Anda ketahui

Teknologi

• Shell

Prasyarat

• Pemahaman tentang menu pintasan

Petunjuk

Langkah 1: Mendaftarkan Handler Lembar Properti untuk Jenis File

Selain pendaftaran Model Objek Komponen (COM) normal, tambahkan subkunjud PropertySheetHandlers ke subkunjang shellex kunci ProgID aplikasi yang terkait dengan jenis file. Buat subkunci PropertySheetHandlers dengan nama handler, dan atur nilai default ke bentuk string GUID pengidentifikasi kelas handler lembar properti (CLSID).

Untuk menambahkan lebih dari satu halaman ke lembar properti, daftarkan handler untuk setiap halaman. Jumlah maksimum halaman yang dapat didukung lembar properti adalah 32. Untuk mendaftarkan beberapa handler, buat kunci di bawah kunci shellex untuk setiap handler, dengan nilai default diatur ke GUID CLSID handler. Tidak perlu membuat objek yang berbeda untuk setiap handler, yang berarti bahwa beberapa handler semuanya dapat memiliki nilai GUID yang sama. Halaman akan ditampilkan dalam urutan kuncinya tercantum di bawah shellex.

Contoh berikut mengilustrasikan entri registri yang memungkinkan dua handler ekstensi lembar properti untuk contoh jenis file .myp. Dalam contoh ini, objek terpisah digunakan untuk setiap halaman, tetapi satu objek juga dapat digunakan untuk keduanya.

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}

Langkah 2: Menerapkan Handler Lembar Properti untuk Jenis File

Selain implementasi umum yang dibahas dalam Cara Kerja Handler Lembar Properti, handler lembar properti untuk jenis file juga harus memiliki implementasi antarmuka IShellPropSheetExt yang sesuai. Hanya metode IShellPropSheetExt::AddPages yang memerlukan implementasi nontoken. Shell tidak memanggil IShellPropSheetExt::ReplacePage.

Metode IShellPropSheetExt::AddPages memungkinkan handler lembar properti untuk menambahkan halaman ke lembar properti. Metode ini memiliki dua parameter input. Yang pertama, lpfnAddPage, adalah penunjuk ke fungsi panggilan balik AddPropSheetPageProc yang digunakan untuk menyediakan Shell dengan informasi yang diperlukan untuk menambahkan halaman ke lembar properti. Yang kedua, lParam, adalah nilai yang ditentukan Shell yang tidak diproses oleh handler. Ini hanya diteruskan kembali ke Shell ketika fungsi panggilan balik dipanggil.

Prosedur umum untuk menerapkan AddPages adalah sebagai berikut.

Menerapkan Metode AddPages

1. Tetapkan nilai yang sesuai untuk anggota struktur PROPSHEETPAGE . Secara khusus:
   • Tetapkan variabel yang menyimpan jumlah referensi handler ke anggota pcRefParent . Praktik ini mencegah objek handler dibongkar saat lembar properti masih ditampilkan.
   • Anda juga dapat menerapkan fungsi panggilan balik PropSheetPageProc dan menetapkan penunjuknya ke anggota pfnCallback . Fungsi ini dipanggil ketika halaman dibuat dan kapan akan dihancurkan.
2. Buat handel HPAGE halaman dengan meneruskan struktur PROPSHEETPAGE ke fungsi CreatePropertySheetPage .
3. Panggil fungsi yang diarahkan oleh lpfnAddPage. Atur parameter pertamanya ke handel HPAGE yang dibuat pada langkah sebelumnya. Atur parameter kedua ke nilai lParam yang diteruskan ke AddPages oleh Shell.
4. Setiap pesan yang terkait dengan halaman akan diteruskan ke prosedur kotak dialog yang ditetapkan ke anggota pfnDlgProc dari struktur PROPSHEETPAGE .
5. Jika Anda menetapkan fungsi panggilan balik PropSheetPageProc ke pfnCallback, itu akan dipanggil ketika halaman akan dihancurkan. Handler Anda kemudian dapat melakukan operasi pembersihan yang diperlukan, seperti merilis referensi apa pun yang dipegangnya.

Sampel kode berikut mengilustrasikan implementasi AddPages sederhana.

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

Variabel g_hInst adalah handel instans ke DLL, dan IDD_PAGEDLG adalah ID sumber daya templat kotak dialog halaman. Fungsi PageDlgProc adalah prosedur kotak dialog yang menangani pesan halaman. Variabel g_DllRefCount menyimpan jumlah referensi objek. Metode AddPages memanggil AddRef untuk menambah jumlah. Namun, jumlah referensi dirilis oleh fungsi panggilan balik, PageCallbackProc, ketika halaman akan dihancurkan.

Keterangan

Untuk diskusi umum tentang cara mendaftarkan penangan ekstensi Shell, lihat Membuat Penangan Ekstensi Shell.

Topik terkait

IShellPropSheetExt