Autodesk University

The out-of-the-box AutoCAD Architecture ribbon tabs include a number of tools that allow you to add AEC content. Rather than duplicate the abilities of tool palette tools to import styles or definitions from a source file when necessary and to preset property values, these ribbon tools “run” a tool palette tool, through the AECRIBBONTOOL command.

To create a ribbon tool for your own custom content, you will need a tool palette tool for the content and an editable customization file in which you can add a ribbon tool.

Tool Palette Tool

Any tool palette tool that exists in the current workspace can be referenced from a ribbon tool, whether or not it is available in the current tool palette group. If the ribbon tool is to be shared with others, everyone will need to have the referenced tool and the palette on which it resides should not be easily deleted or edited. The out-of-the-box setup achieves this by having the ribbon tools reference tools that are on a read-only palette that is not part of any of the out-of-the-box tool palette groups. To see this palette, you need to set “All Palettes” current. You may want to set up a similar read-only palette for the tools that will be referenced by your ribbon tools, if you do not have a read-only, network-based tool palette location that everyone has in their workspace.

Figure 1 – Custom Ribbon Tools palette with tools to be added to the ribbon

Customization File

Ribbon tools are created in a CUIx file by placing commands on a ribbon panel. Ribbon panels are added to ribbon tabs, which are then added to one or more Workspaces. All of this is done within the Customize User Interface dialog.

Where to create your ribbon customizations is up to you, but it is generally considered good practice to keep your customizations separate from the out-of-the-box files whenever possible, to ease maintenance and migration to future releases. The example here will create a CUIx file (AECRibbonTool.cuix), loaded as a partial customization file, to hold custom commands and ribbon tools, a panel, and a tab. A ribbon panel defined in a partial customization file can be added to a ribbon tab defined in any currently loaded customization file, so you could create your new commands and ribbon panel in your own customization file and limit your modification of an out-of-the-box customization file to adding the new panel to the ribbon tab.

Create and Load the Partial Customization File

1. On the Manage tab, on the Customization panel, click the User Interface tool (or type " CUI" at the Command prompt and press Enter).
2. Click the Transfer tab, if it is not current.
3. On the right side, click the Create a new customization file button.
4. In the Save As dialog, navigate to the folder in which the new customization file is to be saved, enter a name for the file ("AECRibbonTool.cuix" in this example) and click Save.
5. Click on the Customize tab. At the lower right corner, if the arrow button is pointing to the right (“>”), click on that button to expand the dialog.
6. On the left side, near the top of the Customizations in… pane, click on the Load partial customization file button.
7. In the Open dialog, navigate to the new customization file’s folder, select the file and click Open.

Create the New Panel

1. With the Customize User Interface dialog still open, in the Customizations in… pane, verify the drop-down list just below the title bar shows the name of your new customization file (aecribbontool.cuix); if not, select your file name on the drop-down list to filter the information shown to just that of the partial file.

   

   Figure 2 – AECRibbonTool.cuix partial customization file loaded and selected

2. In the Customizations in… pane, expand the Ribbon node.
3. Right click the Panels node, and choose New Panel.
4. Enter a name for your panel. The example panel will be used on a ribbon tab called “AEC Content”, so the panel is named "AEC Content - Ribbon Tools". Press Enter to register the name.
5. In the Properties pane, both the Name and Display Text properties have been set to your panel name. If you prefixed your panel name with the name of the tab, edit the Display Text property to show just the panel name (Ribbon Tools). This is what will show on the title bar of the panel.
6. KeyTips provide access to ribbon tools via the keyboard (after pressing the Alt key). For panels with tools in the slideout, enter a string of up to three characters in the KeyTip property to enable the user to expand the panel from the keyboard and access the tools in the slideout. Panels without slideout tools do not need a KeyTip string.

   

   Figure 3 – Ribbon Tools Panel properties

7. Repeat Steps 10 – 13 as required to create the panels you need. When you are done creating panels, click the Apply button to save the current changes to the CUIx file.

Populate the New Panel

1. With the Custom User Interface dialog still open, in the Command List pane at bottom left, click the Create a new command button.
2. In the Properties pane, enter the following information for the ribbon tool command:
   • Name: Enter the tool name (Vending Machine).
   • Description: Describe the purpose of the tool, for the tool tip.
   • Extended Help File: Optional! See the Customization Guide in the Help for information on creating an XAML file to provide extended help in the tool tip.
   • Command Display Name: Enter a string representing the command macro, for the tool tip (AECRIBBONTOOL Vending Machine).
   • Macro: Enter the macro string that the command will execute directly in the edit box or click on the ellipsis button to enter/edit the macro in the Long String Editor dialog. An AECRibbonTool command macro should look similar to this:

     ^C^C_AecRibbonTool Vending Machine - ribbon;

     Replace Vending Machine - ribbon with the name of the tool palette tool you want the ribbon tool to invoke.

   • Tags: Enter any key words to be associated with your ribbon tool. These are used as part of the command search feature on the Application Menu.
   • Element ID: A default value is entered automatically, and is used to reference the macro programmatically. Enter your own value, if you like.
   • Images: The small (16 x 16 pixels) and large (32 x 32 pixels) images can be specified from external files here, or use the Button Image pane to select from the available images, import a file (BMP) or draw your own.

      TIP: Click the Edit button in the Button Image pane to open the Button Editor. The light gray color at the bottom of the left column of colors will be treated as “clear” allowing the background color of the ribbon to show through, including the blue-green highlight when hovering over a button. Use this color for pixels at the edge, beyond the image proper.

     

     Figure 4 – Vending Machine command properties

3. In the Command List pane, left click and drag your newly defined command up onto the Customizations in… pane, position your cursor on the Row 1 node of the ribbon panel created in Step 10 and release the mouse button to add the command to that row.

   

   Figure 5 – Drag-n-drop the command on the panel

4. On the right side, you will see a preview image of the panel and have access to the Button Image and Properties panes.
   • Enter a value for the Name property only if you want the ribbon tool name to be different from the command name.
   • Choose a Button Style, which controls the button size and associated text, if any.
   • Most of the other properties will be filled in with the same values as those specified for the command, and changing them here will also change them for the command.
   • Enter up to three characters in the KeyTip property to specify a key sequence unique to the ribbon tab on which the tool’s panel will appear.
5. Repeat Steps 15 – 18 to create and place additional commands. Add rows, sub-panels, and drop-downs to organize your tools, as desired. When you are done creating and adding commands, click the Apply button to save the current changes to the CUIx file.

   

   Figure 6 – Ribbon Tools panel with Vending Machine as a tool and an Office Equipment split button with three tools on the drop-down

Create a Ribbon Tab and Add the Panel

1. Skip down to Step 24 if you intend to add your new panel(s) to an existing ribbon tab. Otherwise, with the Customize User Interface dialog still open, in the Customizations in… pane, right click on the Tabs node and choose New Tab from the context menu.
2. Type a name for your tab (AEC Content) and press Enter to register the name.
3. In the Properties pane, use the Default Display property to set whether or not the tab is automatically added to the Workspace(s) when loaded as a partial CUIx.
4. Enter up to three characters for the KeyTip property. You must do so for the tab if you want the KeyTips entered for the tools to work.
5. Skip to Step 25 if you created a new tab for your panel(s). If you are adding your panel to an existing ribbon tab from a different CUIx file, choose All Customization Files in the drop-down at the top of the Customizations in… pane.
   • Expand the nodes to expose Customization File Name > Ribbon > Tabs for the customization file that has the target tab.
   • Expand the nodes to expose the panels to be added, under you newly created customization file (AECRIBBONTOOL).
6. In the Customizations in… pane, left click and drag the name of the panel to be added (AEC Content – Ribbon Tools) from under the Panels node to the name of the target tab and release the mouse button.

   

   Figure 7 – Drag-n-drop the panel on the tab

7. Add additional panels, if you have them. Drag the panel names under a tab to change the order of the panels on the tab.
8. When you are done adding panels to tabs, click the Apply button to save the current changes to the CUIx file.

Add the Ribbon Tab to Your Workspace (New Tab Only)

You will now need to manually add a new tab to the desired Workspace(s). (If you set the panel to be added when loading as a partial file, you could unload the file and then reload it to add the tab to all Workspaces.)

1. With the Customize User Interface dialog still open, set the drop-down at the top of the Customize in… pane to All Customization Files.
2. Under the main customization file (ACA in the example here), expand the Workspaces node and select the name of a Workspace to which you want your new tab added.
3. In the Workspace Contents pane at top right, click the Customize Workspace button.
4. In the Customizations in… pane, expand the nodes to expose Partial Customization Files > Customization File Name (AECRIBBONTOOL) > Ribbon > Tabs.
5. Click the toggle in front of each tab name to be added to the Workspace, or click the toggle in front of the Tabs node to add all of the tabs under the node.
6. In the Workspace Contents pane, select a tab name and review its properties. Tabs can be included in a Workspace but not displayed, if the Show property is set to No. A ToolPalette Group can be associated with a ribbon tab, if you want.
7. Click on the Done button to exit the editing of that Workspace.
8. Repeat Steps 29 – 34 to add your new tab to additional Workspaces.
9. Click the OK button to accept the changes made, close the CUI dialog and return to the drawing.

Your new tools should now be available. Click on the appropriate tab and try them out.

Figure 8 – The Ribbon Tools panel on the AEC Content tab