ribbon
- Ribbon UI configuration can be extended with a manifest.
- Freely configure tabs and groups on the ribbon, and place buttons that call commands and check boxes that display and change the ON/OFF state on the ribbon.
Ribbon elements
The elements of the ribbon that can be extended with extensions are:
- tab
- group
- Single control
- button
- Checkbox
- Separator
- Composite control
- button group
- stack panel
- menu
- Split button
Details per element
tabs (elements of tabs)
-
Tabs that make up the ribbon
-
property
key description range required id ID that uniquely identifies the tab. A unique string for all components of the ribbon. 1 String representing ID Required label tab label arbitrary string required 4 orderBefore/orderAfter ID of the ribbon element indicating the relative position to add the tab. 2
If not specified, it will be added before the Help tab. If a tab with the same ID already exists, no new tab will be added and the existing tab position will remain.
Refer to ribbon element ID for the system standard built-in ribbon element IDs.String representing ID - visible The visible state of the target element. Displayed if omitted or if true is specified. Specify false to hide. "true", "false" - groups array of groups that make up the tab object array - -
child element type
- group
groups (elements of groups)
-
Groups that separate ribbon tabs
-
property
key description range required id ID that uniquely identifies the target element. A unique string for all components of the ribbon. 1 String representing ID Required label group label any string required 4 orderBefore/orderAfter ID of the ribbon element indicating the relative position to add the target element. 2
See ribbon element IDs for the system standard built-in ribbon element IDs.String representing ID - visible The visible state of the target element. Displayed if omitted or if true is specified. Specify false to hide. "true", "false" - controls Array of controls to place in the group Object array - -
Types of controls that can be placed as child elements
- Button
- CheckBox
- Separator
- ButtonGroup
- StackPanel
- Menu
- Split Button
Button (type: Button)
-
command execution button on the ribbon
- You can assign a command to be executed when the button is pressed.
- The enabled/disabled state and toggle state of the button are linked with the assigned command.
-
properties
key description range required type The type of the element. "Button" Required id ID that uniquely identifies the target element. A unique string for all components of the ribbon. 1 String representing ID Required label button label any string required5 description Description displayed in tooltip Any string - orderBefore/orderAfter ID of the ribbon element indicating the relative position to add the target element. 2 String representing ID - visible The visible state of the target element. Displayed if omitted or if true is specified. Specify false to hide. "true", "false" - isEnabled Property name that holds the enabled/disabled state of the button. If omitted, it is linked to the status of the assigned command. A string representing the property name - imageSmall PNG file path to a small icon (16x16 image recommended) to display on the button. 3 string representing a relative path - imageLarge PNG file path of the large icon (32x32 image recommended) to display on the button. 3 string representing a relative path - command ID of the command to assign to the button. a string representing the ID required
CheckBox (type: CheckBox)
-
Checkbox
- The display of the check box changes according to the value of the property associated with the isChecked property.
- When the checkbox is operated, the value of the associated property is updated.
-
property
key description range required type The type of the element. "CheckBox" Required id ID that uniquely identifies the target element. A unique string for all components of the ribbon. 1 String representing ID Required label checkbox label any string required orderBefore/orderAfter ID of the ribbon element indicating the relative position to add the target element. 2 String representing ID - visible The visible state of the target element. Displayed if omitted or if true is specified. Specify false to hide. "true", "false" - isChecked Property name that holds the checked state String representing the property name Required
Separator (type: Separator)
-
Separator.
-
property
key description range required type The type of the element. "Separator" Required id ID that uniquely identifies the tab. A unique string for all components of the ribbon. 1 String representing ID Required
Button Group (type: ButtonGroup)
-
A container that displays multiple buttons side by side like a toolbar
-
property
key description range required type The type of the element. "ButtonGroup" Required id ID that uniquely identifies the target element. A unique string for all components of the ribbon. 1 String representing ID Required orderBefore/orderAfter ID of the ribbon element indicating the relative position to add the target element. 2 String representing ID - visible The visible state of the target element. Displayed if omitted or if true is specified. Specify false to hide. "true", "false" - controls array of controls to tile object array - -
Types of controls that can be placed as child elements
- Button (Small)
- Separator
StackPanel (type: StackPanel)
-
A container that displays multiple buttons vertically.
- Used when you want to display small image buttons vertically.
-
property
key description range required type The type of the element. "StackPanel" Required id ID that uniquely identifies the target element. A unique string for all components of the ribbon. 1 String representing ID Required orderBefore/orderAfter ID of the ribbon element indicating the relative position to add the target element. 2 String representing ID - visible The visible state of the target element. Displayed if omitted or if true is specified. Specify false to hide. "true", "false" - controls An array of controls to tile. You can place up to 3 controls. object array - -
Types of controls that can be placed as child elements
- Button (Small)
- SplitButton (Small)
- CheckBox
Menu (type: Menu)
-
A container that displays multiple buttons in a pull-down menu format
-
properties
key description range required type The type of the element. "Menu" Required id ID that uniquely identifies the target element. A unique string for all components of the ribbon. 1 String representing ID Required label menu label arbitrary string required orderBefore/orderAfter ID of the ribbon element indicating the relative position to add the target element. 2 String representing ID - visible The visible state of the target element. Displayed if omitted or if true is specified. Specify false to hide. "true", "false" - imageLarge PNG file path of the icon to display on the button. A string representing a relative path - controls array of controls to tile object array - -
Types of controls that can be placed as child elements
- Button (Small)
- Separator
Split Button (type: SplitButton)
-
A container that has the function of a button that can be pressed to execute a command, and also displays other buttons in the form of a pull-down menu.
-
property
key description range required type The type of the element. "SplitButton" Required id ID that uniquely identifies the target element. A unique string for all components of the ribbon. 1 String representing ID Required label button label any string required description Description displayed in tooltip Any string - orderBefore/orderAfter ID of the ribbon element indicating the relative position to add the target element. 2 String representing ID - visible The visible state of the target element. Displayed if omitted or if true is specified. Specify false to hide. "true", "false" - isEnabled Property name that holds the enabled/disabled state of the button. If omitted, it is linked to the status of the assigned command. A string representing the property name - imageSmall PNG file path to a small icon (16x16 image recommended) to display on the button. 3 string representing a relative path - imageLarge PNG file path of the large icon (32x32 image recommended) to display on the button. 3 string representing a relative path - command ID of the command assigned to the button string representing the ID required controls array of controls to tile object array - -
Types of controls that can be placed as child elements
- Menu
Multilingual
- The values of
labelanddescriptionproperties can also be multilingual (localized). - Instead of specifying a display string in the property value, specify something like "%resource string name%" and it will be replaced with the resource string in the localized locale file.
note
For more information on multilingual support, see Advanced Topics > Multilingual Support.
Ribbon definition example
manifest.json
{
"name": "My Extension",
"main": "main.cs",
"lifecycle": "project",
"baseprofile": "MBD",
"extensionPoints": {
"ribbon": {
"tabs": [
{
"id": "MBD",
"label": "MBD",
"orderAfter": "System.View",
"groups": [
{
"id": "MbdSync",
"label": "Block",
"controls": [
{
"id": "MbdSync.CreateBlock",
"type": "Button",
"label": "Create Block",
"imageLarge": "resources/createBlock.png",
"command": "myExtension.createBlock"
},
{
"id": "MbdSync.Menu",
"type": "Menu",
"label": "Update Block",
"imageLarge": "resources/blocks.png",
"controls": [
{
"id": "MbdSync.UpdateAllBlocks",
"type": "Button",
"imageSmall": "resources/updateAllBlocks.png",
"label": "Bulk update",
"description": "Batch update blocks",
"command": "myExtension.updateAllBlocks"
},
{
"id": "MbdSync.Separator",
"type": "Separator"
},
{
"id": "MbdSync.UpdateBlock",
"type": "Button",
"imageSmall": "resources/updateBlock.png",
"label": "Update",
"description": "Update selected blocks",
"isEnabled": "IsBlockSelected",
"command": "myExtension.updateBlock"
}
]
},
{
"id": "MbdSync.StackPanel",
"type": "StackPanel",
"controls": [
{
"id": "MbdSync.UpdateAllBlocks",
"type": "Button",
"imageSmall": "resources/updateAllBlocks.png",
"label": "Bulk update of blocks",
"description": "Batch update blocks",
"command": "myExtension.updateAllBlocks"
},
{
"id": "MbdSync.UpdateBlock",
"type": "Button",
"imageSmall": "resources/updateBlock.png",
"label": "Update Block",
"description": "Update selected blocks",
"isEnabled": "IsBlockSelected",
"command": "myExtension.updateBlock"
}
]
}
]
},
{
"id": "CodeGen",
"label": "Generate Source Code",
"controls": [
{
"id": "CodeGen.GenerateCode",
"type": "Button",
"label": "Generate Source Code",
"imageLarge": "resources/generate.png",
"command": "myExtension.generateCode"
}
]
}
]
}
]
},
"commands": [
{
"id": "myExtension.createBlock",
"execFunc": "createBlock"
},
{
"id": "myExtension.updateAllBlocks",
"execFunc": "updateAllBlocks"
},
{
"id": "myExtension.updateBlock",
"execFunc": "updateBlock"
},
{
"id": "myExtension.generateCode",
"execFunc": "generateCode"
}
]
}
}
Footnotes
-
If you specify the same ID as an existing component, it will be integrated into the same component. Otherwise a new component is created. ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9 ↩10
-
You can specify the id of the sibling element to indicate the relative position. Can be either before (orderBefore) or after (orderAfter) the specified element. If not specified for elements other than tabs, it will be added to the end of sibling elements. ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9
-
Set either imageSmall or imageLarge. The size of the displayed icons will be adjusted according to the layout in the ribbon. Set imageSmall for elements in the StackPanel. ↩ ↩2 ↩3 ↩4 ↩5
-
If the same ID as an existing component is specified for ID, label specification is unnecessary. ↩ ↩2
-
Can be omitted when placed under the button group. However, if label is not specified, specify imageSmall or imageLarge. ↩