SandRibbon User Guide

Items Reference

Back to Table of Contents

This page outlines the features of all the ribbon items that are not to do with popups (they are covered later). This is not an exhaustive guide to their properties but should serve as a guide to what they can do.

Container Items

StripLayout

The usage of StripLayout has already been discussed on a previous page.

CenterLayout determines whether the strip of items is centered in the direction of layout. This only takes effect when there is an excess of space in the strip. For example, a horizontal strip with an excess of space will pad the beginning of the layout so that the items appear centered horizontally.

ItemJustification determines how items are aligned perpendicular to the direction of the strip. The values for this are Near, Far, Center and Stretch. In the case of a horizontal strip, near refers to the top of the layout and far refers to the bottom. The default is Stretch, which will cause all items in a horizontal strip to adopt the height of the largest item. This property should not be confused with the CenterLayout property, since that works in the direction at right angles to that of the strip.

ItemSpacing simply determines the space in pixels between each item. This excludes any additional margin settings an individual item might have.

FurtherOptions property determines whether this is shown, and the ShowFurtherOptions event is raised when it is activated by the user.

Ribbon chunks automatically collapse when space becomes tight and there is no longer enough room to display them all on their parent ribbon tab. The order in which they collapse is governed by their Importance property. Chunks with a lower importance are collapsed first. When an chunk is collapsed its text is shown and also its Image, which is not shown when expanded.

ButtonGroup

This derives from StripLayout and simply changes the appearance of buttons placed in it. It has no additional properties that can be set.

Gallery

The gallery is different from the other container items in that it lays out its child items in a flow, rather than a strip. This is similar to a strip only items are wrapped to a new line when the limit of horizontal space is reached. While any type of item can be added to a Gallery, the only type you will typically add is a GalleryButton.

Child items in a gallery have a potentially very large amount of space because the entire control is scrollable. While a scrollbar is always displayed, it takes different forms depending on where the gallery is situated. If the gallery is in a ribbon a simple up and down button arrangement is shown. If the gallery is in a popup a full featured scrollbar is shown.

ScrollAmount determines by how many pixels the contents of the gallery will scroll when the scroll buttons are pressed. This has no effect if the gallery is hosted in a ribbon, where the gallery will always scroll by a whole page.

ViewportOffset is not normally used directly, but can be used to get and set the offset of the viewable area.

ViewportSize is very important and is the amount of space allowed to child items horizontally, and the amount of space to show vertically. A gallery cannot scroll horizontally. This property directly affects the size of the gallery wherever it is located.

Other Items

ComboBox and WindowsComboBox

We provide two types of combo box in the SandRibbon library. WindowsComboBox is a wrapper around the standard windows forms ComboBox control and therefore has identical features. It exposes the most common properties and events and is easy to work with, but has some shortcomings such as not rendering precisely how the office combo boxes do, and not offering live preview. The underlying windows forms control is exposed via the ComboBox property for fine-grained control.

ComboBox is our own implementation of a combo box written on the same library as the rest of the SandRibbon controls. It offers full live preview support, direct text editing capability and because it uses a gallery for dropdown display, any type of item can be added to it.

To populate a ComboBox, simply add items to its Items collection. Usually you would use GalleryButton in keeping with the Office product. The SelectedItem property indicates the child item (if any) that is selected, and can be null. The SelectedItemChanged event is fired whenever this value changes.

You can enable direct text editing of the value in a combo box with the Editable property. When a combo box is editable the ValueEdited event fires whenever its text changes. If the user picks an item from the dropdown list the Value property is automatically set to the text of that item.

The color picker control is an extremely useful device that presents a list of colors to the user for choosing. Its simple API offers a Colors collection, which is simply a collection of Color structures, and it can show them alone or with a set of graduations (e.g. darker and lighter tones) to choose from.

BlockSize determines the size of each color block that is presented to the user.

ShowGraduations determines whether the graduation options are shown. If this is set to false only the colors in the Colors collection are shown.

The ColorPicker control raises the ColorPicked event when a color is picked by the user.

GalleryButton

This class is designed to help with implementing galleries in your application and is discussed in detail in the section dedicated to Galleries.

Label

The label control displays text and an image, and aligns them relative to each other based upon a horizontal or vertical preference, horizontal alignment preference and right-to-left settings.

TextContentRelation determines how the text is positioned next to the content (in this case an image) of the label. Values are Beside and Underneath.

LabelAlignment determines, for text set to display beside the image, whether the text is displayed on the right or on the left of the image.

Hyperlink

This control is a simple extension of Label that draws an underline under text by default, changes the foreground color, displays the traditional "Hand" cursor and fires the Activate event when the control is clicked.

The default blue color of the link can be changed with the ForeColor property.

Slider

The slider is a control normally displayed on a status bar and presents the user with a way to graphically select a value between a set minimum and maximum value. They can do this by clicking plus and minus buttons or dragging a scrollable "thumb".

Minimum and Maximum are the inclusive lower and upper bounds of the range of values the user should be able to choose from.

Value gets or sets the value currently selected in the control.

MarkerPosition allows a graphical marker to be drawn at a certain value within the range of potential values. Often this is a half-way marker, in which case for a minimum of 0 and a maximum of 100 this property would be set to 50.

SmallChange determines the amount to alter the value by when the plus or minus button is clicked.

TrackWidth determines the width of the scroll track and therefore directly affects the width of the control in its container.

Next: Popups and Menus