Windows Ribbon for WinForms, Part 8 – ComboBox

21 באוקטובר 2009

ComboBox Control
A ribbon ComboBox control is basically the normal ComboBox control that we all love, but with the additional feature of dividing the items into categories. A category is not an item and cannot be selected from the ComboBox. It is only used to organized the items.

image 

ComboBox Properties
Every ribbon control has properties that defines the way it looks and behaves. Here is a quick review of ComboBox properties, divided into logical groups:

ComboBox Value Related Properties

  • Items Source – The list of ComboBox items. It is exposed as an IUICollection where every element in the collection is of type: IUISimplePropertySet. More on this later.
    Property Identifier: UI_PKEY_ItemsSource
  • Categories – The list of categories. Also exposed as an IUICollection of IUISimplePropertySet elements.
    Property Identifier: UI_PKEY_Categories
  • Selected Item – The index of the selected item in the ComboBox. If nothing is selected returns UI_Collection_InvalidIndex, which is a fancy way to say -1.
    Property Identifier: UI_PKEY_SelectedItem
  • String Value – The current string in the ComboBox. This can be a string that isn’t one of the possible items in the ComboBox, in case the ComboBox has IsEditable set to true.
    Property Identifier: UI_PKEY_StringValue

ComboBox Appearance Related Properties

  • Representative String – A string that represents the common value for the ComboBox. This is used to calculate the width of the ComboBox, so you should set here the longest string you forecast. Note that it doesn’t have to be an actual value, it can be also: “XXXXXXXX”.
    Property Identifier: UI_PKEY_RepresentativeString

Common Appearance & Image Properties

See these sections at Windows Ribbon for WinForms, Part 7 – Spinner

Using ComboBox – Ribbon Markup
As always, a command should be defined:

<Command Name="cmdComboBox2" Id="1019" />

The views section:

<Application.Views>
  <Ribbon>
    <Ribbon.Tabs>
      <Tab>
        <Group>
          <ComboBox CommandName="cmdComboBox2"
                    IsAutoCompleteEnabled="true"
                    IsEditable="true"
                    ResizeType="VerticalResize" />
        </Group>
      </Tab>
    </Ribbon.Tabs>
  </Ribbon>
</Application.Views>

ComboBox Attributes:

  • CommandName – Name of the command attached to this ComboBox.
  • IsAutoCompleteEnabled – Flag that indicated whether to complete the words as you write.
  • IsEditable – Flag that indicates whether to allow free writing in the ComboBox.
  • ResizeType – Allow resize of the ComboBox. Can be NoResize or VerticalResize.

Using ComboBox – Code Behind
In a similar way to the spinner control, I’ve created a helper classes that encapsulates the interaction between the ComboBox and ribbon framework. To use the ComboBox, create a RibbonComboBox instance, passing to the constructor the Ribbon instance and command ID of the ComboBox:

private Ribbon _ribbon;
private RibbonComboBox _comboBox2;

public Form1()
{
    InitializeComponent();

    _ribbon = new Ribbon();
    _comboBox2 = new RibbonComboBox(_ribbon, (uint)RibbonMarkupCommands.cmdComboBox2);
    _comboBox2.RepresentativeString = "XXXXXXXXXXX";
}

Note: We set the RepresentativeString property BEFORE the initializing the ribbon framework. This is because for some reason the framework reads this property only once, when the ribbon is initialized. This means that if you change it after initialization it will have no affect since the framework doesn’t reads this property anymore. By the way, according to the current documentation of the ribbon framework, this property is not part of the ComboBox, but as mentioned earlier, this property controls the width of the ComboBox.

In the next code snippet you can see how to use another helper class, named GalleryItemPropertySet. This class represents a container for properties of a single element in an IUICollection.

Adding categories and items to the ComboBox is done like this:

private void Form1_Load(object sender, EventArgs e)
{
    _ribbon.InitFramework(this);

    // set combobox2 label
    _comboBox2.Label = "Advanced Combo";
    
    // set _comboBox2 categories
    IUICollection categories2 = _comboBox2.Categories;
    categories2.Clear();
    categories2.Add(new GalleryItemPropertySet() { Label="Category 1", CategoryID=1 });
    categories2.Add(new GalleryItemPropertySet() { Label="Category 2", CategoryID=2 });

    // set _comboBox2 items
    IUICollection itemsSource2 = _comboBox2.ItemsSource;
    itemsSource2.Clear();
    itemsSource2.Add(new GalleryItemPropertySet() { Label="Label 1", CategoryID=1 });
    itemsSource2.Add(new GalleryItemPropertySet() { Label="Label 2", CategoryID=1 });
    itemsSource2.Add(new GalleryItemPropertySet() { Label="Label 3", CategoryID=2 });
}

Note: Adding items and categories can be done only AFTER the Ribbon Framework has been initialized.

Finally, you must connect the IUICommandHandler.UpdateProperty method with the implementation of this method in our RibbonComboBox class:

public HRESULT UpdateProperty(uint commandId, ref PropertyKey key, PropVariantRef currentValue, ref PropVariant newValue)
{
    if (commandId == (uint)RibbonMarkupCommands.cmdComboBox2)
    {
        _comboBox2.UpdateProperty(ref key, currentValue, ref newValue);
    }
    return HRESULT.S_OK;
}

Update (18.11.2009): The updated version of the Ribbon class provides an implementation for IUICommandHandler, so the user doesn't need to implement Execute and UpdateProperty methods anymore.

IUICollection Events
Objects that implements IUICollection interface usually expose an OnChanged event that is called when the collection has changed due to: Insert item, Remove item, Replace item, Reset collection.

This event is exposed using the standard COM events mechanism, namely: IConnectionPointContainer, IConnectionPoint and Advise().

To help the user to avoid these issue altogether, I’ve created the UICollectionChangedEvent class, which attaches to a given IUICollection and exposes the OnChanged event as a normal .NET event.

Following is an example of using it:

private RegisterEvent()
{
    _uiCollectionChangedEvent = new UICollectionChangedEvent();
    _uiCollectionChangedEvent.Attach(_comboBox1.ItemsSource);
    _uiCollectionChangedEvent.OnChanged +=
        new UICollectionChangedEvent.OnChangedEventHandler(_ChangedEvent_OnChanged);
}

 

void _ChangedEvent_OnChanged(UI_CollectionChange action,
                             uint oldIndex, object oldItem,
                             uint newIndex, object newItem)
{
    MessageBox.Show("Got OnChanged event. Action = " + action.ToString());
}

Note: There is no OnChanged event for the ComboBox. Only for IUICollection, which is completely different.

Update (27.10.2009): The ComboBox itself has 3 events, Execute, Preview and CancelPreview. The Execute event can be used as a "Selected Change" event. See this future post.

Summary
You can find a working sample that demonstrates using a ComboBox control at Windows Ribbon for WinForms under sample “06-ComboBox”.

That’s it for now,
Arik Poznanski.

kick it on DotNetKicks.com Shout it

הוסף תגובה
facebook linkedin twitter email

כתיבת תגובה

האימייל לא יוצג באתר. (*) שדות חובה מסומנים

6 תגובות

  1. Stelios18 במרץ 2010 ב 13:54

    I am trying to populate 2 combo boxes with string items. The first combobox is populated without problems but when i try to populate the second combobox, i get the following error "The type of this variable is not support ('0')".

    The error occurs at the IUICollection declaration:

    IUICollection _combo_Collection = _combo_Types.Categories;

    The _combo_Types is declared as follows:

    _combo_Types = new RibbonLib.Controls.RibbonComboBox(_ribbon, 2220);

    And below is the xml declaration of item 2220:

    Id ='2220'
    LabelTitle='Types'/>

    להגיב
  2. arik19 במרץ 2010 ב 16:26

    I think that the combobox issue was already solved a few weeks ago.
    Can you download the latest changeset under the SOURCE section
    Note that the latest changeset has some minor bug fixes that doesn't appear in the latest RELEASE download.

    Please let me know your results.
    If the problem still continues, it would be helpful if you send me a small project demonstrating the problem.

    Thanks,
    Arik Poznanski.

    להגיב
  3. Jody13 במאי 2010 ב 4:01

    I've run into a bug where the combobox will only appear on the first tab. Placing it on any other tab results in the following error in the initiation of the dropdown values:

    Line xxx: itemsSource.Clear(); //errors out here with the following error:

    "Object reference not set to an instance of the object."

    I believe this may have been discovered and resolved above, but I don't know hot to turn a changeset into a ribbon.dll file. Is it possible to post the most current dll on codeplex?

    להגיב
  4. arik14 במאי 2010 ב 17:13

    I've updated the release but I think the version you got already had this fix.
    If the problem continues, send me a small demo that shows the exception and I'll have a look.

    להגיב
  5. rhummer22 ביולי 2010 ב 5:31

    Hi, I'm seeing the same issue with putting a ComboBox on another Tab. It is simple enough to reproduce with the latest download of the source using the example project provided by the library.

    להגיב
  6. arik3 באוגוסט 2010 ב 1:14

    Having a ComboBox in another tab had some problems.
    This is now fixed in a version I just released.
    check this post for more details:
    http://blogs.microsoft.co.il/blogs/arik/archive/2010/08/03/windows-ribbon-for-winforms-v2-3-released-bug-fixes.aspx

    להגיב