Příklad: Provádění stránku vlastností

Tento příklad ukazuje, jak vytvořit stránku vlastností, která zobrazuje (a umožňuje změnit) vlastnosti Třídy dokumentů rozhraní.Toto rozhraní je vystavena dokumenty v aplikaci Visual Studio Běžné příklady modelu objektu prostředí (i když stránka vlastností, které vytvoříte nebude péči, kde se manipuluje s objekty pocházet z jako podporují správné rozhraní).

V příkladu je založen ATLPages vzorku.

K dokončení tohoto příkladu, budou:

• Přidání třídy ATL vlastnost stránky pomocí Průvodce ATL vlastnosti stránky a v dialogovém okně Přidat třídu.

• Upravit zdroj dialogové okno přidáním nové ovládací prvky pro zajímavé vlastnosti dokument rozhraní.

• Přidání obslužné rutiny zpráv ponechejte web stránky vlastností informován o změny provedené uživatelem.

• Přidat některé #import prohlášení a definice typu v domácnosti oddílu.

• Přepsat IPropertyPageImpl::SetObjects k ověření objektů do stránky vlastností.

• Přepsat IPropertyPageImpl::Activate inicializovat rozhraní stránky vlastností.

• Přepsat IPropertyPageImpl::Apply aktualizace s nejnovější hodnoty vlastností objektu.

• Na stránce vlastností zobrazení vytvořením jednoduchého pomocný objekt.

• Vytvořte makro , budou testovací stránka vlastností.

Přidání třídy ATL vlastnosti stránky

Nejprve vytvořte nový projekt ATL DLL serveru s názvem ATLPages7 .Nyní používat ATL vlastnost stránky průvodce generovat stránky vlastností.Dát na stránce vlastností Krátký název z DocProperties pak přepnout do řetězce stránky nastavení vlastností stránky položky, jak je znázorněno v následující tabulce.

Položka	Value
Title	TextDocument
Řetězec DOC	Vlastnosti TextDocument VCUE
Soubor nápovědy	<blank>

Hodnoty, které nastavíte na této stránce průvodce bude vrácena do kontejneru stránky vlastností při volá IPropertyPage::GetPageInfo.Co se stane na řetězce, po který je závislý na kontejner, ale obvykle používají k identifikaci stránku uživateli.Název obvykle zobrazí v kartě nad stránkou a řetězec dokumentu může být zobrazena ve stavovém řádku nebo popisku (ačkoli standardní vlastnosti rámce nepoužívá vůbec tento řetězec).

[!POZNÁMKA]

Řetězce, které jste nastavili jsou uloženy jako řetězec zdroje v projektu pomocí průvodce.Tyto řetězce pomocí editoru zdroje, potřebujete-li tyto informace změnit poté, co byl vygenerován kód stránky můžete snadno upravit.

Klepněte na tlačítko OK průvodce generovat stránky vlastností.

Úpravy zdroje dialogové okno

Nyní, vygeneruje stránky vlastností, budete muset přidat několik ovládací prvky dialogového okna prostředků představující stránky.Přidat textové pole, ovládacího prvku statický text a zaškrtávací políčko a nastavit jejich ID, jak je ukázáno níže:

Tyto ovládací prvky se použije k zobrazení názvu souboru dokumentu a jeho stav jen pro čtení.

[!POZNÁMKA]

Dialogové okno zdroj neobsahuje rámeček nebo příkazového tlačítka, ani nemá s kartami vzhled, který může očekávat.Tyto funkce poskytují rámce stránky vlastností například vytvořené voláním OleCreatePropertyFrame.

Přidání obslužné rutiny zpráv

Obslužné rutiny zpráv aktualizovat stav nevyřízeného stránky při změně hodnoty buď ovládací prvky můžete přidat ovládací prvky na místě:

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

Tento kód reaguje na změny textové pole nebo zaškrtávací políčko voláním IPropertyPageImpl::SetDirty, která informuje o stránku webu, který byl změněn na stránce.Obvykle reagovat na web stránce povolení nebo zakázání použít tlačítko na rámec stránky vlastností.

[!POZNÁMKA]

Ve své vlastní stránky vlastností můžete ke sledování přesně vlastnosti, které byly změněny uživatelem tak, aby se zabránilo aktualizace vlastnosti, které nebyly změněny.Tento příklad implementuje udržování přehledu o původní hodnoty vlastností a porovnání pomocí aktuální hodnoty z uživatelského rozhraní, když je čas použít změny kódu.

Domácnosti

Nyní přidat několik #import DocProperties.h příkazy tak, aby kompilátor ví o dokument rozhraní:

// 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

Budete také potřebovat odkazovat IPropertyPageImpl základní třída; přidat následující typedef se CDocProperties třídy:

typedef IPropertyPageImpl<CDocProperties> PPGBaseClass;

Přepsání IPropertyPageImpl::SetObjects

První IPropertyPageImpl je metoda, která je třeba přepsat SetObjects.Zde přidáte kód byl předán pouze jeden objekt a podporuje ji dokument rozhraní, který:

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

[!POZNÁMKA]

Nemá smysl podporovat pouze jeden objekt pro tuto stránku, protože umožňuje uživateli nastavit název souboru objektu – na libovolné místo jednoho může existovat pouze jeden soubor.

Přepsání IPropertyPageImpl::Activate

Dalším krokem je při prvním vytvoření stránky inicializaci stránky vlastností s hodnotami vlastností podkladového objektu.

V tomto případě by přidat členy do třídy, protože také použijete vlastnost počáteční hodnoty pro porovnání při jejich změny použít stránky:

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

Provádění základní třídy aktivovat metoda je zodpovědný za vytváření dialogového okna a jeho ovládací prvky, takže můžete přepsat tuto metodu a přidat vlastní inicializace po volání základní třídy:

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

Tento kód používá metody COM dokument rozhraní získat vlastnosti, které vás zajímají.Poté použije rozhraní Win32 API obalů podle CDialogImpl a jeho základní třídy zobrazení hodnot vlastností pro uživatele.

Přepsání IPropertyPageImpl::Apply

Uživatele chcete použít své změny na objekty, vlastnosti stránky webu bude volat použít metoda.Místo pro opačný kód v aktivovat – že aktivovat trvalo hodnoty z objektu a je posunuta do ovládacích prvků na stránce vlastností použít trvá hodnoty z ovládacích prvků na stránce vlastností a předá je do objektu.

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

[!POZNÁMKA]

Kontrola proti m_bDirty na začátku této implementace je počáteční kontrole Pokud vyhnout zbytečnému aktualizace objektů použít se nazývá více než jednou.Jsou také proti každé hodnoty vlastností k zajištění, že pouze změny výsledkem volání metody kontroly dokument.

[!POZNÁMKA]

Dokument poskytuje FullName jako vlastnost jen pro čtení.Aktualizovat dokument založený na změny provedené na stránce vlastností název souboru, je nutné použít Uložit metoda uložte soubor pod jiným názvem.Tedy kód na stránce vlastností nemá sám omezit na získání nebo nastavení vlastností.

Na stránce vlastností zobrazení

Tuto stránku zobrazit, musíte vytvořit jednoduchý pomocný objekt.Pomocný objekt poskytne metodu, která zjednodušuje OleCreatePropertyFrame rozhraní API pro zobrazení jednotlivých stránek připojen jako jediný objekt.Tento pomocník bude navržen tak, že lze prostřednictvím jazyka Visual Basic.

Použít dialogové okno Přidat třídu a ATL jednoduchý objekt Průvodce generování nové třídy a použití Helper jeho krátký název.Po vytvoření můžete přidáte metodu, jak je znázorněno v následující tabulce.

Položka	Value
Název metody	ShowPage
Parametry	[in] BSTR bstrCaption, [in] BSTR bstrID, [in] IUnknown* pUnk

bstrCaption Parametr je titulek zobrazený v záhlaví dialogového okna. bstrID Parametr je řetězec představující identifikátor CLSID nebo ProgID na stránce vlastností zobrazení. pUnk Bude mít parametr IUnknown ukazatel na objekt, jehož vlastnosti budou nakonfigurovány pomocí stránky vlastností.

Implementovat metodu, jak je ukázáno níže:

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

Vytvoření makra

Po sestavení projektu můžete otestovat na stránce vlastností a pomocný objekt pomocí jednoduché makro, které můžete vytvořit a spustit ve vývojovém prostředí Visual Studio.Toto makro vytvoří pomocníka objekt a potom volat jeho ShowPage metoda s použitím identifikátoru ProgID DocProperties stránka vlastností a IUnknown ukazatel dokumentu aktivní v editoru Visual Studio.Kód, který potřebujete pro toto makro je uvedena níže:

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

Pokud spustíte makro, stránky vlastností se zobrazí název souboru a stav aktivní textový dokument jen pro čtení.Stav jen pro čtení dokumentu pouze odráží schopnost zápisu do dokumentu ve vývojovém prostředí; neovlivní atribut jen pro čtení souboru na disku.

Viz také

Koncepty

Stránky vlastností COM ATL

Vzorek ATLPages