ProGuide Ribbon Tabs and Groups - kataya/arcgis-pro-sdk GitHub Wiki
Language: C#
Subject: Framework
Contributor: ArcGIS Pro SDK Team <[email protected]>
Organization: Esri, http://www.esri.com
Date: 11/24/2020
ArcGIS Pro: 2.7
Visual Studio: 2017, 2019
Overview
Groups
How to add a popup to a group
How to modify the contents of a group
Subgroups
Tabs
Tab groups
Toolbars
ArcGIS Pro uses the ribbon paradigm popularized by newer versions of Microsoft Office. The ribbon consists of a single fixed toolbar containing one or more tabs. The number of available (visible) tabs may vary dynamically depending on the state of the application. Tabs are activated through user interaction (clicks), or when directed by code running within the application.
Each tab is composed of one or more groups, small rectangular regions having a caption, and containing one or more controls. The representation of controls within groups varies depending on how frequently the control is expected to be used, and is configured declaratively in the DAML customization file. Frequently used controls should be large and obvious, while less frequently used tools should be smaller. In addition, controls are typically paired with a caption to make their function more obvious.
The location of a control within the ribbon, including its size and relative placement, is established using the group and tab elements.
Groups are declared as lists of controls within a groups container element within the module DAML element :
<groups>
<group id="esri_core_DockWindows" caption="Windows" condition="esri_core_MapPane">
<button refID="esri_core_ShowProjectDockPane" size="large" />
</group>
<group id="esri_core_ProjectFile" caption="Project">
<button refID="esri_core_OpenProjectButton" size="large" />
<button refID="esri_core_NewProjectButton" size="middle"/>
<button refID="esri_core_SaveProjectButton" size="middle"/>
<button refID="esri_core_SaveProjectAsButton" size="middle" separator="true"/>
<button refID="esri_core_CloseProjectButton" size="middle"/>
<button refID="esri_core_ProjectSettingsButton" size="middle"/>
</group>
<group id="esri_core_ProjectImport" caption="Import">
<button refID="esri_core_ImportMapButton" size="large" />
</group>
<group id="esri_core_ProjectNewItem" caption="New">
<button refID="esri_core_NewMapButton" size="large" />
</group>
</groups>In the example above, four groups are declared. Note that the button elements refer to previously declared buttons. While the button image is supplied elsewhere in the button declaration, the size of the button is specified on the group. Note that the same button could appear in more than one group. Any control can be added to the group; label controls, checkboxes, editboxes, and so on. The separator attribute can be used to segregate multiple controls in the same group.
The condition attribute is used to control whether or not the group is visible, and thus available. If no condition is specified, the group is always visible.
Groups may optionally support a “more” button—a small link widget located next to the group caption—that is used to show a dialog box where more obscure functions may be accessed. Use the launcherButtonID attribute on the group element to reference a button function.
<group id="esri_mapping_navigateGroup" caption="Navigate"
launcherButtonID="esri_mapping_navigationOptionsButton"
smallImage="pack://application:,,,/ArcGIS.Desktop.Resources;component/Images/3DNavigationTool16.png">
<tool refID="esri_mapping_exploreSplitButton" size="large" />
<button refID="esri_mapping_zoomFullButton" size="small" />
...
</group>
Like controls, existing groups can be modified using DAML files. The following example removes a button from an existing group:
<updateModule refID="esrimappingExtension">
<groups>
<updateGroup refID="ESRImappingFindGroup">
<deleteButton refID="ESRImappingFindButton"/>
</updateGroup>
</groups>
</updateModule>Subgroups are optionally declared inside groups. Subgroups provide finer control over ribbon scaling and ensure that the user experience is optimal when the application window is resized. Each subgroup can hold up to 3 controls.
<subgroups>
<!-- Can only have 3 items in a subgroup-->
<subgroup id="esri_core_editBtns" size="MediumThenSmallWhenSmall" verticalAlignment="Center" >
<button refID="esri_core_editCutButton"/>
<button refID="esri_core_editCopyButton"/>
<button refID="esri_core_editCopyPaths"/>
</subgroup>
</subgroups>A subgroup has two attributes: size and verticalAlignment. verticalAlignment can be "Center" or "Top" (Default)
`size' can be one of the following:
| size Attribute | Description |
|---|---|
| AlwaysLarge | Child controls always use a Large variant size no matter what the ribbon size is. |
| AlwaysMedium | Child controls always use a Medium variant size no matter what the ribbon size is. |
| AlwaysSmall | Child controls always use a Small variant size no matter what the ribbon size is. |
| Default | Child controls use a Large variant size when the ribbon size is Large. They change to a Medium variant size when the ribbon size is Medium. They change to a Small variant size when the ribbon size is Small. This option provides the largest number of variants for child controls. |
| LargeThenMediumWhenMedium | Child controls use a Large variant size when the ribbon size is Large. They change to a Medium variant size when the ribbon size is Medium or Small. |
| LargeThenMediumWhenSmall | Child controls use a Large variant size when the ribbon size is Large or Medium. They change to a Medium variant size when the ribbon size is Small. |
| LargeThenSmallWhenMedium | Child controls use a Large variant size when the ribbon size is Large. They change to a Small variant size when the ribbon size is Medium or Small. |
| LargeThenSmallWhenSmall | Child controls use a Large variant size when the ribbon size is Large or Medium. They change to a Small variant size the ribbon size is Small. |
| MediumThenSmallWhenMedium | Child controls use a Medium variant size when the ribbon size is Large. They change to a Small variant size when the ribbon size is Medium or Small. |
| MediumThenSmallWhenSmall | Child controls use a Medium variant size when the ribbon size is Large or Medium. They change to a Small variant size the ribbon size is Small. |
Multiple subgroups can be declared within a group.
<subgroups>
<subgroup id="esri_datasourcesraster_georefAdjustSubGroup1" verticalAlignment="Top" size="Default">
<button refID="esri_datasourcesraster_georefAutoFitToRefButton"/>
<button refID="esri_datasourcesraster_georefImportControlPointsButton"/>
<button refID="esri_datasourcesraster_georefAddControlPointsButton" separator="false" />
</subgroup>
<subgroup id="esri_datasourcesraster_georefAdjustSubGroup2" verticalAlignment="Center" size="LargeThenSmallWhenMedium">
<gallery refID="esri_datasourcesraster_georefXformTypesGallery"/>
<button refID="esri_datasourcesraster_georefAutoAdjustButton" separator="false" />
</subgroup>
<subgroup id="esri_datasourcesraster_georefAdjustSubGroup3" verticalAlignment="Top" size="MediumThenSmallWhenSmall">
<button refID="esri_datasourcesraster_georefUpdateDisplayButton"/>
<button refID="esri_datasourcesraster_georefResetXformButton"/>
</subgroup>
</subgroups>Each of the subgroup can then be placed in a desired group(s).
<group id="esri_datasourcesraster_georefAdjustGroup" caption="Adjust" smallImage="pack://application:,,,/ArcGIS.Desktop.Resources;component/Images/RasterGeoRefTransform16.png">
<subgroup refID="esri_datasourcesraster_georefAdjustSubGroup1"/>
<subgroup refID="esri_datasourcesraster_georefAdjustSubGroup2"/>
<subgroup refID="esri_datasourcesraster_georefAdjustSubGroup3"/>
</group>Once a group is declared, it can be referenced and placed on tabs. Tabs are declared as lists of groups within a tab's collection element. In the following example, previously declared groups are added to a new tab labeled “Map”.
<tabs>
<tab id="esri_core_MapTab" caption="Map" condition="esri_core_MapPane" keytip="M">
<group refID="esri_core_NavigateGroup" />
<group refID="esri_core_MapGroup" />
<group refID="esri_core_ViewGroup" />
<group refID="esri_core_SelectionGroup"/>
<group refID="esri_core_InquiryGroup"/>
<group refID="esri_core_MapWindowsGroup"/>
</tab>
</tabs>Like controls, a tab’s relevance can be governed using a condition. The condition attribute is used to control whether or not the tab is visible, and thus available. Conditions are not used to control tab activation, only tab availability. If no condition is specified, the tab is always visible.
To support accessibility, an appropriate keytip should be supplied for each tab. The characters chosen should make sense and should conflict with any existing keytips; keytips can consist of multiple characters to disambiguate if necessary.
Collections of related tabs can be grouped together in colored, named groups to improve clarity. These collections are called tab groups. In the ribbon displayed below, there is a tab group containing three tabs called FEATURE LAYER.
Tab groups are declared within a tabGroups collection element and consist of an ID, a color, and a caption. Tabs are associated with a tab group using the tabGroupID attribute. The DAML below creates the tabs and tab group as displayed above.
<tabGroups>
<tabGroup caption="Feature Layer" id="esri_mapping_featureLayerTabGroup">
<color A="255" R="238" G="170" B="90" />
<borderColor A="0" R="251" G="226" B="195" />
</tabGroup>
</tabGroups>
<tabs>
<tab id="esri_mapping_featureLayerAppearanceTab" caption="Appearance" condition="esri_mapping_onlyFeatureLayersSelectedCondition" tabGroupID="esri_mapping_featureLayerTabGroup">
<group refID="esri_mapping_layerScaleVisibilityGroup"/>
<group refID="esri_mapping_layerEffectsGroup" />
<group refID="esri_mapping_layerSymbology" />
<group refID="esri_mapping_layerExtrusion" />
<group refID="esri_mapping_layer3DGroup" />
</tab>
<tab id="esri_mapping_labelingTab" caption="Labeling" condition="esri_mapping_onlyFeatureLayersSelectedCondition" tabGroupID="esri_mapping_featureLayerTabGroup">
<group refID="esri_mapping_labelingLayerGroup" />
<group refID="esri_mapping_labelingLabelClassGroup" />
<group refID="esri_mapping_labelingScalesGroup" />
<group refID="esri_mapping_labelingTextSymbolGroup" />
<group refID="esri_mapping_labelingPlacementStyleGroup" />
<group refID="esri_mapping_labelingMapGroup" />
</tab>
<tab id="esri_mapping_featureLayerDataTab" caption="Data" condition="esri_mapping_onlyFeatureLayersSelectedCondition" tabGroupID="esri_mapping_featureLayerTabGroup">
<group refID="esri_mapping_layerDefQueryGroup" />
<group refID="esri_mapping_featureLayerAttributeGroup" />
<group refID="esri_mapping_layerSelectionGroup"/>
<group refID="esri_mapping_designViewGroup"/>
<group refID="esri_mapping_layerRelationshipsGroup"/>
<group refID="esri_mapping_layerToolsGroup"/>
</tab>
</tabs>Tab groups are typically used in situations where the user temporarily enters a mode, such as editing graphic elements. Tab groups are not typically used with tabs that are always visible (global tabs).
The ribbon group supports an inner collection and grouping of buttons into a toolbar. Toolbars are purely declarative and support multiple groups. The group definition describes what the toolbar looks like. Use the appropriate control element with a refID to specify the elements you want to appear in the toolbar. The example below shows a toolbar with several comboboxes and buttons.
<toolbars>
<toolbar id="esri_mapping_labelTextSymbolFontToolbar">
<group>
<comboBox refID="esri_mapping_labelTextSymbolFontFamilyComboBox" />
<comboBox refID="esri_mapping_labelTextSymbolFontSizeComboBox" size="small" />
<button refID="esri_mapping_labelTextSymbolIncreaseSizeButton" size="small" />
<button refID="esri_mapping_labelTextSymbolDecreaseSizeButton" size="small" />
</group>
<group>
<customControl refID="esri_mapping_labelTextSymbolColorPicker" size="small" />
<button refID="esri_mapping_labelTextSymbolBoldButton" size="small" />
<button refID="esri_mapping_labelTextSymbolItalicButton" size="small" />
<button refID="esri_mapping_labelTextSymbolUnderlineButton" size="small" />
</group>
</toolbar>
</toolbars> 