Ribbon Customisation - Commands (Custom)

Have you ever wondered what goes here?

Yes, me too!

This is a route to creating custom buttons containing key-in sequences that can be used in your ribbon customisation. Any key-in that you can compile and test in the key-in dialog can be added to a custom command. The advantage of this is that the XML created by the following steps is read directly by the application; this enables tools to be updated after they have been added to any custom ribbon locations simply by updating the XML.

If you only need a couple of tools, move along, this is over the top.....but if you need to create and manage lots of tools, read on...

The help documentation gives us a start point: Home > The Ribbon > Ribbon Interface > Customizing the Ribbon > Application Commands and Custom Commands.

Here you will find that the variable MS_NAMEDCOMMANDSLIST can be set to point to one or more XML files containing lists of commands, e.g.:

MS_NAMEDCOMMANDSLIST = $(_USTN_ORGANIZATION)/Dgnlib/GUI/GUICustomCommandsSource.xml

Here is sample of the XML code contained in such a file:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<UserNamedCommands xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<UserNamedCommand>
		<Name>Unique.Command.Name</Name>
		<Label>Label that appears in Customize Ribbon UI</Label>
		<Keyin>Keyin</Keyin>
		<Description>Command description, tool pop-up text</Description>
		<IconName>Name of icon</IconName>
		<VisibilityExpression/>
		<EnableExpression/>
		<SyncItemEvent/>
	</UserNamedCommand>
</UserNamedCommands>

Each custom command is contained with the <UserNamedCommand> tag.

A valid XML file can be generated from Excel using it's XML features. To see these enable the Developer tab. Once enabled, the XML Source panel can be used to create a schema from this code structure. Note that for Excel to correctly create a schema the source XML must contain at least two instances of the <UserNamedCommand> tag, here is a sample that can be used to try this out:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<UserNamedCommands  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<UserNamedCommand>
		<Name>Example1</Name>
		<Label>Label1</Label>
		<Keyin>Keyin1</Keyin>
		<Description>Description1</Description>
		<IconName>Icon1</IconName>
		<VisibilityExpression>null</VisibilityExpression>
		<EnableExpression>null</EnableExpression>
		<SyncItemEvent>null</SyncItemEvent>
	</UserNamedCommand>
	<UserNamedCommand>
		<Name>Example2</Name>
		<Label>Label2</Label>
		<Keyin>Keyin2</Keyin>
		<Description>Description2</Description>
		<IconName>Icon2</IconName>
		<VisibilityExpression>null</VisibilityExpression>
		<EnableExpression>null</EnableExpression>
		<SyncItemEvent>null</SyncItemEvent>
	</UserNamedCommand>
</UserNamedCommands>

Download and open the file in Excel, use the 'As an XML table' option:

The result should look like this.

The fields can be populated taking advantage of the usual Excel features such as copy and fill to duplicate and sequence values, this video shows the steps required:

The file is here 1106.CustomCommandsSource_Template.xlsx.

Populating the XML file

Field Values

Important: The command Name (Column A) must be unique.

Ideally the command Label should also be unique. However as the Label is the command name that will be displayed in the Ribbon there may be cases where the same Label is used more than once. Hovering over a tool in the list will show the command Name so the commands can be identified as they are added to your Ribbon.

Here's more detail on values:

Name (mandatory)

Name of Command. This name must be unique across all commands both defined by user or applications.  One simple way to ensure that your command name is unique is to prefix the command name with a company or project code, e.g.  "ABC01.RunPlaceLineMacro". Note the separator between code and command name. The name can contain these special characters: [_.a-zA-Z0-9\-]+

Label (mandatory)

The Label shown when command is used in the Ribbon.

Keyin (mandatory)

The key-in to process when command is executed. The key-in format is "[task1;task2;...]keyin command string1;ac={{expressionname}}" which is identical to the all the key-ins support in the Customize Dialog.

Key-ins can be tested in the key-in window before they are added to the XML.

Description (recommended)

Description of command to execute. Shown in ToolTip.

IconName (recommended)

Name of  the Icon that is to be displayed when a Command is used on a Ribbon Button or DropDown menu. The name must be an icon available from an icon resource file or a configured Dgnlib.

VisibilityExpression (optional)

Name of Named Expression that returns True or False.

If True is returned then the item associated with the command will be visible. This can optionally be an in-line expression which has the format of [symbolset1,symbolset2,..symbolsetn]expression.
An example of an in-line expression is [Session]Session.TreatActiveModelAs3D() and [Session not(Session.TreatActiveModelAs3D()) to test for being in 3D and 2D models respectively.

EnableExpression (optional)

Name of Named Expression that returns True or False. If True is return then item associated with the command will be enabled.
This can optionally be an in-line expression which has the format of [symbolset1,symbolset2,..symbolsetn]expression.
An example of an in-line expression is [Session]Session.TreatActiveModelAs3D() and [Session]not(Session.TreatActiveModelAs3D()) to test for being in 3D and 2D models respectively.

SyncItemEvent (optional)

Name of UISyncEvent which should trigger re-evaluation Visibility and Enable expressions. If multiple events need to be specified they should be separated by a vertical bar ("|"). If none are specified the expression will be evaluated on every model change.

Filling in the Fields

None of us like repetitive text entry so if a lot of tools are required make the most of Excel to semi-automate things. Rather than entering direct into the XML template worksheet CustomCommandsSource_Template.xlsx, it can be more practical to assemble the field content in a separate workbook using Excel concatenation to compile unique command names and conditional formatting to identify duplications or other data.

For instance in this example values from columns B (3), D (2) and I (1) have been concatenated to create the unique name in column A using the formula

=CONCATENATE("CustomTools.",I4,".",(SUBSTITUTE(D4," ","")),".",(SUBSTITUTE(B4," ","")))

The CustomTools. prefix is set, then the rest of the text is pulled in from the subsequent fields using SUBSTITUTE's ability to remove spaces

  (click to enlarge)

This example file is here 8244.CustomButtons_EditAndConcatenateSource.xlsx.

Once the content is ready to use simply copy and paste Values into a copy of CustomCommandsSource_Template.xlsx saving it with an appropriate name.

From this file save as XML Data (*.xml) in the location defined by MS_NAMEDCOMMANDSLIST

This will directly populate the Commands (Custom) pop-down. 

A Limitation

Custom commands cannot at this time be used in Split-button or Drop-down button sub-menus, limiting the scope for construction of menu structures. We are looking into this.