リボン オブジェクト モデルの概要

更新 : 2008 年 7 月

Visual Studio Tools for Office が公開する厳密に型指定されたオブジェクト モデルを使用して、実行時にリボン コントロールのプロパティを取得および設定できます。たとえば、メニュー コントロールを動的に設定したり、コントロールの表示/非表示をコンテキストに応じて切り替えたりすることができます。

また、Office アプリケーションがリボンを読み込む前であれば、タブ、グループ、およびコントロールをリボンに追加することもできます。詳細については、「読み取り専用になるプロパティの設定」を参照してください。

このリボン オブジェクト モデルの主要な要素は、リボン クラス、リボン イベント、およびリボン コントロール クラスです。

リボン クラス

新しいリボン (ビジュアル デザイナ) 項目をプロジェクトに追加すると、Visual Studio Tools for Office によって、OfficeRibbon クラスを継承するクラスがプロジェクトに追加されます。

このクラスは、リボン コード ファイルとリボン デザイナ コード ファイルを分割する部分クラスとして位置付けられます。

リボン イベント

OfficeRibbon クラスには、次の 3 つのイベントが含まれています。

• Load

• LoadImage

• Close

Load イベントは、Office アプリケーションがリボンのカスタマイズを読み込んだときに発生します。Load イベント ハンドラがリボン コード ファイルに自動的に追加されます。このイベント ハンドラを使用して、リボン ツールが読み込まれるときにカスタム コードを実行します。

LoadImage イベントにより、リボンが読み込まれたときに、リボンのカスタマイズ内のイメージをキャッシュできます。これにより、リボンのイメージをこのイベント ハンドラにキャッシュするコードを作成する場合に、パフォーマンスを多少向上させることができます。詳細については、「LoadImage」を参照してください。

Close イベントは、リボンのインスタンスを閉じたときに発生します。

リボン コントロール クラス

Microsoft.Office.Tools.Ribbon 名前空間には、[ツールボックス] の [Office リボン コントロール] グループに表示される各コントロールのリボン クラスが含まれています。

各リボン コントロールのクラスを次の表に示します。各コントロールの詳細については、「リボンの概要」を参照してください。

Microsoft.Office.Tools.Ribbon 名前空間では、System.Windows.Forms 名前空間に属するコントロール クラスとの名前の衝突を回避するために、クラス名にプレフィックス "Ribbon" が追加されています。

リボン デザイナにコントロールを追加すると、そのコントロールのクラスがリボン デザイナ コード ファイルにフィールドとして宣言されます。

リボン コントロール クラスのプロパティを使用する一般的なタスク

各リボン コントロール クラスには、コントロールへのラベルの追加やコントロールの表示/非表示の切り替えなど、さまざまなタスクの実行に使用できるプロパティが含まれています。

リボンが読み込まれた後、またはコントロールが動的メニューに追加された後で、プロパティが読み取り専用になることがあります。詳細については、「読み取り専用になるプロパティの設定」を参照してください。

リボン コントロールのプロパティを使用して実行できる一部のタスクについて、次の表で説明します。

読み取り専用になるプロパティの設定

リボンが読み込まれる前にのみ設定できるプロパティがあります。それらのプロパティは次の 3 つの方法で設定できます。

• Visual Studio の [プロパティ] ウィンドウ

• リボン クラスのコンストラクタ

• プロジェクトの ThisAddin クラスの CreateRibbonExtensibilityObject メソッド

動的メニューにはいくつかの例外があります。メニューを含むリボンが読み込まれた後であっても、新しいコントロールを作成し、それらのプロパティを設定し、それらのコントロールを実行時に動的メニューに追加できます。

Visual Studio 2008 Service Pack 1 (SP1) 以降、動的メニューに追加するコントロールのプロパティはいつでも設定できます。ただし、SP1 をインストールしていないと、これらのプロパティには、コントロールがメニューに追加された後で読み取り専用になるものがあります。

詳細については、「読み取り専用になるプロパティ」を参照してください。

リボンのコンストラクタでのプロパティの設定

リボン コントロールのプロパティをリボン クラスのコンストラクタで設定できます。このコードは、InitializeComponent メソッドの呼び出しの後に置く必要があります。次のコード例は、現在の時刻が太平洋標準時間 (UTC-8) の 17:00 以降である場合に、新しいボタンをグループに追加します。

<System.Diagnostics.DebuggerNonUserCode()> _
Public Sub New()
    MyBase.New()

    'This call is required by the Component Designer.
    InitializeComponent()
    If DateTime.Now.Hour > 16 Then
        Group1.Items.Add(New RibbonButton())
        CType(Group1.Items.Last(), RibbonButton).Label = "New Button"
    End If
End Sub

public Ribbon1()
{
    InitializeComponent();
    if (DateTime.Now.Hour > 16)
    {
        group1.Items.Add(new RibbonButton());
        ((RibbonButton)group1.Items.Last()).Label = "New Button";
    }

}

CreateRibbonExtensibilityObject メソッドでのプロパティの設定

プロジェクトの ThisAddin、ThisWorkbook、ThisDocument のいずれかのクラスの CreateRibbonExtensibilityObject メソッドをオーバーライドするときに、リボン コントロールのプロパティを設定できます。CreateRibbonExtensibilityObject メソッドの詳細については、リボンの概要 を参照してください。

次のコード例は、Excel 2007 ブック プロジェクトの ThisWorkbook クラスの CreateRibbonExtensibilityObject メソッドでリボンのプロパティを設定します。

Protected Overrides Function CreateRibbonExtensibilityObject() _
    As Microsoft.Office.Core.IRibbonExtensibility
    Dim myCondition As Boolean = True
    If myCondition = True Then
        Dim tempRibbon As New Ribbon1()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabHome"
        Return New Microsoft.Office.Tools.Ribbon.RibbonManager _
            (New Microsoft.Office.Tools.Ribbon.OfficeRibbon() {tempRibbon})
    Else
        Dim tempRibbon As New Ribbon2()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabInsert"
        Return New Microsoft.Office.Tools.Ribbon.RibbonManager _
            (New Microsoft.Office.Tools.Ribbon.OfficeRibbon() {tempRibbon})
    End If
End Function

protected override Microsoft.Office.Core.IRibbonExtensibility
    CreateRibbonExtensibilityObject()
{
    bool myCondition = true;
    if (myCondition == true)
    {
        Ribbon1 tempRibbon = new Ribbon1();
        tempRibbon.tab1.ControlId.ControlIdType = 
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabHome";
        return new Microsoft.Office.Tools.Ribbon.RibbonManager(
            new Microsoft.Office.Tools.Ribbon.OfficeRibbon[] 
                { tempRibbon });
    }
    else
    {
        Ribbon2 tempRibbon = new Ribbon2();
        tempRibbon.tab1.ControlId.ControlIdType = 
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabInsert";
        return new Microsoft.Office.Tools.Ribbon.RibbonManager(
            new Microsoft.Office.Tools.Ribbon.OfficeRibbon[] 
                { tempRibbon });
    }
}

読み取り専用になるプロパティ

リボンが読み込まれる前にのみ設定できるプロパティを次の表に示します。

メモ :
SP1 をインストールすると、いつでも、動的メニューのコントロールのプロパティを設定できます。この場合、次の表の内容は該当しません。

Outlook インスペクタに表示されるリボンのプロパティの設定

ユーザーがリボンを含むインスペクタを開くたびにリボンの新しいインスタンスが作成されます。ただし、上の表に示すプロパティは、リボンの最初のインスタンスが作成される前にのみ設定できます。最初のインスタンスが作成されると、そのインスタンスによって Outlook がリボンの読み込みに使用する XML ファイルを定義するため、これらのプロパティは読み取り専用になります。

リボンの他のインスタンスが作成されたときにこれらのプロパティを別の値に設定する条件ロジックがある場合、そのコードは何の効果ももたらしません。

メモ :
Outlook リボンに追加した各コントロールで Name プロパティが設定されるようにしてください。実行時にコントロールを Outlook リボンに追加する場合は、このプロパティをコードで設定する必要があります。デザイン時にコントロールを Outlook リボンに追加する場合は、Name プロパティが自動的に設定されます。

リボン コントロール イベント

各コントロール クラスに 1 つ以上のイベントが含まれています。次の表は、それらのイベントについての説明です。

これらのイベントのイベント ハンドラには、次の 2 つのパラメータがあります。

参照

処理手順

方法 : リボンのカスタマイズの概要

チュートリアル : リボン デザイナを使用したカスタム タブの作成

チュートリアル : 実行時のリボン コントロールの更新

方法 : 組み込みタブをカスタマイズする

方法 : Microsoft Office メニューをカスタマイズする

方法 : リボンをリボン デザイナからリボン XML にエクスポートする

方法 : アドインのユーザー インターフェイス エラーを表示する

概念

実行時のリボンへのアクセス

リボンの概要

リボン デザイナ

Outlook のリボンのカスタマイズ

参照

Microsoft.Office.Tools.Ribbon

履歴の変更