リボン オブジェクト モデルの概要
更新 : 2008 年 7 月
対象 |
---|
このトピックの情報は、指定された Visual Studio Tools for Office プロジェクトおよび Microsoft Office のバージョンにのみ適用されます。 プロジェクトの種類
Microsoft Office のバージョン
詳細については、「アプリケーションおよびプロジェクトの種類別の使用可能な機能」を参照してください。 |
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 |
|
Button |
|
ButtonGroup |
|
CheckBox |
|
ComboBox |
|
DropDown |
|
EditBox |
|
Gallery |
|
Group |
|
Label |
|
Menu |
|
Separator |
|
SplitButton |
|
Tab |
|
ToggleButton |
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 内の選択された項目を取得する。 |
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 });
}
}
読み取り専用になるプロパティ
リボンが読み込まれる前にのみ設定できるプロパティを次の表に示します。
メモ : |
---|
SP1 をインストールすると、いつでも、動的メニューのコントロールのプロパティを設定できます。この場合、次の表の内容は該当しません。 |
プロパティ |
リボン コントロール クラス |
---|---|
BoxStyle |
|
ButtonType |
|
ColumnCount |
|
ControlId |
|
DialogLauncher |
|
Dynamic |
|
Global |
|
Groups |
|
ImageName |
|
ItemSize |
|
MaxLength |
|
Name |
|
Position |
|
RibbonType |
|
RowCount |
|
ShowItemImage |
|
ShowItemLabel |
|
ShowItemSelection |
|
SizeString |
|
StartFromScratch |
|
Tabs |
|
Title |
Outlook インスペクタに表示されるリボンのプロパティの設定
ユーザーがリボンを含むインスペクタを開くたびにリボンの新しいインスタンスが作成されます。ただし、上の表に示すプロパティは、リボンの最初のインスタンスが作成される前にのみ設定できます。最初のインスタンスが作成されると、そのインスタンスによって Outlook がリボンの読み込みに使用する XML ファイルを定義するため、これらのプロパティは読み取り専用になります。
リボンの他のインスタンスが作成されたときにこれらのプロパティを別の値に設定する条件ロジックがある場合、そのコードは何の効果ももたらしません。
メモ : |
---|
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 にエクスポートする
方法 : アドインのユーザー インターフェイス エラーを表示する
概念
参照
履歴の変更
日付 |
履歴 |
理由 |
---|---|---|
2008 年 7 月 |
SP1 のインストール後における動的メニューのコントロールのプロパティ設定に関する情報を改訂 |
SP1 機能変更 |