Ribbon of Revit API – 5: Stacked Group and AddStackedItems - RevitNetAddinWizard & NavisworksNetAddinWizard

Ok, let’s talk about Stacked Button Group and the AddStackedItems method of the Revit Ribbon API in this post.

It is nothing magic about the stacked button group and it is just a container to stack some buttons together. They stay one above another as can be imagined. In fact, there is actually not such as Stacked Button Group thing in the Revit Ribbon API since it does not have a counterpart class. I made it up to make the discussions here easier. At least we need to call this kind of button behaviour something.

There are some limitations though. That is, it can only hold two or three items; cannot be less such as one and cannot be more such as four. So if we only have a TextBox or ComboBox at present for example, we have to wait for a while for it to become a pair at least so as to put it into a stacked button group.

And it only supports four kinds of button types, PulldownButton, PushButton, ComboBox, and TextBox. It may not make sense for the stacked button group to support RadioButtonGroup or ToggleButton instances as they are apparently too big, or to support separators as they do not really mean anything. However, since it supports PulldownButton it does not seem natural that it does not support SplitButton as they are almost the same animals except for a bit difference in appearance and behaviour as we discussed earlier.

The count limitation of the stacked buttons is imposed by the two different signatures of the method AddStackedItems(), one of which accepts two button item arguments and the other three. As mentioned above, the method does not really return a class representing the stacked button group; instead, it returns a RibbonItem Collection (IList actually). So we have to get the button instance back after its data is added to the group so as to feed something more to it, and this is very common since the button data does not hold all necessary information for the button though the data and button have some duplicate properties sometimes such as Image and Tooltip.
The two and only two signatures can prevent something like one item is provided or more than three are provided from happening. So it seems better than a single signature which accepts a list argument, but it surely makes the work of automatic code generation tougher. It is not a big deal. The RevitAddinWizard can handle it nicely.

People may raise a lof of other questions regarding stacked button group, just name a few below:

Why not to give out some control such as setting margins and alignments for those stacked buttons?
How could we find out what stacked button groups are in the panel of interest and in turn what buttons are in each group some time later on?
Why does not the method accept button arguments since the stacked button group is a button container rather than a data container?

Here is some code to create a couple of stacked button groups the first of which contains two PushButtons and a PulldownButton and the second of which has one ComboBox and one TextBox:

        private void AddStackedButtonGroups(RibbonPanel panel)
        {
            string assemFullName = Assembly.GetExecutingAssembly().Location;
            string assemPath = Path.GetDirectoryName(assemFullName);

            // Two PushButton data
            PushButtonData itemData1 = new PushButtonData("itemName1", "Command 1", AssemblyFullName, "RevitAddinCSProject.ExtCmd1");
            itemData1.ToolTip = itemData1.Text; // Can be changed to a more descriptive text.
            itemData1.Image = BmpImageSource("RevitAddinCSProject.Resources.Embedded_Item1_16x16.bmp");
            itemData1.LargeImage = BmpImageSource("RevitAddinCSProject.Resources.Embedded_Item1_32x32.bmp");

            PushButtonData itemData2 = new PushButtonData("itemName2", "Command 2", AssemblyFullName, "RevitAddinCSProject.ExtCmd2");
            itemData2.ToolTip = itemData2.Text; // Can be changed to a more descriptive text.
            itemData2.Image = new BitmapImage(new Uri(Path.Combine(AssemblyPath, "Standalone_Item1_16x16.bmp"), UriKind.Absolute));
            itemData2.LargeImage = new BitmapImage(new Uri(Path.Combine(AssemblyPath, "Standalone_Item1_32x32.bmp"), UriKind.Absolute));

            // A PulldownButton data
            PulldownButtonData group1Data = new PulldownButtonData("PulldownGroup1", "Pulldown Group 1");
            group1Data.ToolTip = group1Data.Text;
            group1Data.Image = BmpImageSource("RevitAddinCSProject.Resources.Embedded_Item1_16x16.bmp");
            group1Data.LargeImage = BmpImageSource("RevitAddinCSProject.Resources.Embedded_Item1_32x32.bmp");

            // Add the two PushButton data and the one PulldownButton data into a statcked button group.
            IList<RibbonItem> stackedGroup1 = panel.AddStackedItems(itemData1, itemData2, group1Data);

// Get back the Pulldown group and add buttons to it.
PulldownButton group1 = stackedGroup1[2] as PulldownButton;

            PushButtonData itemData11 = new PushButtonData("itemName11", "Command 11", AssemblyFullName, "RevitAddinCSProject.ExtCmd1");
            PushButton item11 = group1.AddPushButton(itemData11) as PushButton;
            item11.ToolTip = itemData11.Text; // Can be changed to a more descriptive text.
            item11.Image = BmpImageSource("RevitAddinCSProject.Resources.Embedded_Item1_16x16.bmp");
            item11.LargeImage = BmpImageSource("RevitAddinCSProject.Resources.Embedded_Item1_32x32.bmp");

            PushButtonData itemData12 = new PushButtonData("itemName12", "Command 12", AssemblyFullName, "RevitAddinCSProject.ExtCmd2");
            PushButton item12 = group1.AddPushButton(itemData12) as PushButton;
            item12.ToolTip = itemData12.Text; // Can be changed to a more descriptive text.
            item12.Image = BmpImageSource("RevitAddinCSProject.Resources.Embedded_Item2_16x16.bmp");
            item12.LargeImage = BmpImageSource("RevitAddinCSProject.Resources.Embedded_Item2_32x32.bmp");

group1.AddSeparator();

            PushButtonData itemData13 = new PushButtonData("itemName13", "Command 13", AssemblyFullName, "RevitAddinCSProject.ExtCmd3");
            PushButton item13 = group1.AddPushButton(itemData13) as PushButton;
            item13.ToolTip = itemData13.Text; // Can be changed to a more descriptive text.
            item13.Image = new BitmapImage(new Uri(Path.Combine(AssemblyPath, "Standalone_Item1_16x16.bmp"), UriKind.Absolute));
            item13.LargeImage = new BitmapImage(new Uri(Path.Combine(AssemblyPath, "Standalone_Item1_32x32.bmp"), UriKind.Absolute));

            // Create one ComboBox data
            ComboBoxData cbData1 = new ComboBoxData("Combo1");

            // Create one TextBox data
            TextBoxData tbData1 = new TextBoxData("itemName3");
            tbData1.Image = BmpImageSource("RevitAddinCSProject.Resources.Embedded_Item2_16x16.bmp");
            tbData1.ToolTip = tbData1.Name; // Can be changed to a more descriptive text.

// Add the ComboBox data and the TextBox data into a second statcked button group.
IList<RibbonItem> stackedGroup2 = panel.AddStackedItems(cbData1, tbData1);

Autodesk.Revit.UI.ComboBox combo1 = stackedGroup2[0] as Autodesk.Revit.UI.ComboBox;

            ComboBoxMemberData cb1MemData1 = new ComboBoxMemberData("com1Mem1", "Combo1 item 1");
            ComboBoxMember cb1Mem1 = combo1.AddItem(cb1MemData1);
            cb1Mem1.Image = BmpImageSource("RevitAddinCSProject.Resources.Embedded_Item1_16x16.bmp");

            ComboBoxMemberData cb1MemData2 = new ComboBoxMemberData("com1Mem2", "Combo1 item 2");
            ComboBoxMember cb1Mem2 = combo1.AddItem(cb1MemData2);
            cb1Mem2.Image = new BitmapImage(new Uri(Path.Combine(assemPath, "Standalone_Item1_16x16.bmp"), UriKind.Absolute));

            ComboBoxMemberData cb1MemData3 = new ComboBoxMemberData("com1Mem3", "Combo1 item 3");
            ComboBoxMember cb1Mem3 = combo1.AddItem(cb1MemData3);
            cb1Mem3.Image = BmpImageSource("RevitAddinCSProject.Resources.Embedded_Item2_16x16.bmp");

            Autodesk.Revit.UI.TextBox tb1 = stackedGroup2[1] as Autodesk.Revit.UI.TextBox;
            tb1.Value = "Option 3";
            tb1.ShowImageAsButton = true;
            tb1.EnterPressed += CallbackOfTextBox;
        }

Still as before, two different approaches to retrieve images have been demonstrated.

If the following method is called in the OnStartup implementation of an IExternalApplication:

        private RibbonPanel CreateRibbonPanel()
        {
            RibbonPanel panel = _cachedUiCtrApp.CreateRibbonPanel("RevitAddinCSProject");
            AddStackedButtonGroups(panel);

return panel;
}

A Revit Ribbon will be created and may look like (depending on what those images really are):

As can be noticed, the ComboBox and the TextBox buttons are aligned perfectly on the right side but not on the left. The stacked button group may not be designed to hold different kinds of buttons in a single group at all, I guess. They are aligned vertically automatically and leave equal space on top and on bottom though, it seems.

A side note: it is obvious that if a separator were added between the two stacked button groups, the display would look better. It is a trivial thing. I’d like to leave it to you guys.

Anyway, the RevitAddinWizard can help us create all these code and actually much more automatically in a few seconds.

Links to some related articles:

Ribbon of Revit API - PushButton And TextBox

Use Ribbon Creator of RevitAddCoder to Create PushButton And Separator

Use Ribbon Creator of RevitAddCoder to Create TextBox

Ribbon of Revit API - ComboBox And ComboBoxMember

Use Ribbon Creator of RevitAddCoder to Create ComboBox And ComboBoxMember

Ribbon of Revit API - PulldownButton And SplitButton

Use Ribbon Creator of RevitAddCoder to Create PulldownButton And PushButton

Use Ribbon Creator of RevitAddCoder to Create SplitButton And PushButton

Ribbon of Revit API - RadioButtonGroup And ToggleButton

Use Ribbon Creator of RevitAddCoder to Create RadioButtonGroup And ToggleButton