次の方法で共有

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

  • [アーティクル]

更新 : 2008 年 7 月

対象

このトピックの情報は、指定された Visual Studio Tools for Office プロジェクトおよび Microsoft Office のバージョンにのみ適用されます。

プロジェクトの種類

  • ドキュメント レベルのプロジェクト

  • アプリケーション レベルのプロジェクト

Microsoft Office のバージョン

  • Excel 2007

  • Word 2007

  • Outlook 2007

  • PowerPoint 2007

詳細については、「アプリケーションおよびプロジェクトの種類別の使用可能な機能」を参照してください。

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

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

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

リボン クラス

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

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

リボン イベント

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

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

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

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

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

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

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

コントロール名

クラス名

Box

RibbonBox

Button

RibbonButton

ButtonGroup

RibbonButtonGroup

CheckBox

RibbonCheckBox

ComboBox

RibbonComboBox

DropDown

RibbonDropDown

EditBox

RibbonEditBox

Gallery

RibbonGallery

Group

RibbonGroup

Label

RibbonLabel

Menu

RibbonMenu

Separator

RibbonSeparator

SplitButton

RibbonSplitButton

Tab

RibbonTab

ToggleButton

RibbonToggleButton

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

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

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

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

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

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

タスク :

方法 :

コントロールの表示/非表示を切り替える。

Visible プロパティを使用します。

コントロールを有効または無効にする。

Enabled プロパティを使用します。

コントロールのサイズを設定する。

ControlSize プロパティを使用します。

コントロールに表示するイメージを取得する。

Image プロパティを使用します。

コントロールのラベルを変更する。

Label プロパティを使用します。

ユーザー定義のデータをコントロールに追加する。

Tag プロパティを使用します。

RibbonBox、RibbonDropDown、RibbonGallery、

RibbonSplitButton のいずれかのコントロールの項目を取得する。

Items プロパティを使用します。

RibbonComboBox、RibbonDropDown、RibbonGallery のいずれかのコントロールに項目を追加する。

Items プロパティを使用します。

RibbonMenu にコントロールを追加する。

Items プロパティを使用します。

リボンが Office アプリケーションに読み込まれた後で RibbonMenu にコントロールを追加する場合は、リボンが Office アプリケーションに読み込まれる前に Dynamic プロパティを true に設定する必要があります。詳細については、「読み取り専用になるプロパティの設定」を参照してください。

RibbonComboBox 内の選択された項目を取得する。

RibbonDropDown または RibbonGallery

SelectedItem プロパティを使用します。RibbonComboBox では、Text プロパティを使用します。

RibbonTab 上のグループを取得する。

Groups プロパティを使用します。

RibbonGallery に表示する行および列の数を指定する。

RowCount プロパティおよび ColumnCount プロパティを使用します。

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

リボンが読み込まれる前にのみ設定できるプロパティがあります。それらのプロパティは次の 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 });
    }
}

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

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

Bb608623.alert_note(ja-jp,VS.90).gifメモ :

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

プロパティ

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

BoxStyle

RibbonBox

ButtonType

RibbonSplitButton

ColumnCount

RibbonGallery

ControlId

RibbonTab

DialogLauncher

RibbonGroup

Dynamic

RibbonMenu

Global

OfficeRibbon

Groups

RibbonTab

ImageName

RibbonButton

RibbonComboBox

RibbonDialogLauncher

RibbonDropDown

RibbonEditBox

RibbonGallery

RibbonMenu

RibbonSplitButton

RibbonToggleButton

ItemSize

RibbonMenu

RibbonSplitButton

MaxLength

RibbonComboBox

RibbonEditBox

Name

RibbonComponent

Position

RibbonButton

RibbonCheckBox

RibbonGallery

RibbonGroup

RibbonMenu

RibbonSeparator

RibbonSplitButton

RibbonTab

RibbonToggleButton

RibbonType

OfficeRibbon

RowCount

RibbonGallery

ShowItemImage

RibbonComboBox

RibbonDropDown

RibbonGallery

ShowItemLabel

RibbonDropDown

RibbonGallery

ShowItemSelection

RibbonGallery

SizeString

RibbonComboBox

RibbonDropDown

RibbonEditBox

StartFromScratch

OfficeRibbon

Tabs

OfficeRibbon

Title

RibbonSeparator

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

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

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

Bb608623.alert_note(ja-jp,VS.90).gifメモ :

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

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

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

イベント

説明

Click

コントロールがクリックされたときに発生します。

TextChanged

編集ボックスまたはコンボ ボックス内のテキストが変更されたときに発生します。

ItemsLoading

コントロールの Items コレクションが Office から要求されたときに発生します。Office は、コードがコントロールのプロパティを変更するか、Microsoft.Office.Core.IRibbonUI.InvalidateControl メソッドが呼び出されるまで、Items コレクションをキャッシュします。

ButtonClick

RibbonGallery または RibbonDropDown 内のボタンがクリックされたときに発生します。

SelectionChanged

RibbonDropDown または RibbonGallery 内の選択項目が変更されたときに発生します。

DialogLauncherClick

グループの右下にあるダイアログ ランチャー アイコンがクリックされたときに発生します。

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

パラメータ

説明

sender

イベントを発生させたコントロールを表す Object。

e

Microsoft.Office.Core.IRibbonControl が格納された RibbonControlEventArgs。このコントロールを使用すると、Visual Studio Tools for Office リボン オブジェクト モデルには用意されていないプロパティにアクセスできます。

参照

処理手順

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

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

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

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

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

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

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

概念

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

リボンの概要

リボン デザイナ

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

参照

Microsoft.Office.Tools.Ribbon

履歴の変更

日付

履歴

理由

2008 年 7 月

SP1 のインストール後における動的メニューのコントロールのプロパティ設定に関する情報を改訂

SP1 機能変更