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

[アーティクル]
07/22/2024

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

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

はじめに

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

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

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

Note

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

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

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

マークアップ

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

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

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

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

[その他のコマンド] コマンド項目のある QAT メニューのスクリーンショット。

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

クイックアクセスツールバー (QAT) のツールバー内にあるアプリケーション既定値の一覧からコマンドを表示するには、各コントロール要素の ApplicationDefaults.IsChecked 属性の値が true である必要があります。上の図には、Save コマンド、Undo コマンド、および Redo コマンドのこの属性を true に設定した結果を示しています。

QuickAccessToolbar.ApplicationDefaults では、Button、Toggle Button、およびCheck Box の 3 種類のリボンコントロールがサポートされます。

Note

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) に追加することはできません。

Note

リボンアプリケーションでは、クイックアクセスツールバー (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 メソッドの呼び出しを介して、コントロールに関連付けられているコマンドを無効にします。 IUICommandHandler::UpdateProperty コールバックメソッドによって、無効化イベントは処理され、プロパティは更新されます。

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

Note

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

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

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

プロパティキー

メモ

UI_PKEY_ItemsSource

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

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

次の方法で共有

はじめに

マークアップ

コード

QAT の永続化

フィードバック

その他のリソース

次の方法で共有

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

はじめに