CommandBarGallery Object
See Also
- CommandBarGallery Members
- CommandBarGalleryItem Object
- CommandBarGalleryItems Object
- CreateGalleryItems Method
- AddItem Method
- AddLabel Method
- CommandBar Property
- ShowLabels Property
- ShowScrollBar Property
- Width Property
Description
Office 2007/2010 style gallery control for toolbar, menu bar, popup menu, and Ribbon Bar controls.
For a list of all members defined in this module, see CommandBarGallery members.
Object Model
Remarks
The Office 2007/2010 style CommandBarGallery object is a control that displays a collection of CommandBarGalleryItem objects that can be scrolled and displayed in a popup menu. CommandBarGallery objects can be displayed in a standard toolbar, popup menu, and a Ribbon Bar group.
CreateGalleryItems must be used to create a CommandBarGalleryItems collection before adding CommandBarGalleryItem objects to a gallery. Note that the Id of the CommandBarGalleryItems collection must use the same Id as the gallery control.
The CommandBar property is used to add a popup toolbar to the gallery. This will also add a popup button to the bottom of the scroll bar that the user can click to display the popup. When a CommandBarGalleryItem is added to the CommandBar, a popup button will automatically appear at the bottom of the scroll bar of the gallery. When the user clicks on the button, the popup toolbar is displayed. A popup toolbar is commonly used to contain another CommandBarGallery object that contains the same items displayed in the parent gallery, only allowing more of the gallery to be displayed.
The picture below shows the popup button that is added to the gallery when an item is added to the gallery's CommandBar.
Scroll bars are used to scroll through the items in a gallery if they are not all currently visible. By default, a scroll bar will be displayed for all galleries, regardless of whether it needs one. ShowScrollBar can be used to remove the scroll bar for galleries that do not need them. The Width and Height properties are used to specify the width and height of the gallery. They can be used to ensure that all items will be visible so no scroll bars would be needed. When a gallery is displayed in a standard toolbar, usually only the width is set; when displayed in a popup toolbar, both width and height are commonly set. EnsureVisible will "ensure" that the item with the specified index is visible in the gallery. This will scroll the items in the gallery until the item is visible.
Label controls are added using the AddLabel method. Labels are used to organize/group the items in the gallery. ShowLabels will hide or show labels that have been added to the gallery.
The Items collection allows you to access, add, modify, and delete the items in a gallery. The AddItem and AddLabel methods are used to add CommandBarGalleryItem objects to the Items collection, and the DeleteAll and DeleteAt methods are used to delete items from the Items collection.
The illustration below shows a gallery control that contains both label and normal gallery items.
The Icons property allows you to use a separate ImageManagerIcons collection for each collection of gallery items, or you can use the same collection for all. These are the images used for CommandBarGalleryItem objects that display an image. The Id of the CommandBarGalleryItem object is used to uniquely identify the control. Label items will have an Id of 0 by default; you can change this if you like, but the AddLabel method does not allow you to set it at the time of creation. Label items cannot display icons, so the ImageIndex property will not be used for a Label item.
The ItemHeight and ItemWidth properties specify the width and height of all the CommandBarGalleryItem objects in a Gallery Items Collection. Setting ItemWidth to 0 (zero) tells the gallery to auto size the width of items to best fit.
The CheckedItem property holds the index of an item in the gallery's collection of items that is displayed as "checked." There can only be one checked item in a gallery. The checked item will remain displayed as checked until another is marked as checked. To have no items checked, set CheckedItem to -1.
The illustration below shows what an item looks like when checked and selected.
The DrawItem event is called before each CommandBarGalleryItem in a CommandBarGallery is drawn. The DrawItem event is used to override the standard drawing functionality of the CommandBarGalleryItem(s) in a CommandBarGallery. This can be very useful to draw custom gallery items.
The illustration below shows a gallery control that is used as a color selector. The color squares in the gallery are all custom drawn in the DrawItem event.
ClipItems specifies whether drawing optimization is used when drawing the CommandBarGalleryItem objects in a gallery. Drawing optimization means that only the item that is checked, the selected item, and previously selected item are re-drawn.
Example
Copyright (c) 1998-2024 Codejock Technologies. All rights reserved.