Toolbar Akses Cepat

Artikel
06/13/2023

Toolbar Akses Cepat (QAT) adalah toolbar kecil yang dapat disesuaikan yang mengekspos sekumpulan Perintah yang ditentukan oleh aplikasi atau dipilih oleh pengguna.

Pendahuluan
Menerapkan Toolbar Akses Cepat
- Markup
- Kode
Persistensi QAT
Properti Bilah Alat Akses Cepat
Topik terkait

Pengantar

Secara default, Toolbar Akses Cepat (QAT) terletak di bilah judul jendela aplikasi tetapi dapat dikonfigurasi untuk ditampilkan di bawah pita. Selain mengekspos Perintah, Toolbar Akses Cepat (QAT) juga menyertakan menu drop-down yang dapat disesuaikan yang berisi kumpulan lengkap Perintah Toolbar Akses Cepat (QAT) default (baik tersembunyi atau ditampilkan di Toolbar Akses Cepat (QAT)) dan sekumpulan Toolbar Akses Cepat (QAT) dan opsi pita.

Cuplikan layar berikut ini memperlihatkan contoh Toolbar Akses Cepat Pita (QAT).

Toolbar Akses Cepat (QAT) terdiri dari kombinasi hingga 20 Perintah yang ditentukan oleh aplikasi (dikenal sebagai daftar default aplikasi) atau dipilih oleh pengguna. Toolbar Akses Cepat (QAT) bisa berisi Perintah unik yang tidak tersedia di tempat lain di UI pita.

Catatan

Meskipun hampir semua kontrol pita memungkinkan Perintah terkait ditambahkan ke Toolbar Akses Cepat (QAT) melalui menu konteks yang diperlihatkan dalam cuplikan layar berikut, Perintah yang diekspos dalam Popup Konteks tidak menyediakan menu konteks ini.

cuplikan layar menu konteks perintah di pita cat microsoft.

Seperti semua kontrol kerangka kerja Windows Ribbon, memanfaatkan sepenuhnya Toolbar Akses Cepat (QAT) memerlukan komponen markup yang mengontrol presentasinya di dalam pita dan komponen kode yang mengatur fungsionalitasnya.

Markup

Kontrol Toolbar Akses Cepat (QAT) dideklarasikan, dan terkait dengan ID Perintah, dalam markup melalui elemen QuickAccessToolbar . ID Perintah digunakan untuk mengidentifikasi dan mengikat Toolbar Akses Cepat (QAT) ke handler Perintah yang ditentukan oleh aplikasi.

Selain penangan Perintah dasar untuk fungsionalitas Toolbar Akses Cepat (QAT) utama, mendeklarasikan atribut elemen CustomizeCommandNameQuickAccessToolbar opsional menyebabkan kerangka kerja menambahkan item Perintah Lainnya ke daftar Perintah menu drop-down Toolbar Akses Cepat (QAT) yang memerlukan penangan Perintah sekunder ditentukan.

Untuk konsistensi di seluruh aplikasi Pita, disarankan agar penangan Perintah CustomizeCommandName meluncurkan dialog kustomisasi Toolbar Akses Cepat (QAT). Karena kerangka kerja Pita hanya menyediakan titik peluncuran di UI, aplikasi hanya bertanggung jawab untuk menyediakan implementasi dialog kustomisasi saat pemberitahuan panggilan balik untuk Perintah ini diterima.

Cuplikan layar berikut ini memperlihatkan menu drop-down Toolbar Akses Cepat (QAT) dengan item Perintah Lainnya .

cuplikan layar menu qat dengan perintah lainnya... item perintah.

Daftar default aplikasi untuk Toolbar Akses Cepat (QAT) ditentukan melalui properti QuickAccessToolbar.ApplicationDefaults yang mengidentifikasi daftar default Perintah yang direkomendasikan, yang semuanya tercantum di menu drop-down Toolbar Akses Cepat (QAT).

Untuk menampilkan Perintah dari daftar default aplikasi di toolbar Toolbar Akses Cepat (QAT), atribut ApplicationDefaults.IsChecked dari setiap elemen kontrol harus memiliki nilai true. Gambar sebelumnya menunjukkan hasil pengaturan atribut ini ke true untuk Perintah Simpan, Batalkan, dan Ulangi .

QuickAccessToolbar.ApplicationDefaults mendukung tiga jenis kontrol Pita: Tombol, Tombol Alih, dan Kotak Centang.

Catatan

Windows 8 dan yang lebih baru: Semua kontrol berbasis galeri didukung (ComboBox, InRibbonGallery, SplitButtonGallery, dan DropDownGallery).

Item dalam kontrol galeri dapat mendukung penyorotan pada hover. Untuk mendukung penyorotan hover, galeri harus berupa galeri item dan menggunakan FlowMenuLayout jenis VerticalMenuLayout.

Contoh berikut menunjukkan markup dasar untuk elemen QuickAccessToolbar .

Bagian kode ini memperlihatkan deklarasi Perintah untuk elemen Toolbar Akses Cepat (QAT ).

<Command Name="cmdQAT"
         Symbol="ID_QAT"
         Id="40000"/>
<Command Name="cmdCustomizeQAT"
         Symbol="ID_CUSTOM_QAT"
         Id="40001"/>

Bagian kode ini memperlihatkan deklarasi kontrol untuk elemen Toolbar Akses Cepat (QAT ).

      <Ribbon.QuickAccessToolbar>
        <QuickAccessToolbar CommandName="cmdQAT"
                            CustomizeCommandName="cmdCustomizeQAT">
          <QuickAccessToolbar.ApplicationDefaults>
            <Button CommandName="cmdButton1"/>
            <ToggleButton CommandName="cmdMinimize"
                          ApplicationDefaults.IsChecked="false"/>
          </QuickAccessToolbar.ApplicationDefaults>
        </QuickAccessToolbar>
      </Ribbon.QuickAccessToolbar>

Kode

Aplikasi kerangka kerja Pita harus menyediakan metode panggilan balik handler Perintah untuk memanipulasi Toolbar Akses Cepat (QAT). Handler ini bekerja dengan cara yang sama dengan handler galeri Perintah, kecuali bahwa Toolbar Akses Cepat (QAT) tidak mendukung kategori. Untuk informasi selengkapnya, lihat Bekerja dengan Galeri.

Kumpulan Perintah Toolbar Akses Cepat (QAT) diambil sebagai objek IUICollection melalui kunci properti UI_PKEY_ItemsSource . Menambahkan Perintah ke Toolbar Akses Cepat (QAT) pada durasi dilakukan dengan menambahkan objek IUISimplePropertySet ke IUICollection.

Tidak seperti galeri Perintah, properti jenis perintah (UI_PKEY_CommandType) tidak diperlukan untuk objek IUISimplePropertySet Toolbar Akses Cepat (QAT). Namun, Perintah harus ada di pita atau daftar default aplikasi Quick Access Toolbar (QAT) ; Perintah baru tidak dapat dibuat pada durasi dan ditambahkan ke Toolbar Akses Cepat (QAT).

Catatan

Aplikasi Pita tidak dapat mengganti IUICollection Toolbar Akses Cepat (QAT) dengan objek koleksi kustom yang berasal dari IEnumUnknown.

Contoh berikut menunjukkan implementasi handler Perintah Quick Access Toolbar (QAT) dasar.

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

    // QAT command handler's Execute method
    STDMETHODIMP Execute(UINT nCmdID,
                         UI_EXECUTIONVERB verb, 
                         const PROPERTYKEY* key,
                         const PROPVARIANT* ppropvarValue,
                         IUISimplePropertySet* pCommandExecutionProperties)
    {
      UNREFERENCED_PARAMETER(nCmdID);
      UNREFERENCED_PARAMETER(verb);
      UNREFERENCED_PARAMETER(ppropvarValue);
      UNREFERENCED_PARAMETER(pCommandExecutionProperties);

      // Do not expect Execute callback for a QAT command
      return E_NOTIMPL;
    }

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

      HRESULT hr = E_NOTIMPL;

      if (key == UI_PKEY_ItemsSource)
      {
        ATLASSERT(ppropvarCurrentValue->vt == VT_UNKNOWN);

        CComQIPtr<IUICollection> spCollection(ppropvarCurrentValue->punkVal);

        UINT nCount;
        if (SUCCEEDED(hr = spCollection->GetCount(&nCount)))
        {
          if (nCount == 0)
          {
            // If the current Qat list is empty, then we will add a few items here.
            UINT commands[] =  { cmdSave, cmdUndo};

            int count = _countof(commands);

            for (int i = 0; i < count; i++)
            {
              PROPERTYKEY keys[1] = {UI_PKEY_CommandId};
              CComObject<CItemProperties> *pItem = NULL;
              if (SUCCEEDED(CComObject<CItemProperties>::CreateInstance(&pItem)))
              {
                PROPVARIANT vars[1];

                InitPropVariantFromUInt32(commands[i], &vars[0]);

                pItem->Initialize(NULL, _countof(vars), keys, vars);

                CComPtr<IUnknown> spUnknown;
                pItem->QueryInterface(&spUnknown);
                spCollection->Add(spUnknown);
                            
                FreePropVariantArray(_countof(vars), vars);
              }
            }
          }
          else
          {
            // Do nothing if the Qat list is not empty.
            // Return S_FALSE to indicate the callback succeeded.
            return S_FALSE; 
          }
        }
      }
    return hr;
  }
};

Persistensi QAT

Item dan pengaturan Perintah Toolbar Akses Cepat (QAT) dapat dipertahankan di seluruh sesi aplikasi menggunakan fungsi IUIRibbon::SaveSettingsToStream dan IUIRibbon::LoadSettingsFromStream . Untuk informasi selengkapnya, lihat Status Pita Yang Bertahan.

Kerangka kerja Pita menentukan kumpulan kunci properti untuk kontrol Toolbar Akses Cepat (QAT).

Biasanya, properti Toolbar Akses Cepat (QAT) diperbarui di UI pita dengan membatalkan Perintah yang terkait dengan kontrol melalui panggilan ke metode IUIFramework::InvalidateUICommand . Peristiwa pembatalan ditangani, dan pembaruan properti ditentukan, oleh metode panggilan balik IUICommandHandler::UpdateProperty .

Metode panggilan balik IUICommandHandler::UpdateProperty tidak dijalankan, dan aplikasi meminta nilai properti yang diperbarui, hingga properti diperlukan oleh kerangka kerja. Misalnya, saat tab diaktifkan dan kontrol terungkap di UI pita, atau saat tipsalat ditampilkan.

Catatan

Dalam beberapa kasus, properti dapat diambil melalui metode IUIFramework::GetUICommandProperty dan diatur dengan metode IUIFramework::SetUICommandProperty .

Tabel berikut ini mencantumkan kunci properti yang terkait dengan kontrol Toolbar Akses Cepat (QAT).

Kunci Properti	Catatan
UI_PKEY_ItemsSource	Mendukung IUIFramework::GetUICommandProperty (tidak mendukung IUIFramework::SetUICommandProperty). IUIFramework::GetUICommandProperty mengembalikan pointer ke objek IUICollection yang mewakili perintah di QAT. Setiap Perintah diidentifikasi oleh ID Perintahnya, yang diperoleh dengan memanggil metode IUISimplePropertySet::GetValue dan meneruskan kunci properti UI_PKEY_CommandId.

Tidak ada kunci properti yang terkait dengan item Perintah Lainnya dari menu drop-down Toolbar Akses Cepat (QAT)

Bagikan melalui

Pengantar

Markup

Kode

Persistensi QAT

Saran dan Komentar

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Pengantar

Menerapkan Toolbar Akses Cepat

Markup

Kode

Persistensi QAT

Properti Bilah Alat Akses Cepat

Topik terkait

Saran dan Komentar

Saran dan Komentar

Sumber Daya Tambahan: