リボン パネルとコントロール
Revit は、カスタム リボン パネルとコントロールを統合する API ソリューションを提供します。これらの API は、IExternalApplication で使用されます。カスタム リボン パネルを[アドイン]タブ、[解析]タブ、または新しいカスタム リボン タブに追加することができます。
パネルには、大小両方のボタンが含まれます。単純なプッシュ ボタン、複数のコマンドを含むプルダウン ボタン、既定のアタッチされた押しボタンを持つプルダウン ボタンである分割ボタンのいずれかです。パネルには、ボタンに加えて、ラジオ グループ、コンボ ボックス、テキスト フィールドを含めることができます。パネルには、コマンドを論理グループに分けるのに役立つ垂直セパレータも含まれます。最後に、パネルには、パネルの下部をクリックしてアクセスするスライド コントロールも含まれます。
オートデスクによって使用される標準に準拠しているユーザ インタフェースの開発の詳細は、「リボンのガイドライン」(「API ユーザ インタフェース ガイドライン」のセクション)を参照してください。
新しいリボン タブを作成する
リボン パネルは[アドイン]タブまたは[解析]タブに追加できますが、新しいカスタム リボンタブに追加することもできます。このオプションは、必要な場合にのみ使用してください。標準的な Revit のリボン タブを引き続き表示させるために、カスタム リボン タブの数は 20 個に制限されています。次のイメージは、リボン パネル 1 つといくつかの簡単なコントロールのある新しいリボン タブです。
リボン タブの上に生成するコードを下に示します。
|
コード領域: 新しいリボン タブ |
publicResult OnStartup(UIControlledApplication application)
{
// Create a custom ribbon tab
String tabName = "This Tab Name";
application.CreateRibbonTab(tabName);
// Create two push buttons
PushButtonData button1 = newPushButtonData("Button1", "My Button #1",
@"C:\ExternalCommands.dll", "Revit.Test.Command1");
PushButtonData button2 = newPushButtonData("Button2", "My Button #2",
@"C:\ExternalCommands.dll", "Revit.Test.Command2");
// Create a ribbon panel
RibbonPanel m_projectPanel = application.CreateRibbonPanel(tabName, "This Panel Name");
// Add the buttons to the panel
List<RibbonItem> projectButtons = newList<RibbonItem>();
projectButtons.AddRange(m_projectPanel.AddStackedItems(button1, button2));
returnResult.Succeeded;
}
|
新しいリボン パネルとコントロールを作成する
次のイメージでは、さまざまなリボン パネルのコントロールを使用して、[アドイン]タブのリボン パネルを示します。次のセクションでは、これらのコントロールについて詳しく説明し、リボンの各部分を作成するためのコード サンプルを提供します。
図 14: 新しいリボン パネルとコントロール
次のコードは、上の図のリボン パネルを作成するための手順について説明します。このサンプルで呼び出される各関数は、この後のセクションのサンプルに提供されています。これらのサンプルは、D:¥ Sample¥HelloWorld¥bin¥Debug¥Hello にアセンブリがあることを前提としています。これには次の外部コマンド タイプが含まれます。
- Hello.HelloButton
- Hello.HelloOne
- Hello.HelloTwo
- Hello.HelloThree
- Hello.HelloA
- Hello.HelloB
- Hello.HelloC
- Hello.HelloRed
- Hello.HelloBlue
- Hello.HelloGreen
|
コード領域: リボン パネルとコントロール |
public Result OnStartup(Autodesk.Revit.UI.UIControlledApplication app)
{
RibbonPanel panel = app.CreateRibbonPanel("New Ribbon Panel");
AddRadioGroup(panel);
panel.AddSeparator();
AddPushButton(panel);
AddSplitButton(panel);
AddStackedButtons(panel);
AddSlideOut(panel);
return Result.Succeeded;
}
|
リボン パネル
カスタム リボンパネルは[アドイン]タブ(既定)または[解析]タブに追加したり、新しいカスタム リボンタブに追加することができます。次のセクションで詳しく説明するリボン パネルに追加できる、さまざまなタイプのリボン コントロールがあります。すべてのリボン コントロールには、いくつかの共通プロパティと機能があります。
リボン コントロールのクラス
各リボン コントロールには、これに関連付けられている 2 つのクラスがあります。 1 つはコントロール(SplitButtonData など)の作成に使用され、そのコントロールをリボン パネルに追加する RibbonItemData から作成したクラスで、もう 1 つは項目がパネルに追加された後に項目を表す RibbonItem (SplitButton など)から作成したクラスです。RibbonItemData (およびその作成元クラス)から使用可能なプロパティは、RibbonItem (およびそれに対応する作成元クラス)からも使用可能です。これらのプロパティは、コントロールをパネルに追加する前に設定したり、パネルに追加した後、RibbonItem クラスを使用して設定することができます。
ツールチップ
ほとんどのコントロールには、ユーザがコントロール上でマウスを移動したときに表示されるツールチップ セット([ツールチップ]プロパティを使用)があります。ユーザが長時間コントロールの上にマウスを置くと、拡張ツールチップが LongDescription と ToolTipImage プロパティを使用して表示されます。LongDescription と ToolTipImage のどちらも設定されていない場合、拡張ツールチップは表示されません。ツールチップが用意されている場合、コントロールのテキスト(RibbonItem.ItemText)は、マウスがコントロール上に移動すると表示されます。
図 15: 拡張ツールチップ
コンテキスト ヘルプ
コントロールには、コントロールに関連付けられたコンテキスト ヘルプがあります。ユーザがコントロールの上にマウスを置いて[F1]を押すと、コンテキスト ヘルプが起動されます。コンテキスト ヘルプオプションには、外部 URL へのリンク、ローカルにインストールされたヘルプ(CHM)ファイルの起動、Autodesk ヘルプ Wiki のトピックへのリンクが含まれます。ContextualHelp クラスを使用してコンテキスト ヘルプのタイプを作成し、その後で、RibbonItem.SetContextualHelp() (または RibbonItemData.SetContextualHelp())がコントロールに関連付けます。ContextualHelp インスタンスがコントロールと関連付けられている場合は、下図のようにマウスがコントロール上に置かれると「ヘルプを表示するには F1 キー」という文がツールチップの下に表示されます。
次の例では、新しい ContextualHelp をプッシュ ボタン コントロールと関連付けています。プッシュ ボタンの上にマウスカーソルを置いて[F1]を押すと、新しいブラウザ ウィンドウにオートデスクのホームページが表示されます。
|
コード領域: コンテキスト ヘルプ |
private void AddPushButton(RibbonPanel panel)
{
PushButton pushButton = panel.AddItem(new PushButtonData("HelloWorld",
"HelloWorld", @"D:\Sample\HelloWorld\bin\Debug\HelloWorld.dll", "HelloWorld.CsHelloWorld")) as PushButton;
// Set ToolTip and contextual help
pushButton.ToolTip = "Say Hello World";
ContextualHelp contextHelp = new ContextualHelp(ContextualHelpType.Url,
"http://www.autodesk.com");
pushButton.SetContextualHelp(contextHelp);
// Set the large image shown on button
pushButton.LargeImage =
new BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\39-Globe_32x32.png"));
}
|
ContextualHelp クラスには、この ContextualHelp オブジェクトのコンテンツによって指定されるヘルプ トピックを表示するためにいつでも呼び出すことのできる Launch()メソッドがあり、コントロールがアクティブな場合に[F1]キーを押した場合と同じ働きをします。これにより、アドイン アプリケーションによって作成されたダイアログ内のユーザ インタフェース コンポーネントとヘルプ トピックの関連付けが可能になります。
コントロールを使用してイメージを関連付ける
すべてのこれらのコントロールには、LargeImage プロパティを使用して、これらに関連付けられたイメージを持たせることができます。スタックされていないリボンやドロップダウン ボタンなど、大きなコントロールに関連付けられたイメージの最適なサイズは 32 x 32 ピクセルですが、大きいイメージは、ボタンにフィットするように調整されます。スタックされたボタンとテキスト ボックスやコンボ ボックスなどの小さなコントロールは 16 × 16 ピクセルのイメージを設定している必要があります。大きなボタンもイメージプロパティに 16 × 16 ピクセルのイメージを設定する必要があります。このイメージは、コマンドをクイック アクセス ツールバーに移動した場合に使用されます。Image プロパティを設定していない場合は、コマンドをクイック アクセス ツールバーに移動してもイメージは表示されません。イメージが 16 × 16 ピクセルより大きい場合は、ツールバーにフィットするように調整されないことに注意してください。
提供されている場合、ToolTipImage が拡張ツールチップの LongDescription の下に表示されます。このイメージに推奨されるサイズはありません。
リボン コントロールの可用性
リボン コントロールを RibbonItem.Enabled プロパティで有効または無効にしたり、RibbonItem.Visible プロパティで表示または非表示にすることができます。
リボン コントロール
次のコントロールに加えて、垂直セパレータをリボン パネルに追加して、関連するコントロール セットをグループ化することができます。
プッシュ ボタン
パネルに追加できるボタンには、3 つのタイプがあります。簡単なプッシュ ボタン、ドロップ ダウン ボタン、分割ボタンです。HelloWorld ボタン(図 14)はプッシュ ボタンです。ボタンを押すと、対応するコマンドがトリガされます。
Enabled プロパティに加えて、PushButton には、コマンドが使用できる場合にコントロールする IExternalCommandAvailability インタフェースの名前の設定に使用できる AvailabilityClassName プロパティがあります。
|
コード領域: プッシュ ボタンを追加 |
private void AddPushButton(RibbonPanel panel)
{
PushButton pushButton = panel.AddItem(new PushButtonData("HelloWorld",
"HelloWorld", @"D:\HelloWorld.dll", "HelloWorld.CsHelloWorld")) as PushButton;
pushButton.ToolTip = "Say Hello World";
// Set the large image shown on button
pushButton.LargeImage =
new BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\39-Globe_32x32.png"));
}
|
ドロップダウン ボタン
ドロップダウン ボタンを拡張して、ドロップダウン メニューに複数のコマンドを表示します。Revit API では、ドロップ ダウンボタンは PulldownButtons と呼ばれます。水平セパレータをドロップダウン メニューの項目の間に追加することができます。
ドロップダウン メニューの各コマンドは、上記の例で示すように関連付けられている LargeImage を持つことができます。
分割ボタン
分割ボタンは、既定のボタンがアタッチされたドロップダウン ボタンです。ボタンの上半分はプッシュ ボタン、下半分の関数はドロップダウン ボタンと同様に機能します。[オプション 1]ボタン(図 14)は分割ボタンです。
最初に、プッシュ ボタンはドロップダウン リストの先頭の項目になります。ただし、IsSynchronizedWithCurrentItem プロパティを使用して、既定のコマンド(分割ボタンの上半分にプッシュ ボタンとして表示される)を最後に使用したコマンドと同期できます。既定では、同期されます。分割ボタンの[オプション 2]を上の図 14 から選択します。
図 16: 現在の項目と同期した分割ボタン
SplitButton の ToolTip、ToolTipImage、LongDescription プロパティは無視されることに注意してください。代わりに現在のプッシュ ボタンのツールチップが表示されます。
|
コード領域: 分割ボタンを追加 |
private void AddSplitButton(RibbonPanel panel)
{
string assembly = @"D:\Sample\HelloWorld\bin\Debug\Hello.dll";
// create push buttons for split button drop down
PushButtonData bOne = new PushButtonData("ButtonNameA", "Option One",
assembly, "Hello.HelloOne");
bOne.LargeImage =
new BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\One.bmp"));
PushButtonData bTwo = new PushButtonData("ButtonNameB", "Option Two",
assembly, "Hello.HelloTwo");
bTwo.LargeImage =
new BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\Two.bmp"));
PushButtonData bThree = new PushButtonData("ButtonNameC", "Option Three",
assembly, "Hello.HelloThree");
bThree.LargeImage =
new BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\Three.bmp"));
SplitButtonData sb1 = new SplitButtonData("splitButton1", "Split");
SplitButton sb = panel.AddItem(sb1) as SplitButton;
sb.AddPushButton(bOne);
sb.AddPushButton(bTwo);
sb.AddPushButton(bThree);
}
|
ラジオ ボタン
ラジオ ボタン グループは相互に排他的な切替ボタンのセットで、一度に 1 つだけ選択できます。RadioButtonGroup をパネルに追加した後、AddItem()または AddItems()メソッドを使用して、切替ボタンをグループに追加します。切替ボタンはプッシュ ボタンから作成しています。RadioButtonGroup.Current プロパティを使用して、現在選択されているボタンにアクセスすることができます。
ツールチップはラジオ ボタン グループに適用されないことに注意してください。代わりに、各切替ボタンのツールチップは、マウスが各ボタンの上に移動すると表示されます。
|
コード領域: ラジオ ボタン グループを追加 |
private void AddRadioGroup(RibbonPanel panel)
{
// add radio button group
RadioButtonGroupData radioData = new RadioButtonGroupData("radioGroup");
RadioButtonGroup radioButtonGroup = panel.AddItem(radioData) as RadioButtonGroup;
// create toggle buttons and add to radio button group
ToggleButtonData tb1 = new ToggleButtonData("toggleButton1", "Red");
tb1.ToolTip = "Red Option";
tb1.LargeImage = new BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\Red.bmp"));
ToggleButtonData tb2 = new ToggleButtonData("toggleButton2", "Green");
tb2.ToolTip = "Green Option";
tb2.LargeImage = new BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\Green.bmp"));
ToggleButtonData tb3 = new ToggleButtonData("toggleButton3", "Blue");
tb3.ToolTip = "Blue Option";
tb3.LargeImage = new BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\Blue.bmp"));
radioButtonGroup.AddItem(tb1);
radioButtonGroup.AddItem(tb2);
radioButtonGroup.AddItem(tb3);
}
|
テキスト ボックス
テキスト ボックスは、ユーザがテキストを入力するための入力コントロールです。テキスト ボックスのイメージを使用して、ShowImageAsButton プロパティを true に設定することで、クリック可能なボタンとして使用することができます。既定は false です。ShowImageAsButton が false の場合は、イメージテキスト ボックスの左に表示され、ボタンのように動作する場合は、テキスト ボックスの右側に表示されます(図 14)。
テキスト ボックスに入力したテキストは、ユーザが[Enter]キーを押した場合や、イメージがボタンとして表示される場合に、関連付けられたイメージをクリックした場合にのみ受け入れられます。それ以外の場合は、テキストは前の値に戻ります。
テキスト ボックスへのツールチップの提供に加え、PromptText プロパティを使用して、テキストボックスに入力する情報のタイプをユーザに示すことができます。プロンプト文字列は、テキスト ボックスが空で、キーボード フォーカスがない場合に表示されます。この文字列は斜体で表示されます。次のテキスト ボックス(図 14)には、「Enter a comment」というプロンプト文字列があります。
Width プロパティを使用してテキスト ボックスの幅を設定できます。既定はデバイスに依存しない 200 単位です。
TextBox.EnterPressed イベントは、ユーザが[Enter]を押した場合、または ShowImageAsButton を true に設定してテキスト ボックスに関連付けられたイメージをクリックした場合にトリガされます。EnterPressed イベント ハンドラを実装する場合は、sender オブジェクトを TextBox にキャストして、次の例に示すようにユーザが入力した値を取得します。
|
コード領域: TextBox.EnterPressed イベント ハンドラ |
void ProcessText(object sender, Autodesk.Revit.UI.Events.TextBoxEnterPressedEventArgs args)
{
// cast sender as TextBox to retrieve text value
TextBox textBox = sender as TextBox;
string strText = textBox.Value as string;
}
|
継承された ItemText プロパティには、TextBox の効果はありません。ユーザが入力したテキストを Value プロパティから取得できます。これは文字列に変換する必要があります。
上記のイベントの追加方法など、TextBox をリボン パネルに追加する例については、スタック リボン 項目のセクションを参照してください。
コンボ ボックス
コンボ ボックスは、選択可能な項目セットを持つプルダウンです。ComboBox をパネルに追加した後、AddItem()または AddItems()メソッドを使用して、ComboBoxMembers をリストに追加します。
セパレータはリストの個別の項目に追加する、またはオプションで、メンバーを ComboBoxMember.GroupName プロパティを使用してグループ化することもできます。同じ GroupName を持つすべてのメンバーは、グループ名が表示されている見出しとともにグループ化されます。GroupName に割り当てられていない項目は、リストの上部に配置されます。項目をグループ化する場合は、セパレータは追加された順番ではなくグループの最後に配置されるため、使用しないよう注意してください。
図 17: グループ化されたコンボ ボックス
ComboBox には 3 つのイベントがあります。
- CurrentChanged - ComboBox の現在の項目が変更された場合にトリガされます
- DropDownClosed - ComboBox のドロップダウン リストを閉じたときにトリガされます
- DropDownClosed - ComboBox のドロップダウン リストを開いたときにトリガされます
ComboBox をリボン パネルに追加するサンプルについては、次のスタック リボン項目のセクションのコード領域を参照してください。
スタックされたパネル項目
パネル スペースを節約するために、2 つまたは 3 つのスタックの小さなパネル項目を追加することができます。スタックの各項目には、プッシュ ボタン、ドロップダウン ボタン、コンボ ボックス、またはテキスト ボックスを使用することができます。ラジオ ボタングループと分割ボタンはスタックすることができません。スタックされたボタンには、LargeImage ではなく、Image プロパティから関連付けられたイメージが必要です。小さなスタック ボタンには、16 x 16 のイメージが理想的です。
次の例では、スタックされたテキスト ボックスおよびコンボ ボックスの手順を示します(図 14)。
|
コード領域: スタック項目としてテキスト ボックスおよびコンボ ボックスを追加 |
private void AddStackedButtons(RibbonPanel panel)
{
ComboBoxData cbData = new ComboBoxData("comboBox");
TextBoxData textData = new TextBoxData("Text Box");
textData.Image =
new BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\39-Globe_16x16.png"));
textData.Name = "Text Box";
textData.ToolTip = "Enter some text here";
textData.LongDescription = "This is text that will appear next to the image"
+ "when the user hovers the mouse over the control";
textData.ToolTipImage =
new BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\39-Globe_32x32.png"));
IList<RibbonItem> stackedItems = panel.AddStackedItems(textData, cbData);
if (stackedItems.Count > 1)
{
TextBox tBox = stackedItems[0] as TextBox;
if (tBox != null)
{
tBox.PromptText = "Enter a comment";
tBox.ShowImageAsButton = true;
tBox.ToolTip = "Enter some text";
// Register event handler ProcessText
tBox.EnterPressed +=
new EventHandler<Autodesk.Revit.UI.Events.TextBoxEnterPressedEventArgs>(ProcessText);
}
ComboBox cBox = stackedItems[1] as ComboBox;
if (cBox != null)
{
cBox.ItemText = "ComboBox";
cBox.ToolTip = "Select an Option";
cBox.LongDescription = "Select a number or letter";
ComboBoxMemberData cboxMemDataA = new ComboBoxMemberData("A", "Option A");
cboxMemDataA.Image =
new BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\A.bmp"));
cboxMemDataA.GroupName = "Letters";
cBox.AddItem(cboxMemDataA);
ComboBoxMemberData cboxMemDataB = new ComboBoxMemberData("B", "Option B");
cboxMemDataB.Image =
new BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\B.bmp"));
cboxMemDataB.GroupName = "Letters";
cBox.AddItem(cboxMemDataB);
ComboBoxMemberData cboxMemData = new ComboBoxMemberData("One", "Option 1");
cboxMemData.Image =
new BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\One.bmp"));
cboxMemData.GroupName = "Numbers";
cBox.AddItem(cboxMemData);
ComboBoxMemberData cboxMemData2 = new ComboBoxMemberData("Two", "Option 2");
cboxMemData2.Image =
new BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\Two.bmp"));
cboxMemData2.GroupName = "Numbers";
cBox.AddItem(cboxMemData2);
ComboBoxMemberData cboxMemData3 = new ComboBoxMemberData("Three", "Option 3");
cboxMemData3.Image =
new BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\Three.bmp"));
cboxMemData3.GroupName = "Numbers";
cBox.AddItem(cboxMemData3);
}
}
}
|
スライド パネル
RibbonPanel.AddSlideOut()メソッドを使用して、リボン パネルの下部にスライドを追加します。スライドを追加したときに、矢印がパネルの下部に表示され、これをクリックするとスライドが表示されます。AddSlideOut()を呼び出した後、パネルに新しい項目を追加する次の呼び出しをスライドに追加するため、スライドは他のすべてのコントロールがリボン パネルに追加された後に追加する必要があります。
図 18: スライド
次の例では、上記のスライドの手順を示します。
|
コード領域: TextBox.EnterPressed イベント ハンドラ |
private static void AddSlideOut(RibbonPanel panel)
{
string assembly = @"D:\Sample\HelloWorld\bin\Debug\Hello.dll";
panel.AddSlideOut();
// create some controls for the slide out
PushButtonData b1 = new PushButtonData("ButtonName1", "Button 1",
assembly, "Hello.HelloButton");
b1.LargeImage =
new BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\39-Globe_32x32.png"));
PushButtonData b2 = new PushButtonData("ButtonName2", "Button 2",
assembly, "Hello.HelloTwo");
b2.LargeImage =
new BitmapImage(new Uri(@"D:\Sample\HelloWorld\bin\Debug\39-Globe_16x16.png"));
// items added after call to AddSlideOut() are added to slide-out automatically
panel.AddItem(b1);
panel.AddItem(b2);
}
|