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.ActivityContextMenu	6	Specifies the command appearance in the activity context menu.

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