ComponentOne WinForms Edition
Elements / Ribbon Items / Gallery
In This Topic
Gallery
In This Topic

Gallery displays a collection of related commands in a Ribbon. The Gallery contains a list of clickable items. Each item when clicked shows the result visually on the selected text.

The GIF below illustrates how the text changes upon applying various Styles from the Gallery.

Gallery snapshot.

The image below shows a gallery item in the C1Ribbon control.

Gallery item.

The Ribbon Gallery has a page-up and page-down button to scroll up and down the gallery. There is also a popup launcher button that opens a window with ribbon items.

Configuring Gallery at Design-Time

The Ribbon Gallery can be added at design-time using the Ribbon Group Floating Toolbar or RibbonGroup Items Collection Editor. Also, you can customize the look of the Ribbon Gallery using the Ribbon Gallery Floating ToolBar or by editing the properties of Gallery in the Properties Window. Refer this topic, for more information on floating toolbars. You can add items to Gallery using the RibbonGallery Items Collection Editor and RibbonGallery MenuItems Collection Editor. For more info on Collection Editors, refer this topic.

The image below shows the floating toolbar of Gallery.

Floating toolbar

Adding Ribbon Gallery and Ribbon Gallery Items

The user can also add Gallery and Gallery items in the C1Ribbon control through code using the RibbonGallery class and RibbonGalleryItem class. For instance, the code below depicts how to add a gallery of shapes to the Ribbon control.

' Add RibbonGallery ribbon item
Dim ribbonGallery As RibbonGallery = New RibbonGallery()
ribbonGallery.ToolTip = "Select a shape"
Dim ribbonGallery1 As RibbonGalleryItem = New RibbonGalleryItem("Rectangle", Image.FromFile("images\rect.png"))
Dim ribbonGallery2 As RibbonGalleryItem = New RibbonGalleryItem("Circle", Image.FromFile("images\circle.png"))
Dim ribbonGallery3 As RibbonGalleryItem = New RibbonGalleryItem("Triangle", Image.FromFile("images\triangle.png"))
Dim ribbonGallery4 As RibbonGalleryItem = New RibbonGalleryItem("Hexagon", Image.FromFile("images\hexagon.png"))
ribbonGallery.Items.Add(ribbonGallery1)
ribbonGallery.Items.Add(ribbonGallery2)
ribbonGallery.Items.Add(ribbonGallery3)
ribbonGallery.Items.Add(ribbonGallery4)
formatGroup.Items.Add(ribbonGallery)

The snapshot of the resulting ribbon control is shown below:

Gallery ribbon.

The user can change the position of the image and text of each gallery item. You can place the image above, before or after the text using the ImageAboveText, ImageBeforeText and ImageAfterText properties of GalleryItemTextImageRelation enum.
Ribbon gallery item.

You can also assign the position of image and text of each item in the gallery via code:

' Specify the position of text And image for gallery items
ribbonGallery1.GalleryItemTextImageRelation = GalleryItemTextImageRelation.ImageBeforeText
ribbonGallery2.GalleryItemTextImageRelation = GalleryItemTextImageRelation.ImageAfterText
ribbonGallery3.GalleryItemTextImageRelation = GalleryItemTextImageRelation.ImageAboveText
ribbonGallery4.GalleryItemTextImageRelation = GalleryItemTextImageRelation.ImageBeforeText

Gallery Grouping

If you click on the popup launcher button, it displays a small window of gallery items, which are grouped by group names.

The image below shows the popup gallery window with items arranged in two groups, Common and Extended.

Gallery window.

Grouping in gallery can be done at design time by assigning GroupName to each gallery item in the RibbonGallery Items Collection Editor.

Gallery grouping.

You can also assign group names to gallery items programmatically using the GroupName property of RibbonGalleryItem class. This is shown in the code snippet below:

'Add gallery items to groups
ribbonGallery1.GroupName = "Common"
ribbonGallery2.GroupName = "Common"
ribbonGallery3.GroupName = "Extended"
ribbonGallery4.GroupName = "Extended"

Gallery Zooming

The C1Ribbon control supports zooming within the Gallery. The user can rest the cursor on each item and get a zoomed preview of that item image.

Gallery zoom

At design time, the zooming feature can be activated using the AllowZooming property of Ribbon Gallery in the Properties window. Note that for the zooming property to work, the ItemSize property of the Gallery should be less than the image size of each item.

Zooming feature in gallery.

You can also add the zooming feature via code using the AllowZooming property of RibbonGallery class.

'Allow zooming in gallery
ribbonGallery.AllowZooming = True

Gallery Filtering

The C1Ribbon control supports filtering in the ribbon gallery. It allows you to filter items by gallery groups. This is illustrated in the GIF below:

Filtering in gallery.

At design time, the filtering feature can be activated using the AllowGroupFiltering property of Ribbon Gallery in the Properties window.

Gallery showing filtering feature.

You can also add the filtering feature via code using the AllowGroupFiltering property of RibbonGallery class.

'Allow filtering in gallery groups
ribbonGallery.AllowGroupFiltering = True

Owner-Drawn Gallery

With 'Owner-Drawn' feature, the items are not drawn with the default logic of Ribbon, rather they are drawn with a custom logic defined by the user of the application. This is useful in cases where complex customizations need to be performed. You can render the contents of the RibbonGallery as Owner Drawn by writing a handler for the DrawItem event. This event is raised as needed to display the contents of Gallery when its OwnerDraw property is set to True.

Gallery UI in ribbon

To create the owner-drawn RibbonGallery in the above illustration, follow the steps below:

  1. Add the following code the Form_Load event:
    C#
    Copy Code 
    //Set OwnerDraw property and bind DrawItem event
//to owner draw RibbonGallery items
ribbonGallery.OwnerDraw = true;
ribbonGallery.DrawItem += RibbonGallery_DrawItem;
  2. Implement the DrawItem event:
    C#
    Copy Code 
    //Handle DrawItem event to owner draw RibbonGallery Items 
private void RibbonGallery_DrawItem(object sender, C1.Win.Ribbon.DrawItemEventArgs e)
{
    switch (e.Item.Name)
    {
        case "Rectangle":
            Rectangle srect = new Rectangle(e.Bounds.X + 10, e.Bounds.Y + 10, 60, 30);
            e.Graphics.DrawRectangle(new Pen(Color.BlueViolet), srect);
            e.Graphics.DrawString("Rectangle", new Font("Arial", 8), new SolidBrush(Color.Maroon), new PointF(e.Bounds.X + 15, e.Bounds.Y + 45));
            break;

        case "Circle":
            Rectangle crect = new Rectangle(e.Bounds.X + 25, e.Bounds.Y + 5, 40, 40);
            e.Graphics.DrawEllipse(new Pen(Color.BlueViolet), crect);
            e.Graphics.DrawString("Circle", new Font("Arial", 8), new SolidBrush(Color.Maroon), new PointF(e.Bounds.X + 30, e.Bounds.Y + 45));
            break;

        case "Triangle":
            Point point1 = new Point(e.Bounds.X + 35, e.Bounds.Y + 5);
            Point point2 = new Point(e.Bounds.X + 15, e.Bounds.Y + 45);
            Point point3 = new Point(e.Bounds.X + 55, e.Bounds.Y + 45);
            Point[] curvePoints = { point1, point2, point3 };
            e.Graphics.DrawPolygon(new Pen(Color.BlueViolet), curvePoints);                    e.Graphics.DrawString("Triangle", new Font("Arial", 8), new SolidBrush(Color.Maroon), new PointF(e.Bounds.X + 15, e.Bounds.Y + 45));
            break;
    }
}