SetCommandState
Description
Sets the command's state to be hidden, visible, enabled or disabled. Calling this method may affect context menu, application toolbar, menus or all of them.
Syntax
shellFrame.Commands.SetCommandState(
commandId, // The ID of the command which state is to be changed
MFiles.MenuLocation.MenuLocation_TopPaneMenu, // The menu location of the change
MFiles.CommandState.CommandState_Hidden // New state of the command in specific location or
);
Parameters
| Name | Type | Description |
|---|---|---|
| commandId | number | The id of the target command. The id can represent either a custom or a builtincommand. The builtin commands are enumerated by BuiltinCommand. |
| location | CommandLocation | Menu location where the command state change takes place. Use All to affect in all locations. |
| state | CommandState | The new command state. |
CommandLocation
Values for the location are
| Name | Value | Description |
|---|---|---|
MFiles.CommandLocation.Undefined | 0 | Undefined value. |
MFiles.CommandLocation.MainMenu | 1 | Specifies the command appearance in the main menus, such as top menu and command bars. |
MFiles.CommandLocation.ContextMenu | 2 | Specifies the command appearance in the context menu. |
MFiles.CommandLocation.TaskPane | 4 | Specifies the command appearance on task pane. |
MFiles.CommandLocation.AppToolbar | 5 | Specifies the command appearance on application toolbar. |
MFiles.CommandLocation.ActivityContextMenu | 6 | Specifies the command appearance in the activity context menu. |
MFiles.CommandLocation.All | 268435455 | Refers to all command locations. |
CommandState
Values for the state are
| Name | Value | Description |
|---|---|---|
MFiles.CommandState.CommandState_Undefined | 0 | Undefined value. |
MFiles.CommandState.CommandState_Active | 1 | The command is visible and enabled. |
MFiles.CommandState.CommandState_Inactive | 2 | The command is visible but not enabled (for example grayed). |
MFiles.CommandState.CommandState_Hidden | 3 | The command is not visible. |
Return type
| Type | Description |
|---|---|
Promise < any > | It returns MFCLIENTSCRIPT~ICOMMANDS~SETCOMMANDSTATE. |
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.