SandRibbon User Guide
Popups and Menus
A the root of evey popup is the Popup widget. These are items like most other SandRibbon items, only they have no ParentItem. They can be resized, by nominating a Gallery control within whose viewport size can be increased and descreased. Because popups are widgets like other items, they are designable in Visual Studio in the same way.
While popups never have a direct parent, they usually have an item with which they are associated. A few controls, like Button and Gallery, have a PopupWidget property that allows you to associate a popup with them. When a popup is associated with a button, it will gain a dropdown arrow indicating access to the popup. The application menu is simply an extended popup, with additional controls.
Because SandRibbon popups are so versatile, you have a lot more flexibility in terms of what presentation you can give your dropdowns. You may only decide to use a traditional menu in certain circumstances, or to have more than one menu in a popup, with helpful headings on each. This means that for a simple menu, there is an extra step: first add the menu to your popup, then add items to the menu. In traditional menu and toolbar components there would only be the menu and items. This is an important step to remember.
Associated Popups and Context Popups
As mentioned previously, most popups are created by associating them with another type of item. Most commonly this will be a Button control. Associating a popup by assigning it to the Button's PopupWidget property turns the button into a dropdown button. At design time, you simply select the button and choose Add Popup, and the designer takes care of the rest. Popups that are not generally displayed standalone, and that are associated with another item instead, are called associated popups.
Alternatively, you can create a ContextPopup, which is a standalone popup that is directly associated with your manager. Designed for use as a context menu, you can then set the ContextPopup property of any standard windows forms control on your form to associate your ContextPopup with it. Right-clicking that control will then invoke your popup.
Menu and MenuItem
A menu control is an extended StripLayout which includes a margin. Unlike many other libraries, SandRibbon supports many menus in one popup. The only type of control that can be parented to a menu is a menu item. These behave very much like buttons.
Menu items always have a popup associated with them, so there is no need to associate one explicitly. In fact, menu items expose an Items property that suggests that they are parents, whereas in fact this property returns the Items collection of the implicit popup associated with the item. This makes it a lot more intuitive to work with menus at runtime.
You may wish certain popups that contain a gallery to be resizable, due to the potentially variable number of items the gallery could contain and different amounts of screen space being available. Popups expose a ResizableGallery property, to which a gallery that is a direct descendant of the popup can be assigned. Once assigned, the popup will feature a resize bar at the bottom which can be manipulated by the user.
This technology is simply an event that is fired on your RibbonManager as the focused item changes during popup navigation. The event is be fired every time the focus changes. In this way your application has live feedback on potential options the user is considering, and can update itself dynamically based upon them. For example, your application might have a Foreground Color dropdown to enable the user to change the color of some selected text. As the user hovers over the various color choices a preview could be shown by temporarily changing the color of that text.
Coupled with the event is a useful base class called LivePreviewOperation. In your application you can derive from this class and assign an instance of your class to the Operation property of the LivePreview event arguments. SandRibbon will then automatically call the Revert method of your derived class when it is time to undo the preview operation.
In the demonstration application this technique is shown with the ForeColor dropdown. A simple derived class remembers the previous selection color and selection scope, then applies a preview color. When the Revert method is called it simply restores the preview selection color. Previews of any level of complexity can be achieved with this simple but powerful API.
The full concept of galleries involves a combination of the Gallery control, the GalleryButton control and using Live Preview to display a concept interactively. However, any of these things can be done individually. Galleries can be hosted in a ribbon but are usually hosted in popups, hence their discussion on this page.
The Gallery control is a scrollable parent that arranges its children in a flow layout. The size of the viewport is defined by the programmer and can optionally be adjusted by the user, if the gallery is contained in a resizable popup. The user has full control of the scrolling of a gallery using both its scrollbar and the mouse wheel, even in a popup.
For the optimum method of displaying a large list of graphical choices, the GalleryButton is ideal. It extends the standard Button class to provide an owner-drawing event, for the host application to hook. It is expensive, resource wise, to assign a potentially large image to each button in a list. Owner drawing is a good way around this, and also ensures the appearance of the buttons remains consistant with your drawing algorithms. For instance, in the demonstration application a gallery of underline styles is simply drawn at runtime.