Örnek: bir özellik sayfası uygulama

Bu örnek özelliklerini görüntüler (ve değiştirmenize izin verir) özellik sayfasını oluşturmak nasıl gösterir Belge sınıfları arabirimi.Bu arabirim tarafından Visual Studio'nun belgelerde maruz Ortak ortam nesnesi modeli örnekleri (oluşturacağınız özellik sayfası doğru arabirim destekledikleri sürece burada ilişkilendirilmesidir nesneleri gelir dikkate olmaz rağmen).

Örnek dayandığı ATLPages örnek.

Bu örnek tamamlamak için şunları yapacaksınız:

• atl özellik sayfasında Add Class Add Class iletişim kutusu ve atl özellik sayfası Sihirbazı'nı kullanma.

• İletişim kaynağı düzenleme ilginç özellikleri için yeni denetimler ekleyerek Belge arabirimi.

• İleti işleyicileri eklemek özellik sayfası site tutmak için kullanıcı tarafından yapılan değişikliklerin bilgilendirildi.

• Bazı ekleme #import ifadeler ve bir typedef olasılığından bölüm.

• Geçersiz kılma IPropertyPageImpl::SetObjects özellik sayfası geçirilen nesneleri doğrulamak için.

• Geçersiz kılma IPropertyPageImpl::Activate özellik sayfasının arabirimi başlatılamıyor.

• Geçersiz kılma IPropertyPageImpl::Apply nesnesi ile en son özellik değerleri güncelleştirmek için.

• Özellik sayfasını görüntülemek basit Yardımcısı nesnesi oluşturarak.

• Makro oluşturma özellik sayfası test.

atl özellik sayfası sınıfı ekleme

İlk olarak, yeni bir atl proje adlı bir dll dosyası sunucu oluşturmak ATLPages7.Şimdi atl özellik sayfası Sihirbazı'nı bir özellik sayfası oluşturmak için.Özellik sayfası vermek bir Kısa adı , DocProperties için geçiş dizeleri sayfa özellik sayfası özel öğeleri aşağıdaki tabloda gösterildiği gibi ayarlayın.

Öğe	Value
Başlık	TextDocument
Doc dize	vcue TextDocument özellik
YardımDosyası	<blank>

Onu çağırdığında sihirbazın bu sayfasında ayarlanan değerler özellik sayfası kabına döner IPropertyPage::GetPageInfo.Dizeleri kabında bağlıdır, ancak genellikle bunlar kullanıcı sayfanıza tanımlamak için kullanılacak sonra gerçekleşecek işlemler.Başlık genellikle bir sekmede sayfanızın üstünde görünür ve (standart özellik çerçevesi bu dize hiç kullanmıyor olsa da) Doc dize durum çubuğunu veya araç ipucu görüntülenebilir.

[!NOT]

Burada belirlediğiniz dize dize kaynakları projenize olarak sihirbaz tarafından depolanır.Sayfanız için kod oluşturulduktan sonra bu bilgileri değiştirmeniz gerekirse, Kaynak Düzenleyicisi'ni kullanarak bu dizeleri kolayca düzenleyebilirsiniz.

' I Tamam Sihirbazı özellik sayfası oluşturmak için.

İletişim kaynağı düzenleme

Özellik sayfası üretilen artık, sayfanızı gösteren iletişim kaynağı birkaç denetimleri eklemek gerekir.Düzenleme kutusu, statik metin denetimi ve bir onay kutusu ekleyin ve kimlikleri aşağıda gösterildiği gibi ayarlayın:

Bu denetimleri, belge ve salt okunur durumunu dosya adını görüntülemek için kullanılacaktır.

[!NOT]

İletişim kaynak kare veya komut düğmeleri içermez, ne de beklenen bir sekmeli görünüm yok.Bu özellikler gibi çağrılarak oluşturulan bir özellik sayfası çerçeve tarafından sağlanan OleCreatePropertyFrame.

İleti işleyicileri ekleme

Yerinde denetimlerle denetimlerden birinin değeri değiştiğinde sayfa kirli durumunu güncelleştirmek için ileti işleyicileri ekleyebilirsiniz:

BEGIN_MSG_MAP(CDocProperties)
   COMMAND_HANDLER(IDC_NAME, EN_CHANGE, OnUIChange)
   COMMAND_HANDLER(IDC_READONLY, BN_CLICKED, OnUIChange)
   CHAIN_MSG_MAP(IPropertyPageImpl<CDocProperties>)
END_MSG_MAP()

   // Respond to changes in the UI to update the dirty status of the page
   LRESULT OnUIChange(WORD wNotifyCode, WORD wID, HWND hWndCtl, BOOL& bHandled)
   {
      wNotifyCode; wID; hWndCtl; bHandled;
      SetDirty(true);
      return 0;
   }

Bu kodu çağırarak onay kutusunu ya da düzenleme denetimi için yapılan değişiklikleri yanıtlar IPropertyPageImpl::SetDirty, sayfa değişti sayfasında site bildirir.Etkinleştirme veya devre dışı bırakma sayfasında site genellikle yanıt vereceği bir Apply düğmesi özellik sayfası çerçevesinde.

[!NOT]

Kendi özellik sayfalarında değiştirilmemiş olması özellikleri güncelleniyor önlemek için tam olarak hangi özellikleri kullanıcı tarafından değiştirilmiş izlemek gerekebilir.Bu örnek kodun özgün özellik değerlerini izlemek ve değişiklikleri uygulamak için zaman olduğunda, kullanıcı Arabiriminin geçerli değerlerle bunları karşılaştırma gerçekleştirir.

Olasılığından

Şimdi birkaç ekleme #import DocProperties.h ifadeleri hakkında derleyici bilir Belge arabirimi:

// MSO.dll
#import <libid:2DF8D04C-5BFA-101B-BDE5-00AA0044DE52> version("2.2") \
   rename("RGB", "Rgb")   \
   rename("DocumentProperties", "documentproperties")   \
   rename("ReplaceText", "replaceText")   \
   rename("FindText", "findText")   \
   rename("GetObject", "getObject")   \
   raw_interfaces_only

// dte.olb
#import <libid:80CC9F66-E7D8-4DDD-85B6-D9E6CD0E93E2> \
   inject_statement("using namespace Office;")   \
   rename("ReplaceText", "replaceText")   \
   rename("FindText", "findText")   \
   rename("GetObject", "getObject")   \
   rename("SearchPath", "searchPath")   \
   raw_interfaces_only

Ayrıca başvurmak gerekir IPropertyPageImpl taban sınıfı; Aşağıdaki typedef için CDocProperties sınıfı:

typedef IPropertyPageImpl<CDocProperties> PPGBaseClass;

IPropertyPageImpl::SetObjects geçersiz kılma

İlk IPropertyPageImpl yöntemi geçersiz kılmak için gereken SetObjects.Burada yalnızca tek bir nesneyi geçirilen ve destekleyip desteklemediğini denetlemek için kod ekleyeceksiniz Belge beklediğiniz arabirimi:

STDMETHOD(SetObjects)(ULONG nObjects, IUnknown** ppUnk)
{
   HRESULT hr = E_INVALIDARG;
   if (nObjects == 1)
   {
      CComQIPtr<EnvDTE::Document> pDoc(ppUnk[0]);
      if (pDoc)
         hr = PPGBaseClass::SetObjects(nObjects, ppUnk);
   }
   return hr;
}

[!NOT]

Nesne dosyası adını ayarlamak kullanıcının izin verir çünkü bu sayfa için yalnızca tek bir nesne desteklemek için mantıklıdır — tek bir dosya herhangi bir konumda bulunması.

IPropertyPageImpl::Activate geçersiz kılma

Sonraki adım sayfayı ilk kez oluşturulduğunda, alttaki nesne özelliği değerleri özellik sayfasıyla yapmaktır.

Bu durumda sayfanın kullanıcıları yaptıkları değişiklikleri uyguladığınızda, aynı zamanda ilk özellik değerleri karşılaştırma için kullanacağınız bu yana aşağıdaki üyelere class eklemeniz gerekir:

CComBSTR m_bstrFullName;  // The original name
VARIANT_BOOL m_bReadOnly; // The original read-only state

Temel sınıf uygulaması, Activate yöntemi bu yöntem geçersiz kılmak ve temel sınıf çağrıldıktan sonra kendi başlatma eklemek için iletişim kutusu ve diğer denetimler oluşturmak için sorumlu:

STDMETHOD(Activate)(HWND hWndParent, LPCRECT prc, BOOL bModal)
{
   // If we don't have any objects, this method should not be called
   // Note that OleCreatePropertyFrame will call Activate even if
   // a call to SetObjects fails, so this check is required
   if (!m_ppUnk)
      return E_UNEXPECTED;

   // Use Activate to update the property page's UI with information
   // obtained from the objects in the m_ppUnk array

   // We update the page to display the Name and ReadOnly properties
   // of the document

   // Call the base class
   HRESULT hr = PPGBaseClass::Activate(hWndParent, prc, bModal);
   if (FAILED(hr))
      return hr;

   // Get the EnvDTE::Document pointer
   CComQIPtr<EnvDTE::Document> pDoc(m_ppUnk[0]);
   if (!pDoc)
      return E_UNEXPECTED;

   // Get the FullName property
   hr = pDoc->get_FullName(&m_bstrFullName);
   if (FAILED(hr))
      return hr;

   // Set the text box so that the user can see the document name
   USES_CONVERSION;
   SetDlgItemText(IDC_NAME, CW2CT(m_bstrFullName));

   // Get the ReadOnly property
   m_bReadOnly = VARIANT_FALSE;
   hr = pDoc->get_ReadOnly(&m_bReadOnly);
   if (FAILED(hr))
      return hr;

   // Set the check box so that the user can see the document's read-only status
   CheckDlgButton(IDC_READONLY, m_bReadOnly ? BST_CHECKED : BST_UNCHECKED);

   return hr;
}

Bu kod com yöntemlerini kullanan Belge ilgilendiğiniz özelliklerini almak için arabirim.Daha sonra tarafından sunulan Win32 API sarmalayıcılar kullanır CDialogImpl ve temel sınıflardan kullanıcıya özellik değerlerini görüntülemek için.

IPropertyPageImpl::Apply geçersiz kılma

Kullanıcıların yaptıkları değişiklikleri uygulamak istediğinizde, özellik sayfası site çağıracak Apply yöntemi.Bu kod tersini yerdir Activate — oysa Activate nesne değerleri sürdü ve bunların özellik sayfasındaki denetimlere itilmiş Uygula özellik sayfasındaki denetimlerin değerleri alır ve nesne iter.

STDMETHOD(Apply)(void)
{
   // If we don't have any objects, this method should not be called
   if (!m_ppUnk)
      return E_UNEXPECTED;

   // Use Apply to validate the user's settings and update the objects'
   // properties

   // Check whether we need to update the object
   // Quite important since standard property frame calls Apply
   // when it doesn't need to
   if (!m_bDirty)
      return S_OK;

   HRESULT hr = E_UNEXPECTED;

   // Get a pointer to the document
   CComQIPtr<EnvDTE::Document> pDoc(m_ppUnk[0]);
   if (!pDoc)
      return hr;

   // Get the read-only setting
   VARIANT_BOOL bReadOnly = IsDlgButtonChecked(IDC_READONLY) ? VARIANT_TRUE : VARIANT_FALSE;

   // Get the file name
   CComBSTR bstrName;
   if (!GetDlgItemText(IDC_NAME, bstrName.m_str))
      return E_FAIL;

   // Set the read-only property
   if (bReadOnly != m_bReadOnly)
   {
      hr = pDoc->put_ReadOnly(bReadOnly);
      if (FAILED(hr))
         return hr;
   }

   // Save the document
   if (bstrName != m_bstrFullName)
   {
      EnvDTE::vsSaveStatus status;
      hr = pDoc->Save(bstrName, &status);
      if (FAILED(hr))
         return hr;
   }

   // Clear the dirty status of the property page
   SetDirty(false);

   return S_OK;
}

[!NOT]

Onay karşı m_bDirty , nesnelerin gereksiz güncelleştirmeleri önlemek için ilk denetimini bu uygulaması, başında olduğu Uygula birden çok kez çağrılır.Ayrıca her özellik değerleri yalnızca değişiklikleri yöntemi çağrısına neden olduğundan emin olmak için denetimler vardır Belge.

[!NOT]

Belge sergiler tam salt okunur bir özellik olarak.Özellik sayfasında yaptığınız değişiklikleri esas belgenin dosya adını güncelleştirmek için kullanmak zorunda kaydetmek dosyayı farklı bir adla kaydetmek için yöntem.Bu nedenle, özellik sayfasındaki kod kendisini sınırlamak zorunda alma veya özelliklerini ayarlama.

Özellik sayfası görüntüleme

Bu sayfayı görüntülemek için basit Yardımcısı nesnesi oluşturmanız gerekir.Yardımcısı nesnesi kolaylaştıran bir yöntem sağlayacaktır OleCreatePropertyFrame tek bir sayfayı görüntülemek için API bağlı tek bir nesne.Visual Basic'ten kullanılabilir olacak şekilde bu yardımcı tasarlanmıştır.

Kullanmak iletişim kutusunda Add Class ve atl Basit Nesne Sihirbazı yeni bir sınıf oluşturmak ve kullanmak için Helper kısa adı olarak.Bir kez oluşturduktan sonra aşağıdaki tabloda gösterildiği gibi bir yöntem ekleyin.

Öğe	Value
Yöntem adı	ShowPage
Parametreler	[in] BSTR bstrCaption, [in] BSTR bstrID, [in] IUnknown* pUnk

bstrCaption İletişim kutusunda başlık gösterilecek resim yazısı parametresidir.bstrID Görüntülenecek bir CLSID veya özellik sayfası ProgID'sini temsil eden bir dize bir parametredir.pUnk Parametresi olacaktır IUnknown fare işaretçisini nesnenin özellikleri özellik sayfası yapılandırılacak.

Yöntem aaıda gösterildii ekilde Uygula:

STDMETHODIMP CHelper::ShowPage(BSTR bstrCaption, BSTR bstrID, IUnknown* pUnk)
{
   if (!pUnk)
      return E_INVALIDARG;

   // First, assume bstrID is a string representing the CLSID 
   CLSID theCLSID = {0};
   HRESULT hr = CLSIDFromString(bstrID, &theCLSID);
   if (FAILED(hr))
   {
      // Now assume bstrID is a ProgID
      hr = CLSIDFromProgID(bstrID, &theCLSID);
      if (FAILED(hr))
         return hr;
   }

   // Use the system-supplied property frame
   return OleCreatePropertyFrame(
      GetActiveWindow(),   // Parent window of the property frame
      0,           // Horizontal position of the property frame
      0,           // Vertical position of the property frame
      bstrCaption, // Property frame caption
      1,           // Number of objects
      &pUnk,       // Array of IUnknown pointers for objects
      1,           // Number of property pages
      &theCLSID,   // Array of CLSIDs for property pages
      NULL,        // Locale identifier
      0,           // Reserved - 0
      NULL         // Reserved - 0
      );
}

Makro oluşturma

Proje oluşturuncaya sonra özellik sayfası ve Yardımcısı nesnesi oluşturma ve Visual Studio geliştirme ortamında çalışan basit bir makro kullanarak test edebilirsiniz.Bu makroyu bir yardımcı oluşturacak nesnesini ve sonra call kendi ShowPage ProgID'sini kullanarak yöntemi DocProperties özellik sayfası ve IUnknown Visual Studio Düzenleyicisi'nde şu anda etkin belge işaretçi.Bu makro için gereken kod aşağıda gösterilmiştir:

Imports EnvDTE
Imports System.Diagnostics

Public Module AtlPages

    Public Sub Test()
        Dim Helper
        Helper = CreateObject("ATLPages7.Helper.1")

        On Error Resume Next
        Helper.ShowPage( _
            ActiveDocument.Name, _
            "ATLPages7Lib.DocumentProperties.1", _
            DTE.ActiveDocument _
            )
    End Sub

End Module

Bu makroyu çalýþtýrdýðýnýzda, dosya adını ve etkin olan metni belgenin salt okunur durumunu gösteren özellik sayfası görüntülenir.Belgenin salt okunur durumunu yalnızca belge geliştirme ortamında yazabilme yeteneği yansıtır; Diskteki dosyayı salt okunur özniteliğini etkilemez.

Ayrıca bkz.

Kavramlar

atl com özellik sayfaları

ATLPages örnek