Przykład: Wykonawczych strony właściwości

Artykuł
06/09/2015

Ten przykład pokazuje jak zbudować strony właściwości wyświetla (i umożliwia zmianę) właściwości Klasy dokumentów interfejsu.Ten interfejs jest narażony na dokumenty w Visual Studio Przykłady modelu obiektów typowego środowiska (chociaż strony właściwości utworzysz nie opieki obiektów go manipuluje skąd jak obsługują poprawny interfejs).

Przykład jest oparty na próbki ATLPages.

Aby ukończyć ten przykład, będą:

Dodawanie klasy ATL właściwości strony za pomocą Kreatora strony właściwości ATL i w oknie dialogowym Dodawanie klasy.
Edycja zasobów okno dialogowe przez dodanie nowych formantów interesujące właściwości dokument interfejsu.
Dodawanie obsługi wiadomości , aby zachować właściwości strony o zmiany wprowadzone przez użytkownika.
Dodać #import instrukcji i typedef w porządkowaniem sekcji.
Zastąpić IPropertyPageImpl::SetObjects do sprawdzania poprawności obiektów przekazywanych do strony właściwości.
Zastąpić IPropertyPageImpl::Activate zainicjować strony właściwości interfejsu.
Zastąpić IPropertyPageImpl::Apply o aktualizację obiektu z najnowszych wartości właściwości.
Wyświetlić stronę właściwości przez utworzenie obiektu proste pomocnika.
Utwórz makro , będzie testować strony właściwości.

Dodawanie klasy ATL właściwości strony

Najpierw należy utworzyć nowy projekt ATL DLL serwera o nazwie ATLPages7.Teraz ATL właściwości strony kreatora do generowania strony właściwości.Strona właściwości nadaj Krótka nazwa z DocProperties przełączyć się do ciągów stronę, aby ustawić elementy strony właściwości, jak pokazano w poniższej tabeli.

Element	Wartość
Tytuł	TextDocument
Ciąg doc	Właściwości TextDocument VCUE
HelpFile	<blank>

Wartości, które można ustawić na tej stronie kreatora, będą zwracane kontenerem strony właściwości, gdy wywołuje IPropertyPage::GetPageInfo.Co się dzieje z ciągów po zależy na pojemniku, ale zazwyczaj będą używane do identyfikowania użytkownika na stronie.Tytuł zwykle pojawiają się w karcie powyżej strony, a ciąg Doc może być wyświetlany w pasku stanu lub ToolTip (chociaż standardowe właściwości ramki nie używa tego ciągu na wszystkich).

[!UWAGA]

Ciągi, ustawione tutaj są przechowywane jako ciąg zasobów projektu przez kreatora.Można z łatwością edytować te ciągi edytora zasobów należy zmienić te informacje po został wygenerowany kod dla strony.

Kliknij OK Kreatora generowania stronę właściwości.

Edytowanie zasobów okno dialogowe

Teraz, że został wygenerowany stronę właściwości, należy dodać kilka formantów do zasobu okno dialogowe reprezentujący stronę.Dodaj pole edycji, kontroli statyczny tekst i pole wyboru i ustawić ich identyfikatory, jak pokazano poniżej:

Edytowanie zasobu okno

Formanty te będą używane do wyświetlania nazwy pliku dokumentu i jego status tylko do odczytu.

[!UWAGA]

Okno dialogowe zasób nie zawiera przycisków ramki lub polecenia, ani nie ma kartach Wygląd ma oczekiwanej.Funkcje te są dostarczane przez ramkę strony właściwości przykład utworzone przez wywołanie OleCreatePropertyFrame.

Dodawanie obsługi wiadomości

Z kontroli na miejscu można dodać obsługi wiadomości, aby zaktualizować stan dirty strony, gdy wartość albo formantów:

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

Kod ten odpowiada zmiany wprowadzone do edycji formantu lub pola wyboru przez wywołanie IPropertyPageImpl::SetDirty, która informuje witryny strony, który zmienił stronę.Zazwyczaj witryny strony będzie odpowiadać przez włączenie lub wyłączenie Zastosuj przycisku na ramce strony właściwości.

[!UWAGA]

Własnych stronach właściwości może być konieczne śledzić dokładnie właściwości, które zostały zmienione przez użytkownika, dzięki czemu można uniknąć aktualizowania właściwości, które nie zostały zmienione.W tym przykładzie zaimplementowano kod rejestrowanie informacji o oryginalnej wartości właściwości i porównywanie ich z bieżącej wartości z interfejsu użytkownika, to czas, aby zastosować zmiany.

Usługi porządkowe

Teraz dodać kilka #import sprawozdania DocProperties.h tak, że kompilator wie o dokument interfejsu:

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

Trzeba będzie również odnosić się do IPropertyPageImpl base klasy; Dodaj następującą typedef do CDocProperties klasy:

typedef IPropertyPageImpl<CDocProperties> PPGBaseClass;

Przesłanianie IPropertyPageImpl::SetObjects

Pierwszy IPropertyPageImpl metoda trzeba zastąpić to SetObjects.Tutaj dodasz kod, który sprawdza pojedynczy obiekt został przekazany i że obsługuje dokument interfejsu, który jest oczekiwany:

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

[!UWAGA]

Warto obsługuje tylko pojedynczy obiekt dla tej strony, ponieważ umożliwi użytkownikowi ustawić nazwę pliku obiektu — może istnieć tylko jeden plik, w jednym miejscu.

Przesłanianie IPropertyPageImpl::Activate

Następnym krokiem jest zainicjować strony właściwości z wartości właściwości obiektu źródłowego podczas tworzenia strony.

W takim przypadku należy dodać następujących członków do klasy, gdyż będzie również stosować wartości początkowej właściwości dla porównania, gdy użytkownicy strony ich zmiany:

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

Klasa podstawowa wykonania Uaktywnij metoda jest odpowiedzialna za tworzenie okna dialogowego i jego formantów, więc można zastąpić tę metodę i dodać własne inicjalizacji po wywołaniu klasy podstawowej:

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

Ten kod zawiera metody COM dokument interfejsu uzyskać właściwości, które Cię.Następnie używa otok Win32 API dostarczonych przez CDialogImpl i jej klas podstawowych, aby wyświetlić wartości właściwości użytkownika.

Przesłanianie IPropertyPageImpl::Apply

Kiedy użytkownik chce zastosować swoje zmiany do obiektów, właściwości strony witryny będzie wywoływać Zastosuj metody.Jest to miejsce, odwrotna kodu w Uaktywnij — należy Uaktywnij miały wartości z obiektu i ich przesunięta do formantów na stronie właściwości Zastosuj przyjmuje wartości z formantów na stronie właściwości i umieszcza je w obiekcie.

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

[!UWAGA]

Wyboru przeciwko m_bDirty na początku tej implementacji jest początkowy wyboru, aby uniknąć niepotrzebnego aktualizacje obiektów Zastosuj jest wywoływana więcej niż raz.Są również kontrole przeciwko każdej wartości właściwości w celu zapewnienia, że tylko zmiany skutkują wywołanie metody dokument.

[!UWAGA]

Dokument udostępnia FullName jako właściwość tylko do odczytu.Aby zaktualizować nazwę pliku dokumentu na podstawie zmian do strony właściwości, należy użyć zapisać metody, aby zapisać plik pod inną nazwą.Tak więc kod na stronie właściwości nie musi ograniczać się do uzyskiwania lub ustawianie właściwości.

Strona właściwości

Aby wyświetlić tę stronę, należy utworzyć obiekt pomocnika proste.Metoda, która upraszcza dostarcza obiekt pomocnika OleCreatePropertyFrame API dla pojedynczej strony wyświetlanie podłączony do jednego obiektu.Ten pomocnik będzie być tak zaprojektowane, aby mogą być używane z języka Visual Basic.

Użyj okno dialogowe Dodawanie klasy i ATL prosty kreator obiektu do generowania nowej klasy i używać Helper jako jej nazwę krótką.Po utworzeniu dodać metodę, jak pokazano w poniższej tabeli.

Element	Wartość
Nazwa metody	ShowPage
Parametry	[in] BSTR bstrCaption, [in] BSTR bstrID, [in] IUnknown* pUnk

bstrCaption Parametr jest podpis wyświetlany jako tytuł okna dialogowego.bstrID Jest ciągiem reprezentującym identyfikatora CLSID lub ProgID strony właściwości, aby wyświetlić.pUnk Parametr będzie IUnknown wskaźnik obiektu, którego właściwości zostaną skonfigurowane przez strony właściwości.

Wdrożenie metody, jak pokazano poniżej:

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

Tworzenie makra

Po zbudowaliśmy projektu, można sprawdzić na stronie właściwości i obiekt pomocnika przy użyciu prostych makro można utworzyć i uruchomić w środowisku programowania Visual Studio.To makro tworzy pomocnika obiekt, a następnie wywołać jej ShowPage metody za pomocą identyfikatora ProgID DocProperties stronę właściwości i IUnknown wskaźnik dokumentu aktualnie aktywne w Edytorze Visual Studio.Poniżej przedstawiono kod, potrzebnych dla tego makra:

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

Po uruchomieniu makra, to pojawi się Strona właściwości zawierające nazwę pliku i stan dokumentu aktualnie aktywnych tekst tylko do odczytu.Stan dokumentu tylko do odczytu tylko odzwierciedla zdolność do zapisu dokumentu w środowisku programowania; nie wpływa na atrybut tylko do odczytu pliku na dysku.

Zobacz też

Koncepcje

Strony właściwości ALT COM

ATLPages próbki.

Udostępnij za pośrednictwem