Skip to main content

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

NameTypeDescription
commandIdnumberThe id of the target command. The id can represent either a
custom or a builtincommand. The builtin commands are enumerated by BuiltinCommand.
locationCommandLocationMenu location where the command state change takes place.
Use All to affect in all locations.
stateCommandStateThe new command state.

CommandLocation

Values for the location are

NameValueDescription
MFiles.CommandLocation.Undefined0Undefined value.
MFiles.CommandLocation.MainMenu1Specifies the command appearance in the main menus, such as top menu and command bars.
MFiles.CommandLocation.ContextMenu2Specifies the command appearance in the context menu.
MFiles.CommandLocation.ActivityContextMenu6Specifies the command appearance in the activity context menu.

CommandState

Values for the state are

NameValueDescription
MFiles.CommandState.CommandState_Undefined0Undefined value.
MFiles.CommandState.CommandState_Active1The command is visible and enabled.
MFiles.CommandState.CommandState_Hidden3The command is not visible.

Return type

TypeDescription
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.