AddCustomCommandToMenu
Description
The AddCustomCommandToMenu function is a part of the M-Files UI Extension framework and is used to include a custom command in a specific location within the M-Files user interface menu. It allows developers to define the position and priority of the custom command in the menu structure. This function typically takes parameters such as the ID of the custom command, the menu location where the command should appear, and a priority value to determine its order within the menu. This enables customization of the user interface by seamlessly integrating custom functionality into the M-Files application's menu system.
The Command to be added must be first created using CreateCustomCommand method.
Syntax
// AddCustomCommandToMenu is part of ICommands is part of the IShellFrame interface
const menuItemId = await shellFrame.Commands.AddCustomCommandToMenu(
customCommandId, // ID of the custom command, created using CreateCustomCommand
MFiles.MenuLocation.MenuLocation_TopPaneMenu, // MenuLocation using MFiles.MenuLocation enumeration
1 // Order priority of the menuitem
);
Parameters
| Name | Type | Description |
|---|---|---|
| customCommand | number | The command identifier. Use CreateCustomCommand method to create a command. |
| location | MenuLocation | Detailed menu location where to add the existing custom command. Possible locations are enumerated. |
| orderPriority | number | The order indication for the command. Smallest priority goes top. |
MenuLocation
Possible values for the location parameter are
| Name | Value | Description |
|---|---|---|
MFiles.MenuLocation.MenuLocation_ContextMenu_ObjectOperations | 26 | Menu location for the position of object operations in the context menu. |
MFiles.MenuLocation.MenuLocation_ContextMenu_Edit | 37 | Menu location for the context menu position for Edit commands. |
MFiles.MenuLocation.MenuLocation_ContextMenu_DocumentConversions | 41 | Menu location for the context menu position for document conversions. |
MFiles.MenuLocation.MenuLocation_ContextMenu_Bottom | 43 | Menu location for the bottom of the context menu. |
MFiles.MenuLocation.MenuLocation_PaneToolbar | 45 | Menu location for the toobar of the shellpane. |
MFiles.MenuLocation.MenuLocation_PaneToolbarDropdown | 46 | Menu location for the dropdown for the shellpane. |
MFiles.MenuLocation.MenuLocation_TopPaneMenu | 47 | TopPane Menu, typically used for the UI Extension applications. |
MFiles.MenuLocation.MenuLocation_ActivityContextMenu_1 | 48 | Menu location for the Activity view Context menu group 1. |
MFiles.MenuLocation.MenuLocation_ActivityContextMenu_2 | 49 | Menu location for the Activity view Context menu group 2. |
MFiles.MenuLocation.MenuLocation_ActivityContextMenu_3 | 50 | Menu location for the Activity view Context menu group 3. |
Return type
| Type | Description |
|---|---|
Promise < number > | Returns the Menu item ID. |
Example
This JavaScript code is a UI Extension for M-Files, creating custom commands such as "Hello World" and providing functionality to dynamically show, hide, and remove these commands from the top menu based on user interactions within the M-Files shell.
// Called when the UI Extension starts
function OnNewShellUI(shellUI) {
// Wait for the ShellFrame to be created.
shellUI.Events.Register(
MFiles.Event.NewShellFrame,
async (shellFrame) => {
// Wait for the shellframe to start
shellFrame.Events.Register(
MFiles.Event.Started,
async () => {
// Create a new custom command and menu item for the command
const createCommand = async ( name: string ) => {
// Create a new custom command
const commandId = await shellFrame.Commands.CreateCustomCommand(name);
// Add the command to the top menu
const menuItemId = await shellFrame.Commands.AddCustomCommandToMenu(
// Command ID
commands.exampleCommand,
// Menulocation
MFiles.MenuLocation.MenuLocation_TopPaneMenu,
// Priority of the command
1
);
// Return a data structure containing essential information about the commands
return {
id: commandId, // ID of the command
menuItemId // Menu item ID, can be used to add sub menus to this menu item.
}
}
// Create an Example command and a set of sample commands to control it's visibility
const commands = {
// This is the sample command
exampleCommand : await createCommand("Hello World"),
// These commands control the state of the example command
addCommand: await createCommand("Add Command To Menu"),
deleteCustomCommand: await createCommand("Delete Command")
hideCommand: await createCommand("Hide Command"),
showCommand: await createCommand("Activate Command"),
executeCommand: await createCommand("Execute Command"),
getCommandName: await createCommand("Get Name"),
getCommandState: await createCommand("Get Command State"),
removeCommandFromMenu: await createCommand("Remove From Menu"),
removeCommand: await createCommand("Remove Command")
}
// Add the command to the top menu
const menuItemId = await shellFrame.Commands.AddCustomCommandToMenu(
commands.exampleCommand,,
MFiles.MenuLocation.MenuLocation_TopPaneMenu,
1 // Priority of the command
);
// Listen for the custom commands.
shellFrame.Commands.Events.Register(
// Listen for the CustomCommand events.
MFiles.Event.CustomCommand,
// Each command has ID and optional data provided with it.
( commandId, data ) => {
// Respond to the command if custom command sent by the application
switch( commandId ) {
// Run the Example command
case commands.exampleCommand.id:
shellFrame.ShowMessage( "Hello World!" );
break;
// Add the new menuitem which runs the example command
case commands.addCommand.id:
await shellFrame.Commands.AddCustomCommandToMenu(
commands.exampleCommand,
MFiles.MenuLocation.MenuLocation_TopPaneMenu,
1 // Priority of the command
);
break;
// Removes the command from particular menu
case commands.removeCommandFromMenu.id:
await shellFrame.Commands.RemoveCustomCommandFromMenu(
commands.exampleCommand,,
MFiles.MenuLocation.MenuLocation_TopPaneMenu
);
break;
// Deletes the command permanently
case commands.deleteCommand.id:
shellFrame.Commands.SetCommandState(
commandId,
MFiles.CommandLocation.MainMenu,
MFiles.CommandState.CommandState_Active
);
break;
// Hiddes all command instances for specific command ID
case commands.hideCommand.id:
// Hide the command
shellFrame.Commands.SetCommandState(
commandId,
MFiles.CommandLocation.MainMenu,
MFiles.CommandState.CommandState_Hidden
);
break;
// Activates (makes visible) all command instances for specific command ID
case commands.showCommand.id:
// Show the command
shellFrame.Commands.SetCommandState(
commandId,
MFiles.MenuLocation.MenuLocation_TopPaneMenu,
MFiles.CommandState.CommandState_Active
);
break;
// Get the command name
case commands.getCommandName.id:
const name = await shellFrame.Commands.getCommandName(commands.exampleCommand.id);
shellFrame.ShowMessage( name );
break;
// Get the Command State
case commands.getCommandState.id:
// NOTE: the MFiles.CommandLocation.MainMenu must be used to get state of items added to the Top Menu
const commandState = await shellFrame.Commands.getCommandState(commands.exampleCommand.id, MFiles.CommandLocation.MainMenu );
shellFrame.ShowMessage( `Command state: ${commandState}` );
break;
}
}
);
}
)
}
)
}
This code is essentially setting up a simple UI extension with custom commands that can be triggered from the top menu, and it allows dynamic control over the visibility of these commands based on user interactions.