クイックアクセスツールバー

[アーティクル]
06/13/2023

クイックアクセスツールバー (QAT) は、アプリケーションによって指定されるか、ユーザーによって選択されたコマンドのセットを公開する、カスタマイズ可能な小さなツールバーです。

はじめに
クイックアクセスツールバーを実装する
- マークアップ
- コード
QAT 永続化
クイックアクセスツールバーのプロパティ
関連トピック

はじめに

既定では、クイックアクセスツールバー (QAT) はアプリケーションウィンドウのタイトルバーにありますが、リボンの下に表示するように構成できます。コマンドの公開に加えて、クイックアクセスツールバー (QAT) には、既定のクイックアクセスツールバー (QAT) コマンドの完全なセット (クイックアクセスツールバー (QAT) に表示されるかどうか) とクイックアクセスツールバー (QAT) とリボンオプションのセットを含むカスタマイズ可能なドロップダウンメニューも含まれています。

次のスクリーンショットは、リボンクイックアクセスツールバー (QAT) の例を示しています。

クイックアクセスツールバー (QAT) は、アプリケーション (アプリケーションの既定値の一覧と呼ばれます) によって指定されるか、ユーザーによって選択された最大 20 個のコマンドの組み合わせで構成されます。クイックアクセスツールバー (QAT) には、リボン UI の他の場所では使用できない一意のコマンドを含めることができます。

注意

ほぼすべてのリボンコントロールでは、次のスクリーンショットに示すコンテキストメニューを使用して、関連するコマンドをクイックアクセスツールバー (QAT) に追加できますが、コンテキストポップアップで公開されるコマンドでは、このコンテキストメニューは提供されません。

Microsoft ペイントリボンのコマンドコンテキストメニューのスクリーンショット。

すべての Windows リボンフレームワークコントロールと同様に、クイックアクセスツールバー (QAT) を最大限に活用するには、リボン内でのプレゼンテーションを制御するマークアップコンポーネントと、その機能を制御するコードコンポーネントの両方が必要です。

マークアップ

クイックアクセスツールバー (QAT) コントロールは、 QuickAccessToolbar 要素を使用してマークアップで宣言され、コマンド ID に関連付けられます。コマンド ID は、クイックアクセスツールバー (QAT) を識別し、アプリケーションによって定義されたコマンドハンドラーにバインドするために使用されます。

主要なクイックアクセスツールバー (QAT) 機能の基本的なコマンドハンドラーに加えて、オプションの CustomizeCommandNameQuickAccessToolbar 要素属性を宣言すると、フレームワークは、セカンダリコマンドハンドラーを定義する必要があるクイックアクセスツールバー (QAT) ドロップダウンメニューのコマンドリストに [ その他 のコマンド] 項目を追加します。

リボンアプリケーション間で一貫性を保つには、 CustomizeCommandName コマンドハンドラーでクイックアクセスツールバー (QAT) のカスタマイズダイアログを起動することをお勧めします。リボンフレームワークは UI の起動ポイントのみを提供するため、アプリケーションは、このコマンドのコールバック通知を受け取ったときにカスタマイズダイアログの実装を提供する必要があります。

次のスクリーンショットは、[ その他のコマンド] コマンド項目を含むクイックアクセスツールバー (QAT) ドロップダウンメニューを示しています。

その他のコマンドを含む qat メニューのスクリーンショット...コマンド項目。

クイックアクセスツールバー (QAT) のアプリケーションの既定の一覧は、推奨されるコマンドの既定の一覧を識別する QuickAccessToolbar.ApplicationDefaults プロパティを使用して指定します。これらはすべて [クイックアクセスツールバー (QAT)] ドロップダウンメニューに表示されます。

クイックアクセスツールバー (QAT) ツールバーにアプリケーションの既定の一覧からコマンドを表示するには、各コントロール要素の ApplicationDefaults.IsChecked 属性の値 trueがである必要があります。上の画像は、保存、元に戻す、やり直しコマンドに対してこの属性をにtrue設定した結果を示しています。

QuickAccessToolbar.ApplicationDefaults では、ボタン、トグルボタン、チェックボックスの 3 種類のリボンコントロールがサポートされています。

注意

Windows 8以降: すべてのギャラリーベースのコントロール (ComboBox、InRibbonGallery、SplitButtonGallery、DropDownGallery) がサポートされています。

ギャラリーコントロール内の項目は、ホバー時の強調表示をサポートできます。ホバー強調表示をサポートするには、ギャラリーが項目ギャラリーであり、VerticalMenuLayout 型の FlowMenuLayout を使用する必要があります。

次の例では、 QuickAccessToolbar 要素の基本的なマークアップを示します。

コードのこのセクションでは、クイックアクセスツールバー (QAT) 要素のコマンド宣言を示します。

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

コードのこのセクションでは、クイックアクセスツールバー (QAT) 要素のコントロール宣言を示します。

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

コード

リボンフレームワークアプリケーションは、クイックアクセスツールバー (QAT) を操作するためのコマンドハンドラーコールバックメソッドを提供する必要があります。このハンドラーは、クイックアクセスツールバー (QAT) がカテゴリをサポートしていない点を除き、コマンドギャラリーハンドラーと同様の方法で動作します。詳細については、「ギャラリーの操作」を参照してください。

クイックアクセスツールバー (QAT) コマンドコレクションは、UI_PKEY_ItemsSource プロパティキーを使用して IUICollection オブジェクトとして取得されます。実行時にクイックアクセスツールバー (QAT) にコマンドを追加するには、 IUISimplePropertySet オブジェクトを IUICollection に追加します。

コマンドギャラリーとは異なり、クイックアクセスツールバー (QAT) IUISimplePropertySet オブジェクトにはコマンドの種類プロパティ (UI_PKEY_CommandType) は必要ありません。ただし、コマンドはリボンまたはクイックアクセスツールバー (QAT) アプリケーションの既定の一覧に存在する必要があります。実行時に新しいコマンドを作成してクイックアクセスツールバー (QAT) に追加することはできません。

注意

リボンアプリケーションは、クイックアクセスツールバー (QAT) IUICollection を IEnumUnknown から派生したカスタムコレクションオブジェクトに置き換えることはできません。

次の例は、基本的なクイックアクセスツールバー (QAT) コマンドハンドラーの実装を示しています。

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

QAT 永続化

クイックアクセスツールバー (QAT) コマンド項目と設定は、 IUIRibbon::SaveSettingsToStream 関数と IUIRibbon::LoadSettingsFromStream 関数を使用して、アプリケーションセッション間で保持できます。詳細については、「リボンの状態を保持する」を参照してください。

リボンフレームワークは、クイックアクセスツールバー (QAT) コントロールのプロパティキーのコレクションを定義します。

通常、クイックアクセスツールバー (QAT) プロパティは、 IUIFramework::InvalidateUICommand メソッドの呼び出しによってコントロールに関連付けられている Command を無効にすることで、リボン UI で更新されます。無効化イベントが処理され、 IUICommandHandler::UpdateProperty コールバックメソッドによって定義されたプロパティが更新されます。

IUICommandHandler::UpdateProperty コールバックメソッドは実行されず、アプリケーションは、フレームワークでプロパティが必要になるまで、更新されたプロパティ値を照会しました。たとえば、タブがアクティブ化され、リボン UI にコントロールが表示されたときや、ツールヒントが表示されたときなどです。

注意

場合によっては、 IUIFramework::GetUICommandProperty メソッドを使用してプロパティを取得し、 IUIFramework::SetUICommandProperty メソッドを使用して設定できます。

次の表に、クイックアクセスツールバー (QAT) コントロールに関連付けられているプロパティキーの一覧を示します。

プロパティキー	メモ
UI_PKEY_ItemsSource	IUIFramework::GetUICommandProperty をサポートします (IUIFramework::SetUICommandProperty はサポートされていません)。IUIFramework::GetUICommandProperty は、QAT 内のコマンドを表す IUICollection オブジェクトへのポインターを返します。各コマンドは、その Command ID によって識別されます。これは、 IUISimplePropertySet::GetValue メソッドを呼び出し、プロパティキー UI_PKEY_CommandIdを渡すことによって取得されます。

プロパティキー

メモ

UI_PKEY_ItemsSource

IUIFramework::GetUICommandProperty をサポートします (IUIFramework::SetUICommandProperty はサポートされていません)。IUIFramework::GetUICommandProperty は、QAT 内のコマンドを表す IUICollection オブジェクトへのポインターを返します。各コマンドは、その Command ID によって識別されます。これは、 IUISimplePropertySet::GetValue メソッドを呼び出し、プロパティキー UI_PKEY_CommandIdを渡すことによって取得されます。

クイックアクセスツールバー (QAT) ドロップダウンメニューの [ その他のコマンド ] コマンド項目に関連付けられているプロパティキーはありません

はじめに

マークアップ

コード

QAT 永続化

フィードバック

フィードバック

その他のリソース

クイック アクセス ツール バー

はじめに