Praca z galeriami

Struktura wstążki systemu Windows zapewnia deweloperom niezawodny i spójny model zarządzania zawartością dynamiczną w różnych kontrolkach opartych na kolekcji. Dzięki dostosowaniu i ponownym skonfigurowaniu interfejsu użytkownika wstążki te dynamiczne kontrolki umożliwiają platformie reagowanie na interakcję użytkownika zarówno w aplikacji hosta, jak i wstążce oraz zapewniają elastyczność obsługi różnych środowisk czasu wykonywania.

• Wprowadzenie
• Galerie
  • Galerie Przedmiotów
  • galerie poleceń
  • Kontrolki galerii
• Jak wdrożyć galerię
  • Podstawowe składniki
  • Deklarowanie kontrolki w znaczniku
  • tworzenie programu obsługi poleceń
  • Powiąż program obsługi poleceń
  • Inicjowanie Kolekcji
  • obsługa zdarzeń zbierania
• Tematy pokrewne

Wprowadzenie

Zdolność wstążki do dynamicznego dostosowywania się do warunków pracy w czasie rzeczywistym, wymagań aplikacji i danych wejściowych użytkownika końcowego podkreśla bogate możliwości interfejsu użytkownika tego rozwiązania oraz zapewnia deweloperom elastyczność w spełnianiu różnorodnych potrzeb klientów.

Celem tego przewodnika jest opisanie dynamicznych kontrolek galerii obsługiwanych przez platformę, wyjaśnienie ich różnic, omówić, kiedy i gdzie najlepiej ich używać, oraz pokazać, jak można je włączyć do aplikacji wstążki.

Galerie

Galerie są funkcjonalnie i graficznie bogatymi kontrolkami listbox. Kolekcja elementów galerii może być zorganizowana według kategorii, wyświetlana w elastycznych układach opartych na kolumnach i wierszach, reprezentowana przy użyciu obrazów i tekstu oraz w zależności od typu galerii, obsługuje podgląd na żywo.

Galerie są funkcjonalnie różne od innych dynamicznych kontrolek wstążki z następujących powodów:

• Galerie implementują interfejs IUICollection definiujący różne metody manipulowania kolekcjami elementów galerii.
• Galerie można aktualizować w czasie wykonywania na podstawie działania wykonywanego bezpośrednio na wstążce, na przykład gdy użytkownik dodaje polecenie do paska narzędzi Szybki dostęp (QAT).
• Galerie można aktualizować w czasie wykonywania na podstawie działania, które występuje pośrednio ze środowiska uruchomieniowego, na przykład gdy sterownik drukarki obsługuje tylko układy stron pionowych.
• Galerie można aktualizować w czasie wykonywania na podstawie działań, które występują pośrednio w aplikacji hosta, na przykład gdy użytkownik wybierze element w dokumencie.

Struktura wstążki udostępnia dwa typy galerii: galerie elementów i galerie poleceń.

Galerie elementów

Galerie elementów zawierają kolekcję elementów pokrewnych opartą na indeksie, w której każdy element jest reprezentowany przez obraz, ciąg lub oba te elementy. Kontrolka jest powiązana z jedną procedurą obsługi poleceń, która opiera się na wartości indeksu identyfikowanej przez właściwość UI_PKEY_SelectedItem.

Galerie elementów obsługują podgląd na żywo, co oznacza wyświetlanie wyniku polecenia na podstawie myszy lub fokusu bez zatwierdzania lub wywoływania polecenia.

Ważny

Platforma nie obsługuje galerii elementów hostingu w menu aplikacji.

 

Galerie poleceń

Galerie poleceń zawierają kolekcję unikatowych, nieindeksowanych elementów. Każdy element jest reprezentowany przez jedną kontrolkę powiązaną z procedurą obsługi poleceń za pomocą identyfikatora polecenia. Podobnie jak w przypadku kontrolek autonomicznych, każdy element w galerii poleceń kieruje zdarzenia wejściowe do skojarzonej procedury obsługi poleceń — sama galeria poleceń nie nasłuchuje zdarzeń.

Galerie poleceń nie obsługują podglądu na żywo.

Kontrolki galerii

Istnieją cztery kontrolki galerii w strukturze wstążki: DropDownGallery, SplitButtonGallery, InRibbonGalleryi ComboBox. Wszystkie z wyjątkiem ComboBox można zaimplementować jako galerię elementów lub galerię poleceń.

Galeria rozwijana

DropDownGallery to przycisk, który wyświetla listę rozwijaną zawierającą kolekcję elementów lub poleceń, które się wzajemnie wykluczają.

Poniższy zrzut ekranu przedstawia kontrolę wstążki Galeria Drop-Down w programie Microsoft Paint dla systemu Windows 7.

SplitButtonGallery

SplitButtonGallery jest kontrolką złożoną, która uwidacznia pojedynczy element domyślny lub polecenie z kolekcji na przycisku podstawowym, a także wyświetla inne elementy lub polecenia na wzajemnie wykluczanej liście rozwijanej wyświetlanej po kliknięciu przycisku pomocniczego.

Poniższy zrzut ekranu przedstawia kontrolkę Galerii przycisków podziału na wstążce w programie Microsoft Paint dla systemu Windows 7.

InRibbonGallery

InRibbonGallery to galeria zawierająca kolekcję powiązanych elementów lub poleceń na wstążce. Jeśli w galerii znajduje się zbyt wiele elementów, zostanie udostępniona strzałka rozwijania, aby wyświetlić resztę kolekcji w rozszerzonym okienku.

Poniższy zrzut ekranu przedstawia kontrolkę Galerii Wstążki In-Ribbon w Microsoft Paint w systemie Windows 7.

Pole listy rozwijanej

ComboBox to lista jednokolumnowa zawierająca zbiór elementów z kontrolką statyczną lub kontrolką edycji oraz strzałką rozwijania. Część listy kontrolki jest wyświetlana, gdy użytkownik kliknie na strzałkę w dół.

Poniższy zrzut ekranu przedstawia kontrolkę wstążki Combo Box programu Windows Live Movie Maker.

Ponieważ ComboBox jest wyłącznie galerią elementów, nie obsługuje elementów poleceń. Jest to również jedyna kontrolka galerii, która nie obsługuje obszaru poleceń. (Obszar poleceń to kolekcja poleceń, które są zadeklarowane w znacznikach i umieszczane w dolnej części galerii elementów lub galerii poleceń).

Poniższy przykład kodu przedstawia znaczniki wymagane do zadeklarowania trzyprzyciskowego obszaru poleceń w DropDownGallery.

<DropDownGallery 
  CommandName="cmdSizeAndColor" 
  TextPosition="Hide" 
  Type="Commands"
  ItemHeight="32"
  ItemWidth="32">
  <DropDownGallery.MenuLayout>
    <FlowMenuLayout Rows="2" Columns="3" Gripper="None"/>
  </DropDownGallery.MenuLayout>
  <Button CommandName="cmdCommandSpace1"/>
  <Button CommandName="cmdCommandSpace2"/>
  <Button CommandName="cmdCommandSpace3"/>
</DropDownGallery>

Poniższy zrzut ekranu przedstawia przestrzeń poleceń z trzema przyciskami z poprzedniego przykładu kodu.

Jak zaimplementować galerię

W tej sekcji omówiono szczegóły implementacji galerii Wstążki oraz przedstawiono, jak je uwzględnić w aplikacji wykorzystującej Wstążkę.

Podstawowe składniki

W tej sekcji opisano zestaw właściwości i metod, które tworzą szkielet zawartości dynamicznej w strukturze wstążki i obsługują dodawanie, usuwanie, aktualizowanie i manipulowanie zawartością i układem wizualnym galerii wstążki w czasie wykonywania.

IUICollection

Galerie wymagają podstawowego zestawu metod uzyskiwania dostępu do poszczególnych elementów w swoich kolekcjach i manipulowania nimi.

Interfejs IEnumUnknown definiuje te metody, a struktura uzupełnia ich funkcjonalność dodatkowymi metodami zdefiniowanymi w interfejsie IUICollection. IUICollection jest implementowana przez platformę dla każdej deklaracji galerii w znaczniku wstążki.

Jeśli wymagane są dodatkowe funkcje, które nie są udostępniane przez interfejs IUICollection, można zastąpić kolekcję platform własnym obiektem kolekcji, który jest implementowany przez aplikację hosta i pochodzi z IEnumUnknown.

IUICollectionChangedEvent (Zdarzenie Zmiany Kolekcji Interfejsu Użytkownika)

Aby aplikacja reagowała na zmiany w kolekcji galerii, musi zaimplementować interfejs IUICollectionChangedEvent. Aplikacje mogą subskrybować powiadomienia z obiektu IUICollection za pośrednictwem odbiornika zdarzeń IUICollectionChangedEvent::OnChanged.

Gdy aplikacja zastępuje kolekcję galerii dostarczoną przez platformę kolekcją niestandardową, aplikacja powinna zaimplementować interfejs IConnectionPointContainer. Jeśli IConnectionPointContainer nie jest zaimplementowana, aplikacja nie może powiadomić struktury zmian w kolekcji niestandardowej, które wymagają aktualizacji dynamicznych w kontrolce galerii.

W takich przypadkach, gdy IConnectionPointContainer nie jest zaimplementowana, kontrolka galerii może zostać zaktualizowana tylko przez unieważnienie za pośrednictwem IUIFramework::InvalidateUICommand i IUICommandHandler::UpdatePropertylub wywołując IUIFramework::SetUICommandProperty.

IUISimplePropertySet

Aplikacje muszą implementować zestaw IUISimplePropertySet dla każdego elementu lub polecenia w kolekcji galerii. Jednak właściwości, które można zażądać za pomocą IUISimplePropertySet::GetValue różnią się.

Elementy są definiowane i powiązane z galerią za pośrednictwem klucza właściwości UI_PKEY_ItemsSource i udostępniają właściwości za pomocą obiektu IUICollection.

Prawidłowe właściwości elementów w galeriach elementów (UI_COMMANDTYPE_COLLECTION) opisano w poniższej tabeli.

Notatka

Niektóre właściwości elementu, takie jak UI_PKEY_Label, można zdefiniować w znacznikach. Aby uzyskać więcej informacji, zobacz dokumentację dotyczącą kluczy właściwości .

 

Kontrola

Właściwości

ComboBox

UI_PKEY_Label, UI_PKEY_CategoryId

DropDownGallery

UI_PKEY_Label, UI_PKEY_ItemImage , UI_PKEY_CategoryId

InRibbonGallery

UI_PKEY_Label, UI_PKEY_ItemImage , UI_PKEY_CategoryId

SplitButtonGallery

UI_PKEY_Label, UI_PKEY_ItemImage, UI_PKEY_CategoryId

UI_PKEY_SelectedItem jest właściwością galerii elementów.

 

Prawidłowe właściwości elementu dla galerii poleceń (UI_COMMANDTYPE_COMMANDCOLLECTION) opisano w poniższej tabeli.

Kontrola	Właściwości
DropDownGallery	UI_PKEY_CommandId, UI_PKEY_CommandType , UI_PKEY_CategoryId
InRibbonGallery	UI_PKEY_CommandId, UI_PKEY_CommandType , UI_PKEY_CategoryId
SplitButtonGallery	UI_PKEY_CommandId, UI_PKEY_CommandType, UI_PKEY_CategoryId

 

Kategorie służą do organizowania elementów i poleceń w galeriach. Kategorie są definiowane i powiązane z galerią za pośrednictwem klucza właściwości UI_PKEY_Categories i udostępniają właściwości za pomocą obiektu IUICollection specyficznego dla kategorii.

Kategorie nie mają typu CommandType i nie obsługują interakcji użytkownika. Na przykład kategorie nie mogą stać się elementem SelectedItem w galerii elementów i nie są one powiązane z poleceniem w galerii poleceń. Podobnie jak w przypadku innych właściwości elementu galerii, właściwości kategorii, takie jak UI_PKEY_Label i UI_PKEY_CategoryId, można pobrać, wywołując IUISimplePropertySet::GetValue.

Ważny

IUISimplePropertySet::GetValue powinna zwrócić UI_COLLECTION_INVALIDINDEX, gdy UI_PKEY_CategoryId jest żądana dla elementu, który nie ma skojarzonej kategorii.

 

Deklarowanie kontrolek w znacznikach

Galerie, podobnie jak wszystkie kontrolki wstążki, muszą być zadeklarowane w znacznikach. Galeria jest identyfikowana w znacznikach jako galeria elementów lub galeria poleceń, a różne szczegóły prezentacji są deklarowane. W przeciwieństwie do innych kontrolek galerie wymagają zadeklarowania tylko podstawowej kontrolki lub kontenera kolekcji. Rzeczywiste kolekcje są wypełniane w okresie wykonywania programu. Gdy galeria jest zadeklarowana w znacznikach, atrybut Type służy do określania, czy galeria jest galerią elementów, czy galerią poleceń.

Istnieje wiele opcjonalnych atrybutów układu dostępnych dla każdego z kontrolek omówionych tutaj. Te atrybuty określają preferencje dewelopera dla frameworku, które wpływają bezpośrednio na to, jak kontrolka jest wypełniana i wyświetlana na wstążce. Preferencje dotyczące znaczników odnoszą się do szablonów wyświetlania i układu oraz zachowań omówionych w Dostosowywanie wstążki przez definicje rozmiarów i zasady skalowania.

Jeśli określona kontrolka nie zezwala na preferencje układu bezpośrednio w znaczniku lub preferencje układu nie są określone, platforma definiuje konwencje wyświetlania specyficzne dla kontrolek na podstawie ilości dostępnego miejsca na ekranie.

W poniższych przykładach pokazano, jak dołączyć zestaw galerii do wstążki.

Deklaracje poleceń

Polecenia należy zadeklarować za pomocą atrybutu CommandName, który jest używany do skojarzenia kontrolki lub zestawu kontrolek z poleceniem.

Atrybut CommandId używany do powiązania polecenia z obsługą poleceń, podczas gdy kod jest kompilowany, można określić również tutaj. Jeśli nie podano identyfikatora, zostanie on wygenerowany przez strukturę.

<!-- ComboBox -->
<Command Name="cmdComboBoxGroup"
         Symbol="cmdComboBoxGroup"
         Comment="ComboBox Group"
         LabelTitle="ComboBox"/>
<Command Name="cmdComboBox"
         Symbol="cmdComboBox"
         Comment="ComboBox"
         LabelTitle="ComboBox"/>

<!-- DropDownGallery -->
<Command Name="cmdDropDownGalleryGroup"
         Symbol="cmdDropDownGalleryGroup"
         Comment="DropDownGallery Group"
         LabelTitle="DropDownGallery"/>
<Command Name="cmdDropDownGallery"
         Symbol="cmdDropDownGallery"
         Comment="DropDownGallery"
         LabelTitle="DropDownGallery"/>

<!-- InRibbonGallery -->
<Command Name="cmdInRibbonGalleryGroup"
         Symbol="cmdInRibbonGalleryGroup"
         Comment="InRibbonGallery Group"
         LabelTitle="InRibbonGallery"/>
<Command Name="cmdInRibbonGallery"
         Symbol="cmdInRibbonGallery"
         Comment="InRibbonGallery"
         LabelTitle="InRibbonGallery"

<!-- SplitButtonGallery -->
<Command Name="cmdSplitButtonGalleryGroup"
         Symbol="cmdSplitButtonGalleryGroup"
         Comment="SplitButtonGallery Group"
         LabelTitle="SplitButtonGallery"/>
<Command Name="cmdSplitButtonGallery"
         Symbol="cmdSplitButtonGallery"
         Comment="SplitButtonGallery"
         LabelTitle="SplitButtonGallery"

Deklaracje sterowania

Ta sekcja zawiera przykłady demonstrujące podstawowy znacznik kontroli wymagany dla różnych typów galerii. Pokazują one, jak zadeklarować kontrolki galerii i skojarzyć je z poleceniem za pomocą atrybutu CommandName.

Poniższy przykład przedstawia deklarację kontrolki dla DropDownGallery, w której atrybut type jest używany do określenia, że jest to galeria poleceń.

<!-- DropDownGallery -->
<Group CommandName="cmdDropDownGalleryGroup">
  <DropDownGallery CommandName="cmdDropDownGallery"
                   TextPosition="Hide"
                   Type="Commands"
                   ItemHeight="32"
                   ItemWidth="32">
    <DropDownGallery.MenuLayout>
      <FlowMenuLayout Rows="2"
                      Columns="3"
                      Gripper="None"/>
    </DropDownGallery.MenuLayout>
    <DropDownGallery.MenuGroups>
      <MenuGroup>
        <Button CommandName="cmdButton1"></Button>
        <Button CommandName="cmdButton2"></Button>
       </MenuGroup>
       <MenuGroup>
        <Button CommandName="cmdButton3"></Button>
      </MenuGroup>
    </DropDownGallery.MenuGroups>
  </DropDownGallery>
</Group>

W poniższym przykładzie przedstawiono deklarację kontrolki dla SplitButtonGallery.

<!-- SplitButtonGallery -->
<Group CommandName="cmdSplitButtonGalleryGroup">
  <SplitButtonGallery CommandName="cmdSplitButtonGallery">
    <SplitButtonGallery.MenuLayout>
      <FlowMenuLayout Rows="2"
                      Columns="3"
                      Gripper="None"/>
    </SplitButtonGallery.MenuLayout>
    <SplitButtonGallery.MenuGroups>
      <MenuGroup>
        <Button CommandName="cmdButton1"></Button>
        <Button CommandName="cmdButton2"></Button>
      </MenuGroup>
      <MenuGroup>
        <Button CommandName="cmdButton3"></Button>
      </MenuGroup>
    </SplitButtonGallery.MenuGroups>
  </SplitButtonGallery>
</Group>

W poniższym przykładzie przedstawiono deklarację kontrolki dla InRibbonGallery.

Notatka

Ponieważ InRibbonGallery jest przeznaczona do wyświetlania podzbioru kolekcji elementów na wstążce bez aktywowania menu rozwijanego, udostępnia wiele opcjonalnych atrybutów, które zarządzają jej rozmiarem i układem elementów podczas inicjalizacji wstążki. Te atrybuty są unikatowe dla InRibbonGallery i nie są dostępne w innych kontrolkach dynamicznych.

 

<!-- InRibbonGallery -->
<Group CommandName="cmdInRibbonGalleryGroup" SizeDefinition="OneInRibbonGallery">
  <InRibbonGallery CommandName="cmdInRibbonGallery"
                   MaxColumns="10"
                   MaxColumnsMedium="5"
                   MinColumnsLarge="5"
                   MinColumnsMedium="3"
                   Type="Items">
    <InRibbonGallery.MenuLayout>
      <VerticalMenuLayout Rows="2"
                          Gripper="Vertical"/>
    </InRibbonGallery.MenuLayout>
    <InRibbonGallery.MenuGroups>
      <MenuGroup>
        <Button CommandName="cmdButton1"></Button>
        <Button CommandName="cmdButton2"></Button>
      </MenuGroup>
      <MenuGroup>
        <Button CommandName="cmdButton3"></Button>
      </MenuGroup>
    </InRibbonGallery.MenuGroups>            
  </InRibbonGallery>
</Group>

W poniższym przykładzie przedstawiono deklarację kontrolki dla ComboBox.

<!-- ComboBox -->
<Group CommandName="cmdComboBoxGroup">
  <ComboBox CommandName="cmdComboBox">              
  </ComboBox>
</Group>

Tworzenie programu obsługi poleceń

Dla każdego polecenia platforma wstążki wymaga odpowiedniej procedury obsługi poleceń w aplikacji hosta. Programy obsługi poleceń są implementowane przez aplikację hostującą wstążkę i są pochodnymi interfejsu IUICommandHandler.

Notatka

Wiele poleceń można powiązać z jedną procedurą obsługi poleceń.

 

Procedura obsługi poleceń służy do dwóch celów:

• IUICommandHandler::UpdateProperty odpowiada na żądania aktualizacji właściwości. Wartości właściwości polecenia, takie jak UI_PKEY_Enabled lub UI_PKEY_Label, są ustawiane za pomocą wywołań IUIFramework::SetUICommandProperty lub IUIFramework::InvalidateUICommand.
• IUICommandHandler::Execute reaguje na zdarzenia wykonywania. Ta metoda obsługuje następujące trzy stany wykonywania określone przez parametr UI_EXECUTIONVERB.
  • Stan wykonania realizuje lub zatwierdza wszelkie polecenia, do których jest przypisana procedura obsługi.
  • Stan podglądu wyświetla podgląd dowolnych poleceń, z którymi jest powiązana procedura obsługi. Zasadniczo wykonuje to polecenia bez zatwierdzania wyniku.
  • Stan anulowania podglądu anuluje wszelkie przeglądane polecenia. Jest to wymagane do obsługi przechodzenia przez menu lub listę i sekwencyjnego podglądania oraz cofania wyników według potrzeb.

W poniższym przykładzie przedstawiono procedurę obsługi poleceń galerii.

/*
 * GALLERY COMMAND HANDLER IMPLEMENTATION
 */
class CGalleryCommandHandler
      : public CComObjectRootEx<CComMultiThreadModel>
      , public IUICommandHandler
{
public:
  BEGIN_COM_MAP(CGalleryCommandHandler)
    COM_INTERFACE_ENTRY(IUICommandHandler)
  END_COM_MAP()

  // Gallery command handler's Execute method
  STDMETHODIMP Execute(UINT nCmdID,
                       UI_EXECUTIONVERB verb, 
                       const PROPERTYKEY* key,
                       const PROPVARIANT* ppropvarValue,
                       IUISimplePropertySet* pCommandExecutionProperties)
  {
    HRESULT hr = S_OK;
        
    // Switch on manner of execution (Execute/Preview/CancelPreview)
    switch (verb)
    {
      case UI_EXECUTIONVERB_EXECUTE:
        if(nCmdID == cmdTextSizeGallery || 
           nCmdID == cmdTextSizeGallery2 || 
           nCmdID == cmdTextSizeGallery3)
        {
          if (pCommandExecutionProperties != NULL)
          {
            CItemProperties *pItem = 
              static_cast<CItemProperties *>(pCommandExecutionProperties);
            g_prevSelection = g_index = pItem->GetIndex();
            UpdateGallerySelectedItems();
            ::InvalidateRect(g_hWindowFrame, NULL, TRUE);
          }
          else
          {
            g_prevSelection = g_index = 0;
            UpdateGallerySelectedItems();
            ::InvalidateRect(g_hWindowFrame, NULL, TRUE);
          }
        }           
        break;
      case UI_EXECUTIONVERB_PREVIEW:
        CItemProperties *pItem = 
          static_cast<CItemProperties *>(pCommandExecutionProperties);
        g_index = pItem->GetIndex();
        ::InvalidateRect(g_hWindowFrame, NULL, TRUE);
        break;
      case UI_EXECUTIONVERB_CANCELPREVIEW:
        g_index = g_prevSelection;
        ::InvalidateRect(g_hWindowFrame, NULL, TRUE);
        break;
    }   
    return hr;
  }

  // Gallery command handler's UpdateProperty method
  STDMETHODIMP UpdateProperty(UINT nCmdID,
                              REFPROPERTYKEY key,
                              const PROPVARIANT* ppropvarCurrentValue,
                              PROPVARIANT* ppropvarNewValue)
  {
    UNREFERENCED_PARAMETER(ppropvarCurrentValue);

    HRESULT hr = E_NOTIMPL;         

    if (key == UI_PKEY_ItemsSource) // Gallery items requested
    {
      if (nCmdID == cmdTextSizeGallery || 
          nCmdID == cmdTextSizeGallery2 || 
          nCmdID == cmdTextSizeGallery3)
      {
        CComQIPtr<IUICollection> spCollection(ppropvarCurrentValue->punkVal);

        int count = _countof(g_labels);

        for (int i = 0; i < count; i++)
        {
          CComObject<CItemProperties> * pItem;
          CComObject<CItemProperties>::CreateInstance(&pItem);
                    
          pItem->AddRef();
          pItem->Initialize(i);

          spCollection->Add(pItem);
        }
        return S_OK;
      }
      if (nCmdID == cmdCommandGallery1)
      {
        CComQIPtr<IUICollection> spCollection(ppropvarCurrentValue->punkVal);

        int count = 12;
        int commands[] = {cmdButton1, 
                          cmdButton2, 
                          cmdBoolean1, 
                          cmdBoolean2, 
                          cmdButton1, 
                          cmdButton2, 
                          cmdBoolean1, 
                          cmdBoolean2, 
                          cmdButton1, 
                          cmdButton2, 
                          cmdBoolean1, 
                          cmdBoolean2};

        for (int i = 0; i < count; i++)
        {
          CComObject<CItemProperties> * pItem;
          CComObject<CItemProperties>::CreateInstance(&pItem);
                    
          pItem->AddRef();
          pItem->InitializeAsCommand(commands[i]);

          spCollection->Add(pItem);
        }
        return S_OK;
      }
    }        
    else if (key == UI_PKEY_SelectedItem) // Selected item requested
    {           
      hr = UIInitPropertyFromUInt32(UI_PKEY_SelectedItem, g_index, ppropvarNewValue);           
    }
    return hr;
  }
};

Powiąż program obsługi poleceń

Po zdefiniowaniu procedury obsługi poleceń należy powiązać polecenie z procedurą obsługi.

W poniższym przykładzie pokazano, jak powiązać polecenie galerii z określoną procedurą obsługi poleceń. W takim przypadku zarówno kontrolki ComboBox, jak i galerii są powiązane z odpowiednimi procedurami obsługi poleceń.

// Called for each Command in markup. 
// Application will return a Command handler for each Command.
STDMETHOD(OnCreateUICommand)(UINT32 nCmdID,
                             UI_COMMANDTYPE typeID,
                             IUICommandHandler** ppCommandHandler) 
{   
  // CommandType for ComboBox and galleries
  if (typeID == UI_COMMANDTYPE_COLLECTION || typeID == UI_COMMANDTYPE_COMMANDCOLLECTION) 
  {
    switch (nCmdID)
    {
      case cmdComboBox:
        CComObject<CComboBoxCommandHandler> * pComboBoxCommandHandler;
        CComObject<CComboBoxCommandHandler>::CreateInstance(&pComboBoxCommandHandler);
        return pComboBoxCommandHandler->QueryInterface(IID_PPV_ARGS(ppCommandHandler));
      default:
        CComObject<CGalleryCommandHandler> * pGalleryCommandHandler;
        CComObject<CGalleryCommandHandler>::CreateInstance(&pGalleryCommandHandler);
        return pGalleryCommandHandler->QueryInterface(IID_PPV_ARGS(ppCommandHandler));
    }
    return E_NOTIMPL; // Command is not implemented, so do not pass a handler back.
  }
}

Inicjowanie kolekcji

W poniższym przykładzie pokazano niestandardową implementację IUISimplePropertySet dla galerii elementów i poleceń.

Klasa CItemProperties w tym przykładzie pochodzi z IUISimplePropertySet. Oprócz wymaganej metody IUISimplePropertySet::GetValueklasa CItemProperties implementuje zestaw funkcji pomocnika na potrzeby inicjowania i śledzenia indeksów.

//
//  PURPOSE:    Implementation of IUISimplePropertySet.
//
//  COMMENTS:
//              Three gallery-specific helper functions included. 
//

class CItemProperties
  : public CComObjectRootEx<CComMultiThreadModel>
  , public IUISimplePropertySet
{
  public:

  // COM map for QueryInterface of IUISimplePropertySet.
  BEGIN_COM_MAP(CItemProperties)
    COM_INTERFACE_ENTRY(IUISimplePropertySet)
  END_COM_MAP()

  // Required method that enables property key values to be 
  // retrieved on gallery collection items.
  STDMETHOD(GetValue)(REFPROPERTYKEY key, PROPVARIANT *ppropvar)
  {
    HRESULT hr;

    // No category is associated with this item.
    if (key == UI_PKEY_CategoryId)
    {
      return UIInitiPropertyFromUInt32(UI_PKEY_CategoryId, 
                                       UI_COLLECTION_INVALIDINDEX, 
                                       pprovar);
    }

    // A Command gallery.
    // _isCommandGallery is set on initialization.
    if (_isCommandGallery)
    {           
      if(key == UI_PKEY_CommandId && _isCommandGallery)
      {
        // Return a pointer to the CommandId of the item.
        return InitPropVariantFromUInt32(_cmdID, ppropvar);
      }         
    }
    // An item gallery.
    else
    {
      if (key == UI_PKEY_Label)
      {
        // Return a pointer to the item label string.
        return UIInitPropertyFromString(UI_PKEY_Label, ppropvar);
      }
      else if(key == UI_PKEY_ItemImage)
      {
        // Return a pointer to the item image.
        return UIInitPropertyFromImage(UI_PKEY_ItemImage, ppropvar);
      }         
    }
    return E_NOTIMPL;
  }

  // Initialize an item in an item gallery collection at the specified index.
  void Initialize(int index)
  {
    _index = index;
    _cmdID = 0;
    _isCommandGallery = false;
  }

  // Initialize a Command in a Command gallery.
  void InitializeAsCommand(__in UINT cmdID)
  {
    _index = 0;
    _cmdID = cmdID;
    _isCommandGallery = true;
  }

  // Gets the index of the selected item in an item gallery.
  int GetIndex()
  {
    return _index;
  }

private:
  int _index;
  int _cmdID;
  bool _isCommandGallery;   
};

Obsługa zdarzeń zbierania

W poniższym przykładzie pokazano implementację IUICollectionChangedEvent.

class CQATChangedEvent
  : public CComObjectRootEx<CComSingleThreadModel>
  , public IUICollectionChangedEvent
{
  public:

  HRESULT FinalConstruct()
  {
    _pSite = NULL;
    return S_OK;
  }

  void Initialize(__in CQATSite* pSite)
  {
    if (pSite != NULL)
    {
      _pSite = pSite;
    }
  }

  void Uninitialize()
  {
    _pSite = NULL;
  }

  BEGIN_COM_MAP(CQATChangedEvent)
    COM_INTERFACE_ENTRY(IUICollectionChangedEvent)
  END_COM_MAP()

  // IUICollectionChangedEvent interface
  STDMETHOD(OnChanged)(UI_COLLECTIONCHANGE action, 
                       UINT32 oldIndex, 
                       IUnknown *pOldItem, 
                       UINT32 newIndex, 
                       IUnknown *pNewItem)
  {
    if (_pSite)
    {
      _pSite->OnCollectionChanged(action, oldIndex, pOldItem, newIndex, pNewItem);
    }
    return S_OK;
  }

  protected:
  virtual ~CQATChangedEvent(){}

  private:
  CQATSite* _pSite; // Weak ref to avoid circular refcounts
};

HRESULT CQATHandler::EnsureCollectionEventListener(__in IUICollection* pUICollection)
{
  // Check if listener already exists.
  if (_spQATChangedEvent)
  {
    return S_OK;
  }

  HRESULT hr = E_FAIL;

  // Create an IUICollectionChangedEvent listener.
  hr = CreateInstanceWithRefCountOne(&_spQATChangedEvent);
    
  if (SUCCEEDED(hr))
  {
    CComPtr<IUnknown> spUnknown;
    _spQATChangedEvent->QueryInterface(IID_PPV_ARGS(&spUnknown));

    // Create a connection between the collection connection point and the sink.
    AtlAdvise(pUICollection, spUnknown, __uuidof(IUICollectionChangedEvent), &_dwCookie);
    _spQATChangedEvent->Initialize(this);
  }
  return hr;
}

HRESULT CQATHandler::OnCollectionChanged(
             UI_COLLECTIONCHANGE action, 
          UINT32 oldIndex, 
             IUnknown *pOldItem, 
          UINT32 newIndex, 
          IUnknown *pNewItem)
{
    UNREFERENCED_PARAMETER(oldIndex);
    UNREFERENCED_PARAMETER(newIndex);

    switch (action)
    {
      case UI_COLLECTIONCHANGE_INSERT:
      {
        CComQIPtr<IUISimplePropertySet> spProperties(pNewItem);
                
        PROPVARIANT var;
        if (SUCCEEDED(spProperties->GetValue(UI_PKEY_CommandId, &var)))
        {
          UINT tcid;
          if (SUCCEEDED(UIPropertyToUInt32(UI_PKEY_CommandId, var, &tcid)))
          {
            FireETWEvent(tcid, L"Added to QAT");
            PropVariantClear(&var);
          }
        }
      }
      break;
      case UI_COLLECTIONCHANGE_REMOVE:
      {
        CComQIPtr<IUISimplePropertySet> spProperties(pOldItem);
                
        PROPVARIANT var;
        if (SUCCEEDED(spProperties->GetValue(UI_PKEY_CommandId, &var)))
        {
          UINT tcid;
          if (SUCCEEDED(UIPropertyToUInt32(UI_PKEY_CommandId, var, &tcid)))
          {
            FireETWEvent(tcid, L"Removed from QAT");
            PropVariantClear(&var);
          }
        }
      }
      break;
    default:
  }
  return S_OK;
}

Tematy pokrewne

Właściwości kolekcji

Tworzenie aplikacji Wstążki

Understanding Commands and Controls (Informacje o poleceniach i kontrolkach)

Wskazówki dotyczące środowiska użytkownika wstążki wstążki

Proces projektowania wstążki

Przykładowa galeria